\n Provide a stable Python driver for all OpenBCI Biosensors\n
\n\nUsing this repo provides a building block for developing with Python. The goal for the Python library is to ***provide a stable Python driver for all OpenBCI Biosensors***, that:\n\n* Allows Python users to install one module and use any board they choose\n* Provides examples of using Python to port data to other apps like lab streaming layer\n* Performs the heavy lifting when extracting and transforming raw binary byte streams\n* Provides a base for the beginner users to use Python to process their OpenBCI data\n\n## To Do\n* Add Ganglion Aux Data\n\n## Requirements\n\n* Python 2.7 or 3.4+\n* Currently the Cyton works on Windows, Linux, and MacOS.\n* Ganglion works on Linux only (Linux VM with enabled Bluetooth works as well).\n* The WiFi shield is known to have reliability issues across different computer configurations. Using it effectively requires advanced technical skills and programming knowledge. Note that the code avaiable here has not been tested accross all platforms.\n\n## Installation\nFirst, make sure you have the necessary dependencies.\n\n```python\npip install numpy pyserial bitstring xmltodict requests\n```\n\nLinux users may need `bluepy` also.\n\nThen you can use pip to install the OpenBCI module.\n\n```python\npip install -i https://test.pypi.org/simple/ pyOpenBCI\n```\n\nOnce installed, try running the examples provided to make sure you can connect to your OpenBCI board.\n\n## Important notes\n\nCurrently the Ganglion board can only be used with a Linux OS. The WiFi shield is known to have reliability issues across different computer configurations. Using it effectively requires advanced technical skills and programming knowledge. Note that the code avaiable here has not been tested accross all platforms.\n\n### Getting Started\n\nFirst you need to initialize your board with one of the following commands:\n\n#### For Cyton board:\n\n```python\n# For Windows replace '*' with the port number\nboard = OpenBCICyton(port='COM*')\n\n# For MacOS and Linux replace '*' with the port number\nboard = OpenBCICyton(port='/dev/ttyUSB*')\n```\n\nTo find the COM port you are connected to you can use the OpenBCI GUI. Otherwise you can leave the port number as None, and the function find_port() will run and connect to the first Cyton Dongle it finds.\n\n#### For Cyton + Daisy:\n\n```python\n# For Windows replace '*' with the port number\nboard = OpenBCICyton(port='COM*', daisy=True)\n\n# For MacOS and Linux replace '*' with the port number\nboard = OpenBCICyton(port='/dev/ttyUSB*', daisy=True)\n```\n\nTo find the COM port you are connected to you can use the OpenBCI GUI. Otherwise you can leave the port number as None, and the function find_port() will run and connect to the first Cyton Dongle it finds.\n\n#### For Ganglion:\n\n```python\n# For Linux replace '*' with the mac address.\nboard = OpenBCIGanglion(mac='*')\n```\nIf you need to find the Ganglion mac address you can use an app like [nRF connect](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp&hl=en_US) to find the ganglion. Otherwise you can leave the mac address as None, and the function find_mac() will run (NOTE: You will need to run the script with sudo for this function to work).\n\n#### For Wifi Shield:\n\n```python\nboard = OpenBCIWifi(shield_name='OpenBCI-2254', sample_rate=200)\n```\n\n### Sending commands\n\nOnce you initialize the board you can use the commands on the OpenBCI SDKs ([Ganglion](https://docs.openbci.com/OpenBCI%20Software/06-OpenBCI_Ganglion_SDK), [Cyton](https://docs.openbci.com/OpenBCI%20Software/04-OpenBCI_Cyton_SDK), [Wifi Shield](https://docs.openbci.com/OpenBCI%20Software/08-OpenBCI_Wifi_SDK)) to send commands to the board using python (make sure your commands are strings).\n\n```python\n# Write commands to the board\nboard.write_command(command)\n```\n\nHere is a table of the most common ones:\n\n| | Ganglion SDK | Cyton SDK | Cyton & Daisy SDK (Additional Commands) | Wifi Shield SDK (Additional Commands) |\n|-------------------------------|--------------|-----------------|-----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Turn Channels OFF | 1 2 3 4 | 1 2 3 4 5 6 7 8 | q w e r t y u i | |\n| Turn Channels ON | | ! @ # $ % ^ & * | Q W E R T Y U I | |\n| Connect to internal GND | | 0 | | |\n| Enable Synthetic Square Wave | [ | [ | | |\n| Disable Synthetic Square Wave | ] | ] | | |\n| Connect to DC Signal | | p | | |\n| Set Channels to Default | | d | | |\n| Start Streaming Data | b | b | | |\n| Stop Streaming Data | s | s | | |\n| Soft Reset | v | v | | ; |\n| Enable Accelerometer | n | | | |\n| Disable Accelerometer | N | | | |\n\n\n### Initializing Stream\n\nTo start your stream you can use the following command with a callback function. You can look at the examples folder for some pre-written callback functions.\n\n```python\n# Start stream\nboard.start_stream(callback)\n```\nThe output of the start_stream function is the OpenBCISample on the callback function. The OpenBCISample object has the following attributes:\n\n* packet_id = The ID of the incomming packet.\n* channels_data = The raw EEG data of each channel. 4 for the Ganglion, 8 for the Cyton, and 16 for the Cyton + Daisy.\n* aux_data = Accelerometer data.\n\nBecause the channels_data and aux_data is the raw data in counts read by the board, we need to multiply the data by a scale factor. There is a specific scale factor for each board:\n\n#### For the Cyton and Cyton + Daisy boards:\n\nMultiply uVolts_per_count to convert the channels_data to uVolts.\n\n```python\nuVolts_per_count = (4500000)/24/(2**23-1) #uV/count\n```\nMultiply accel_G_per_count to convert the aux_data to G.\n\n```python\naccel_G_per_count = 0.002 / (2**4) #G/count\n```\n#### For the Ganglion Board\n\nMultiply Volts_per_count to convert the channels_data to Volts.\n\n```python\nVolts_per_count = 1.2 * 8388607.0 * 1.5 * 51.0 #V/count\n```\nMultiply accel_G_per_count to convert the aux_data to G.\n\n```python\naccel_G_per_count = 0.032 #G/count\n```\n\n#### For the Wifi Shield\n\nThe Wifi Shield already outputs the data in Volts and the aux data in G.\n\n### Example (Print Raw Data)\n\nTo test this example, use `py Examples\\print_raw_example.py` or `python Examples\\print_raw_example.py`.\n\n```python\nfrom pyOpenBCI import OpenBCICyton\n\ndef print_raw(sample):\n print(sample.channels_data)\n\nboard = OpenBCICyton(port='COM5', daisy=False)\n\nboard.start_stream(print_raw)\n\n```\n\n### Example (Simple LSL Streamer)\n\nTo run this example, use `py Examples\\lsl_example.py` or `python Examples\\lsl_example.py`.\n\n```python\n\nfrom pyOpenBCI import OpenBCICyton\nfrom pylsl import StreamInfo, StreamOutlet\nimport numpy as np\n\nSCALE_FACTOR_EEG = (4500000)/24/(2**23-1) #uV/count\nSCALE_FACTOR_AUX = 0.002 / (2**4)\n\n\nprint(\"Creating LSL stream for EEG. \\nName: OpenBCIEEG\\nID: OpenBCItestEEG\\n\")\n\ninfo_eeg = StreamInfo('OpenBCIEEG', 'EEG', 8, 250, 'float32', 'OpenBCItestEEG')\n\nprint(\"Creating LSL stream for AUX. \\nName: OpenBCIAUX\\nID: OpenBCItestEEG\\n\")\n\ninfo_aux = StreamInfo('OpenBCIAUX', 'AUX', 3, 250, 'float32', 'OpenBCItestAUX')\n\noutlet_eeg = StreamOutlet(info_eeg)\noutlet_aux = StreamOutlet(info_aux)\n\ndef lsl_streamers(sample):\n outlet_eeg.push_sample(np.array(sample.channels_data)*SCALE_FACTOR_EEG)\n outlet_aux.push_sample(np.array(sample.aux_data)*SCALE_FACTOR_AUX)\n\nboard = OpenBCICyton(port='COM5', daisy=False)\n\nboard.start_stream(lsl_streamers)\n\n```\n### Who are we?\n\nThe founder of the OpenBCI Python repository is Jermey Frey. The Python driver is one of the most popular repositories and has the most contributors!\n\nThe contributors to these repos are people using Python mainly for their data acquisition and analytics.\n\n\n### Get involved\n\nIf you think you can help in any of the areas listed above (and we bet you can) or in any of the many areas that we haven't yet thought of (and here we're *sure* you can) then please check out our [contributors' guidelines](CONTRIBUTING.md) and our [roadmap](ROADMAP.md).\n\nPlease note that it's very important to us that we maintain a positive and supportive environment for everyone who wants to participate. When you join us we ask that you follow our [code of conduct](CODE_OF_CONDUCT.md) in all interactions both on and offline.\n\n### Contact us\n\nIf you want to report a problem or suggest an enhancement we'd love for you to [open an issue](../../issues) at this github repository because then we can get right on it. But you can also contact [AJ][link_aj_keller] by email (pushtheworldllc AT gmail DOT com) or on [twitter](https://twitter.com/aj-ptw).\n\n### Find out more\n\nYou might be interested in:\n\n* Purchase a [Cyton][link_shop_cyton] | [Ganglion][link_shop_ganglion] | [WiFi Shield][link_shop_wifi_shield] from [OpenBCI][link_openbci]\n* Get taught how to use OpenBCI devices by [Push The World][link_ptw] BCI Consulting\n\nAnd of course, you'll want to know our:\n\n* [Contributors' guidelines](CONTRIBUTING.md)\n* [Roadmap](ROADMAP.md)\n\n### Glossary\n\nOpenBCI boards are commonly referred to as _biosensors_. A biosensor converts biological data into digital data. \n\nThe [Ganglion][link_shop_ganglion] has 4 channels, meaning the Ganglion can take four simultaneous voltage readings.\n \nThe [Cyton][link_shop_cyton] has 8 channels and [Cyton with Daisy][link_shop_cyton_daisy] has 16 channels. \n\nGenerally speaking, the Cyton records at a high quality with less noise. Noise is anything that is not signal.\n\n### Thank you\n\nThank you so much (Danke sch\u00c3\u00b6n! Merci beaucoup!) for visiting the project and we do hope that you'll join us on this amazing journey to make programming with OpenBCI fun and easy.\n\n### License:\n\nMIT\n\n[link_shop_wifi_shield]: https://shop.openbci.com/collections/frontpage/products/wifi-shield?variant=44534009550\n[link_shop_ganglion]: https://shop.openbci.com/collections/frontpage/products/pre-order-ganglion-board\n[link_shop_cyton]: https://shop.openbci.com/collections/frontpage/products/cyton-biosensing-board-8-channel\n[link_shop_cyton_daisy]: https://shop.openbci.com/collections/frontpage/products/cyton-daisy-biosensing-boards-16-channel\n[link_nodejs_cyton]: https://github.com/openbci/openbci_nodejs_cyton\n[link_nodejs_ganglion]: https://github.com/openbci/openbci_nodejs_ganglion\n[link_nodejs_wifi]: https://github.com/openbci/openbci_nodejs_wifi\n[link_javascript_utilities]: https://github.com/OpenBCI/OpenBCI_JavaScript_Utilities\n[link_openbci]: http://www.openbci.com", "description_content_type": "text/markdown", "docs_url": null, "download_url": "https://github.com/andreaortuno/pyOpenBCI/archive/0.13.tar.gz", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/andreaortuno/pyOpenBCI", "keywords": "device,control,eeg,emg,ekg,ads1299,openbci,ganglion,cyton,wifi", "license": "MIT", "maintainer": "", "maintainer_email": "", "name": "pyOpenBCI", "package_url": "https://pypi.org/project/pyOpenBCI/", "platform": "", "project_url": "https://pypi.org/project/pyOpenBCI/", "project_urls": { "Download": "https://github.com/andreaortuno/pyOpenBCI/archive/0.13.tar.gz", "Homepage": "https://github.com/andreaortuno/pyOpenBCI" }, "release_url": "https://pypi.org/project/pyOpenBCI/0.13/", "requires_dist": null, "requires_python": "", "summary": "A lib for controlling OpenBCI devices", "version": "0.13" }, "last_serial": 5324266, "releases": { "0.12": [ { "comment_text": "", "digests": { "md5": "03d0e225cc69882fb8e61681a7c2e9af", "sha256": "c8b4553fef76998ce767ca9232c710557e62b96afbca29209ded3cba0c45b4cd" }, "downloads": -1, "filename": "pyOpenBCI-0.12.tar.gz", "has_sig": false, "md5_digest": "03d0e225cc69882fb8e61681a7c2e9af", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 25676, "upload_time": "2019-05-20T23:00:52", "url": "https://files.pythonhosted.org/packages/b0/19/15c52f0f3d4298d3cb1f432c398724ce35a089bef34f02b78d7bb8839148/pyOpenBCI-0.12.tar.gz" } ], "0.13": [ { "comment_text": "", "digests": { "md5": "dc89bb6ccaab4f85770b5a1548a08f46", "sha256": "c5b8a06aa6e38aa3191e2d28c8939f26c1839c3ed179004e786cf05e23070da5" }, "downloads": -1, "filename": "pyOpenBCI-0.13.tar.gz", "has_sig": false, "md5_digest": "dc89bb6ccaab4f85770b5a1548a08f46", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 25637, "upload_time": "2019-05-27T23:21:33", "url": "https://files.pythonhosted.org/packages/be/bf/0def649047687c6443fdee295256abe13dd3704cb693789c643cbe3210fc/pyOpenBCI-0.13.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "dc89bb6ccaab4f85770b5a1548a08f46", "sha256": "c5b8a06aa6e38aa3191e2d28c8939f26c1839c3ed179004e786cf05e23070da5" }, "downloads": -1, "filename": "pyOpenBCI-0.13.tar.gz", "has_sig": false, "md5_digest": "dc89bb6ccaab4f85770b5a1548a08f46", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 25637, "upload_time": "2019-05-27T23:21:33", "url": "https://files.pythonhosted.org/packages/be/bf/0def649047687c6443fdee295256abe13dd3704cb693789c643cbe3210fc/pyOpenBCI-0.13.tar.gz" } ] }