budulinek
diff --git a/‎README.md
Lines changed: 97 additions & 62 deletions b/‎README.md
Lines changed: 97 additions & 62 deletions
@@ -9,102 +9,146 @@ Change settings of your Arduino-based Modbus RTU to Modbus TCP/UDP gateway via w
 
 ## What are the technical specifications?
 
-* slaves are connected via RS485 interface
-* master(s) are connected via ethernet interface
-* up to 247 Modbus RTU slaves
-* up to 7 Modbus TCP masters
-* unlimited number of Modbus UDP masters
+* slaves are connected via RS485 interface:
+  - up to 247 Modbus RTU slaves
+* master(s) are connected via ethernet interface:
+  - up to 6 Modbus TCP masters (depending on hardware)
+  - unlimited number of Modbus UDP masters
 * RS485 interface protocols:
   - Modbus RTU
-* Ethernet interface protocols:
+* ethernet interface protocols:
   - Modbus TCP
   - Modbus UDP
   - Modbus RTU over TCP
   - Modbus RTU over UDP
-* supports broadcast (slave address 0x00) and error codes
+* supports broadcast (slave address 0x00)
 * supports all Modbus function codes
-* diagnostics and Modbus RTU scan via web interface
-* optimized queue for Modbus requests (queue will accept only one requests to non-responding slaves)
-* settings can be changed via web interface, they are stored in EEPROM
-* user settings are retained during firmware upgrade (only in case of major VERSION change, Arduino loads factory defaults).
+* supports error codes:
+  - codes 1~8 are forwarded from slaves
+  - codes 10, 11 are generated by the gateway
+* diagnostics via web interface:
+  - send Modbus request and recieve Modbus response
+  - scan Modbus slaves on RS485 interface
+  - queue (buffer) status
+  - error counts
+  - content of the Modbus Status page is updated in the background (fetch API), javascript alert is shown if connection is lost
+* optimized TCP socket management (web interface and Modbus TCP):
+  - gateway always listens for new web and Modbus TCP connections
+  - existing connections are kept alive (persistent), unless the gateway runs out of available sockets
+  - if there are no available sockets, oldest connections are closed after they are idle for a certain time, Modbus TCP idle timeout is configured in user settings (web UI), webserver idle timeout is configured in advanced settings (sketch)
+* optimized queue (buffer) for Modbus requests:
+  - queue will accept only one requests to a non-responding slave
+  - requests to responding slaves are prioritized over requests to non-responding slaves
+  - queue size configured in advanced settings (sketch)
+* user settings:
+  - can be changed via web interface (see screenshots bellow)
+  - stored in EEPROM
+  - retained during firmware upgrade (only in case of major version change, Arduino loads factory defaults)
+  - all web interface inputs have proper validation
+  - settings marked \* are only available if ENABLE_DHCP is defined in the sketch
+  - settings marked \*\* are only available if ENABLE_EXTRA_DIAG is defined in the sketch
+* advanced settings:
+  - can be changed in sketch (see the initial section of arduino-modbus-rtu-tcp-gateway.ino)
+  - stored in flash memory
 
 <img src="/pics/modbus1.png" alt="01" style="zoom:100%;" />
 
-### System Info:
-
-**Load Default Settings**. Loads default settings (see DEFAULT_CONFIG in arduino-modbus-rtu-tcp-gateway.ino)
+**Load Default Settings**. Loads default settings (see DEFAULT_CONFIG in advanced settings). MAC address is retained.
 
 **Reboot**.
 
-**Generate New MAC**. Generate new MAC address. Fisrt 3 bytes are fixed 90:A2:DA, remaining 3 bytes are true random.
+**Generate New MAC**. Generate new MAC address. First 3 bytes are fixed 90:A2:DA, remaining 3 bytes are true random.
 
 <img src="/pics/modbus2.png" alt="02" style="zoom:100%;" />
 
-### Modbus Status:
+**Modbus RTU Request**. Send a Modbus RTU request directly from web UI. First byte (slave address) and second byte (function code) are mandatory, no need to calculate CRC. Gateway remembers last request for your convenience.
 
-**Run Time**.
+**Modbus RTU Response**. Shows response to the last Modbus request. Response is shown in Modbus RTU format (incl. CRC). Due to memory limitations, only few initial bytes are shown.
 
-**Modbus Statistics**.
+**Run Time**.\*\* Days, hours, minutes and seconds since boot or stat reset.
 
-**Requests Queue**.
+**RTU Data**.\*\* Counter for bytes sent and received via RS485.
 
-**Modbus TCP/UDP Masters**.
+**Ethernet Data**.\*\* Counter for bytes sent and received via Modbus TCP/UDP.
 
-**Modbus Slaves**.
+**Requests Queue**. Monitors internal request queue (buffer). The limits for bytes and for the number of requests stored in the queue can be configured in advanced settings.
 
-**Scan Slaves**.
+**Modbus Statistics**. Counters for various errors. Insigned longs are used, rollover of counters is synchronized:
+* **Slave Responded**. Slave responded with a valid Modbus RTU response within response timeout.
+* **Slave Responded with Error (Codes 1~8)**. Slave responded, but with an error. For the list of error codes see https://en.wikipedia.org/wiki/Modbus#Exception_responses.
+* **Gateway Overloaded (Code 10)**. Request queue is full (either the number of bytes stored or the number of requests stored). Request was dropped and the gateway responded with an error code 10.
+* **Slave Failed to Respond (Code 11)**. Slave is not responding. Response timeouts have passed, all attempts have failed. The gateway responded with an error code 11.
+* **Invalid TCP/UDP Request**. Invalid request was received via TCP or UDP. Request was dropped, no response was sent by the gateway. Validation criteria depends on the Modbus mode:
+  - Modbus TCP/UDP: MBAP header (protocol identifier is 0x0000, length is < 255 and corresponds to the number of bytes in the remainder of the Modbus request)
+  - Modbus RTU over TCP/UDP: CRC ckeck
+* **Invalid RTU Response**. Invalid data were recieved via RS485. Could be caused by wrong Modbus RTU settings, short response timeout (any response arriving after timeout is invalid) or Arduino delays in processing the response. Validation criteria:
+  - silence between individual bytes is shorter than char timeout specified in Modbus RTU standards
+  - CRC check
+  - slave address in the Modbus RTU response corresponds to the slave address in the request
+  - response arrived before response timeout
+* **Response Timeout**. Slave failed to respond within the specified response timeout. New attempt follows (or error code 11 if all attempts were spent).
 
-<img src="/pics/modbus3.png" alt="03" style="zoom:100%;" />
+**Modbus Masters**. Shows IP addresses for Modbus TCP or UDP masters:
+* **UDP**. Only the last Modbus UDP master is shown, because all UDP masters connect to the same socket.
+* **TCP**. All connected Modbus TCP masters are shown. Each Modbus TCP connection occupies one socket.
 
-### IP Settings:
+**Modbus Slaves**. Shows the slave address (in hex) and the last status (error) for all slaves who responded to a slave scan or who were recipients of a Modbus request.
 
-**Auto IP**. Only if ENABLE_DHCP. Once enabled, Arduino will receive IP, gateway, subnet and DNS from the DHCP server.
+**Scan Slaves**. An attempt is made to find Modbus RTU slaves connected to the RS485 interface:
+  - scan is launched automaticaly after boot or manualy
+  - scans all slave addresses 1 - 247
+  - dummy requests are sent to each slave address for two different Modbus functions (configured in advanced settings)
+  - fixed response timeout (very short, configured in advanced settings), only one attempt
+  - gateway marks the slave as "Slave Responded" if any response is sent by the slave (even error)
 
-**Static IP**.
+
+<img src="/pics/modbus3.png" alt="03" style="zoom:100%;" />
+
+**Auto IP**.\* Once enabled, Arduino will receive IP, gateway, subnet and DNS from the DHCP server.
+
+**Static IP**. Set new static IP address. Gateway automatically redirect the web interface to the new IP.
 
 **Submask**.
 
 **Gateway**.
 
-**DNS**. Only if ENABLE_DHCP.
+**DNS**.\*
 
 <img src="/pics/modbus4.png" alt="04" style="zoom:100%;" />
 
-### TCP/UDP Settings:
-
 **Modbus TCP Port**.
 
-**Modbus UDP Port**.
+**Modbus UDP Port**. Can be the same as Modbus TCP Port.
 
-**Web Port**.
+**Web Port**. Gateway automatically redirect the web interface to the new Web UI port.
 
-**Modbus Mode**. Modbus TCP/UDP or Modbus RTU over TCP/UDP.
+**Modbus Mode**. Modbus TCP/UDP or Modbus RTU over TCP/UDP. Be aware that "Modbus RTU over TCP/UDP" is not a standard Modbus protocol. In this mode, the gateway expects to recieve Modbus RTU request (incl. CRC) via TCP or UDP. Responses from RS485 line are forwarded as they are in Modbus RTU format (incl. CRC).
+
+**Modbus TCP Idle Timeout**. Amount of time that a connection is always held alive (open) with no incoming traffic from a Modbus TCP master. This timeout should be longer than polling period (scan rate) set on your Modbus TCP master device.
 
 <img src="/pics/modbus5.png" alt="05" style="zoom:100%;" />
 
-### RS485 Settings:
+**Baud Rate**. Choose baud rate from a pre-aranged list. The list can be adjusted in advanced settings.
 
-**Baud Rate**.
+**Data Bits**. Data bits available on arduino HW serial line: 5, 6, 7, 8.
 
-**Data Bits**.
+**Parity**. Parity options available on arduino HW serial line: None, Even, Odd.
 
-**Parity**.
+**Stop Bits**. 1 or 2 stop bits.
 
-**Stop Bits**.
+**Inter-frame Delay**. Delay (ms) between the end of reading Modbus RTU frame and writing new frame. Higher Frame Delay is needed for RS485 modules with automatic flow control. Increase Frame Delay if you have very short polling period and Response Timeouts in stats. The minimum Inter-frame Delay is calculated from baud rate according to Modbus standards.
 
-**Frame Delay**. Delay (ms) between the end of reading Modbus RTU frame and writing new frame. Higher Frame Delay is needed for RS485 modules with automatic flow control. Increase Frame Delay if you see Response Timeouts in stats.
+**Response Timeout**. Timeout for Modbus RTU response. Increase Response Timeout if you see Response Timeouts in Modbus statistics.
 
-**Response Timeout**.
+**Attempts**. Number of attempts before error (Code 11) is sent back to the Modbus TCP/UDP master.
 
-**Attempts**.
-    
 ## How can I build it myself?
 Get the hardware (cheap clones from China are sufficient) and connect together:
 
-* Arduino Nano, Uno or Mega (and possibly other). On Mega you have to configure Serial in ADVANCED SETTINGS in the sketch.
-* W5100, W5200 or W5500 based Ethernet shield (for Nano, I recommend W5500 Ethernet Shield from RobotDyn)
-* TTL to RS485 module:
-  - with hardware automatic flow control (recommended)<br>
+* **Arduino Nano, Uno or Mega** (and possibly other). On Mega you have to configure Serial in advanced settings in the sketch.
+* **W5100, W5200 or W5500 based Ethernet shield**. The ubiquitous W5100 shield for Uno/Mega is sufficient. If available, I recommend W5500 Ethernet Shield. !!! ENC28J60 will not work !!!
+* **TTL to RS485 module**:
+  - with hardware automatic flow control (recommended, available on Aliexpress)<br>
       Arduino <-> Module<br>
       Tx1 <-> Tx<br>
       Rx0 <-> Rx
@@ -113,13 +157,12 @@ Get the hardware (cheap clones from China are sufficient) and connect together:
       Tx1 <-> DI<br>
       Rx0 <-> RO<br>
       Pin 6 <-> DE,RE
-      
 
 Here is my setup:
-Terminal shield + Arduino Nano + W5500 eth shield (RobotDyn) + TTL to RS485 module (HW automatic flow control)
+Terminal shield + Arduino Nano + W5500 ethernet shield (RobotDyn) + TTL to RS485 module (HW automatic flow control)
 <img src="/pics/HW.jpg" alt="01" style="zoom:100%;" />
 
-Download this repository (all *.ino files) and open arduino-modbus-rtu-tcp-gateway.ino in Arduino IDE. Download all required libraries (both are available in "library manager"). If you want, you can check the default factory settings (can be later changed via web interface) and advanced settings (can only be changed in sketch). Compile and upload your program to Arduino. Connect your Arduino to ethernet, connect your Modbus RTU slaves to MAX485 module. Use your web browser to access the web interface on default IP  http://192.168.1.254   Enjoy :-)
+Download this repository (all *.ino files) and open arduino-modbus-rtu-tcp-gateway.ino in Arduino IDE. Download all required libraries (they are available in "library manager"). If you want, you can check the default factory settings (can be later changed via web interface) and advanced settings (can only be changed in the sketch). Compile and upload your program to Arduino. Connect your Arduino to ethernet, connect your Modbus RTU slaves to MAX485 module. Use your web browser to access the web interface on default IP  http://192.168.1.254   Enjoy :-)
 
 ## Where can I learn more about Modbus protocols?
 
@@ -136,7 +179,7 @@ The key to success is:
 
 * use StreamLib https://github.com/jandrassy/StreamLib
 * use F macros for your HTML code
-* use for() loop for repetitive code
+* use for() loop or dedicated functions for repetitive code
 * use POST method (rather than GET) for your webforms, see this tutorial https://werner.rothschopf.net/202003_arduino_webserver_post_en.htm
 
 Big thanks to the authors of these libraries and tutorials!
@@ -147,27 +190,19 @@ Big thanks to the authors of these libraries and tutorials!
 
 The code was tested on Arduino Nano, Uno and Mega, ethernet chips W5100 and W5500. It may work on other platforms, but:
 
-* The pseudorandom generator (for random MAC) is seeded through watch dog timer interrupt - this will work only on Arduino (credits to https://sites.google.com/site/astudyofentropy/project-definition/timer-jitter-entropy-sources/entropy-library/arduino-random-seed)
+* The random number generator (for random MAC) is seeded through watch dog timer interrupt - this will work only on Arduino (credits to https://sites.google.com/site/astudyofentropy/project-definition/timer-jitter-entropy-sources/entropy-library/arduino-random-seed)
 * The restart function will also work only on Arduino.
 
-#### Ethernet socket
+#### Ethernet sockets
 
-The default Ethernet.h library determines MAX_SOCK_NUM by microcontroller RAM (not by Ethernet chip type). So if you use W5500 (which has 8 sockets available) on Arduino Nano, only 4 sockets will be used. If you want to force the library to use 8 sockets, redefine MAX_SOCK_NUM in advanced settings in the sketch.
+The number of used sockets is determined (by the Ethernet.h library) based on microcontroller RAM. Therefore, even if you use W5500 (which has 8 sockets available) on Arduino Nano, only 4 sockets will be used due to limited RAM on Nano.
 
 #### Memory
 
-Not everything could fit into the limited flash memory of Arduino Nano / Uno. If you have a microcontroller with more memory (such as Mega), you can enable extra features in the main sketch by uncommenting:
-
-* #define ENABLE_DHCP will allow you to set "Auto IP" via DHCP in the IP settings web interface. Leased IP is automatically renewed.
-
-<img src="/pics/modbus6.png" alt="06" style="zoom:100%;" />
-
-* #define ENABLE_EXTRA_DIAG  shows extra info on "Current status" page: per socket diagnostics, run time counter, ethernet data counter.
-
-<img src="/pics/modbus1x.png" alt="01x" style="zoom:100%;" />
+Not everything could fit into the limited flash memory of Arduino Nano / Uno. If you have a microcontroller with more memory (such as Mega), you can enable extra settings in the main sketch by defining ENABLE_DHCP and/or ENABLE_EXTRA_DIAG in the sketch.
 
 ## Version history
 
 For version history see:
- 
+
 https://github.com/budulinek/arduino-modbus-rtu-tcp-gateway/blob/master/arduino-modbus-rtu-tcp-gateway/arduino-modbus-rtu-tcp-gateway.ino#L27