Current version: 2.0.0
Enables control of up to 4 software and 4 hardware (UART) serial ports. Multiple ports can be used simultaneously (depending on restrictions of a given microcontroller board's capabilities).
Example files:
- Version 2.0 of the Serial feature has not yet been implemented.
Use these constants to identify the hardware or software serial port to address for each command.
HW_SERIAL0 = 0x00 (for using Serial when another transport is used for the Firmata Stream)
HW_SERIAL1 = 0x01
HW_SERIAL2 = 0x02
HW_SERIAL3 = 0x03
SW_SERIAL0 = 0x08
SW_SERIAL1 = 0x09
SW_SERIAL2 = 0x0A
SW_SERIAL3 = 0x0B
Use these constants to identify the pin type in a capability query response.
// Where the pin mode = "Serial" and the pin resolution = one of the following:
RES_RX0 = 0x00
RES_TX0 = 0x01
RES_RX1 = 0x02
RES_TX1 = 0x03
RES_RX2 = 0x04
RES_TX2 = 0x05
RES_RX3 = 0x06
RES_TX3 = 0x07
// extensible up to 8 HW ports
PIN_MODE_SERIAL = 0x0A
Configures the specified hardware or software serial port. RX and TX pins are optional and should only be specified if the platform requires them to be set.
0 START_SYSEX (0xF0)
1 SERIAL_DATA (0x67) // command byte
2 SERIAL_CONFIG (0x00)
3 port (HW_SERIALn OR SW_SERIALn)
4 baud (bits 0 - 6)
5 baud (bits 7 - 13)
6 baud (bits 14 - 20) // need to send 3 bytes for baud even if value is < 14 bits
7 rxPin (0-127) [optional] // only set if platform requires RX pin number
8 txPin (0-127) [optional] // only set if platform requires TX pin number
7|9 END_SYSEX (0xF7)
Firmata client -> Board
Receive serial data from Firmata client, reassemble and write for each byte received.
0 START_SYSEX (0xF0)
1 SERIAL_DATA (0x67)
2 SERIAL_WRITE (0x01)
3 port (HW_SERIALn OR SW_SERIALn)
4 data 0 (LSB)
5 data 0 (MSB)
6 data 1 (LSB)
7 data 1 (MSB)
... // up to max buffer - 5
n END_SYSEX (0xF7)
Board -> Firmata client
Read contents of serial buffer and send to Firmata client (send with SERIAL_REPLY).
maxBytesToRead optionally specifies how many bytes to read for each iteration. Set to 0 (or do not
define) to read all available bytes. If there are less bytes in the buffer than the number of bytes
specified by maxBytesToRead then the lesser number of bytes will be returned.
0 START_SYSEX (0xF0)
1 SERIAL_DATA (0x67)
2 SERIAL_READ (0x02)
3 port (HW_SERIALn OR SW_SERIALn)
4 SERIAL_READ_MODE (0x00) // 0x00 => read continuously, 0x01 => stop reading
5 maxBytesToRead (lsb) [optional]
6 maxBytesToRead (msb) [optional]
5|7 END_SYSEX (0xF7)
Board -> Firmata client
Sent in response to a SERIAL_READ event or on each iteration of the reporting loop if SERIAL_READ_CONTINUOUSLY is set.
0 START_SYSEX (0xF0)
1 SERIAL_DATA (0x67)
2 SERIAL_REPLY (0x03)
3 port (HW_SERIALn OR SW_SERIALn)
4 data 0 (LSB)
5 data 0 (MSB)
6 data 1 (LSB)
7 data 1 (MSB)
... // up to max buffer - 5
n END_SYSEX (0xF7)
Close the serial port. If you close a port, you will need to send a SERIAL_CONFIG message to
reopen it.
0 START_SYSEX (0xF0)
1 SERIAL_DATA (0x67)
2 SERIAL_CLOSE (0x04)
3 port (HW_SERIALn OR SW_SERIALn)
4 END_SYSEX (0xF7)
Flush the serial port. The exact behavior of flush depends on the underlying platform. For example,
with Arduino, calling flush on a HW serial port will drain the TX output buffer, calling flush
on a SW serial port will reset the RX buffer to the beginning, abandoning any data in the buffer.
Other platforms may define flush differently as well so see the documentation of flush for the
platform you are working with to understand exactly how it functions.
Generally flush is rarely needed so this functionality is primarily provided for advanced use
cases.
0 START_SYSEX (0xF0)
1 SERIAL_DATA (0x67)
2 SERIAL_FLUSH (0x05)
3 port (HW_SERIALn OR SW_SERIALn)
4 END_SYSEX (0xF7)
Enable switching serial ports. Necessary for Arduino SoftwareSerial but may not be applicable to other platforms.
0 START_SYSEX (0xF0)
1 SERIAL_DATA (0x67)
2 SERIAL_LISTEN (0x06)
3 port (HW_SERIALn OR SW_SERIALn)
4 END_SYSEX (0xF7)
Update the baud rate on a configured serial port.
0 START_SYSEX (0xF0)
1 SERIAL_DATA (0x67)
2 SERIAL_UPDATE_BAUD (0x07)
3 port (HW_SERIALn OR SW_SERIALn)
4 baud (bits 0 - 6)
5 baud (bits 7 - 13)
6 baud (bits 14 - 20) // need to send 3 bytes for baud even if value is < 14 bits
7 END_SYSEX (0xF7)
Set to collect bytes received by serial port until the receive buffer is filled or a data gap is detected to avoid forwarding single bytes at baud rates below 50000.
To set a delay value, specify the number of bits, where the delay is calculated by the following:
numBits * 1000 / baudRate
For example, if the baud is 9600, and 50 bits is specified (5 chars since 8N1 = 10 bits/char), then 50 * 1000 / 9600 = 5.2 which is a delay of 5 milliseconds (value is char or int). This means approximately 5 chars will be sent every 5 milliseconds if the baud is 9600.
Ensure that numBits * 1000 / baud is >= 1.0 or serial data will be sent on every iteration.
A value of 0 = no delay (default behavior), results in single byte transfers to the host with baud rates below approximately 56k (varies with CPU speed).
0 START_SYSEX (0xF0)
1 SERIAL_DATA (0x67)
2 SERIAL_MAX_CHAR_DELAY (0x08)
3 port (HW_SERIALn OR SW_SERIALn)
4 numBits (0 - 127) // 50 is a good value for baud rates < 56k
7 END_SYSEX (0xF7)