Firmata

The Firmata protocol is based on the MIDI protocol used for communicating with musical equipment.

It is also one of the most widely used protocols for communication with Arduino devices.

This driver is built to be compatible with the StandardFirmata Arduino Sketch which can be found here (Version last changed on August 17th, 2017)

Supported Operations

Name Value Description

write

Writing is only supported to digital addresses.

subscribe

Subscribing is supported for both digital and analog addresses. See note below.

Neither the Go nor the Java driver reads; a board is driven and monitored, never polled.

When subscribing to pins, these are configured to become read pins. When writing to digital pins, these are configured to become output pins. However, writing to pins for which a subscription exists, an exception will be thrown. In order to write to previously subscribed pins, all subscriptions for this have to be cancelled first.

Connection String

firmata:serial://{comm-port}[?{options}]
firmata:tcp://{ip-address}[?{options}]

serial is the default transport - the classic Firmata-over-UART path. tcp targets StandardFirmataWiFi / StandardFirmataEthernet style boards, and is also used as a fallback when the serial transport can’t open a socat-bridged PTY (as on macOS).

Connection String Options

Name

Type

Default Value

Required

Description

Name

Firmata

Code

firmata

Maven Dependency

 
<dependency>
  <groupId>org.apache.plc4x</groupId>
  <artifactId>plc4j-driver-firmata</artifactId>
  <version>1.0.0</version>
</dependency>

Default Transport

serial

Supported Transports

  • serial

  • tcp

Config options:

request-timeout-ms

INT

10000

Maximum time (in milliseconds) to wait for the initial firmware-report reply during connection setup.

Transport config options:

serial

serial.baud-rate

INT

9600

Baud rate (bits per second)

serial.data-bits

INT

8

Number of data bits (5, 6, 7, or 8)

serial.stop-bits

INT

1

Number of stop bits (1 or 2)

serial.parity

STRING

none

Parity: none, odd, even, mark, space (case-insensitive)

serial.flow-control

STRING

none

Flow control: none, rts-cts, xon-xoff (case-insensitive)

serial.read-timeout-ms

INT

1000

Read timeout in milliseconds. 0 means blocking read.

serial.write-timeout-ms

INT

1000

Write timeout in milliseconds.

serial.dtr

BOOLEAN

false

Enable DTR (Data Terminal Ready) signal

serial.rts

BOOLEAN

false

Enable RTS (Request To Send) signal

serial.reuse-port

BOOLEAN

false

Reuse the underlying serial port across multiple transport instances. When true, instances with the same port will share a connection. This is useful for protocols where multiple logical connections share one serial port. Connections sharing a port must target distinct unit ids; Modbus RTU responses carry no transaction ids, so same-unit traffic from multiple connections cannot be told apart.

serial.interframe-delay

INT

0

Interframe delay in milliseconds for protocols that need spacing between messages. Applies to shared and dedicated ports; the gap is measured from the last write or received data.

tcp

tcp.connect-timeout-ms

INT

5000

Connection timeout in milliseconds.

tcp.read-timeout-ms

INT

0

Socket read timeout in milliseconds. 0 means no timeout.

tcp.write-timeout-ms

INT

0

Socket write timeout in milliseconds. 0 means no timeout.

tcp.no-delay

BOOLEAN

true

Enable TCP_NODELAY (disable Nagle’s algorithm).

tcp.keep-alive

BOOLEAN

false

Enable SO_KEEPALIVE.

tcp.send-buffer-size

INT

81920

Send buffer size in bytes. 0 uses system default.

tcp.receive-buffer-size

INT

81920

Receive buffer size in bytes. 0 uses system default.

tcp.local-address

STRING

Local address to bind to (optional). If not set, uses default.

tcp.local-port

INT

0

Local port to bind to (optional). 0 uses ephemeral port.

Tag Addresses

Addressing is implemented in Go and Java. Neither driver reads; a board is driven and monitored, never polled. See the protocol support matrix for what each implementation does.

Firmata addresses carry no type, so the brackets did not move when the notation was unified - and their meaning changed with nothing to reject. 3[4] used to mean four pins starting at pin 3; it now means one pin, the fifth. Rewrite these as 3[0..3].

General Format

A Firmata address always begins with a digital: or analog: prefix, naming which of the two address forms below applies. See Addressing arrays for the [{selection}] part shared by both.

The Java driver caps the pin number itself at 3 digits (0-999, FirmataTag.ADDRESS_PATTERN, \d{1,3}), and separately caps the address plus selection at the 256 pins the protocol can name on the wire (FirmataTag.PIN_COUNT). The Go driver’s ported pattern uses an unbounded \d+ for the pin number itself (plc4go/internal/firmata/TagHandler.go:38), so digital:1234 parses on the Go side and is rejected by Java - see the firmata entry in the Java/Go address divergence report for this restructure.

Binary Addresses

The full format for a digital address is:

digital:{start-address}[{selection}]:{special-config}

The start-address is a plain integer. special-config can be used to configure the digital input pin to something else than INPUT; currently the only supported option is PULLUP, which configures the Arduino’s digital input pin to use its built-in pullup-resistor.

Both the [{selection}] and the :{special-config} parts are optional.

A normal Arduino Uno is equipped with 14 digital inputs: 0-13.

However in case of using the serial port (which will always be the case when using this driver), the pins 0 and 1 are the RX and TX pins of the serial port and can’t be used.

Analog Addresses

The full format for an analog address is:

analog:{start-address}[{selection}]

The start-address is a plain integer, and [{selection}] is optional.

A normal Arduino Uno is equipped with 6 analog inputs: 0-5.

Data Types

Firmata addresses carry no type suffix; the type is implied by which prefix is used. Digital addresses are always BOOL (FirmataTagDigital.getPlcValueType()); analog addresses are always INT (FirmataTagAnalog.getPlcValueType()).

Examples

digital:2
digital:5
digital:8[0..3]:PULLUP
digital:0[0..255]
analog:0
analog:3
analog:0[0..2]

More Information