{"id":13426148,"url":"https://github.com/rivasd/jsPsychHardware","last_synced_at":"2025-03-15T21:30:44.966Z","repository":{"id":98988671,"uuid":"59779183","full_name":"rivasd/jsPsychHardware","owner":"rivasd","description":"A Google Chrome Extension and native hosts allowing jspsych to interact with hardware","archived":false,"fork":false,"pushed_at":"2018-12-21T23:46:02.000Z","size":402,"stargazers_count":16,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-28T04:25:35.220Z","etag":null,"topics":["arduino","chrome-extension","jspsych","parallel-port","psychology-experiments","serial-communication"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rivasd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2016-05-26T19:55:10.000Z","updated_at":"2024-06-07T06:31:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"1bcff086-9159-4b17-9af9-e4f2fc1cdc5f","html_url":"https://github.com/rivasd/jsPsychHardware","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rivasd%2FjsPsychHardware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rivasd%2FjsPsychHardware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rivasd%2FjsPsychHardware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rivasd%2FjsPsychHardware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rivasd","download_url":"https://codeload.github.com/rivasd/jsPsychHardware/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243792283,"owners_count":20348606,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","chrome-extension","jspsych","parallel-port","psychology-experiments","serial-communication"],"created_at":"2024-07-31T00:01:27.459Z","updated_at":"2025-03-15T21:30:44.618Z","avatar_url":"https://github.com/rivasd.png","language":"JavaScript","readme":"# jsPsychHardware\n\n\u003e A Google Chrome Extension that allows client-side JavaScript to read/write Serial and Parallel ports.\n\nControl Arduinos and send Parallel Port triggers for electrophysiological devices and other legacy hardware from a webpage. No server required!\n\n## Getting Started\n\njsPsychHardware was built as a companion to the fantastic [jsPsych](https://github.com/jspsych/jsPsych) library for creating and running behavioral experiments in a browser. However, you don't need to include it on your page, here's how to get up and running\n\n### Prerequisites\n\n#### Native C++ program \n\nYou will need to install [this small native C++ program](https://github.com/rivasd/chromeparallel/releases) to relay messages from the extension to the hardware. \n\n*Windows x64 and x86 only, Linux support planned*\n\n### Installing\n\nYou can find and install the latest version of this extension [here](https://chrome.google.com/webstore/detail/jspsychhardware/jfodnelopfigofnkclnkeeehjjjlnkan)\n\n#### DOM trace\n\nLet jsPsychHardware know that your page will need it by setting a custom \"jspsych\" attribute on your `\u003chtml\u003e` element. This is done automatically if you have already included [jsPsych](http://www.jspsych.org) through a `\u003cscript\u003e` tag in your page.\n\n```html\n\u003c!-- Set this attribute --\u003e\n\u003chtml jspsych=\"present\"\u003e\n    ...\n    \u003c!-- Rest of your webpage goes here --\u003e\n\u003c/html\u003e\n```\n\nYou can now use jsPsychHardware by clicking the jsPsych icon on the top right of your Chrome screen!\n\n#### Settings\n\n##### COM ports\nYou can connect to a COM port by selecting one from the options. The icon will turn green upon successful connection. Make sure no other processes (like an Arduino Serial monitor) are using the COM port you are trying to connect to!\n\n##### LPT port\nYou will need to provide jsPsychHardware with the hardware address of your Parallel port. It is a 4-digit hex number you can find by consulting your system's settings [as described here](https://www.sevenforums.com/hardware-devices/344035-i-o-address-parallel-lpt-port-missing-resource-tab.html), then click the \"on\" button next to the input box to confirm the address\n\n## Documentation\n\njsPsychHardware uses [Custom Events](https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Creating_and_triggering_events) to communicate with your client-side JS. You will thus send commands by dispatching `jspsych` type Events on the `document` element\n\n```javascript\n// Creating a message to display a byte with value 255 on the parallel port\nvar myEvent = new CustomEvent('jspsych', {\n    detail:{\n        target : 'parallel',\n        action : 'trigger',\n        payload: 255\n    }\n});\n\n//send the message\ndocument.dispatchEvent(myEvent);\n```\n\njsPsychHardware's events have a `detail` object with 3 fields describing the desired operation:\n\n|__Field name__ | *Usage*                                                   | *Possible values*     |\n|---------------|-----------------------------------------------------------|-----------------------|\n|target         |indicates the target hardware to operate                   |`serial` `parallel`    |\n|action         |What operation to conduct                                  | `trigger` `send` `read` |\n|payload        |action-dependent information needed to complete the command|`{String|number}`      |\n\n### Serial Ports\n#### action: send\nYou can write to the serial port using event detail with target `serial`, action `send`, and a String for `payload`\n```javascript\n//you can 'send' Strings to the serial port\ndocument.dispatchEvent(new CustomEvent('jspsych',{\n    detail:{\n        target: 'serial',\n        action: 'send',\n        payload: 'Hello Arduino' //String only, other types will fail\n    }\n}));\n```\n#### action: read\n`payload` must be a valid integer representing the maximal number of bytes to read from the port. jsPsychHardware will emit a `jspsych-hardware-message` event when the hardware responds. The event objects' `detail` member will contain the data. \n\n\u003e If no data is available on the port when the read command is sent, the event will contain no data. **Make sure your device has written data before attempting to read**\n\n\n\n```javascript\n//create a listener that will receive the result of all read operations\ndocument.addEventListener('jspsych-hardware-message', function(evt){\n    var receivedObject = evt.detail;\n    var value = receivedObject.result               //the char array read from the port\n    if(value){\n        //do something with the received data...\n    }\n    else{\n        //there was nothing to read when this request was sent...\n    }\n    \n});\n\n//Now that we are ready to receive the data, send the read request\ndocument.dispatchEvent(new CustomEvent('jspsych', {\n    detail:{\n        target: 'serial',\n        action: 'read',\n        payload: 1          //must be integer, here reads single byte if available\n    }\n}));\n```\n\n### Parallel Port\n\n#### action: trigger\nCurrently, only writing is supported for LPT ports. Byte value appears on the port's pins for **5ms** then goes back to zero (used to send triggers to BioSemi EEG acquisition box).\n\npayload must be integer between 0 and 255.\n\n```javascript\n//send a byte value to indicate an interesting event (like a visual stimulus appearing during a psychological experiment)\ndocument.dispatchEvent(new CustomEvent('jspsych', {\n    detail:{\n        target:'parallel',\n        action:'trigger',\n        payload: 64         //only valid byte accepted (0-255)\n    }\n}));\n```\n\n## Contributing\n\nContributions and suggestions for future hardware support are more than welcome! raise an issue on this GitHub :)\n\n## Authors\n\n* **Daniel Rivas** - (https://github.com/rivasd)\n\n## Acknowledgments\n\n* Hat tip to [Josh de Leeuw](https://github.com/jodeleeuw) for the jsPsych library\n* [Montreal's Centre for Research on Brain Language and Music](http://crblm.ca/) for their support.\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frivasd%2FjsPsychHardware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frivasd%2FjsPsychHardware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frivasd%2FjsPsychHardware/lists"}