+/*
+ * Communicate to the Devantech ETH008 relay card via TCP and Ethernet.
+ * Also supports other cards when their protocol is similar enough.
+ * USB and Modbus attached cards are not covered by this driver.
+ *
+ * See http://www.robot-electronics.co.uk/files/eth008b.pdf for device
+ * capabilities and a protocol discussion. See other devices' documents
+ * for additional features (digital input, analog input, TCP requests
+ * which ETH008 does not implement).
+ * See https://github.com/devantech/devantech_eth_python for MIT licensed
+ * Python source code which is maintained by the vendor.
+ * This sigrok driver implementation was created based on information in
+ * version 0.1.2 of the Python code (corresponds to commit 0c0080b88e29),
+ * and PDF files that are referenced in the shop's product pages (which
+ * also happen to provide ZIP archives with examples that are written
+ * using other programming languages).
+ *
+ * The device provides several means of communication: HTTP requests
+ * (as well as an interactive web form). Raw TCP communication with
+ * binary requests and responses. Text requests and responses over
+ * TCP sockets. Some of these depend on the firmware version. Version
+ * checks before command transmission is essentially non-existent in
+ * this sigrok driver implementation. Binary transmission is preferred
+ * because it is assumed that this existed in all firmware versions.
+ * The firmware interestingly accepts concurrent network connections
+ * (up to five of them, all share the same password). Which means that
+ * the peripheral's state can change even while we are controlling it.
+ *
+ * TCP communication seems to rely on network fragmentation and assumes
+ * that software stacks provide all of a request in a single receive
+ * call on the firmware side. Which works for local communication, but
+ * could become an issue when long distances and tunnels are involved.
+ * This sigrok driver also assumes complete reception within a single
+ * receive call. The short length of binary transmission helps here
+ * (the largest payloads has a length of four bytes).
+ *
+ * The lack of length specs as well as termination in the protocol
+ * (both binary as well as text variants over TCP sockets) results in
+ * the inability to synchronize to the firmware when connecting and
+ * after hiccups in an established connection. The fixed length of
+ * requests and responses for binary payloads helps a little bit,
+ * assuming that TCP connect is used to recover. The overhead of
+ * HTTP requests and responses is considered undesirable for this
+ * sigrok driver implementation. [This also means that a transport
+ * which lacks the concept of network frames cannot send passwords.]
+ * The binary transport appears to lack HELLO or NOP requests that
+ * could be used to synchronize. Firmware just would not respond to
+ * unsupported commands. Maybe a repeated sequence of identity reads
+ * combined with a read timeout could help synchronize, but only if
+ * the response is known because the model was identified before.
+ *
+ * The sigrok driver source code was phrased with the addition of more
+ * models in mind. Only few code paths require adjustment when similar
+ * variants of requests or responses are involved in the communication
+ * to relay cards that support between two and twenty channels. Chances
+ * are good, existing firmware is compatible across firmware versions,
+ * and even across hardware revisions (model upgrades). Firmware just
+ * happens to not respond to unknown requests.
+ *
+ * Support for models with differing features also was kept somehwat
+ * simple and straight forward. The mapping of digital outputs to relay
+ * numbers from the user's perspective is incomplete for those cards
+ * where users decide whether relays are attached to digital outputs.
+ * When an individual physical channel can be operated in different
+ * modes, or when its value gets presented in different formats, then
+ * these values are not synchronized. This applies for digital inputs
+ * which are the result of applying a threshold to an analog value.
+ *
+ * TODO
+ * - Add support for other models.
+ * - The Ethernet (and Wifi) devices should work as they are with
+ * the current implementation.
+ * https://www.robot-electronics.co.uk/files/eth484b.pdf.
+ * - USB could get added here with reasonable effort. Serial over
+ * CDC is transparently supported (lack of framing prevents the
+ * use of variable length requests or responses, but should not
+ * apply to these models anyway). The protocol radically differs
+ * from Ethernet variants:
+ * https://www.robot-electronics.co.uk/files/usb-rly16b.pdf
+ * - 0x38 get serial number, yields 8 bytes
+ * - 0x5a get software version, yields module ID 9, 1 byte version
+ * - 0x5b get relay states, yields 1 byte current state
+ * - 0x5c set relay state, takes 1 byte for all 8 relays
+ * - 0x5d get supply voltage, yields 1 byte in 0.1V steps
+ * - 0x5e set individual relay, takes 3 more bytes: relay number,
+ * hi/lo pulse time in 10ms steps
+ * - for interactive use? 'd' all relays on, 'e'..'l' relay 1..8 on,
+ * 'n' all relays off, 'o'..'v' relay 1..8 off
+ * - Modbus may or may not be a good match for this driver, or may
+ * better be kept in yet another driver? Requests and responses
+ * again differ from Ethernet and USB models, refer to traditional
+ * "coils" and have their individual and grouped access.
+ * https://www.robot-electronics.co.uk/files/mbh88.pdf
+ * - Reconsider the relation of relay channels, and digital outputs
+ * and their analog sampling and digital input interpretation. The
+ * current implementation is naive, assumes the simple DO/DI/AI
+ * groups and ignores their interaction within the firmware.
+ * - Add support for password protection?
+ * - See command 0x79 to "login" (beware of the differing return value
+ * compared to other commands), command 0x7a to check if passwords
+ * are involved and whether the login needs refreshing, command 0x7b
+ * for immediate "logout" in contrast to expiration.
+ * - Alternatively consider switching to the "text protocol" in that
+ * use case, which can send an optional password in every request
+ * that controls relays (command 0x3a).
+ * - How to specify the password in applications and how to pass them
+ * to this driver is yet another issue that needs consideration.
+ */
+
+#include "config.h"
+
+#include <string.h>
+