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:
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
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
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
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
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.
Page last edited April 25, 2016
Text editor powered by tinymce.
