[plc4x] 02/02: - Added a documentation page for the firmata driver

[cd...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

cdutz pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/plc4x.git

commit afbb0fed58ca0d2da96a2e7f6576c6d512459212
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Tue Mar 10 13:22:15 2020 +0100

    - Added a documentation page for the firmata driver
---
 src/site/asciidoc/users/protocols/firmata.adoc | 104 +++++++++++++++++++++++++
 1 file changed, 104 insertions(+)

diff --git a/src/site/asciidoc/users/protocols/firmata.adoc b/src/site/asciidoc/users/protocols/firmata.adoc
new file mode 100644
index 0000000..d5fbda2
--- /dev/null
+++ b/src/site/asciidoc/users/protocols/firmata.adoc
@@ -0,0 +1,104 @@
+//
+//  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
+//
+//      http://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)
+
+=== Connection String Options
+
+[cols="2,2a,5a"]
+|===
+|Name |Value |Description
+
+|Code
+2+|`firmata`
+
+|Name
+2+|Firmata Protocol
+
+|Maven Dependency
+2+|
+----
+<dependency>
+  <groupId>org.apache.plc4x</groupId>
+  <artifactId>plc4j-driver-firmata</artifactId>
+  <version>{current-last-released-version}</version>
+</dependency>
+----
+
+|Default Transport:
+2+| `serial`
+
+|Compatible Transports:
+2+| - `serial`
+
+3+|Supported Operations
+
+|
+| `write`
+|
+
+|
+| `subscribe`
+|
+
+3+|Options
+
+|===
+
+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.
+
+=== Individual Resource Address Format
+
+Similar to the Modbus protocol, the Firmata protocol support Boolean and Short values.
+
+Booleans are used for the digital IO pins and short values for the analog inputs.
+
+==== Binary Addresses
+
+The full format for a digital address has the following format:
+
+----
+digital:{start-address}[{array-size}]:{special-config}
+----
+
+The `start-address` and `array-size` are simple integer values.
+`special-config` can be used to fonfigure the digital input pin to something else than `INPUT`.
+
+Currently the only supported option is `PULLUP` which configured the Arduino's digital input pin to use it's built in pullup-resistor.
+
+Both the `array-size` as well as the `special-config` parts are optional. So the fillowing addresses would also be valid:
+
+----
+digital:4
+digital:4[5]
+digital:4:PULLUP
+----
+
+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
+