Using a custom ESP32 / Ganglion board with serial connection to OpenBCI GUI

Paul_KPaul_K Berlin
edited March 2019 in Other Platforms

Hi all, 

I am new to this forum, but have been reading for a while and working on a custom EEG Board, basically based on the Ganglion Board but without the simblee chip and an ESP32 instead.

I also ported the Firmware of the Ganglion Board so it works on the ESP32, yet I do not want to use BLE for data transmission but a wired connection instead, since my use case requires a stable connection in noisy (wifi and cell phone packed) areas, like a trade fair.


For simplicity I prefer serial over USB (a USB Isolator will be used for security reasons of course).


Now my question is basically how, if at all, can a custom board be used with the OpenBCI GUI via serial connection?

The GUI only Shows a selection of two boards for Live Data: Ganglion and Cyton. How can I add a custom board?


Even though I basically use the same firmware from the Ganglion with the same commands (e.g. b to start the data stream, 1-4 to deactivate channels, z for impedance test etc.) obviously the Open BCI GUI would expect a Ganglion board to be connected via BLE or with the Wifi Shield.


Is there any easy way to extend OpenBCI GUI to accept also other, custom boards?

Or am I looking in the wrong place and actually I need to create my own version of the Open BCI Hub? 

But then again, how would I add a custom board to show up in the OpenBCI GUI?


Any help or link to further information on how to integrate/connect a custom board into the OpenBCI GUI would be highly appreciated.


Thanks a lot

Paul

Comments

  • wjcroftwjcroft Mount Shasta, CA
    Paul, hi.

    The Ganglion BLE radio protocol is highly optimized and compressed to conform to the bandwidth limitations of the BLE link. Your usb serial stream need have no such limitations, depending on how fast is the usb serial baud rate.

    The GUI / Hub code for Ganglion assumes a BLE protocol interface at many levels. So there is not a straightforward and modular way to insert another type of Ganglion interface.

    The situation is also more complicated because you would have to mod two packages: GUI and Hub, which have complex interlinkage.

    Here's an alternative possibility: have you considered colocating the (original) Ganglion as close as possible to the BLED112 dongle, via a usb extension cable. That way the radio signals are as strong as possible. They could even be placed inside a shielded box to provide more isolation from the environment.

    Alternately, if you go down the ESP32 route with serial interface, you may find it easier to model your code changes after the Cyton type of serial protocol, which is just a serial stream. In other words, develop a striped down version of the Cyton stream format, with only 4 channels and no Aux data. Split this code out and call it something like "ganglion-serial". 

    But in summary, the software changes involved in the GUI and Hub would be substantial and likely offset any savings you are hoping to achieve. If you count your development and engineering time at your hourly rate.

    ----

    One other option that is available with the ESP32 is that it also supports "classic Bluetooth", that is v2 and v3. In those formats, there is a protocol, SPP, Serial Port Protocol available. That is intended for serial streaming over a radio link. Granted this does not address your perceived 'interference' issue. But it is a more widely used form of serial data streaming using ESP32.

    Regards,

    William

  • Paul_KPaul_K Berlin
    Thanks a lot for your reply William,

    your answer implies that I chose this route in order to save a buck or two, that is not primarily the case.
    The Ganglion Board is a rather "closed" ecosystem with the default firmware. Even though the Simblee Chip would have no issues streaming data via the integrated serial port, it seems to be an option that is rather disliked in the development. 
    I am aware that it would be quite simple to modify the Ganglion Firmware to add streaming via the serial port, I basically have done that in my ESP32-"Ganglion"-Firmware.

    Considering that both, the Ganglion design and the GUI are open source, I was hoping that they where designed to be more loosely coupled instead of being bound together so tightly. And especially the GUI is not really modular when it comes to 3rd Party Board support. 
    It is a great GUI with useful features thus I would love to use it with the custom board, rather than any other 3rd party GUI (there are not that many others that run on Linux and Mac OSX anyway).

    I was just hoping there was a way to deal with this requirement, even if it might not be document very well.

    I will have a look at the Cyton firmware as suggested and see if I can easily mimic the Cytons behaviour over serial with the ESP32 to basically trick the GUI/Hub into accepting it as a regular Cyton board.

    I also checked the Hub source code, but the documentation is rather thin and I couldn't find any documentation of the interaction between GUI and HUB when it comes to device detection and data transfer modes.

    Probably the Cyton serial approach is the way to go then.

    Putting the BLE Dongle and the Ganglion Board into a shielded housing is a bit of a "hack" rather than a solid and production ready solution.
    At the end we still have the option to go this way, but I would like to evaluate other ways before throwing in the towel.
  • wjcroftwjcroft Mount Shasta, CA
    Paul, here is the Hub documentation in case you were looking just at the Hub source code,


    re: "I am aware that it would be quite simple to modify the Ganglion Firmware to add streaming via the serial port, I basically have done that in my ESP32-"Ganglion"-Firmware."

    I understand that it may be possible to mod the firmware to output a serial stream, with the same packets that are sent over the BLE link. However, have you also considered the difficulty at the Hub end, where the Hub is reading and manipulating the BLE stream with specific BLE API libraries. One of these written in node.js, for the case using the built-in BLE or CSR dongle. The other case using the BLED112 dongle, which speaks over a special serial port interface protocol. Again I think this code segment is in node.js, and assumes it is speaking BLE protocol.

    re: other possible interfaces.

    The OpenBCI_Python code can read a serial port in the case of Cyton dongle. And then output LabStreamingLayer stream format. This LSL format is read by a wide variety of BCI programs that can provide GUI like and DSP functionality. For example OpenViBE can read LSL streams, and runs on both Windows and Linux.


    What is your end application for the finished board?

    re: "The Ganglion Board is a rather "closed" ecosystem with the default firmware."

    Actually not that much, when you consider that many BCI / DSP apps can consume the LSL streams.


    Regards,

  • Paul_KPaul_K Berlin
    Thanks for pointing out the LSL format, I was not aware of that so far. Will investigate that further.

  • wjcroftwjcroft Mount Shasta, CA
    Is your end application a 'live' scenario such as BCI or neurofeedback? Or do you just want to record an EEG stream for later analysis? The OpenBCI_GUI does not actually 'do' that much other than providing a way to monitor the stream. There are a few 'widgets' available, but any BCI / neurofeedback application will require many more DSP and processing elements.
  • Paul_KPaul_K Berlin
    edited March 2019
    the application will be used to control a stepper motor driver, based on specific frequency bands (alpha and beta primarily), so it is a 'live' scenario.
    The GUI will not be used in the final application, but it will be tested for R&D phase and as a quick QA tool to compare our own softwares output with a somewhat standard-software, to check if we get the same results in regards to the band strengths and also the impedance checks
  • wjcroftwjcroft Mount Shasta, CA
    My suggestion for your custom board would be to use OpenViBE, it can be setup to give you the same type of displays as the GUI: FFT, time series, frequency bands, and also drive a separate Arduino (on a separate serial port) used to control your stepper motors.

    Alternately if you were to use an actual Ganglion with BLED112, the neurofeedback application BioEra could also be easily be adapted to your prototype situation.


    What you are describing is essentially a neurofeedback protocol. BioEra is used widely in this field.
  • Paul_KPaul_K Berlin
    Hi William,

    I had a look at the Cyton Firmware and at least ported the data package format. 
    Unfortunately the Open BCI GUI seems to do some further initialization procedure to connect to a Cyton board.

    Any chance there is a document of the initialization sequence of the cyton board when connected to Open BCI GUI via serial?
    I can revers engineer it of course, but it would be perfect if you could point me to a document that shows which serial commands need to be implemented on a cyton firmware at a bare minimum to convince OpenBCI GUI to start the data stream.


    I also checked out the Cyton Board product page to evaluate if we just go with the Cyton board for our first prototype, but it seems the serial connection to a cyton board is also only possible via a separate dongle, that communicates with the cyton board via some radio interface. Did I get this correct? So even when using a Cyton board we would still have some radio communication involved to stream data.

    Thanks a lot for all the information and the prompt feedback on all questions
  • wjcroftwjcroft Mount Shasta, CA
    Paul, take a look around our docs site. For some odd reason it seems to be down momentarily. Should be back later today.


    The 'SDK' docs describe the command sequences to the boards.
  • Paul_KPaul_K Berlin
    Hi William, 

    I checked the SDK Docs (using the web.archive.org :-) ) yet I could only find a full list of commands for the cyton board (including he extra commands added in later firmware versions). I was wondering which specific commands need to be implemented to connect a cyton-ish board to OpenBCI GUI in order to get some data out of it. I assume not all commands are really needed to get the serial stream going in the GUI.

    So far I noticed, that 0x07 is called by the GUI/HUB when selecting the serial port of our board.
    Obviously later on the "b" command will be send to start the stream, but it seems there are also other commands involved. I will implement them step by step but it is quite cumbersome to do this step by step.

    Maybe I have just overseen the command sequence that is issued in the initialization phase of the GUI in the SDK documentation. I will dig in some more.
  • wjcroftwjcroft Mount Shasta, CA
    re: "which specific commands need to be implemented to connect a cyton-ish board to OpenBCI GUI in order to get some data out of it."

    Sad to say, but the only way to determine this is by examining the Hub source code. Which is quite voluminous. 


    this appears to be the main javascript function:


    ----

    As I mentioned earlier, it might be simplest to utilize the OpenBCI_Python ability to read a simple stream from a Cyton like device, and output LSL. That LSL could then be consumed by OpenViBE which can provide nearly all the GUI functionality that you want. In addition to being the basis for your neurofeedback app. Which the OpenBCI_GUI would not help with.


    You'll find the Python code a lot easier to understand.

  • wjcroftwjcroft Mount Shasta, CA
    re: Hub javascript that speaks to Cyton

    The background.js file above in the Hub, invokes the Cyton functions in this repo, this function,


    Back in the old days, the GUI used to speak to the Cyton serial port directly. Then after Ganglion came along, the Hub idea was developed to split off some of that processing. Finally the Hub was also made to talk to Cyton.

    If you've looked at the OpenBCI_Python sections that speak to Cyton serial, you can see it is considerably easier to understand and modify.

  • wjcroftwjcroft Mount Shasta, CA
    Paul, you mentioned earlier that you might consider Cyton, if it allowed wired usb connection. This thread shows how to do that for the V2 Cyton firmware. V3 firmware adaptation should be relatively straightforward. As the firmware organization did not change that much with V3, mostly it was adding new features.

  • Paul_KPaul_K Berlin
    edited March 2019

    Thanks for the link William,


    I am still trying different approaches.


    Modifying the Ganglion firmware to return a "$$$" terminated String when the v command is called via serial, allowed me to select the device in the Open BCI GUI and start connecting to the board via serial.

    Starting the data stream works (b command) but unfortunately the ADC values from Cyton and Ganglion represent completely different values (the equations for both boards to convert the counts to milli volts are different due to the different hardware components). Thus even though I stream data in the cyton package format, it is not really creating a correct data stream to be visualized by the OpenBCI GUI.


    Btw. the equation for the Ganglion board on the page https://docs.openbci.com/Hardware/08-Ganglion_Data_Format is not explained in a very helpful way. It simply refers to a part in the MCP3912 datasheet, which I could not find anywhere in the datasheet. There is a "table 7" mentioned which does not exist in the datasheet (http://ww1.microchip.com/downloads/en/DeviceDoc/20005348A.pdf), but no such table exists (only "TABLE 7-1" which refers to sampling speed). Maybe this can be corrected and the equation be explained a bit further for the sake of completeness. It seems the sentence with the reference to the datasheet has simply been copied from the cyton board (https://docs.openbci.com/Hardware/03-Cyton_Data_Format)


    Also the equation just seems wrong somehow, since it consists solely of multiplications: 1.2 Volts * 8388607.0 * 1.5 * 51.0;  

    According to this formula the volts per count would be  770,074,122.6 (770 million volts per count!) for the ganglion board, while it is 0,000000022351744 for the cyton board (with a gain of 24), which seems like a more reasonable factor.


    While trying to follow the manual to create your own firmware for the Ganglion Board I noticed, that the Simblee Chip used on the Ganglion board is not manufactured anymore, which unfortunately also includes, that the manufacturer took down the site that is linked in the Simblee Quick Start Gudie that is linked in the Ganglion Board programming tutorial (https://docs.openbci.com/Hardware/09-Ganglion_Programming_Tutorial) 


    In the "What You Need" section. So it was not possible for me to download the actual Simblee Library that is needed to compile you own Ganglion firmware. If there is an alternative download link it would help users to list it in the manual and maybe also update the link to the Simblee Quick Start Guide.


    Just my two cents on my experience with working with the two boards (or their firmware) so far, maybe it helps other used too

Sign In or Register to comment.

© Vanilla Keystone Theme 2026