Arduino

Reference Language | Libraries | Comparison | Changes

Firmata - Library - Baud Rate Details - Protocol Details - Protocol Proposals

# Firmata Library

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.

## Methods

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

#### Sending Messages

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

#### Receiving Messages

`available()`
  check to see if there are any incoming messages in the buffer
`processInput()`
  process incoming messages from the buffer, sending the data to any registered callback functions
`attach(byte command, callbackFunction myFunction)`
  attach a function to an incoming message type
`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: generic, string, 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));
        }
    }

Reference Home

Corrections, suggestions, and new documentation should be posted to the Forum.

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

### Share

### This link has expired.
Please re-subscribe to our Newsletters.

### Subscribe to our Newsletters

Email

Please enter a valid email to subscribe

Arduino Newsletter
Arduino Store Newsletter

### Confirm your email address

We need to confirm your email address.
To complete the subscription, please click the link in the email we just sent you.

Thank you for subscribing!

Arduino
via Egeo 16
Torino, 10131
Italy

###### Newsletter

- ©2015 Arduino
- Copyright Notice
- Contact us
- Careers