rename writeStringToBuffer and some more documentation rework. (#53)

* fix handler explanation

* Update readme

* Update readme

* change String to Array and pass uint16_t

Author: ysmilda

README.md

@@ -2,60 +2,58 @@
 
 ##### ModbusSlave library for Arduino
 
-This modbus slave library uses callbacks to handle modbus requests for one or multiple slave ids.
-Handler functions are called on modbus request, and the users can implement them in their sketch.
+This Modbus RTU slave library uses callbacks to handle modbus requests for one or multiple slave ids.
+Handler functions are called on modbus a request, and the users can implement them within their sketch.
 
 ### ModbusSlave is fun and easy to use
+
 Register a handler function:
+
 ```c
 slave.cbVector[CB_READ_INPUT_REGISTERS] = ReadAnalogIn;
 ```
+
 Implement it:
+
 ```c
 void ReadAnalogIn(uint8_t fc, uint16_t address, uint16_t length) {
     for (int i = 0; i < length; i++)
         slave.writeRegisterToBuffer(i, analogRead(address + i));
 }
 ```
+
 And thats it, your sketch is modbus enabled. (see the full examples for more detail)
 
-----
+---
 
 - [Install](#install)
-- [Competabilty](#competabilty)
-- [Callback vector](#callback-vector)
-      - [Multiple Slaves](#multiple-slaves)
-      - [Slots](#slots)
-      - [Handler function](#handler-function)
-      - [Function codes](#function-codes)
-      - [Reading and writing to the request buffer](#reading-and-writing-to-the-request-buffer)
-- [Examples](#examples)
-      - [handle "Force Single Coil" as arduino digitalWrite](#handle-force-single-coil-as-arduino-digitalwrite)
-      - [handle "Read Input Registers" as arduino analogRead](#handle-read-input-registers-as-arduino-analogread)
-
-----
+- [Compatibility](#compatibility)
+- [Callback vector](#callback-vector) - [Multiple Slaves](#multiple-slaves) - [Slots](#slots) - [Handler function](#handler-function) - [Function codes](#function-codes) - [Reading and writing to the request buffer](#reading-and-writing-to-the-request-buffer)
+- [Examples](#examples) - [handle "Force Single Coil" as arduino digitalWrite](#handle-force-single-coil-as-arduino-digitalwrite) - [handle "Read Input Registers" as arduino analogRead](#handle-read-input-registers-as-arduino-analogread)
+
+---
 
 ### Install
 
 Download the zip package, and install it into your Arduino IDE. See the Arduino tutorial about installing 3rd party libraries: https://www.arduino.cc/en/Guide/Libraries#toc4
 
-### Competabilty
+### Compatibility
 
 ###### This class implements:
 
-* FC1 "Read Coil Status"
-* FC2 "Read Input Status"
-* FC3 "Read Holding Registers"
-* FC4 "Read Input Registers"
-* FC5 "Force Single Coil"
-* FC6 "Preset Single Register"
-* FC15 "Force Multiple Coils"
-* FC16 "Preset Multiple Registers"
+- FC1 "Read Coil Status"
+- FC2 "Read Input Status"
+- FC3 "Read Holding Registers"
+- FC4 "Read Input Registers"
+- FC5 "Force Single Coil"
+- FC6 "Preset Single Register"
+- FC15 "Force Multiple Coils"
+- FC16 "Preset Multiple Registers"
 
 ### Serial port
 
-* The default serial port is Serial, but any class that inhirets from Stream can be used.
-To set a different Serial class, explicitly set the Stream in the Modbus class constuctor.
+- The default serial port is Serial, but any class that inherits from the Stream class can be used.
+  To set a different Serial class, explicitly pass the Stream in the Modbus class constuctor.
 
 ### Callback vector
 
@@ -67,127 +65,141 @@ This can be done independently for one or multiple slaves with different IDs.
 
 ###### Slots
 
-The callback vector has 4 slots for request handlers:
+The callback vector has 7 slots for request handlers:
 
-* slave.cbVector[CB_READ_COILS] - called on FC1
-* slave.cbVector[CB_READ_DISCRETE_INPUTS] - called on FC2
-* slave.cbVector[CB_READ_HOLDING_REGISTERS] - called on FC3
-* slave.cbVector[CB_READ_INPUT_REGISTERS] - called on FC4
-* slave.cbVector[CB_WRITE_COILS] - called on FC5 and FC15
-* slave.cbVector[CB_WRITE_HOLDING_REGISTERS] - called on FC6 and FC16
+- slave.cbVector[CB_READ_COILS] - called on FC1
+- slave.cbVector[CB_READ_DISCRETE_INPUTS] - called on FC2
+- slave.cbVector[CB_READ_HOLDING_REGISTERS] - called on FC3
+- slave.cbVector[CB_READ_INPUT_REGISTERS] - called on FC4
+- slave.cbVector[CB_WRITE_COILS] - called on FC5 and FC15
+- slave.cbVector[CB_WRITE_HOLDING_REGISTERS] - called on FC6 and FC16
+- slave.cbVector[CB_READ_EXCEPTION_STATUS] - called on FC7
 
 ###### Handler function
 
-Handler functions must return unit8_t and take:
-* uint8_t  fc - request function code
-* uint16_t address - first register / first coil address
-* uint16_t length - length of data
-
-Return codes:
-
-*  STATUS_OK = 0,
-*  STATUS_ILLEGAL_FUNCTION,
-*  STATUS_ILLEGAL_DATA_ADDRESS,
-*  STATUS_ILLEGAL_DATA_VALUE,
-*  STATUS_SLAVE_DEVICE_FAILURE,
-*  STATUS_ACKNOWLEDGE,
-*  STATUS_SLAVE_DEVICE_BUSY,
-*  STATUS_NEGATIVE_ACKNOWLEDGE,
-*  STATUS_MEMORY_PARITY_ERROR,
-*  STATUS_GATEWAY_PATH_UNAVAILABLE,
-*  STATUS_GATEWAY_TARGET_DEVICE_FAILED_TO_RESPOND
+A handler functions must return an uint8_t code and take the following as parameters:
+
+- uint8_t fc - request function code
+- uint16_t address - first register / first coil address
+- uint16_t length - length of data
+
+Usable return codes:
+
+- STATUS_OK = 0,
+- STATUS_ILLEGAL_FUNCTION,
+- STATUS_ILLEGAL_DATA_ADDRESS,
+- STATUS_ILLEGAL_DATA_VALUE,
+- STATUS_SLAVE_DEVICE_FAILURE,
+- STATUS_ACKNOWLEDGE,
+- STATUS_SLAVE_DEVICE_BUSY,
+- STATUS_NEGATIVE_ACKNOWLEDGE,
+- STATUS_MEMORY_PARITY_ERROR,
+- STATUS_GATEWAY_PATH_UNAVAILABLE,
+- STATUS_GATEWAY_TARGET_DEVICE_FAILED_TO_RESPOND
 
 ###### Function codes
 
-* FC_READ_COILS = 1
-* FC_READ_DISCRETE_INPUT = 2
-* FC_READ_REGISTERS = 3
-* FC_READ_INPUT_REGISTERS = 4
-* FC_WRITE_COIL = 5
-* FC_WRITE_REGISTER = 6
-* FC_WRITE_MULTIPLE_COILS = 15
-* FC_WRITE_MULTIPLE_REGISTERS = 16
+- FC_READ_COILS = 1
+- FC_READ_DISCRETE_INPUT = 2
+- FC_READ_REGISTERS = 3
+- FC_READ_INPUT_REGISTERS = 4
+- FC_WRITE_COIL = 5
+- FC_WRITE_REGISTER = 6
+- FC_READ_EXCEPTION_STATUS = 7
+- FC_WRITE_MULTIPLE_COILS = 15
+- FC_WRITE_MULTIPLE_REGISTERS = 16
 
-----
+---
 
 ###### Reading and writing to the request / response buffer
 
-* int readCoilFromBuffer(int offset) : read one coil value from the request buffer.
-* uint16_t readRegisterFromBuffer(int offset) : read one register value from the request buffer.
-* void writeCoilToBuffer(int offset, int state) : write one coil state into the answer buffer.
-* void writeRegisterToBuffer(int offset, uint16_t value) : write one register value into the answer buffer.
+- bool readCoilFromBuffer(int offset) : read one coil value from the request buffer.
+- uint16_t readRegisterFromBuffer(int offset) : read one register value from the request buffer.
+- uint8_t writeExceptionStatusToBuffer(int offset, bool status) : write an exception status into the response buffer.
+- uint8_t writeCoilToBuffer(int offset, int state) : write one coil state into the response buffer.
+- uint8_t writeDiscreteInputToBuffer(int offset, bool state) : write one discrete input value into the response buffer.
+- uint8_t writeRegisterToBuffer(int offset, uint16_t value) : write one register value into the response buffer.
+- uint8_t writeArrayToBuffer(int offset, uint16_t \*str, uint8_t length); : writes an array of data into the response register.
 
-----
+---
 
 ### Examples
 
-----
-###### handle "Force Single Coil" as arduino digitalWrite
-```c
+---
+
+###### Handle "Force Single Coil" and write the received value to digitalWrite()
+```cpp
 #include <ModbusSlave.h>
 
-// implicitly set stream to use the Serial serialport
+// Implicitly set stream to use the Serial serialport.
 Modbus slave(1, 8); // [stream = Serial,] slave id = 1, rs485 control-pin = 8
 
 void setup() {
-    // register one handler functions
-    // if a callback handler is not assigned to a modbus command 
-    // the default handler is called. 
-    // default handlers return a valid but empty replay.
-    slave.cbVector[CB_WRITE_COILS] = writeDigitlOut;
-    
-    // start slave at baud 9600 on Serial
-    Serial.begin( 9600 ); // baud = 9600
-    slave.begin( 9600 );
+    // Register functions to call when a certain function code is received.
+    // If there is no handler assigned to the function code a valid but empty message will be replied.
+    slave.cbVector[CB_WRITE_COILS] = writeDigitalOut;
+
+    // Start the slave at a baudrate of 9600bps on the Serial port.
+    Serial.begin(9600);
+    slave.begin(9600);
 }
 
 void loop() {
-    // listen for modbus commands con serial port
+    // Listen for modbus requests on the serial port.
+    // When a request is received it's going to get validated.
+    // And if there is a function registered to the received function code, this function will be executed.
     slave.poll();
 }
 
-// Handel Force Single Coil (FC=05)
-uint8_t writeDigitlOut(uint8_t fc, uint16_t address, uint16_t length) {
-    if (slave.readCoilFromBuffer(0) == HIGH) {
+// Handel Force Single Coil (FC=05).
+uint8_t writeDigitalOut(uint8_t fc, uint16_t address, uint16_t length) {
+    if (slave.readCoilFromBuffer(0) == HIGH)
+    {
         digitalWrite(address, HIGH);
-    } else {
+    }
+    else
+    {
         digitalWrite(address, LOW);
     }
     return STATUS_OK;
 }
 
 ```
 
-----
-###### handle "Read Input Registers" as arduino analogRead
-```c
+---
+
+###### Handle "Read Input Registers" and return analogRead()
+
+```cpp
 #include <ModbusSlave.h>
 
-// explicitly set stream to use the Serial serialport
+// Explicitly set a stream to use the Serial port.
 Modbus slave(Serial, 1, 8); // stream = Serial, slave id = 1, rs485 control-pin = 8
 
 void setup() {
-    // register handler functions
-    slave.cbVector[CB_READ_INPUT_REGISTERS] = ReadAnalogIn;
-    
-    // start slave at baud 9600 on Serial
-    Serial.begin( 9600 ); // baud = 9600
-    slave.begin( 9600 );
+    // Register functions to call when a certain function code is received.
+    // If there is no handler assigned to the function code a valid but empty message will be replied.
+    slave.cbVector[CB_WRITE_COILS] = readAnalogIn;
+
+    // Start the slave at a baudrate of 9600bps on the Serial port.
+    Serial.begin(9600);
+    slave.begin(9600);
 }
 
 void loop() {
-    // listen for modbus commands con serial port
+    // Listen for modbus requests on the serial port.
+    // When a request is received it's going to get validated.
+    // And if there is a function registered to the received function code, this function will be executed.
     slave.poll();
 }
 
-// Handel Read Input Registers (FC=04)
-uint8_t ReadAnalogIn(uint8_t fc, uint16_t address, uint16_t length) {
-    // write registers into the answer buffer
+// Handle Read Input Registers (FC=04).
+uint8_t readAnalogIn(uint8_t fc, uint16_t address, uint16_t length) {
+    // Write the result of analogRead() into the response buffer.
     for (int i = 0; i < length; i++) {
       slave.writeRegisterToBuffer(i, analogRead(address + i));
     }
     return STATUS_OK;
 }
 
 ```
-

examples/full/full.ino

@@ -86,7 +86,7 @@ void loop()
 }
 
 // Modbus handler functions
-// The handler functions must return void and take the following parameters:
+// The handler functions must return an uint8_t and take the following parameters:
 //     uint8_t  fc - function code
 //     uint16_t address - first register/coil address
 //     uint16_t length/status - length of data / coil status

examples/multi/multi.ino

@@ -62,6 +62,12 @@ void loop()
     modbus.poll();
 }
 
+// Modbus handler functions
+// The handler functions must return an uint8_t and take the following parameters:
+//     uint8_t  fc - function code
+//     uint16_t address - first register/coil address
+//     uint16_t length/status - length of data / coil status
+
 // Handle the function code Read Holding Registers (FC=03).
 uint8_t readMemorySlave1(uint8_t fc, uint16_t address, uint16_t length)
 {

examples/simple/simple.ino

@@ -92,7 +92,7 @@ void loop()
 }
 
 // Modbus handler functions
-// The handler functions must return void and take the following parameters:
+// The handler functions must return an uint8_t and take the following parameters:
 //     uint8_t  fc - function code
 //     uint16_t address - first register/coil address
 //     uint16_t length/status - length of data / coil status

src/ModbusSlave.cpp

@@ -462,31 +462,36 @@ uint8_t Modbus::writeRegisterToBuffer(int offset, uint16_t value)
     }
 
     _responseBuffer[index] = value >> 8;
-    _responseBuffer[index + 1] = value & 0xff;
+    _responseBuffer[index + 1] = value & 0xFF;
 
     return STATUS_OK;
 }
 
 /**
  * Writes an uint8_t array to the output buffer.
  *
- * @param offset The offset from the first register in the buffer.
- * @param str The array to write into the buffer.
- * @param length The array length.
+ * @param offset The offset from the first data register in the response buffer.
+ * @param str The array to write into the response buffer.
+ * @param length The length of the array.
  * @return STATUS_OK if succeeded, STATUS_ILLEGAL_DATA_ADDRESS if the data doesn't fit in the buffer.
  */
-uint8_t Modbus::writeStringToBuffer(int offset, uint8_t *str, uint8_t length)
+uint8_t Modbus::writeArrayToBuffer(int offset, uint16_t *str, uint8_t length)
 {
-    // (1 x valueBytes, n x values).
+    // Index to start writing from (1 x valueBytes, n x values (offset)).
     uint8_t index = MODBUS_DATA_INDEX + 1 + (offset * 2);
 
-    // Check the length of the array.
-    if ((index + length) > _responseBufferLength - MODBUS_CRC_LENGTH)
+    // Check if the array fits in the remaining space of the response.
+    if ((index + (length * 2)) > _responseBufferLength - MODBUS_CRC_LENGTH)
     {
+        // If not return an exception.
         return STATUS_ILLEGAL_DATA_ADDRESS;
     }
 
-    memcpy(_responseBuffer + index, str, length);
+    for (int i = 0; i < length; i++)
+    {
+        _responseBuffer[index + (i * 2)] = str[i] >> 8;
+        _responseBuffer[index + (i * 2) + 1] = str[i] & 0xFF;
+    }
 
     return STATUS_OK;
 }
@@ -851,7 +856,7 @@ uint16_t Modbus::writeResponse()
 
         // Calculate and add the CRC.
         uint16_t crc = Modbus::calculateCRC(_responseBuffer, _responseBufferLength - MODBUS_CRC_LENGTH);
-        _responseBuffer[_responseBufferLength - MODBUS_CRC_LENGTH] = crc & 0xff;
+        _responseBuffer[_responseBufferLength - MODBUS_CRC_LENGTH] = crc & 0xFF;
         _responseBuffer[(_responseBufferLength - MODBUS_CRC_LENGTH) + 1] = crc >> 8;
 
         // Start transmission mode for RS485.

src/ModbusSlave.h

@@ -112,7 +112,7 @@ class Modbus
   uint8_t writeCoilToBuffer(int offset, bool state);
   uint8_t writeDiscreteInputToBuffer(int offset, bool state);
   uint8_t writeRegisterToBuffer(int offset, uint16_t value);
-  uint8_t writeStringToBuffer(int offset, uint8_t *str, uint8_t length);
+  uint8_t writeArrayToBuffer(int offset, uint16_t *str, uint8_t length);
 
   uint8_t readFunctionCode();
   uint8_t readUnitAddress();