V2.0ProtocolDetails
From Firmata
This version of the protocol is now obsolete, check ProtocolChangeLog for the most up-to-date version.
This page describes version 2.0 of the Firmata protocol. This version is very similar to version 1, the main difference is that the format of the digital messages changed to be based on 8-bit ports rather than 14-bit chunks. The 14-bit chunks were derived from the Arduino's 14 digital pins. 8-bit ports are standard on most microcontrollers.
The Firmata protocol is designed to be extended, the Proposals page is the place to propose new extensions.
Contents |
I/Os Supported
- up to 16 analog pins
- up to 128 digital pins (16 * 8-bit ports)
Message Types
/* 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. * * MIDI format: http://www.harmony-central.com/MIDI/Doc/table1.html * * MIDI * type command 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 pin # disable/enable(0/1) - n/a - * report digital port 0xD0 port disable/enable(0/1) - n/a - * * sysex start 0xF0 * set pin mode(I/O) 0xF4 pin # (0-127) pin state(0=in) * sysex end 0xF7 * protocol version 0xF9 major version minor version * system reset 0xFF * */
/* SysEx-based commands (0x00-0x7F) are used for an extended command set. * * type command first byte second byte ... *----------------------------------------------------------------------------- * string 0x71 char *string ... * firmware name/version 0x79 major version minor version char *name... */
Data Message Expansion
/* two byte digital data format * 0 digital data, 0x90-0x9F, (MIDI NoteOn, but different data format) * 1 digital pins 0-6 bitmask * 2 digital pins 7-13 bitmask */
/* analog 14-bit data format * 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) */
Control Messages Expansion
/* set pin mode * 1 set digital pin mode (0xF4) (MIDI Undefined) * 2 pin number (0-127) * 3 state (INPUT/OUTPUT/ANALOG/PWM/SERVO, 0/1/2/3/4) */
/* toggle analogIn reporting by pin * 0 toggle digitalIn reporting (0xC0-0xCF) (MIDI Program Change) * 1 disable(0)/enable(non-zero) */
/* toggle digital port reporting by port * 0 toggle digital port reporting (0xD0-0xDF) (MIDI Aftertouch) * 1 disable(0)/enable(non-zero) */
/* request version report * 0 request version report (0xF9) (MIDI Undefined) */
Sysex Message Format
The idea for SysEx is to have a second command space using the first byte after the SysEx Start byte. The key difference is that the data can be of any size, rather than just one or two bytes for standard MIDI messages.
/* Generic Sysex Message * 0 START_SYSEX (0xF0) * 1 sysex command (0x00-0x7F) * x between 0 and MAX_DATA_BYTES 7-bit bytes of arbitrary data * last END_SYSEX (0xF7) */
Query Firmware Name and Version
The firmware name to be reported should be exactly the same as the name of the Arduino file, minus the .pde. So for Standard_Firmata.pde, the firmware name is: Standard_Firmata.
/* 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 7-bits of firmware name * 5 second 7-bits of firmware name * x ...for as many bytes as it needs) * 6 END_SYSEX (0xF7) */
