openbci / documentation

Documentation for OpenBCI!

WELCOME!

Welcome to OpenBCI's Github. This is the place where we will keep the software that we want to share with the community and where we will keep the software that the community shares with us.

Contents

• Arduino: Here are the Arduino libraries and sketches to help you run OpenBCI with an Arduino. Currently, all development has been with the Arduino UNO. We will expand to other Arduino platforms in the future.

• Processing GUI: Here are some Processing libraries and sketches to help you receive data from the Arduino/OpenBCI. You can use these sketches to watch the data in real time. Some of the sketches also log the data to disk so that you can analyze it after the test.

documentation's Issues

Update GUI Data image in MarkIV Doc

This image in the docs needs to be switched out (https://docs.openbci.com/AddOns/Headwear/MarkIV/). It’s not helpful. That data is bad. It’s 15hz noise, not ~11hz Alpha.

Add spectrogram to GUI widget guide w/ screenshot

I noticed this is missing, and it can be a helpful widget for testing.

Erroneous descriptions in Documentation?

I have found some confusing descriptions in the “Documentation” OpenBCI recently renewed.

1 Setting up for EEG

In the table describing how to connect the electrodes to the Gannglion board, there is a description I cannot understand.
There are no "SRB" and "Bias" pins on the Ganglion board.
Here is my idea !

2 Ganglion Specs

The documentations in the website tells us to connect the ground electrode to Both the top And bottom of the D_G pin. The similar explanations are given for the REF pin.
However in another web pages, they tell me i need to connect One electrode to the top D_G (REF) pin.

・Headband-Ganglion Tutorial

Does it mean i may connect to the top OR bottom of D_G (REF) pin?
I suppose it is enough to connect the ground(reference) electrodes to the top OR bottom pins.

I think i have been badly mistaken... ??
I would appreciate knowing more about it.

move several docs out of Deprecated

Three documents should be moved out of deprecated: the two docs on FTDI adjustment; and the doc on VirtualBox.

A number of VirtualBox users of BrainBay, BioEra, or OpenViBE, depend on VirtualBox to run Windows apps on their Mac or Linux system. I fully understand that OpenBCI users should NOT run the GUI via VirtualBox. This Windows apps workaround is only for official Windows only apps.

Regarding the FTDI docs. These should be titled something like: "FTDI buffering adjustment on Mac" and "FTDI buffering adjustment on Windows". Along with this change, it may be helpful to do a benchmark test on a totally new Mac or Windows install, to see if these docs still apply to the latest versions of those respective OSes. They certainly HAVE been necessary for past versions of the OSes, and thus should not be deprecated. One could add a disclaimer to the top of the docs, stating which OSes may no longer need the fixes.

Regards, William

Docusaurus v1 -> Docusaurus v2

Docusaurus v2 is now production ready with tools to help migrate. We are not using versioned or translated docs, so it should be a relatively easy process.

Notable Improvements:

• Dark theme!
• more customizable header

Update external trigger example

The Cyton External Trigger doc needs to be cleaned up to reflect what actually works and has been learned. It should also be updated to point to the OpenBCI Video Experiment doc (mentioned below).

https://docs.openbci.com/Cyton/CytonExternal/

Optoisolation and using a photodiode pressed against the screen are two functional methods.

We also have an experiment that uses a photodiode (involving visual stimuli of puppies and kittens). Maybe this doc could be changed slightly (title + mentioning it uses external trigger a little more) to further increase clarity. The purpose of this doc is to show one reliable use-case for an external trigger using a photodiode. This doc also highlights how to time-lock sync visual stimuli.

https://docs.openbci.com/Examples/VideoExperiment/

sampling rate

Hi,

I am starting to get to know your tool and I couldn't find in the docs the sampling rate in the case on dongle ...is it 250 Hz ?
(it seems it's written only here https://docs.openbci.com/Cyton/CytonSDCard/#overview )

• it could be better to add it also in the general page for Cython
• is there a way to change it ? in particular, to decrease it ?

thanks

Add info on new Focus Widget

OpenBCI/OpenBCI_GUI#924

• Update GUI Widget Guide to include new info on updated Focus widget which uses BrainFlow metrics.

• Also, update the Arduino instructrable https://www.instructables.com/Send-Focus-Data-From-OpenBCI-GUI-to-Arduino/

• Also, we should update the following official Doc: https://docs.openbci.com/docs/07Examples/19-EEGProjects/FocusArduino

Clarify EEG Setup HardwareSettings/Filters

From OpenBCI team member: "... EEG setup it is not super clear. I noticed that you never explicitly say what the hardware settings are for the setup and which filter the user should use. Is it because those are on by default? I understand that you specify the pins used and the screenshot shows the filter but I would suggest to have those clearly stated in writing to avoid confusion..."

Applies mainly to Cyton(hardware settings controller), but may include Ganglion.

Update Mac FTDI Buffer Fix doc in Troubleshooting

https://github.com/OpenBCI/Documentation/blob/master/website/docs/Troubleshooting/05-FTDI_Driver_Fix_Mac.md

Mention that it may not be possible at this time to apply the fix for Apple Silicon M1+.

Note that the FTDI “Latency Fix” tweak, is STILL not available for M1 (and eventually M2) Macs. This has already greatly frustrated an M1 customer. Who requires minimum Cyton latency for his application.

Applies to any Mac user of macOS 11.x. Both M1 and Intel.

FTDI Buffer Fix for Linux

I noticed my Cyton data was choppy on Linux. So, I tried to fix the FTDI latency fix and it worked!

/sys/bus/usb-serial/devices/ttyUSB0/latency_timer

16 -> 1

Clarify ChannelSelect feature in GUI 5.0.3

OpenBCI/OpenBCI_GUI#942 (comment)

Applies to a handful of widgets, including TimeSeries, Spectrogram, and BandPower.

This feature is completed, so it can now be documented!

Confirm FTDI fix on Mac and Windows

From #6 @wjcroft

Regarding the FTDI docs. These should be titled something like: "FTDI buffering adjustment on Mac" and "FTDI buffering adjustment on Windows". Along with this change, it may be helpful to do a benchmark test on a totally new Mac or Windows install, to see if these docs still apply to the latest versions of those respective OSes. They certainly HAVE been necessary for past versions of the OSes, and thus should not be deprecated. One could add a disclaimer to the top of the docs, stating which OSes may no longer need the fixes.

Add info on how to convert Large SD Recordings

Fixes this issue:
OpenBCI/OpenBCI_GUI#355

Doesn't seem possible at this point to set Java heap space for Processing using code in a .pde file. This requires users to launch the GUI from Processing only, processing-java and VSCode may not pick up on the changes to Processing preferences right away.

Restructure OpenBCI GUI Instructions

Copied from old Docs repo:

Revised Solution: Separate OpenBCI GUI doc into walkthrough and troubleshooting

Additional Requirement: Networking How-To and data output list

Document Marker Mode for Cyton Users

OpenBCI/OpenBCI_GUI#341

https://openbci.com/community/v3-0-0-cyton-firmware-now-available/

A new board mode called MARKER. In this mode, if a command in the format of “’`n’“ (where n is ASCII ‘0’:’9′) is received by the Cyton over any of the serial streams (including wifi) then a marker of int(n) is inserted in the AUX1 channel. Note that this mode is mutually exclusive to the DEFAULT (accelerometer mode) as it uses the AUX1/ACCELX channel.

Add Write to SD Card screenshot

I wonder if it could be useful for noobs to include a screenshot showing how to capture sd card data from the visualizer after the SD card formatting section of https://docs.openbci.com/docs/02Cyton/CytonSDCard

Right now it kind of dives super deep but doesn't actually describe how to initiate data recording.

Documentation Errors for Neuromore

Three Challenges with Documentation:

https://docs.openbci.com/docs/06Software/02-CompatibleThirdPartySoftware/Neuromore

1. Nothing specifies this information is unique to the Cyton Board (add simple note at top of documentation)
2. using the command: ls /dev/tty.* as instructed, Ganglion board is never detected as in example given

https://docs.openbci.com/docs/10Troubleshooting/FTDI_Fix_Mac
3) The FTDI Driver 2.4.2 that is recommended no longer exists on the FTDI page (Mac 10.14 - now has Driver 2.4.4)

Update information on Impedance testing

The following section in the GUI doc is now out of date. Update with information about the Cyton Signal Widget.

https://docs.openbci.com/Software/OpenBCISoftware/GUIDocs/#impedance-testing

Update GUI Troubleshooting and Minimizing Noise Docs

Can we combine feedback with the common causes of noisy data below and add the cumulative list of suggestions to relevant troubleshooting sections in the Docs:

battery low
dongle too close to computer
bluetooth noise in the room
incorrect electrode connections

Customer feedback:

1. Reduced the distance between the Dongle and the Headset, that is, "the Dongle is fixed on the Headset with a USB extension cable."
2. Reduced the load for Windows, that is, "without any operations with OpenBCI_GUI and no other running applications in Windows."
3. I did 60 minutes of continuous measurement, that is, "I made Zen meditation while I sat on a zazen cushion very calmly."
   This is to eliminate metal objects that interfere with radio waves around my surrounding area.

Add Info for Connection Issues [Packet Loss] to GUI troubleshooting

@wjcroft ""Users should at least be advised that packet loss can occur in noisy environments and how to check for it / monitor / fix (e.g. by channel change, etc.) Especially in university lab environments with multiple Cytons running.""

Update GUI -> LSL -> OpenVibe Example

Needs to be revised!

One of the pictures shows the driver as "OpenBCI" when it should say "LSL". This could confuse users with the OpenVibe Cyton driver, which connects directly to the Cyton without the GUI.

^^Clarify the above to fix this issue

Cyton Daisy Y Splitter Image is Incorrect

the photo showing the Y-splitter with Daisy is wrong. The bottom pins are the ones to be bridged, as stated in the text.

https://openbci.com/forum/index.php?p=/discussion/comment/15048#Comment_15048

Update LSL doc to exclude old libraries and repos

https://docs.openbci.com/docs/06Software/02-CompatibleThirdPartySoftware/LSL

Contains old repos that should not be used.

Update GUI TImeSeries Screenshot in GUI Widget Guide

Replace with a new screenshot of actual data instead of touching pins.

https://docs.openbci.com/Software/OpenBCISoftware/GUIWidgets/#time-series

Edit text to remove mention of touching the Cyton pins.

The above screenshot was taken while touching the Cyton pins directly.

Make Doc Explaining how to make simple and complex changes to the Docs

Talk about he "Edit this page" button.

Copy information from the Wiki about developer setup.

Add a link to the landing page.

Add EEG+EMG setup instructions for Cyton

In old docs, the Cyton getting started guide used to include an EEG + EMG example setup. Part of the trick here is to change the hardware settings controller.

https://github.com/openbci-archive/Docs/blob/master/Tutorials/01-Cyton_Getting%20Started_Guide.md#3-connect-your-electrodes-to-your-head-and-body

GUI: Document "Streaming Board" Data Mode

https://openbci.com/forum/index.php?p=/discussion/2708/openbci-gui-5-0-serial-port#latest

This allows users to stream an OpenBCI board from an external process, e.g. from Python script.

Combined EEG, EMG, EKG, EOG guide for the Cyton

Add a guide with screenshots that show the different types of data being streamed at the same time.

Fix ECG Doc Electrode Placement

Mentioned here on the forum:

https://openbci.com/forum/index.php?p=/discussion/2709/correct-cyton-cables-setup-for-5-lead-ecg#latest

Add 3 lead ECG tutorial from this research paper

The supplementary materials of this paper looks like it would be an excellent ECG tutorial to put in the docs
https://www.sciencedirect.com/science/article/pii/S2405844021012512

See Appendix A:
https://www.sciencedirect.com/science/article/pii/S2405844021012512#appsec1

Wifi Shield Programming Tutorial, needs to specify ESP library 2.5.0

See this forum thread,

https://openbci.com/forum/index.php?p=/discussion/2327/defaultwifishield-bin-works-but-defaultwifishield-ino-doesnt#latest

If this library is not used, the binary produced does not match the .bin we provide. And most importantly, the Shield fails to function correctly.

The instructions to use convert and playback data files could potentially be improved

Reading https://docs.openbci.com/docs/02Cyton/CytonSDCard you have to guess a bit to figure out what to do. Some screenshots/detailed steps and clarity about where the converted data ends up on different operating systems might help. It might also help if the original SD file name was included in the playback file name to more immediately understand which files correspond.

Re-make Ganglion ECG Tutorial

https://docs.openbci.com/GettingStarted/Biosensing-Setups/ECGSetup/#3-lead-ecg-with-cyton-or-ganglion-boards

This part of the tutorial was not able to be replicated with success. It contains an incorrect picture of a Cyton and other extraneous information. This entire section should be redone.

Mark IV Document Cleanup

https://docs.openbci.com/docs/04AddOns/01-Headwear/MarkIV#completed-8-channel-mark-iv-setup

This doc has missing images, and the following section needs an actual chart, not bulleted points.

For the remainder of this tutorial, the blue nodes on the 10-20 system diagram (channels 1-8 of the OpenBCI default settings) will be used. The channel to 10-20 system correlations are as follows:
Channel 1(N1P) - Fp1
Channel 2(N2P) - Fp2
Channel 3(N3P) - C3
Channel 4(N4P) - C4
Channel 5(N5P) - P7
Channel 6(N6P) - P8
Channel 7(N7P) - O1
Channel 8(N8P) - O2

Additional clarifications and cleanup as needed.

Update MATLAB doc to include reference to BrainFlow+Matlab Live Data

Original Post from User:
https://openbci.com/forum/index.php?p=/discussion/2893/fastest-way-to-import-live-open-bci-data-to-matlab-20a#latest

We should update the Doc found here: https://docs.openbci.com/docs/06Software/02-CompatibleThirdPartySoftware/Matlab#method-2-stream-openbci-data-via-lsl

• remove the mention of "OpenBCI Python"
• Add a method pointing to the Matlab-BrainFlow example

Deprecate WiFi Shield Documentation

The WiFi shield documentation and references to using the WiFi shield in other Docs pages should be deprecated.

Also, the core docs are extensive and possibly confusing.

Making this change now in Q4 2021 will improve the overall clarity and ease-of-use for the Docs.

This is a larger project that will require searching/reading references in other docs.

Things to look for:

• Pictures in other docs that mention the WiFi shield
• Moving core WiFi shield docs to deprecated
• Whole sections of other docs that differentiate instructions solely for coupling with the WiFi shield
• References to being able to use higher sampling rates for Ganglion and Cyton

Add info to OpenVibe Doc for Ganglion via LSL

Copied from old Docs repo:

Similar to openbci-archive/Docs#148. Fixing this issue will resolve both!

See short how-to at the bottom of OpenBCI/OpenBCI_GUI#463

OpenBCI/OpenBCI_GUI#463 (comment)

The above How-To should be working for Windows and Linux, just needs to be added to the Docs!

Add Documentation for GUI CSV Output and Header

https://openbci.com/forum/index.php?p=/discussion/2735/understanding-the-csv-headers-of-the-new-v5-gui#latest

This is an easy fix. Should be done ASAP.

Add Documentation for Cyton Signal Check Widget (GUI 5.0.9 October 2021)

High Priority Task

A new Cyton Signal Check Widget has been made and the Ohm icons have been removed from the TimeSeries Widget.

We need new documentation for this widget in the GUI widget guide and probably the Cyton Getting Started Guide.

It should be clear to new users how to check signal quality using Railed Percentage and injected current at 31.5Hz on one channel at a time.

Update OpenBCI GUI main doc for v4.1.7

The control panel and other things have change, so this doc probably needs to get updated.

"...adjust your channel settings" section missing in new docs

The old Cyton Getting Started guide, had a section on how to adjust the settings panel in the GUI. I cannot seem to find this anywhere in the new docs. Here is the old docs link:

https://github.com/OpenBCI/Docs/blob/master/Tutorials/01-Cyton_Getting%20Started_Guide.md#4-launch-the-gui-and-adjust-your-channel-settings

In the case mentioned above, the user is seeing EEG noise when doing simultaneous EEG, EMG, ECG. The solution being to remove the stronger signals from the common reference bus, and change the scale factor, etc.

Admittedly not a common case. But some EMG, ECG users do have need for customization of these settings.

They ARE mentioned in the SDK doc. But that is geared to programmers, not GUI users.

sudo access for changing FTDI and timestamp problem

Hi,

I am using brainflow to stream data from OpenBCI. My problem is when I flush data from buffer, every two or three records which poped from the buffer are the same timestamp. I contacted with brainflow guys and they suggested me to change FTDI buffer settings and changing it from 16 to 1. With this change, timestamps are correct. But the problem is in Linux for changing FTDI buffer I need sudo access. It means I cannot run the code in systems that I don't have sudo access. Also, each time I connect dongle to USB port, I should again set the FTDI buffer. Do you have any solution for this?

Add labeled pictures for how to connect earclip electrodes for EEG using Cyton or Cyton+Daisy

https://openbci.com/forum/index.php?p=/discussion/2546/cyton-ultracortex-railed-issue#latest

Add information on GUI Gain convention change w/ GUI 5.0.2

First Draft of what to communicate:

Starting with GUI v5.0.2, all ADS1299 boards (Cyton, Cyton+Daisy) will use a dynamic scaler to ensure that the Gain in the Hardware Settings view is what is being displayed and saved to file. For Cyton and Cyton+Daisy, the default scale is x24 for all channels.

Add Tutorial info for EMG using Ganglion

Suggested in forum:
https://openbci.com/forum/index.php?p=/discussion/2311/measuring-emg-using-a-ganglion-board#latest

Bad link to OpenBCI forums

openbci-archive/Docs#236

Electrode cap user, confused that no channel assignments are recommended (for GUI use)

'Alexey' on NeuroTechX wrote this regarding his confusion over the electrode cap doc:

...However I have a lot of questions that the tutorials don’t seem to cover. Including the order of the electrodes and verification that I am connecting the electrodes in the right location. That information seems to be missing all together.

I wrote him a PM in response:

---

This is the default head map used in the GUI for the 16 channel Cyton:

https://openbci.com/forum/index.php?p=/discussion/1087/connecting-mark-iv-to-cyton-including-daisy-board/p1

I’m surprised this was not mentioned in the cap tutorial. It is also shown in the Ultracortex tutorial.

https://docs.openbci.com/docs/04AddOns/01-Headwear/MarkIV#electrode-location-overview

In your own case, you can assign any scalp location to any channel.

---

So some links similar to this should be inserted in the electrode cap tutorial doc.

Regards, William

Streaming Analog Read Data through Networking Widget using 'Accel/Aux' Clarification

It's not clear that the 'Accel/Aux' option in the Networking Widget is the one that needs to be used to stream Analog Read data using LSL. It would be great to make a note explaining it.

Clearly state how data is saved from the GUI using CSV and BDF

Fixes OpenBCI/OpenBCI_GUI#921

It would be great for this to be a whole section of the main GUI doc. Currently, this information is "hidden" in a small paragraph that is hard to find.