This page describes the format for custom extensions to the standard Firmata sketch that the Circuit Playground Firmata sketch implements.  These extensions allow Firmata clients to interact with the devices on the board more easily, like to read accelerometer data or light up the NeoPixels.

If you're developing a library or code to talk to the Circuit Playground Firmata sketch this page will be very useful to review.  However if you're just planning to use Circuit Playground Firmata with Python or other existing Firmata clients then you don't need to worry about the information here--you're all set to start exploring Firmata and Circuit Playground!

Also it is highly recommended that you skim through and familiarize yourself with the Firmata protocol before diving too deeply into these custom extensions.

Circuit Playground Firmata SysEx Commands

To support controlling the components of Circuit Playground with Firmata a set of custom Firmata/MIDI SysEx commands are implemented.  These commands follow the SysEx message format in the Firmata protocol and use a variable number of arguments depending on the command.  None of the standard Firmata commands have been modified with Circuit Playground Firmata, only new SysEx commands were added.

For all Circuit Playground SysEx commands they start with a unique byte value that identifies the command as specific to Circuit Playground.  The value of this Circuit Playground SysEx command byte is 0x40.  SysEx messages that start with this byte will be interpreted as Circuit Playground commands.

Following the Circuit Playground SysEx identifier is sub-command byte (or in some cases two bytes) that identifies the type of Circuit Playground command.  Each Circuit Playground command has a unique sub-command value that's described below.

All bytes that follow the sub-command byte are parameters to the Circuit Playground command.  See the description of a command below to see the exact number and format of parameters to expect with the command.  Remember a byte in the Firmata protocol is only 7-bytes long--the high order bit is always 0 to indicate the byte being data instead of a command.  In order to send an 8-bit or larger value it must be broken down into multiple 7-bit bytes and reassembled.  Carefully read the description of commands to understand how and when they break large values into smaller 7-bit bytes.

Below is a description of each custom Circuit Playground SysEx command:

NeoPixel Commands

Set NeoPixel Color

Sub-command byte: 0x10

Parameters: 5 bytes total

• NeoPixel ID (1 byte): This is the number of the NeoPixel on the board (0-9) to change.
• Color (4 bytes): These 4 bytes pack in 24 bits of color data for the NeoPixel in red, green, blue component order.  Each component is a full 8-bit byte with a value from 0-255 (lowest intensity to highest intensity).  For example the bits of the color parameters look like: 0RRRRRRR 0RGGGGGG 0GGBBBBB 0BBB0000  Notice the first bit of each byte is 0 (Firmata protocol requirement) and color component bits are tightly packed into the bits that follow.

Description: This command will change the color of the specified NeoPixel.  Note that the pixel won't actually change, instead just the color in the pixel data buffer will be updated.  You must call the pixel show command to push the pixel data buffer to all the pixels and update them.

Example: To change the color of pixel 2 to red = 255, green = 127, blue = 63 the following SysEx command bytes are sent:

0x40 0x10 0x02 0x7F 0x5F 0x67 0x70

Show NeoPixels

Sub-command byte: 0x11

Parameters: None

Description: This command pushes the current NeoPixel color buffer out to the physical pixels.  After calling this command the pixels will update their colors.

Example: To call the show NeoPixels command send the following SysEx command bytes:

0x40 0x11

Clear All NeoPixels

Sub-command byte: 0x12

Parameters: None

Description: This command will clear all NeoPixels in the pixel data buffer to 0/off.  You must call the show NeoPixels command to update the pixels after calling this command!

Example: To call the clear all NeoPixels command send the following SysEx command bytes:

0x40 0x12

Set NeoPixel Brightness

Sub-command byte: 0x13

Parameters: 1 byte

• Brightness (1 byte): This is the brightness value to set for the NeoPixels (see the NeoPixel library setBrightness function for more information).  The value should be a byte from 0 to 100 inclusive.

Description: This command will adjust the brightness of all the NeoPixels.  The value should be 0 to 100 where 0 is completely dark and 100 is full brightness.  Note that animating brightness is not recommended as going down to 0 will 'lose' information and not bable to go back up to 100.  Instead just use this function to set the brightness once at the start.  Note that by default the pixels are set to 20% brightness.

Example: To change the brightness to 50% send the following SysEx command bytes:

0x40 0x13 0x32

Speaker/Buzzer Commands

Play Tone

Sub-command byte: 0x20

Parameters: 4 bytes total

• Frequency (2 bytes): These two 7-bit bytes define an unsigned 14-bit frequency for the tone in hertz (0-16,383).  The byte order is little endian with the first byte defining the lower 7 bits and the second byte defining the upper 7 bits.
• Duration (2 bytes): This is the duration to play the tone in milliseconds.  Like frequency this is an unsigned 14-bit value in little endian byte order.  Note that a value of 0 (zero) will start playback of a tone with no duration--the stop tone function must be called to stop playback.

Description: This command will play a tone of the specified frequency on the speaker/buzzer.  The tone is generated using a square wave so it will have a slightly harsh sound but is great for simple sounds and music.  You can specify the duration the tone should be played, or you can specify to start playing the tone forever until a stop tone command is sent.

Example: To play a 440 hz tone for 2 seconds (2000 milliseconds) send the following SysEx command bytes:

0x40 0x20 0x38 0x03 0x50 0x0F

To start playback of a 338 hz tone send (no duration, i.e. play forever) the following SysEx command bytes:

0x40 0x20 0x52 0x02 0x00 0x00

Stop Tone

Sub-command byte: 0x21

Parameters: None

Description: This command will stop the playback of any tone on the speaker/buzzer.

Example: To stop tone playback send the following SysEx command bytes:

0x40 0x21

Accelerometer Commands

Single Accelerometer Reading

Sub-command byte: 0x30

Parameters: None

Description: This command will request a single accelerometer reading.  The result of this command will be an accelerometer read response command sent back from the Circuit Playground board to the host computer.  See the description of the accelerometer read response below for what data to expect.

Example: To request a single accelerometer reading send the following SysEx bytes:

0x40 0x30

Accelerometer Read Response

Sub-command byte: 0x36 0x00 (Note this sub-command has two bytes instead of one byte as a side-effect of using internal Firmata sketch SysEx functions)

Parameters: 24 bytes total

• X Axis Acceleration (8 bytes): These bytes define a 32-bit floating point value in little endian byte order (least significant bytes first).  Each pair of 7-bit bytes defines an 8-bit byte in the float so 8 bytes total will give 4 bytes of floating point data (32 bits total).  For these pairs of 7-bit bytes they are in little endian order with the 7 lowest bits first and the 8th/high order bit in the second position.  This parameter is the X axis acceleration in meters per second squared.
• Y Axis Acceleration (8 bytes): These bytes define a 32-bit floating point value in little endian byte order (least significant bytes first).  Each pair of 7-bit bytes defines an 8-bit byte in the float so 8 bytes total will give 4 bytes of floating point data (32 bits total).  For these pairs of 7-bit bytes they are in little endian order with the 7 lowest bits first and the 8th/high order bit in the second position.  This parameter is the Y axis acceleration in meters per second squared.
• Z Axis Acceleration (8 bytes): These bytes define a 32-bit floating point value in little endian byte order (least significant bytes first).  Each pair of 7-bit bytes defines an 8-bit byte in the float so 8 bytes total will give 4 bytes of floating point data (32 bits total).  For these pairs of 7-bit bytes they are in little endian order with the 7 lowest bits first and the 8th/high order bit in the second position.  This parameter is the Z axis acceleration in meters per second squared.

Description: This command is sent back from the Circuit Playground board to the host computer when an accelerometer reading is available.  The current X, Y, Z acceleration is returned in meters per second squared units.

Example: An accelerometer reading of X = 9.8, Y = -1.0, Z = 0.0 will have the following SysEx command bytes:

0x40 0x36 0x00 0x41 0x00 0x1C 0x00 0x4C 0x01 0x4D 0x01 0x3F 0x01 0x00 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00

Enable Accelerometer Streaming

Sub-command byte: 0x3A

Parameters: None

Description: This command will turn on continuous streaming of accelerometer readings from Circuit Playground to the host computer.  Reading will be taken every 20 milliseconds and sent to the host using the accelerometer read response command above.  This is useful for quickly reading the accelerometer without all the overhead of constantly sending single accelerometer read requests.  To disable the streaming see the disable accelerometer streaming function below.

Example: To enable steaming of accelerometer data send the following SysEx bytes:

0x40 0x3A

Disable Accelerometer Streaming

Sub-command byte: 0x3B

Parameters: None

Description: This command will turn off continuous streaming of accelerometer readings from Circuit Playground to the host computer.

Example: To disable steaming of accelerometer data send the following SysEx bytes:

0x40 0x3B

Set Accelerometer Range

Sub-command byte: 0x3C

Parameters: 1 byte

• Range (1 byte): This value defines the range of the accelerometer and should be one of the following values:
• 0 = +/- 2G
• 1 = +/- 4G
• 2 = +/- 8G
• 3 = +/- 16G

Description: This command will change the range of the accelerometer.  Increasing the range will allow you to read higher forces, but will reduce the accuracy of the readings.  The default range is +/- 2G.

Example: To set the range of the accelerometer to +/- 16G send the following SysEx bytes:

0x40 0x3C 0x03

Tap Detection Commands

Single Tap Detection Reading

Sub-command byte: 0x31

Parameters: None

Description: This command will request a single tap detection reading.  The result of this command will be a tap detection response command sent back from the Circuit Playground board to the host computer.  See the description of the tap detection response below for what data to expect.

Example: To request a single tap detection reading send the following SysEx bytes:

0x40 0x31

Tap Detection Response

Sub-command byte: 0x37 0x00 (Note this sub-command has two bytes instead of one byte as a side-effect of using internal Firmata sketch SysEx functions)

Parameters: 2 bytes

• Tap Detection Register Value (2 bytes):  These two bytes define an unsigned 8-bit value that is the current tap detection register value.  The bytes are in little endian order so the low 7-bits are in the first byte and the 8th/high order bit is in the second byte.  See the LIS3DH accelerometer datasheet for the exact meaning, however a double tap will have bit 6 set and a single tap will have bit 5 set.

Description: This command is sent back from the Circuit Playground board to the host computer when a tap detection reading is available.  The current tap detection register value is returned.

Example: A double tap detection event would respond with the following SysEx bytes:

0x40 0x37 0x00 0x20 0x00

Enable Tap Detection Streaming

Sub-command byte: 0x38

Parameters: None

Description: This command will turn on continuous streaming of tap detection readings from Circuit Playground to the host computer.  Reading will be taken every 20 milliseconds and sent to the host using the tap detection response command above.  This is useful for quickly reading the tap detection state without all the overhead of constantly sending single tap detection read requests.  To disable the streaming see the disable tap detection streaming function below.

Example: To enable steaming of tap detection data send the following SysEx bytes:

0x40 0x38

Disable Tap Detection Streaming

Sub-command byte: 0x39

Parameters: None

Description: This command will turn off continuous streaming of tap detection readings from Circuit Playground to the host computer.

Example: To disable steaming of tap detection data send the following SysEx bytes:

0x40 0x39

Set Tap Detection Configuration

Sub-command byte: 0x3D

Parameters: 4 bytes

• Type (2 bytes): These two bytes define an unsigned 8-bit value which identifies the type of tap detection to perform.  The lower 7 bits of the value are in the first byte and the 8th/high order bit are in the second byte.  The following values are allowed:
• 0 = no tap detection
• 1 = single tap detection only
• 2 = single & double tap detection (default)
• Tap Threshold (2 bytes): These two bytes define an unsigned 8-bit value (0-255) which is the threshold for tap detection.  The higher the value the less sensitive the tap detection.  Generally the threshold should be set depending on the accelerometer range and good values to try are:
• 5-10 for +/- 16G range
• 10-20 for +/- 8G range
• 20-40 for +/- 4G range
• 40-80 for +/- 2G range (default is 80)

Description: This command will change the type and sensitivity of tap detection.

Example: To configure tap detection for only single clicks with a threshold of 40 send the following SysEx bytes:

0x40 0x3D 0x01 0x00 0x28 0x00

Capacitive Touch Commands

Single Capacitive Touch Reading

Sub-command byte: 0x40

Parameters: 1 byte

• Input number (1 byte): This byte specified which capacitive touch input to read and should be one of: 0, 1, 2, 3, 6, 9, 10, 12

Description: This command will request a single capacitive touch reading.  The result of this command will be a capacitive touch response command sent back from the Circuit Playground board to the host computer.  See the description of the capacitive touch response below for what data to expect.

Example: To request a single capacitive touch reading for input 12 send the following SysEx bytes:

0x40 0x40 0x0C

Capacitive Touch Response

Sub-command byte: 0x43 0x00 (Note this sub-command has two bytes instead of one byte as a side-effect of using internal Firmata sketch SysEx functions)

Parameters: 10 bytes

• Input number (2 bytes): These bytes define an unsigned 8-bit value which is the input number that is associated with this response (0, 1, 2, 3, 6, 9, 12).  The bytes are in little endian order with the 7 low bits first and the 8th/high order bit last (note this bit will never really be set since the inputs only go up to 12).
• Raw capacitive touch value (8 bytes):  These eight bytes define an unsigned 32-bit value which is the raw capacitive touch reading for this input.  The bytes are in little endian order with each pair of bytes representing a single byte in the reading (the 7 low bits are first, then the 8th/high order bit follows).  The higher the value the larger the capacitance touching the input.  You can apply your own threshold to consider an input 'pressed', for example values above 300 or so are a good reading to detect a press.

Description: This command is sent back from the Circuit Playground board to the host computer when a capacitive input reading is available.

Example: A response for input 12 with a capacitive touch reading of 316 is made of the following SysEx bytes:

0x40 0x43 0x00 0x0C 0x00 0x3C 0x00 0x01 0x00 0x00 0x00 0x00 0x00

Enable Capacitive Touch Streaming

Sub-command byte: 0x41

Parameters: 1 byte

• Input number (1 byte): This byte specified which capacitive touch input to enable streaming and should be one of: 0, 1, 2, 3, 6, 9, 10, 12

Description: This command will turn on continuous streaming of capacitive touch readings from Circuit Playground to the host computer.  Reading will be taken every 20 milliseconds and sent to the host using the capacitive touch response command above.  This is useful for quickly reading the capacitive touch state without all the overhead of constantly sending single capacitive touch read requests.  To disable the streaming see the disable capacitive touch streaming function below.

Example: To enable steaming of capacitive touch for input 12 send the following SysEx bytes:

0x40 0x41 0x0C

Disable Capacitive Touch Streaming

Sub-command byte: 0x42

Parameters: 1 byte

• Input number (1 byte): This byte specified which capacitive touch input to disable streaming and should be one of: 0, 1, 2, 3, 6, 9, 10, 12

Description: This command will turn off continuous streaming of capacitive touch readings from Circuit Playground to the host computer. 

Example: To disable steaming of capacitive touch for input 12 send the following SysEx bytes:

0x40 0x42 0x0C

Color Sensing Commands

These commands use the light sensor and NeoPixel #1 (adjacent to the light sensor) to perform basic color detection of an object in front of the sensor.  See this video for more details and examples of the color sensing logic: https://www.youtube.com/watch?v=30NKAKwgklM

Single Color Sense Command

Sub-command byte: 0x50

Parameters: None

Description: This command will perform a single color sense using the light sensor and NeoPixel #1.  The result will be returned in a new color sense command response (see below).

Example: To request a color sense send the following SysEx bytes:

0x40 0x50

Color Sense Response

Sub-command byte: 0x51 0x00 (Note this sub-command sends two bytes instead of one)

Parameters: 6 bytes

• Red component value (2 bytes): These two bytes define the unsigned 8-bit value for the red component of the detected color.  The first byte is the 7 low order bits and the second byte is the 8th/high order bit.
• Green component value (2 bytes): These two bytes define the unsigned 8-bit value for the green component of the detected color.  The first byte is the 7 low order bits and the second byte is the 8th/high order bit.
• Blue component value (2 bytes): These two bytes define the unsigned 8-bit value for the blue component of the detected color.  The first byte is the 7 low order bits and the second byte is the 8th/high order bit.

Description: This response is sent from Circuit Playground to the host when a color sense result is available.  The parameters include the red, green, blue component values of the detected color (0 is minimum intensity and 255 is maximum intensity).

Example: A color sense response with red=255, green=128, and blue=0 would send the following SysEx bytes:

0x40 0x51 0x00 0x7F 0x01 0x00 0x01 0x00 0x00

Other Components

For other components on the Circuit Playground board you can use existing Firmata functions to read them:

• Light Sensor: The light sensor is connected to analog input 5 and can be read with Firmata's standard analog input functions.  The value of the light sensor has no units and increases as more light is visible.
• Temperature Sensor: The temperature sensor is a thermistor connected to analog input 0 and can be read with Firmata's standard analog input functions.  You probably want to apply Steinhart-Hart thermistor equations to the output in order to convert it to a temperature.  See how the Python Circuit Playground Firmata client does this conversion for more details.
• Microphone: The microphone is connected to analog input 4 and can be read with Firmata's standard analog input functions.  The value of these microphone readings are raw analog samples and must be averaged or smoothed out to understand the volume.  You can also take a set of sample and apply a FFT for example to find the frequencies of sound being heard.
• Left Pushbutton: The left pushbutton is connected to digital input 4 and can be read with Firmata's standard digital input functions.  When the button is pressed it will be pulled to a high logic level, and when not pressed it will be pulled to a low/ground logic level.
• Right Pushbutton: The right pushbutton is connected to digital input 19 and can be read with Firmata's standard digital input functions.  When the button is pressed it will be pulled to a high logic level, and when not pressed it will be pulled to a low/ground logic level.
• Slide Switch: The slide switch is connected to digital input 21 and can be read with Firmata's standard digital input functions.  When the switch is pulled to the left it will read a high logic level, and when pulled to the right it will read a low/ground logic level.