Reference.Firmata History

Hide minor edits - Show changes to output

November 25, 2008, at 08:28 PM by Hans Steiner -
Deleted line 0:
[[Interfacing.Firmata|Firmata]] - Library - [[Interfacing.FirmataBaudRateDetails|Baud Rate Details]] - [[Interfacing.FirmataProtocolDetails|Protocol Details]] - [[Interfacing.FirmataProtocolProposals | Protocol Proposals]]
Added lines 2-3:
[[|Firmata]] - Library - [[|Baud Rate Details]] - [[|Protocol Details]] - [[ | Protocol Proposals]]
November 25, 2008, at 08:24 PM by Hans Steiner -
Added lines 1-84:
[[Interfacing.Firmata|Firmata]] - Library - [[Interfacing.FirmataBaudRateDetails|Baud Rate Details]] - [[Interfacing.FirmataProtocolDetails|Protocol Details]] - [[Interfacing.FirmataProtocolProposals | 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)
analogWrite(pin, value);

void setup()
Firmata.setFirmwareVersion(0, 1);
Firmata.attach(ANALOG_MESSAGE, analogWriteCallback);

void loop()
while(Firmata.available()) {
for(analogPin = 0; analogPin < TOTAL_ANALOG_PINS; analogPin++) {
Firmata.sendAnalog(analogPin, analogRead(analogPin));