Firmata Library

Firmata is a generic protocol for communicating with microcontrollers like the Arduino and 86Duino from software on a host computer. The protocol details can be found in the wiki page, and for more on the Firmata protocol, see http://firmata.org.

The Firmata library implements the Firmata protocol and allows you to write custom firmware without having to create your own protocol and objects for the programming environment that you are using. (You may be interested in seeing the video that shows 86Duino communicates with Processing via the Firmata library.)

Methods

  • Firmata.begin: start the library
  • Firmata. begin(long): start the library and override the default baud rate
  • Firmata.printversion: send the protocol version to the host computer
  • Firmata.blinkVersion: blink the protocol version on pin 13
  • Firmata.printFirmwareVersion: send the firmware name and version to the host computer
  • Firmata.setFirmwareVersion(byte major, byte minor): set the firmware name and version, using the sketch’s filename, minus the .pde

Sending Messages :

  • Firmata.sendAnalog(byte pin, int value): send an analog message
  • Firmata.sendDigitalPorts(byte pin, byte firstPort, byte secondPort): send digital ports as individual bytes
  • Firmata.sendDigitalPortPair(byte pin, int value): send digital ports as one int
  • Firmata.sendSysex(byte command, byte bytec, byte* bytev): send a command with an arbitrary array of bytes
  • Firmata.sendString(const char* string): send a string to the host computer
  • Firmata.sendString(byte command, const char* string): send a string to the host computer using a custom command type

Receiving Messages :

  • Firmata.available(): check to see if there are any incoming messages in the buffer
  • Firmata.processInput(): process incoming messages from the buffer, sending the data to any registered callback functions
  • Firmata.attach(byte command, callbackFunction myFunction): attach a function to an incoming message type
  • Firmata.detach(byte command): detach a function from an incoming message type

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: genericstring, and sysex.

  • generic
    void callbackFunction(byte pin, int value);
  • system_reset
    void systemResetCallbackFunction(void);
  • string
    void stringCallbackFunction(char *myString);
  • sysex
    void sysexCallbackFunction(byte pin, byte byteCount, byte *arrayPointer);

Message Types :

These are the various message types that you can attach functions to.

  • ANALOG_MESSAGE: the analog value for a single pin
  • DIGITAL_MESSAGE: 8-bits of digital pin data (one port)
  • REPORT_ANALOG: enable/disable the reporting of analog pin
  • REPORT_DIGITAL: enable/disable the reporting of a digital port
  • SET_PIN_MODE: change the pin mode between INPUT/OUTPUT/PWM/etc.
  • FIRMATA_STRING: C-style strings, uses stringCallbackFunction for the function type
  • SYSEX_START: generic, arbitrary length messages (via MIDI SysEx protocol), uses sysexCallbackFunction for the function type
  • SYSTEM_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.

#include <Firmata.h>
 
byte analogPin;
 
void analogWriteCallback(byte pin, int value)
{
    pinMode(pin,OUTPUT);
    analogWrite(pin, value);
}
 
void setup()
{
    Firmata.setFirmwareVersion(0, 1);
    Firmata.attach(ANALOG_MESSAGE, analogWriteCallback);
    Firmata.begin();
}
 
void loop()
{
    while(Firmata.available()) {
        Firmata.processInput();
    }
    for(analogPin = 0; analogPin < TOTAL_ANALOG_PINS; analogPin++) {
        Firmata.sendAnalog(analogPin, analogRead(analogPin)); 
    }
}

DEMO VIDEO


Libraries Reference Home

The text of the 86Duino reference is a modification of the Arduino reference and is licensed under a Creative Commons Attribution-ShareAlike 3.0 License. Code samples in the reference are released into the public domain.

Leave a Comment

Scroll to Top