From beb1b0591e98066c4d4041c3448ad37767116a36 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Karl=20S=C3=B6derby?=
 <35461661+karlsoderby@users.noreply.github.com>
Date: Wed, 22 Sep 2021 14:53:27 +0200
Subject: [PATCH] Add docs

---
 docs/api.md    | 860 +++++++++++++++++++++++++++++++++++++++++++++++++
 docs/readme.md |  20 ++
 2 files changed, 880 insertions(+)
 create mode 100644 docs/api.md
 create mode 100644 docs/readme.md

diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..f5a0f2c
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,860 @@
+# Arduino Modbus Library
+
+## Modbus Client
+
+### `coilRead()`
+
+#### Description
+
+Perform a "Read Coils" operation for the specified address for a single coil.
+
+#### Syntax
+
+```
+int coilRead(int address);
+int coilRead(int id, int address);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address address to use for operation
+
+
+#### Returns
+coil value on success, -1 on failure.
+
+### `discreteInputRead()`
+
+#### Description
+
+Perform a "Read Discrete Inputs" operation for the specified address for a single discrete input.
+
+#### Syntax
+
+```
+int discreteInputRead(int address);
+int discreteInputRead(int id, int address);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address address to use for operation
+
+
+#### Returns
+discrete input value on success, -1 on failure.
+
+### `holdingRegisterRead()`
+
+#### Description
+
+Perform a "Read Holding Registers" operation for a single holding register.
+
+#### Syntax
+
+```
+long holdingRegisterRead(int address);
+long holdingRegisterRead(int id, int address);
+```
+
+#### Parameters
+
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address start address to use for operation
+- holiding register value on success, -1 on failure.
+
+### `inputRegisterRead()`
+
+#### Description
+
+Perform a "Read Input Registers" operation for a single input register.
+
+#### Syntax
+
+```
+long inputRegisterRead(int address);
+long inputRegisterRead(int id, int address);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address address to use for operation
+
+
+#### Returns
+input register value on success, -1 on failure.
+
+### `coilWrite()`
+
+#### Description
+
+Perform a "Write Single Coil" operation for the specified address and value.
+
+#### Syntax
+
+```
+int coilWrite(int address, uint8_t value);
+int coilWrite(int id, int address, uint8_t value);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address address to use for operation
+- value coi -l value to write
+
+
+#### Returns
+1 on success, 0 on failure.
+
+### `coilWrite()`
+
+#### Description
+
+Perform a "Write Single Coil" operation for the specified address and value.
+
+#### Syntax
+
+```
+int coilWrite(int address, uint8_t value);
+int coilWrite(int id, int address, uint8_t value);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address address to use for operation
+- value coi -l value to write
+
+
+#### Returns
+1 on success, 0 on failure.
+
+### `holdingRegisterWrite()`
+
+#### Description
+
+Perform a "Write Single Holding Register" operation for the specified address and value.
+
+#### Syntax
+
+```
+int holdingRegisterWrite(int address, uint16_t value);
+int holdingRegisterWrite(int id, int address, uint16_t value);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address address to use for operation
+- value - holding register value to write
+
+
+#### Returns
+1 on success, 0 on failure.
+
+### `registerMaskWrite()`
+
+#### Description
+
+Perform a "Mask Write Registers" operation for the specified address, AND mask and OR mask.
+
+#### Syntax
+
+```
+int registerMaskWrite(int address, uint16_t andMask, uint16_t orMask);
+int registerMaskWrite(int id, int address, uint16_t andMask, uint16_t orMask);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address address to use for operation
+- andMask - AND mask to use for operation
+- orMask - OR mask to use for operation
+
+
+#### Returns
+1 on success, 0 on failure.
+
+### `beginTransmission()`
+
+#### Description
+
+Begin the process of a writing multiple coils or holding registers.
+Use write(value) to set the values you want to send, and endTransmission() to send request on the wire.
+
+#### Syntax
+
+```
+int beginTransmission(int type, int address, int nb);
+int beginTransmission(int id, int type, int address, int nb);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- type - type of write to perform, either COILS or HOLD_REGISTERS
+- address start address to use for operation
+- nb - number of values to write
+
+
+#### Returns
+1 on success, 0 on failure
+
+### `write()`
+
+#### Description
+
+Set the values of a write operation started by beginTransmission(...).
+
+#### Syntax
+
+```
+int write(unsigned int value);
+```
+
+#### Parameters
+- value - value to write
+
+
+#### Returns
+1 on success, 0 on failure
+
+### `endTransmission()`
+
+#### Description
+
+End the process of a writing multiple coils or holding registers.
+
+#### Syntax
+
+```
+int endTransmission();
+```
+
+#### Parameters
+none
+
+
+#### Returns
+1 on success, 0 on failure
+
+### `requestFrom()`
+
+#### Description
+
+Read multiple coils, discrete inputs, holding registers, or input register values.
+Use available() and read() to process the read values.
+
+#### Syntax
+
+```
+int requestFrom(int type, int address, int nb);
+int requestFrom(int id, int type, int address,int nb);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+type - type of read to perform, either COILS, DISCRETE_INPUTS, HOLD_REGISTERS, or INPUT_REGISTERS
+- address start address to use for operation
+- nb - number of values to read
+
+
+#### Returns
+0 on failure, number of values read on success
+
+### `available()`
+
+#### Description
+
+Query the number of values available to read after calling requestFrom(...)
+
+#### Syntax
+
+```
+int available();
+```
+
+#### Parameters
+none
+
+
+#### Returns
+number of values available for reading use read()
+
+### `read()`
+
+#### Description
+
+Read a value after calling requestFrom(...)
+
+#### Syntax
+
+```
+long read();
+```
+
+#### Parameters
+None
+
+
+#### Returns
+-1 on failure, value on success
+
+### `lastError()`
+
+#### Description
+
+Read the last error reason as a string
+
+#### Syntax
+
+```
+const char* lastError();
+```
+
+#### Parameters
+none
+
+
+#### Returns
+Last error reason as a C string
+
+### `end()`
+
+#### Description
+
+Stop the client and clean up
+
+#### Syntax
+
+```
+void end();
+```
+
+#### Parameters
+None
+
+
+#### Returns
+nothing
+
+## ModbusRTUClient Class
+
+### `begin()`
+
+#### Description
+
+Start the Modbus RTU client with the specified parameters.
+
+#### Syntax
+
+```
+ModbusRTUClient.begin(baudrate);
+ModbusRTUClient.begin(baudrate, config);
+```
+
+#### Parameters
+- baudrate - Baud rate to use for serial
+- config - Config to use for serial (see Serial.begin(...) for more info.) defaults to SERIAL_8N1 if not provided
+
+
+#### Returns
+1 on success, 0 on failure
+
+## ModbusTCPClient Class
+
+### `ModbusTCPClient()`
+
+#### Description
+
+Creates a Modbus TCP client using the provided Client for the transport.
+
+#### Syntax
+
+```
+ModbusTCPClient(client);
+```
+
+#### Parameters
+- Client - to use for the transport
+
+### `begin()`
+
+#### Description
+
+Start the Modbus TCP client with the specified parameters.
+
+#### Syntax
+
+```
+modbusTCPClient.begin(ip, port);
+```
+
+#### Parameters
+- ip - the IP Address the client will connect to
+- port - port to the client will connect to
+
+
+#### Returns
+1 on success, 0 on failure
+
+### `connected()`
+
+#### Description
+
+Returns the connection status.
+
+#### Syntax
+
+```
+modbusTCPClient.connected();
+```
+
+#### Parameters
+None
+
+
+#### Returns
+Returns true if the client is connected, false if not.
+
+### `stop()`
+
+#### Description
+
+Disconnect from the server.
+
+#### Syntax
+
+```
+modbusTCPClient.stop();
+```
+
+#### Parameters
+None
+
+
+#### Returns
+Nothing
+
+## ModbusServer Class
+
+### `configureCoils()`
+
+#### Description
+
+Configure the servers coils.
+
+#### Syntax
+
+```
+int configureCoils(int startAddress, int nb);
+```
+
+#### Parameters
+- startAddress - start address of coils
+- nb - number of coils to configure
+
+
+#### Returns
+0 on success, 1 on failure
+
+### `configureDiscreteInputs()`
+
+#### Description
+
+Configure the servers discrete inputs.
+
+#### Syntax
+
+```
+int configureDiscreteInputs(int startAddress, int nb);
+```
+
+#### Parameters
+- startAddress - start address of discrete inputs
+- nb - number of discrete inputs to configure
+
+
+#### Returns
+0 on success, 1 on failure
+
+### `configureHoldingRegisters()`
+
+#### Description
+
+Configure the servers holding registers.
+
+#### Syntax
+
+```
+int configureHoldingRegisters(int startAddress, int nb);
+```
+
+#### Parameters
+- startAddress - start address of holding registers
+- nb - number of holding registers to configure
+
+
+#### Returns
+0 on success, 1 on failure
+
+### `configureInputRegisters()`
+
+#### Description
+
+Configure the servers input registers.
+
+#### Syntax
+
+```
+int configureInputRegisters(int startAddress, int nb);
+```
+
+#### Parameters
+- startAddress - start address of input registers
+- nb - number of input registers to configure
+
+
+#### Returns
+0 on success, 1 on failure
+
+### `coilRead()`
+
+#### Description
+
+Perform a "Read Coils" operation for the specified address for a single coil.
+
+#### Syntax
+
+```
+int coilRead(int address);
+int coilRead(int id, int address);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address address to use for operation
+
+
+#### Returns
+coil value on success, -1 on failure.
+
+### `discreteInputRead()`
+
+#### Description
+
+Perform a "Read Discrete Inputs" operation for the specified address for a single discrete input.
+
+#### Syntax
+
+```
+int discreteInputRead(int address);
+int discreteInputRead(int id, int address);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address address to use for operation
+
+
+#### Returns
+discrete input value on success, -1 on failure.
+
+### `holdingRegisterRead()`
+
+#### Description
+
+Perform a "Read Holding Registers" operation for a single holding register.
+
+#### Syntax
+
+```
+long holdingRegisterRead(int address);
+long holdingRegisterRead(int id, int address);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address start address to use for operation
+- holiding register value on success, -1 on failure.
+
+### `inputRegisterRead()`
+
+#### Description
+
+Perform a "Read Input Registers" operation for a single input register.
+
+#### Syntax
+
+```
+long inputRegisterRead(int address);
+long inputRegisterRead(int id, int address);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address address to use for operation
+
+
+#### Returns
+input register value on success, -1 on failure.
+
+### `coilWrite()`
+
+#### Description
+
+Perform a "Write Single Coil" operation for the specified address and value.
+
+#### Syntax
+
+```
+int coilWrite(int address, uint8_t value);
+int coilWrite(int id, int address, uint8_t value);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address address to use for operation
+- value coi -l value to write
+
+
+#### Returns
+1 on success, 0 on failure.
+
+### `holdingRegisterWrite()`
+
+#### Description
+
+Perform a "Write Single Holding Register" operation for the specified address and value.
+
+#### Syntax
+
+```
+int holdingRegisterWrite(int address, uint16_t value);
+int holdingRegisterWrite(int id, int address, uint16_t value);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address address to use for operation
+- value - holding register value to write
+
+
+#### Returns
+1 on success, 0 on failure.
+
+### `registerMaskWrite()`
+
+#### Description
+
+Perform a "Mask Write Registers" operation for the specified address, AND mask and OR mask.
+
+#### Syntax
+```
+int registerMaskWrite(int address, uint16_t andMask, uint16_t orMask);
+int registerMaskWrite(int id, int address, uint16_t andMask, uint16_t orMask);
+```
+
+#### Parameters
+- id (slave) - id of target, defaults to 0x00 if not specified
+- address address to use for operation
+- andMask - AND mask to use for operation
+- orMask - OR mask to use for operation
+
+
+#### Returns
+1 on success, 0 on failure.
+
+### `discreteInputWrite()`
+
+#### Description
+
+Write the value of the server's Discrete Input for the specified address and value.
+
+#### Syntax
+
+```
+int discreteInputWrite(int address, uint8_t value);
+```
+
+#### Parameters
+- address address to use for operation
+- value - discrete input value to write
+
+
+#### Returns
+1 on success, 0 on failure.
+
+### `writeDiscreteInputs()`
+
+#### Description
+
+Write values to the server's Discrete Inputs for the specified address and values.
+
+#### Syntax
+
+```
+int writeDiscreteInputs(int address, uint8_t values[], int nb);
+```
+
+#### Parameters
+- address address to use for operation
+- values - array of discrete inputs values to write
+- nb - number of discrete inputs to write
+
+
+#### Returns
+1 on success, 0 on failure.
+
+### `inputRegisterWrite()`
+
+#### Description
+
+Write the value of the server's Input Register for the specified address and value.
+
+#### Syntax
+
+```
+int inputRegisterWrite(int address, uint16_t value);
+```
+
+#### Parameters
+- address address to use for operation
+- value - input register value to write
+
+
+#### Returns
+1 on success, 0 on failure.
+
+### `writeInputRegisters()`
+
+#### Description
+
+Write values to the server's Input Registers for the specified address and values.
+
+#### Syntax
+
+```
+int writeInputRegisters(int address, uint16_t values[], int nb);
+```
+
+#### Parameters
+- address address to use for operation
+- values - array of input registers values to write
+- nb - number of input registers to write
+
+#### Returns
+1 on success, 0 on failure.
+
+### `poll()`
+
+#### Description
+
+Poll for requests
+
+#### Syntax
+
+```
+virtual void poll() = 0;
+```
+
+#### Parameters
+None
+
+#### Returns
+nothing
+
+### `end()`
+
+#### Description
+
+Stop the server
+
+#### Syntax
+
+```
+void end();
+```
+
+#### Parameters
+None
+
+#### Return
+nothing
+
+## ModbusRTUServer Class
+
+### `begin()`
+
+#### Description
+
+Start the Modbus RTU server with the specified parameters.
+
+#### Syntax
+
+```
+ModbusRTUServer.begin(id, baudrate);
+ModbusRTUServer.begin(id, baudrate, config);
+```
+
+#### Parameters
+- id - (slave) id of the server baudrate - Baud rate to use for serial
+- config - Config to use for serial (see Serial.begin(...) for more info.) defaults to SERIAL_8N1 if not provided
+
+
+#### Returns
+1 on success, 0 on failure
+
+## ModbusTCPServer
+
+### `ModbusTCPServer()`
+
+#### Description
+
+Creates a Modbus TCP server.
+
+#### Syntax
+
+```
+ModbusTCPServer();
+```
+
+#### Parameters
+None
+
+### `begin()`
+
+#### Description
+
+Start the Modbus TCP server.
+
+#### Syntax
+
+```
+modbusTCPserver.begin();
+modbusTCPserver.begin(id);
+```
+
+#### Parameters
+- id - the (slave) id of the server, defaults to 0xff (TCP);
+
+
+#### Returns
+1 on success, 0 on failure
+
+### `accept()`
+
+#### Description
+
+Accept a client connection.
+
+#### Syntax
+
+```
+modbusTCPserver.accept(client);
+```
+
+#### Parameters
+- client - the Client to accept a connection from;
+
+
+#### Returns
+Nothing
+
diff --git a/docs/readme.md b/docs/readme.md
new file mode 100644
index 0000000..c1ae8bd
--- /dev/null
+++ b/docs/readme.md
@@ -0,0 +1,20 @@
+# Arduino Modbus Library
+
+This library implements the [Modbus protocol](https://en.wikipedia.org/wiki/Modbus) over two different types of transport: serial communication over RS485 with RTU (Remote Terminal Unit) or Ethernet and WiFi communication with TCP protocol. There are a few differences in the APIs depending on the transport, but the majority of the functions are the same for both.
+Modbus is also a client server protocol where Client = master and Server = slave in Modbus terminilogy; we suggest to read some papers about this protocol if you don't have any former experience because it is based heavily on some formal conventions.
+
+We have organized this reference so that you find the common functions of both transports together and only the transport related functions are given individually. As a rule of thumb, RTU communication is multipoint and therefore the ID of the unit involved in the communication needs to be specified. TCP is point to point using the IP address and therefore there is no need for an ID in the parameters.
+
+The library is available in our Library Manager; it is compatible with our [MKR RS485 Shield](https://store.arduino.cc/products/arduino-mkr-485-shield) and with our network enabled products like the [Ethernet shield](https://store-usa.arduino.cc/products/arduino-ethernet-shield-2), the MKR family of boards and the [Arduino UNO WiFi Rev 2](https://store.arduino.cc/products/arduino-uno-wifi-rev2) just to name a few.
+
+To use this library:
+
+```
+#include <ArduinoModbus.h>
+```
+
+## Further readings
+
+- [Modbus Tutorial from Control Solutions](https://www.csimn.com/CSI_pages/Modbus101.html)
+- [Modbus Application Protocol (PDF)](http://www.modbus.org/docs/Modbus_Application_Protocol_V1_1b3.pdf)
+- [Modbus FAQ](https://modbus.org/faq.php)
\ No newline at end of file