Note: this page refers to a product that is retired.

Firmata Library

The Firmata library implements the Firmata protocol for communicating with software on the host computer.

The Firmata library implements the Firmata protocol for communicating with software on the host computer. This allows you to write custom firmware without having to create your own protocol and objects for the programming environment that you are using.

To use this library

1#include <Firmata.h>

Methods

1begin(); //start the library
2begin(long); //start the library and override the default baud rate
3begin(Stream &s); // start the library using a [Stream](http://www.arduino.cc/en/Reference/Stream) other than Serial (eg Serial1 or EthernetClient)
4printVersion(); //send the protocol version to the host computer
5blinkVersion(): //blink the protocol version on the build in LED (typically pin 13)
6printFirmwareVersion(); //send the firmware name and version to the host computer
7setFirmwareVersion(byte major, byte minor); //set the firmware name and version, using the sketch's filename, minus the '.ino'
8setFirmwareNameAndVersion(const char *name, byte major, byte minor); //set both the name and version of the firmware

Sending Messages

1sendAnalog(byte pin, int value); //send an analog message
2sendDigitalPort(byte portNumber, int portData); //send an 8-bit port in a single digital message
3sendString(const char* string); //send a string to the host computer
4sendString(byte command, byte bytec, byte *bytev); //send a string to the host computer using a custom command type
5sendSysex(byte command, byte bytec, byte* bytev); //send a command with an arbitrary array of bytes
6write(byte c); //write a byte to the Stream

Receiving Messages

1available(); //check to see if there are any incoming messages in the buffer
2processInput(); //process incoming messages from the buffer, sending the data to any registered callback functions
3attach(byte command, callbackFunction myFunction); //attach a function to an incoming message type
4detach(byte command); //detach a function from an incoming message type

Utility methods

1sendValueAsTwo7bitBytes(int value); //writes value as 2 bytes
2startSysex(void); //starts a sysex message
3endSysex(void); //ends a sysex message

Callback Functions

In order to attach your function to a message type, your function must match the standard callback function. There are currently three types of callback functions in Firmata: generic, string, and sysex.

generic

1void callbackFunction(byte pin, int value);

system_reset

1void systemResetCallbackFunction(void);

string

1void stringCallbackFunction(char *myString);

sysex

1void sysexCallbackFunction(byte command, byte byteCount, byte *arrayPointer);

Message Types

There are various message types that you can attach callback functions to.

1ANALOG_MESSAGE //the analog value for a single pin
2DIGITAL_MESSAGE //8-bits of digital pin data (one port)
3REPORT_ANALOG //enable/disable the reporting of an analog pin
4REPORT_DIGITAL //enable/disable the reporting of a digital port
5SET_PIN_MODE //change the pin mode between INPUT/OUTPUT/PWM/etc.
6STRING_DATA //C-style strings, uses stringCallbackFunction for the function type
7SYSEX_START //generic, arbitrary length messages (via MIDI SysEx protocol), uses sysexCallbackFunction for the function type
8SYSTEM_RESET //message to reset firmware to its default state, uses systemResetCallbackFunction for the function type

Example

This example shows how to send and receive analog messages using Firmata.

1#include <Firmata.h>
2
3byte analogPin;
4
5void analogWriteCallback(byte pin, int value)
6{
7 pinMode(pin, OUTPUT);
8 analogWrite(pin, value);
9}
10
11void setup()
12{
13 Firmata.setFirmwareVersion(FIRMATA_MAJOR_VERSION, FIRMATA_MINOR_VERSION);
14 Firmata.attach(ANALOG_MESSAGE, analogWriteCallback);
15 Firmata.begin();
16}
17
18void loop()
19{
20 while (Firmata.available()) {
21 Firmata.processInput();
22 }
23 for (analogPin = 0; analogPin < TOTAL_ANALOG_PINS; analogPin++) {
24 Firmata.sendAnalog(analogPin, analogRead(analogPin));
25 }
26}

Suggest changes

The content on docs.arduino.cc is facilitated through a public GitHub repository. If you see anything wrong, you can edit this page here.

License

The Arduino documentation is licensed under the Creative Commons Attribution-Share Alike 4.0 license.