Current version: 2.6.0
The intention of this protocol is to allow as much of the microcontroller to be controlled as possible from the host computer. This protocol was designed for the direct communication between a microcontroller and a software object on a host computer. The host software object should then provide an interface that makes sense in that environment.
The data communication format uses MIDI messages. It is not necessarily a MIDI device, first it uses a faster serial speed, and second, the messages don't always map the same.
This protocol uses the MIDI message format, but does not use the whole protocol. Most of the command mappings here will not be directly usable in terms of MIDI controllers and synths. It should co-exist with MIDI without trouble and can be parsed by standard MIDI interpreters. Just some of the message data is used differently.
| type | command | MIDI channel | first byte | second byte |
|---|---|---|---|---|
| analog I/O message | 0xE0 | pin # | LSB(bits 0-6) | MSB(bits 7-13) |
| digital I/O message | 0x90 | port | LSB(bits 0-6) | MSB(bits 7-13) |
| report analog pin | 0xC0 | analog Ch# | disable/enable(0/1) | - n/a - |
| report digital port | 0xD0 | port | disable/enable(0/1) | - n/a - |
| start sysex | 0xF0 | |||
| set pin mode(I/O) | 0xF4 | pin # (0-127) | pin mode | |
| set digital pin value | 0xF5 | pin # (0-127) | pin value(0/1) | |
| sysex end | 0xF7 | |||
| protocol version | 0xF9 | major version | minor version | |
| system reset | 0xFF |
Sysex-based sub-commands (0x00 - 0x7F) are used for an extended command set.
| type | sub-command | first byte | second byte | ... |
|---|---|---|---|---|
| string | 0x71 | char *string ... | ||
| firmware name/version | 0x79 | major version | minor version | char *name ... |
Two byte digital data format, second nibble of byte 0 gives the port number (eg 0x92 is the third port, port 2)
0 digital data, 0x90-0x9F, (MIDI NoteOn, bud different data format)
1 digital pins 0-6 bitmask
2 digital pin 7 bitmask
Analog 14-bit data format. For analog input, the Arduino Axx format is used. Therefore argument value 0 means A0, argument value
1 means A1, etc. On an Arduino Uno, A0 is equal to physical pin 14. So to enable analog reporting on A1, send 0xF4 0x0E 0x03 (SET_PIN_MODE, 14, ANALOG) followed by 0xC1 0x01 (REPORT_ANALOG, enable). The mapping between physical pins and analog channels is provided by the ANALOG_MAPPING message. There are boards where the numbering is not continuous, so don't expect that if A0 and A5 exist, A1 does as well. Neither can you expect that if A0 = pin 10, A1 is pin 11.
0 analog pin, 0xE0-0xEF, (MIDI Pitch Wheel)
1 analog least significant 7 bits
2 analog most significant 7 bits
Version report format
0 version report header (0xF9) (MIDI Undefined)
1 major version (0-127)
2 minor version (0-127)
Set pin mode
0 set digital pin mode (0xF4) (MIDI Undefined)
1 set pin number (0-127)
2 mode (INPUT/OUTPUT/ANALOG/PWM/SERVO/I2C/ONEWIRE/STEPPER/ENCODER/SERIAL/PULLUP, 0/1/2/3/4/6/7/8/9/10/11)
Set digital pin value (added in v2.5)
0 set digital pin value (0xF5) (MIDI Undefined)
1 set pin number (0-127)
2 value (LOW/HIGH, 0/1)
Toggle analogIn reporting by analog pin number (see above for numbering scheme)
0 toggle analogIn reporting (0xC0-0xCF) (MIDI Program Change)
1 disable(0) / enable(non-zero)
As of Firmata 2.4.0, upon enabling an analog pin, the pin value should be reported to the client application.
Toggle digital port reporting by port (second nibble of byte 0), eg 0xD1 is port 1 is pins 8 to 15
0 toggle digital port reporting (0xD0-0xDF) (MIDI Aftertouch)
1 disable(0) / enable(non-zero)
As of Firmata 2.4.0, upon enabling a digital port, the port value should be reported to the client application.
Request version report
0 request version report (0xF9) (MIDI Undefined)
System exclusive (sysex) messages are used to define sets of core and optional firmata features. Core features are related to functionality such as digital and analog I/O, querying information about the state and capabilities of the microcontroller board and the firmware running on the board. All core features are documented in this protocol.md file. Optional features extend the hardware capabilities beyond basic digital I/O and analog I/O and also provide APIs to interface with general and specific components and system services. Optional features are individually documented in separate markdown files.
Each firmata sysex message has a feature ID composed of either a single byte or an extended ID composed of 3 bytes where the first byte is always 0 to indicate it's an extended ID. The following table illustrates the structure. The most significant bit must be set to 0 in each byte between the START_SYSEX and END_SYSEX which frame the message.
| byte 0 | byte 1 | bytes 2 - N-1 | byte N |
|---|---|---|---|
| START_SYSEX | ID (01H-7DH) | PAYLOAD | END_SYSEX |
| START_SYSEX | ID (00H) | EXTENDED_ID (00H 00H - 7FH 7FH) + PAYLOAD | END_SYSEX |
Following are SysEx commands used for core features defined in this version of the protocol:
EXTENDED_ID 0x00 // A value of 0x00 indicates the next 2 bytes define the extended ID
RESERVED 0x01-0x0F // IDs 0x01 - 0x0F are reserved for user defined commands
ANALOG_MAPPING_QUERY 0x69 // ask for mapping of analog to pin numbers
ANALOG_MAPPING_RESPONSE 0x6A // reply with mapping info
CAPABILITY_QUERY 0x6B // ask for supported modes and resolution of all pins
CAPABILITY_RESPONSE 0x6C // reply with supported modes and resolution
PIN_STATE_QUERY 0x6D // ask for a pin's current mode and state (different than value)
PIN_STATE_RESPONSE 0x6E // reply with a pin's current mode and state (different than value)
EXTENDED_ANALOG 0x6F // analog write (PWM, Servo, etc) to any pin
STRING_DATA 0x71 // a string message with 14-bits per char
REPORT_FIRMWARE 0x79 // report name and version of the firmware
SAMPLING_INTERVAL 0x7A // the interval at which analog input is sampled (default = 19ms)
SYSEX_NON_REALTIME 0x7E // MIDI Reserved for non-realtime messages
SYSEX_REALTIME 0X7F // MIDI Reserved for realtime messages
The full set of core and optional Firmata feature IDs is defined in the firmata-registry.md file. See the registry for more info on proposing a new feature and obtaining an feature ID.
The firmware name to be reported should be exactly the same as the name of the Firmata client file, minus the file extension. So for StandardFirmata.ino, the firmware name is: StandardFirmata.
Query firmware Name and Version
0 START_SYSEX (0xF0)
1 queryFirmware (0x79)
2 END_SYSEX (0xF7)
Receive Firmware Name and Version (after query)
0 START_SYSEX (0xF0)
1 queryFirmware (0x79)
2 major version (0-127)
3 minor version (0-127)
4 first char of firmware name (LSB)
5 first char of firmware name (MSB)
6 second char of firmware name (LSB)
7 second char of firmware name (MSB)
... for as many bytes as it needs
N END_SYSEX (0xF7)
As an alternative to the normal analog message, this extended version allows addressing beyond pin 15 and supports sending analog values with any number of bits. The number of data bits is inferred by the length of the message. Starting with protocol version 2.7, the maximum number of bits for the value is 32 (encoded in 5 octets).
This message is originally intend for configuring PWM outputs. When the EXTENDED_REPORT_ANALOG message is used, this message is also used in reporting changes to analog inputs for analog channels > 15.
0 START_SYSEX (0xF0)
1 extended analog message (0x6F)
2 pin (0-127)
3 bits 0-6 (least significant byte)
4 bits 7-13 (most significant byte)
... additional bytes may be sent if more bits are needed
N END_SYSEX (0xF7)
The capability query provides a list of all modes supported by each pin. Each mode is described by 2 bytes where the first byte is the pin mode (such as digital input, digital output, PWM) and the second byte is the resolution (or sometimes the type of pin such as RX or TX for a UART pin). A value of 0x7F is used as a separator to mark the end each pin's list of modes. The number of pins supported is inferred by the message length.
0 START_SYSEX (0xF0)
1 CAPABILITY_QUERY (0x6B)
2 END_SYSEX (0xF7)
0 START_SYSEX (0xF0)
1 CAPABILITY_RESPONSE (0x6C)
2 1st supported mode of pin 0
3 1st mode's resolution of pin 0
4 2nd supported mode of pin 0
5 2nd mode's resolution of pin 0
... additional modes/resolutions, followed by `0x7F`,
to mark the end of the pin's modes. Subsequently, each pin
follows with its modes/resolutions and `0x7F`,
until all pins are defined.
N END_SYSEX (0xF7)
The modes in the following list are the modes of operation that can be returned during the capability response:
DIGITAL_INPUT (0x00)
DIGITAL_OUTPUT (0x01)
ANALOG_INPUT (0x02)
PWM (0x03)
SERVO (0x04)
SHIFT (0x05)
I2C (0x06)
ONEWIRE (0x07)
STEPPER (0x08)
ENCODER (0x09)
SERIAL (0x0A)
INPUT_PULLUP (0x0B)
// Extended modes
SPI (0x0C)
SONAR (0x0D)
TONE (0x0E)
DHT (0x0F)
If no modes are defined for a pin, no values are returned (other than the separator value 0x7F) and it should be assumed that pin is unsupported by Firmata.
A client implementation shall ignore any modes it does not support
The resolution byte serves a couple of different purpose:
- The original purpose was to define the resolution for analog input, pwm, servo and other modes that define a specific resolution (such as 10-bit for analog).
- The resolution byte has been adapted for another purpose for Serial/UART pins, it defines if the pin is RX or TX and which UART it belongs to. RX0 is the RX pin of UART0 (Serial on an Arduino for example), TX1 if the TX pin of UART1 (Serial1 on an Arduino).
Modes utilizing the resolution byte as resolution data:
DIGITAL_INPUT (0x00) // resolution is 1 (binary)
DIGITAL_OUTPUT (0x01) // resolution is 1 (binary)
ANALOG_INPUT (0x02) // analog input resolution in number of bits
PWM (0x03) // pwm resolution in number of bits
SERVO (0x04) // servo resolution in number of bits
STEPPER (0x08) // resolution is number number of bits in max number of steps
INPUT_PULLUP (0x0B) // resolution is 1 (binary)
Modes utilizing the resolution byte to define type of pin:
SERIAL (0x0A) // See description in [serial.md](https://github.com/firmata/protocol/blob/master/serial-1.0.md#serial-pin-capability-response)
// also to be added to I2C in the future to define SCL and SDA pins
For other features (including I2C until updated) the resolution information is less important so a value of 1 is used.
Analog messages are numbered 0 to 15, which traditionally refer to the Arduino pins labeled A0, A1, A2, etc. However, these pins are actually configured using "normal" pin numbers in the pin mode message, and when those pins are used for non-analog functions. The analog mapping query provides the information about which pins (as used with Firmata's pin mode message) correspond to the analog channels.
Analog mapping query
0 START_SYSEX (0xF0)
1 analog mapping query (0x69)
2 END_SYSEX (0xF7)
Analog mapping response
0 START_SYSEX (0xF0)
1 analog mapping response (0x6A)
2 analog channel corresponding to pin 0, or 127 if pin 0 does not support analog
3 analog channel corresponding to pin 1, or 127 if pin 1 does not support analog
4 analog channel corresponding to pin 2, or 127 if pin 2 does not support analog
... etc, one byte for each pin
N END_SYSEX (0xF7)
The above 2 queries provide static data (should never change for a particular board). Because this information is fixed and should only need to be read once, these messages are designed for a simple implementation in StandardFirmata, rather that bandwidth savings (eg, using packed bit fields).
The pin state is any data written to the pin (it is important to note that pin state != pin value). For output modes (digital output, PWM, and Servo), the state is any value that has been previously written to the pin. For input modes, typically the state is zero. However, for digital inputs, the state is the status of the pull-up resistor which is 1 if enabled, 0 if disabled.
The pin state query can also be used as a verification after sending pin modes or data messages.
Pin state query
0 START_SYSEX (0xF0)
1 pin state query (0x6D)
2 pin (0-127)
3 END_SYSEX (0xF7)
Pin state response
0 START_SYSEX (0xF0)
1 pin state response (0x6E)
2 pin (0-127)
3 pin mode (the currently configured mode)
4 pin state, bits 0-6
5 (optional) pin state, bits 7-13
6 (optional) pin state, bits 14-20
... additional optional bytes, as many as needed
N END_SYSEX (0xF7)
Send short string messages between the board and the client application. String length is basically unlimited for messages sent from the board to the client (string messages from the client to the board are meaningless), since it is not expected that the client has a critical memory limit. String messages from the board are typically used for error messages or debugging purposes.
0 START_SYSEX (0xF0)
1 STRING_DATA (0x71)
2 first char LSB
3 first char MSB
4 second char LSB
5 second char MSB
... additional bytes
N END_SYSEX (0xF7)
The sampling interval sets how often analog data and i2c data is reported to the client. The default for the arduino implementation is 19ms. This means that every 19ms analog data will be reported and any i2c devices with read continuous mode will be read.
0 START_SYSEX (0xF0)
1 SAMPLING_INTERVAL (0x7A)
2 sampling interval on the millisecond time scale (LSB)
3 sampling interval on the millisecond time scale (MSB)
4 END_SYSEX (0xF7)