//
//  Licensed to the Apache Software Foundation (ASF) under one or more
//  contributor license agreements.  See the NOTICE file distributed with
//  this work for additional information regarding copyright ownership.
//  The ASF licenses this file to You under the Apache License, Version 2.0
//  (the "License"); you may not use this file except in compliance with
//  the License.  You may obtain a copy of the License at
//
//      https://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
//
:imagesdir: ../../images/users/protocols
:icons: font

= 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 https://github.com/firmata/arduino/blob/master/examples/StandardFirmata/StandardFirmata.ino[here] (Version last changed on August 17th, 2017)

== Supported Operations

[cols="2,2a,5a"]
|===
|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.

NOTE: 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

[source]
----
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

include::partial$firmata.adoc[]

== Tag Addresses

Addressing is implemented in Go and Java. Neither driver reads; a board is driven and monitored,
never polled. See the xref:protocols/index.adoc[protocol support matrix] for what each
implementation does.

[WARNING]
====
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 xref:array-notation.adoc[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.

WARNING: 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

* xref:array-notation.adoc[Addressing arrays] - the shared `[\{selection}]` syntax.
