Ganglion Programming Tutorial
Please note, you do NOT need to program the Ganglion in order to use it. All OpenBCI boards ship ready to use out of the box. This guide is for users who want to upload their own firmware to the Ganglion or modify existing firmware.
This guide will walk you through how to update your Ganglion firmware. Downloading the latest binary and Over The Air programming (OTA) makes updating the Ganglion a breeze with a mobile device. If you want to compile the code in Arduino continue to the Building From Source portion of the guide.
To program the Ganglion over the air, keep reading. To program using hardware, scroll all the way down to the last section.
Download The Latest Firmware Build
You can read the release notes and more at the on Github or jump down to setup your mobile device for OTA programming to continue
Building From source
The Simblee (website discontinued) radio module that is at the heart of the Ganglion board offers the ability to reprogram Over The Air OTA
. The method for doing this in a nutshell is:
- Create new Ganglion firmware, or modify existing code in Arduino IDE
- Generate a compiled HEX file in the Arduino IDE
- Compress it into a ZIP with some other important files
- Transfer the ZIP file to your phone or tablet
- Connect your phone or tablet to the Ganglion
- Upload new code Over The Air
The following tutorials will get your computer and the Arduino IDE set up to create the correct ZIP file, and also show how to use your phone or tablet to upload new code to the Ganglion. This guide will also teach you how to upload code to your ganglion for the first time.
IMPORTANT: Ganglions shipped prior to February 27, 2017 will NOT program Over The Air for the first time! If you purchased your Ganglion prior to 2/27/17, Please follow the instructions below up till How to create an OTA File and read the instructions the bottom of this page to program your Ganglion for the first time.
What You Need
- Arduino IDE v1.8.0 Or Newer
- Simblee Board Files
- Ganglion Library Firmware
- Wifi Master Library Firmware
- Compiler Tools (for OTA)
If you don't already have the Arduino IDE software on your computer, go here to download the latest version for macOS.
Here is a temporary link to the Simblee board files.
Deprecated: Then, follow the instructions in the Simblee Quick Start Guide(website deprecated) to install the Simblee board files in Arduino for macOS.
Modify The Simblee Board Files
In order to program the Simblee to communicate and control the Ganglion, we need to make a quick change to the variants.h
file in the Simblee folder that you just loaded into Arduino. Naviage to the folder /Applications/Arduino.app/Contents/Java/portable/packages
/Simblee/hardware/Simblee/1.1.0/variants/Simblee
,
and you will find the file called variant.h
. Open this file up in the editor of your choice, and change the pin defines as shown.
NOTE To access the application contents, right click on the application [or control
+ left click] and select Show Package Contents
.
define | DEFAULT | Change To |
---|---|---|
PIN_SPI_SS | 6u | 26u |
PIN_SPI_MOSI | 5u | 18u |
PIN_SPI_MISO | 3u | 15u |
PIN_SPI_SCK | 4u | 16u |
Make sure to save and close the file.
IMPORTANT NOTE: If you don't do this, your Ganglion will not work after you reprogram it!
Install Firmware From Arduino Library Manager (easiest!)
Don't know what the Library Manager is? Skim over the Official Arduino Guide.
Open the Library Manager and search for OpenBCI and install the latest version for OpenBCI_Ganglion_Library
and OpenBCI_Wifi_Master
.
Manual Installation of Ganglion Firmware
Download the latest OpenBCI_Ganglion_Library, it's the top most zip file.
Unzip the folder and change the name to
OpenBCI_Ganglion_Library
Move
OpenBCI_Ganglion_Library
to:On Mac:
/Documents/Arduino/libraries
On Windows:C:\Users\username\Documents\Arduino\libraries
If you don't have a libraries
folder there, go ahead and make one.
If you're have trouble or want to learn more checkout the Official Arduino Guide for manual installation.
Manual Installation of WiFi Master Firmware
Download the latest WiFi Master Library, it's the top most zip file.
Unzip the folder and change the name to
OpenBCI_Wifi_Master
Move
OpenBCI_Wifi_Master
to:On Mac:
/Documents/Arduino/libraries
On Windows:C:\Users\username\Documents\Arduino\libraries
If you're have trouble or want to learn more checkout the Official Arduino Guide for manual installation.
Clone The Repos From Github
Developers looking to contribute or write custom firmware can clone the firmware repositories directly to your libraries
folder
On Mac: `/Documents/Arduino/libraries`
On Windows: `C:\Users\username\Documents\Arduino\libraries`
Select 'Simblee' as Board
If you followed the process in the previous link, and you will be able to select the Simblee board from the Tools >> Board >> dropdown menu!
Select DefaultGanglion.ino from Examples
- In the Arduino IDE go to
File-->Examples-->OpenBCI_Ganglion_Library-->DefaultGanglion
which will launch the Ganglion firmware. NOTE You must upload ONLY theDefaultGanglion
Sketch! If you can't seeOpenBCI_Ganglion_Library
then verifySimblee
is selected as board type.
How to Create OTA File
In order to create a zip file with the appropriate components to do OTA, we need to further modify the Simblee board files in your Arduino/Contents/Java/portable
folder. Navigate to the folder
/Arduino.app/Contents/Java/portable/packages
/Simblee/hardware/Simblee/1.1.0
Then change the name of the file platform.txt
to platform_NORMAL.txt
.
We're doing this in case you ever want to revert to the original.
Next, download the necessary files here. They are:
- mkdfuzip
- nrfutil_macosx
- platform.txt
Move the files called mkdfuzip
, nrfutil_macosx
, and platform.txt
into your Simblee/1.1.0
folder. Restart or launch Arduino.

Now you're ready to create custom Ganglion firmware that is packaged correctly for OTA programming! This walk through will use example code as an example.
IMPORTANT NOTE: Whenever you want to create or modify Ganglion firmware, You must xAlways put the line
#include <OpenBCI_Ganglion_Library.h>
at the top of your code!
To create the OTA files, simply select Export compiled Binary
from the Sketch
menu. The Arduino IDE will take a few moments, and the tools you just installed will create the .zip
file you need for OTA right in the sketch folder right beside your sketch! Cool! Go ahead and change the name of the file to remove the .ino.Simblee
and you are good to go.
Setting Up for OTA Programming On A Windows
Coming Sooooon!
Setup Mobile Device For OTA Programming
The Simblee is designed around a Nordic Semiconductor nRF51822, and so we need to use the Nordic nRF apps to do the actual Over-The-Air stuff. Here's what you will need for this tutorial:
iPhone Setup: What You Need
- iPhone
- nRF Toolbox App
- Lightblue Explorer App
Install apps
Install the nRF Toolbox and Lightblue Explorer apps onto you device.
Verify Ganglion Version
Turn on your Ganglion, and turn on your phone's bluetooth Then open the Lightblue app. The app will open and show you what Bluetooth Peripherals are nearby. The Ganglion will be listed as Simblee
. Tap that peripheral, and Lightblue will connect to and interrogate it.
NOTE: the Ganglion may also show up as DfuTarg
In the Device Information, you will find the following:
- Manufacturer Name String
- Model Number String
- Hardware Revision String
- Firmware Revision String
- Software Revision String
You should see openbci.com
as the Manufacturer, Gagnlion
as the Model Number, and 1.1.1
as the Software Revision String. The Hardware and Firmware versions are generated by the Simblee itself.
IMPORTANT NOTE: If the Software Revision String is earlier than 1.1.1 you cannot do OTA until you follow the Hardware Upload Tutorial at the bottom of this page.
Android Setup: What You Need
- Android Device
- nRF Toolbox App
- nRF Connect App
Install apps
Install the nRF Toolbox and nRF Connect Apps onto you device.
Verify Ganglion Version
Turn on your Ganglion, and turn on your device's bluetooth then open the nRF Connect App. The app will open and show you what Bluetooth Peripherals are nearby. The Ganglion will be listed as Ganglion-XXXX
where XXXX
is the 4 character code specific to your Ganglion. Tap that peripheral, and nRF Connect will connect to and interrogate it.
Tap the Device Information
service, and it will open up to show you the following information.
NOTE: You may need to tap the screen to read this data.
- Manufacturer Name String
- Model Number String
- Hardware Revision String
- Firmware Revision String
- Software Revision String
You should see openbci.com
as the Manufacturer, Ganglion
as the Model Number, and 1.1.1
as the Software Revision String. The Hardware and Firmware versions are generated by the Simblee itself.
IMPORTANT NOTE: If the Software Revision String is earlier than 1.1.1 you cannot do OTA until you follow the Hardware Upload Tutorial at the bottom of this page.
Using Your Mobile Device To Do OTA Programming
Now we need to get the .zip
file from your Arduino Sketch folder to your iPhone. In this example, I'm going to use email. Email the .zip
file to yourself, and then open and download it on your iPhone. Tap the sharing options in the lower left corner and select the Import with nRF Toolbox
option. Since you have already installed nRF Toolbox, the DFU
tool will open with the downloaded file already selected.
If you ever want to re-upload a program that you already have on your phone, select the DFU
tool after launching the nRF Toolbox app. Tap the Select File
button, and on the next screen at the bottom you will see an option for User Files
. Select that, and then Inbox
on the next screen to choose from all of your nRF Imported files.
Setting up to Program Ganglion Using Hardware
Older Ganglions (pre-2017) could only be programmed using hardware first, then over the air. Newer Ganglions can be programmed OTA or using hardware.
What You Need
- FTDI Breakout or OpenBCI Cyton Dongle
- 0.1uF Capacitor
- Jumper Wires
- Arduino IDE v
For this tutorial, I will use the Adafruit FTDI Friend. You can use any FTDI breakout, as long as it uses only 3V for logic levels. If you go to Adafruit to purchase one, you can also pick up some jumper wires, and 0.1uF Capacitors as well.
IMPORTANT NOTE: THE GANGLION IS A 3V DEVICE! YOU MUST NEVER CONNECT ANY HIGHER VOLTAGE SOURCE TO ANY OF THE PINS!
The 0.1uF capacitor needs to be in between the RESET
pin of the Ganglion and the RTS
pin of the FTDI breakout.
Set Up Arduino to Program Your Ganglion
Follow the guide at the top of this page called Build From Source all the way down till How To Create an OTA File, then come back here.
'Simblee' selected and 'DefaultGanglion' open
Select Simblee from menu bar Tools > Board
and open the DefaultGanglion
example from File > Examples > OpenBCI_Ganglion_Library > DefaultGanglion
.
Plug in Dongle or FTDI Friend and Select Serial Port
Now is a good time to plug your Dongle in and power up the Ganglion.
Select the correct serial port from the
Tools > Port
menu for your OpenBCI Dongle or FTDI friend.On Macs, this will be named /dev/tty.usbserial-DN00nnnn where the nnnn is a combination of numbers and letters specific to your OpenBCI Dongle.
On Windows, the serial port will be listed as a numbered COM port.
On Linux, it will be different.
Verify Wire Connections and Press Upload
With your wires all connected correctly, you should be able to click the Upload
button and successfully re-program the Ganglion. Now you're ready to do OTA Programming!