firmata::FirmataClass Class Reference

Public Types
typedef void(*	callbackFunction) (uint8_t, int)
typedef void(*	systemCallbackFunction) (void)
typedef void(*	stringCallbackFunction) (char *)
typedef void(*	sysexCallbackFunction) (uint8_t command, uint8_t argc, uint8_t *argv)

Public Member Functions
	FirmataClass ()
void	begin ()
void	begin (long)
void	begin (Stream &s)
void	printVersion (void)
void	blinkVersion (void)
void	printFirmwareVersion (void)
void	setFirmwareNameAndVersion (const char *name, byte major, byte minor)
void	disableBlinkVersion ()
int	available (void)
void	processInput (void)
void	parse (unsigned char value)
boolean	isParsingMessage (void)
void	sendAnalog (byte pin, int value)
void	sendDigital (byte pin, int value)
void	sendDigitalPort (byte portNumber, int portData)
void	sendString (const char *string)
void	sendString (byte command, const char *string)
void	sendSysex (byte command, byte bytec, byte *bytev)
void	write (byte c)
void	attach (uint8_t command, callbackFunction newFunction)
void	attach (uint8_t command, systemCallbackFunction newFunction)
void	attach (uint8_t command, stringCallbackFunction newFunction)
void	attach (uint8_t command, sysexCallbackFunction newFunction)
void	detach (uint8_t command)
byte	getPinMode (byte pin)
void	setPinMode (byte pin, byte config)
int	getPinState (byte pin)
void	setPinState (byte pin, int state)
void	sendValueAsTwo7bitBytes (int value)
void	startSysex (void)
void	endSysex (void)

Friends
void	FirmataMarshaller::encodeByteStream (size_t bytec, uint8_t *bytev, size_t max_bytes=0) const

Constructor & Destructor Documentation

FirmataClass()

FirmataClass::FirmataClass

(

)

The Firmata class. An instance named "Firmata" is created automatically for the user.

Member Function Documentation

attach() [1/3]

void FirmataClass::attach	(	uint8_t	command,
		stringCallbackFunction	newFunction
	)

Attach a callback function for the STRING_DATA command.

Parameters

command	Must be set to STRING_DATA or it will be ignored.
newFunction	A reference to the string callback function to attach.

attach() [2/3]

void FirmataClass::attach	(	uint8_t	command,
		sysexCallbackFunction	newFunction
	)

Attach a generic sysex callback function to sysex command.

Parameters

command	The ID of the command to attach a callback function to.
newFunction	A reference to the sysex callback function to attach.

attach() [3/3]

void FirmataClass::attach	(	uint8_t	command,
		systemCallbackFunction	newFunction
	)

Attach a callback function for the SYSTEM_RESET command.

Parameters

command	Must be set to SYSTEM_RESET or it will be ignored.
newFunction	A reference to the system reset callback function to attach.

available()

int FirmataClass::available

(

void

)

A wrapper for Stream::available()

Returns

The number of bytes remaining in the input stream buffer.

begin() [1/3]

void FirmataClass::begin

(

void

)

Initialize the default Serial transport at the default baud of 57600.

begin() [2/3]

void FirmataClass::begin

(

long

speed

)

Initialize the default Serial transport and override the default baud. Sends the protocol version to the host application followed by the firmware version and name. blinkVersion is also called. To skip the call to blinkVersion, call Firmata.disableBlinkVersion() before calling Firmata.begin(baud).

Parameters

speed

The baud to use. 57600 baud is the default value.

begin() [3/3]

void FirmataClass::begin

(

Stream &

s

)

Reassign the Firmata stream transport.

Parameters

s	A reference to the Stream transport object. This can be any type of transport that implements the Stream interface. Some examples include Ethernet, WiFi and other UARTs on the board (Serial1, Serial2, etc).

blinkVersion()

void FirmataClass::blinkVersion

(

void

)

Blink the Firmata protocol version to the onboard LEDs (if the board has an onboard LED). If VERSION_BLINK_PIN is not defined in Boards.h for a particular board, then this method does nothing. The first series of flashes indicates the firmware major version (2 flashes = 2). The second series of flashes indicates the firmware minor version (5 flashes = 5).

detach()

void FirmataClass::detach

(

uint8_t

command

)

Detach a callback function for a specified command (such as SYSTEM_RESET, STRING_DATA, ANALOG_MESSAGE, DIGITAL_MESSAGE, etc).

Parameters

command

The ID of the command to detatch the callback function from.

disableBlinkVersion()

void FirmataClass::disableBlinkVersion

(

)

Provides a means to disable the version blink sequence on the onboard LED, trimming startup time by a couple of seconds. Call this before Firmata.begin(). It only applies when using the default Serial transport.

endSysex()

void FirmataClass::endSysex

(

void

)

A helper method to write the end of a Sysex message transmission.

getPinMode()

byte FirmataClass::getPinMode

(

byte

pin

)

Parameters

pin	The pin to get the configuration of.

Returns

The configuration of the specified pin.

getPinState()

int FirmataClass::getPinState

(

byte

pin

)

Parameters

pin	The pin to get the state of.

Returns

The state of the specified pin.

isParsingMessage()

boolean FirmataClass::isParsingMessage

(

void

)

Returns

Returns true if the parser is actively parsing data.

parse()

void FirmataClass::parse

(

unsigned char

value

)

Parse data from the input stream.

Parameters

inputData

A single byte to be added to the parser.

printFirmwareVersion()

void FirmataClass::printFirmwareVersion

(

void

)

Sends the firmware name and version to the Firmata host application. The major and minor version numbers are the first 2 bytes in the message. The following bytes are the characters of the firmware name.

printVersion()

void FirmataClass::printVersion

(

void

)

Send the Firmata protocol version to the Firmata host application.

processInput()

void FirmataClass::processInput

(

void

)

Read a single int from the input stream. If the value is not = -1, pass it on to parse(byte)

sendAnalog()

void FirmataClass::sendAnalog	(	byte	pin,
		int	value
	)

Send an analog message to the Firmata host application. The range of pins is limited to [0..15] when using the ANALOG_MESSAGE. The maximum value of the ANALOG_MESSAGE is limited to 14 bits (16384). To increase the pin range or value, see the documentation for the EXTENDED_ANALOG message.

Parameters

pin	The analog pin to send the value of (limited to pins 0 - 15).
value	The value of the analog pin (0 - 1024 for 10-bit analog, 0 - 4096 for 12-bit, etc). The maximum value is 14-bits (16384).

sendDigitalPort()

void FirmataClass::sendDigitalPort	(	byte	portNumber,
		int	portData
	)

Send an 8-bit port in a single digital message (protocol v2 and later). Send 14-bits in a single digital message (protocol v1).

Parameters

portNumber	The port number to send. Note that this is not the same as a "port" on the physical microcontroller. Ports are defined in order per every 8 pins in ascending order of the Arduino digital pin numbering scheme. Port 0 = pins D0 - D7, port 1 = pins D8 - D15, etc.
portData	The value of the port. The value of each pin in the port is represented by a bit.

sendString() [1/2]

void FirmataClass::sendString	(	byte	command,
		const char *	string
	)

Send a string to the Firmata host application.

Parameters

command	Must be STRING_DATA
string	A pointer to the char string

sendString() [2/2]

void FirmataClass::sendString

(

const char *

string

)

Send a string to the Firmata host application.

Parameters

string

A pointer to the char string

sendSysex()

void FirmataClass::sendSysex	(	byte	command,
		byte	bytec,
		byte *	bytev
	)

Send a sysex message where all values after the command byte are packet as 2 7-bit bytes (this is not always the case so this function is not always used to send sysex messages).

Parameters

command	The sysex command byte.
bytec	The number of data bytes in the message (excludes start, command and end bytes).
bytev	A pointer to the array of data bytes to send in the message.

sendValueAsTwo7bitBytes()

void FirmataClass::sendValueAsTwo7bitBytes

(

int

value

)

Split a 16-bit byte into two 7-bit values and write each value.

Parameters

value

The 16-bit value to be split and written separately.

setFirmwareNameAndVersion()

void FirmataClass::setFirmwareNameAndVersion	(	const char *	name,
		byte	major,
		byte	minor
	)

Sets the name and version of the firmware. This is not the same version as the Firmata protocol (although at times the firmware version and protocol version may be the same number).

Parameters

name	A pointer to the name char array
major	The major version number
minor	The minor version number

setPinMode()

void FirmataClass::setPinMode	(	byte	pin,
		byte	config
	)

Set the pin mode/configuration. The pin configuration (or mode) in Firmata represents the current function of the pin. Examples are digital input or output, analog input, pwm, i2c, serial (uart), etc.

Parameters

pin	The pin to configure.
config	The configuration value for the specified pin.

setPinState()

void FirmataClass::setPinState	(	byte	pin,
		int	state
	)

Set the pin state. The pin state of an output pin is the pin value. The state of an input pin is 0, unless the pin has it's internal pull up resistor enabled, then the value is 1.

Parameters

pin	The pin to set the state of
state	Set the state of the specified pin

startSysex()

void FirmataClass::startSysex

(

void

)

A helper method to write the beginning of a Sysex message transmission.

write()

void FirmataClass::write

(

byte

c

)

A wrapper for Stream::available(). Write a single byte to the output stream.

Parameters

c	The byte to be written.

---

The documentation for this class was generated from the following files:

• Firmata.h
• Firmata.cpp