From 6932b4d1c0995f77a4be4caa8d795d137692fa48 Mon Sep 17 00:00:00 2001 From: aleks Date: Mon, 25 May 2020 13:29:08 +0200 Subject: [PATCH] freemodbus: add comments for limitation in current version of freemodbus --- components/freemodbus/README.rst | 6 + docs/en/api-reference/protocols/modbus.rst | 7 + examples/protocols/modbus/serial/README.md | 84 ++++++++++ .../modbus/serial/mb_master/README.md | 154 ++++++++++++++++++ examples/protocols/modbus_slave/README.md | 3 +- 5 files changed, 253 insertions(+), 1 deletion(-) create mode 100644 components/freemodbus/README.rst create mode 100644 examples/protocols/modbus/serial/README.md create mode 100644 examples/protocols/modbus/serial/mb_master/README.md diff --git a/components/freemodbus/README.rst b/components/freemodbus/README.rst new file mode 100644 index 000000000..0c9d8f41b --- /dev/null +++ b/components/freemodbus/README.rst @@ -0,0 +1,6 @@ +# Modbus assumptions, dependencies and constraints + +1. Current implementation of Modbus has limitation: maximum frame size should be less than 120 bytes (default UART receive FIFO full threshold value). +This limitation is removed in ESP-IDF v4.2. + +2. The only one instance of Modbus port can be initialized at the same time. diff --git a/docs/en/api-reference/protocols/modbus.rst b/docs/en/api-reference/protocols/modbus.rst index b9fb8cb99..189bb9a89 100644 --- a/docs/en/api-reference/protocols/modbus.rst +++ b/docs/en/api-reference/protocols/modbus.rst @@ -109,3 +109,10 @@ The examples below use the FreeModbus library port for slave and master implemen Please refer to the specific example README.md for details. +Modbus Readme File +------------------ + + +.. include:: ../../../../components/freemodbus/README.rst + + diff --git a/examples/protocols/modbus/serial/README.md b/examples/protocols/modbus/serial/README.md new file mode 100644 index 000000000..a1e2b5ef2 --- /dev/null +++ b/examples/protocols/modbus/serial/README.md @@ -0,0 +1,84 @@ +# Modbus Master-Slave Example + +## Overview + +These two projects illustrate the communication between Modbus master and slave device in the segment. +Master initializes Modbus interface driver and then reads parameters from slave device in the segment. +After several successful read attempts slave sets the alarm relay (end of test condition). +Once master reads the alarm it stops communication and destroy driver. + +The examples: + +* `examples/protocols/modbus/serial/mb_master` - Modbus serial master ASCII/RTU +* `examples/protocols/modbus/serial/mb_slave` - Modbus serial slave ASCII/RTU + +See README.md for each individual project for more information. + +## How to use example + +### Hardware Required + +This example can be run on any commonly available ESP32 development board. +The master and slave boards should be connected to each other through the RS485 interface line driver. +See the connection schematic in README.md files of each example. + +### Configure the project + +This example test requires communication mode setting for master and slave be the same and slave address set to 1. +Please refer to README.md files of each example project for more information. + +## About common_component in this example + +The folder "mb_example_common" includes definitions of parameter structures for master and slave device (both projects share the same parameters). +However, currently it is for example purpose only and can be modified for particular application. + +## Example Output + +Example of Slave output: + +``` +I (343) SLAVE_TEST: Modbus slave stack initialized. +I (343) SLAVE_TEST: Start modbus test... +I (81463) SLAVE_TEST: HOLDING READ (81150420 us), ADDR:1, TYPE:2, INST_ADDR:0x3ffb2868, SIZE:6 +I (82463) SLAVE_TEST: HOLDING READ (82150720 us), ADDR:1, TYPE:2, INST_ADDR:0x3ffb2868, SIZE:6 +I (83573) SLAVE_TEST: HOLDING READ (83260630 us), ADDR:1, TYPE:2, INST_ADDR:0x3ffb2868, SIZE:6 +I (84603) SLAVE_TEST: HOLDING READ (84290530 us), ADDR:1, TYPE:2, INST_ADDR:0x3ffb2868, SIZE:6 +I (85703) SLAVE_TEST: HOLDING READ (85396692 us), ADDR:1, TYPE:2, INST_ADDR:0x3ffb2868, SIZE:6 +``` + +Example of Modbus Master output: + +``` +I (399) MASTER_TEST: Modbus master stack initialized... +I (499) MASTER_TEST: Start modbus test... +I (549) MASTER_TEST: Characteristic #0 Data_channel_0 (Volts) value = 1.230000 (0x3f9d70a4) read successful. +I (629) MASTER_TEST: Characteristic #1 Humidity_1 (%rH) value = 12.100000 (0x4141999a) read successful. +I (709) MASTER_TEST: Characteristic #2 Temperature_1 (C) value = 3.560000 (0x4063d70a) read successful. +I (769) MASTER_TEST: Characteristic #3 Humidity_2 (%rH) value = 23.400000 (0x41bb3333) read successful. +I (829) MASTER_TEST: Characteristic #4 Temperature_2 (C) value = 5.890000 (0x40bc7ae1) read successful. +I (889) MASTER_TEST: Characteristic #5 Humidity_3 (%rH) value = 34.500000 (0x420a0000) read successful. +E (949) MB_CONTROLLER_MASTER: mbc_master_get_parameter(111): SERIAL master get parameter failure error=(0x108) (ESP_ERR_INVALID_RESPONSE). +E (949) MASTER_TEST: Characteristic #6 (RelayP1) read fail, err = 264 (ESP_ERR_INVALID_RESPONSE). +E (1029) MB_CONTROLLER_MASTER: mbc_master_get_parameter(111): SERIAL master get parameter failure error=(0x108) (ESP_ERR_INVALID_RESPONSE). +E (1029) MASTER_TEST: Characteristic #7 (RelayP2) read fail, err = 264 (ESP_ERR_INVALID_RESPONSE). +``` + +## Troubleshooting + +If the examples do not work as expected and slave and master boards are not able to communicate correctly it is possible to find the reason for errors. +The most important errors are described in master example output and formatted as below: + +``` +E (1692332) MB_CONTROLLER_MASTER: mbc_master_get_parameter(111): SERIAL master get parameter failure error=(0x107) (ESP_ERR_TIMEOUT). +``` + +ESP_ERR_TIMEOUT (0x107) - Modbus slave device does not respond during configured timeout. Check the connection and ability for communication using uart_echo_rs485 example or increase +Kconfig value CONFIG_FMB_MASTER_TIMEOUT_MS_RESPOND (CONFIG_FMB_SERIAL_ASCII_TIMEOUT_RESPOND_MS). + +ESP_ERR_NOT_SUPPORTED (0x106), ESP_ERR_INVALID_RESPONSE (0x108) - Modbus slave device does not support requested command or register and sent exeption response. + +ESP_ERR_INVALID_STATE (0x103) - Modbus stack is not configured correctly or can't work correctly due to critical failure. + +Note: Refer to file below for more information about current implementation of Modbus: + +* `components/freemodbus/README.rst` \ No newline at end of file diff --git a/examples/protocols/modbus/serial/mb_master/README.md b/examples/protocols/modbus/serial/mb_master/README.md new file mode 100644 index 000000000..6132676d5 --- /dev/null +++ b/examples/protocols/modbus/serial/mb_master/README.md @@ -0,0 +1,154 @@ +# Modbus Master Example + +This example demonstrates using of FreeModbus stack port implementation for ESP32 as a master device. +This implementation is able to read/write values of slave devices connected into Modbus segment. All parameters to be accessed are defined in data dictionary of the modbus master example source file. +The values represented as characteristics with its name and characteristic CID which are linked into registers of slave devices connected into Modbus segment. +The example implements simple control algorithm and checks parameters from slave device and gets alarm (relay in the slave device) when value of holding_data0 parameter exceeded limit. +The instances for the modbus parameters are common for master and slave examples and located in examples\protocols\modbus\serial\common_components folder. + +Example parameters definition: +-------------------------------------------------------------------------------------------------- +| Slave Address | Characteristic ID | Characteristic name | Description | +|---------------------|----------------------|----------------------|----------------------------| +| MB_DEVICE_ADDR1 | CID_INP_DATA_0, | Data_channel_0 | Data channel 1 | +| MB_DEVICE_ADDR1 | CID_HOLD_DATA_0, | Humidity_1 | Humidity 1 | +| MB_DEVICE_ADDR1 | CID_INP_DATA_1 | Temperature_1 | Sensor temperature | +| MB_DEVICE_ADDR1 | CID_HOLD_DATA_1, | Humidity_2 | Humidity 2 | +| MB_DEVICE_ADDR1 | CID_INP_DATA_2 | Temperature_2 | Ambient temperature | +| MB_DEVICE_ADDR1 | CID_HOLD_DATA_2 | Humidity_3 | Humidity 3 | +| MB_DEVICE_ADDR1 | CID_RELAY_P1 | RelayP1 | Alarm Relay outputs on/off | +| MB_DEVICE_ADDR1 | CID_RELAY_P2 | RelayP2 | Alarm Relay outputs on/off | +-------------------------------------------------------------------------------------------------- +Note: The Slave Address is the same for all parameters for example test but it can be changed in the ```Example Data (Object) Dictionary``` table of master example to address parameters from other slaves. +The Kconfig ```Modbus slave address``` - CONFIG_MB_SLAVE_ADDR parameter in slave example can be configured to create Modbus multi slave segment. + +Simplified Modbus connection schematic for example test: + ``` + MB_DEVICE_ADDR1 + ------------- ------------- + | | RS485 network | | + | Slave 1 |---<>--+---<>---| Master | + | | | | + ------------- ------------- +``` +Modbus multi slave segment connection schematic: +``` + MB_DEVICE_ADDR1 + ------------- + | | + | Slave 1 |---<>--+ + | | | + ------------- | + MB_DEVICE_ADDR2 | + ------------- | ------------- + | | | | | + | Slave 2 |---<>--+---<>---| Master | + | | | | | + ------------- | ------------- + MB_DEVICE_ADDR3 | + ------------- RS485 network + | | | + | Slave 3 |---<>--+ + | | + ------------- +``` + +## Hardware required : +Option 1: +PC (Modbus Slave app) + USB Serial adapter connected to USB port + RS485 line drivers + ESP32 WROVER-KIT board. + +Option 2: +Several ESP32 WROVER-KIT board flashed with modbus_slave example software to represent slave device with specific slave address (See CONFIG_MB_SLAVE_ADDR). The slave addresses for each board have to be configured as defined in "connection schematic" above. +One ESP32 WROVER-KIT board flashed with modbus_master example. All the boards require connection of RS485 line drivers (see below). + +The MAX485 line driver is used as an example below but other similar chips can be used as well. +RS485 example circuit schematic for connection of master and slave devices into segment: +``` + VCC ---------------+ +--------------- VCC + | | + +-------x-------+ +-------x-------+ + RXD <------| RO | DIFFERENTIAL | RO|-----> RXD + | B|---------------|B | + TXD ------>| DI MAX485 | \ / | MAX485 DI|<----- TXD +ESP32 WROVER KIT 1 | | RS-485 side | | External PC (emulator) with USB to serial or + RTS --+--->| DE | / \ | DE|---+ ESP32 WROVER KIT 2 (slave) + | | A|---------------|A | | + +----| /RE | PAIR | /RE|---+-- RTS + +-------x-------+ +-------x-------+ + | | + --- --- + Modbus Master device Modbus Slave device + +``` + +## How to setup and use an example: + +### Configure the application +Start the command below to setup configuration: +``` +idf.py menuconfig +``` +Configure the UART pins used for modbus communication using and table below. +Define the communication mode parameter for master and slave in Kconfig - CONFIG_MB_COMM_MODE (must be the same for master and slave devices in one segment). +Configure the slave address for each slave in the Modbus segment (the CONFIG_MB_SLAVE_ADDR in Kconfig). + +``` + ------------------------------------------------------------------------------------------------ + | ESP32 Interface | #define | Default ESP32 Pin | External RS485 Pin| + | ----------------------|------------------------------|-------------------|-------------------| + | Transmit Data (TxD) | CONFIG_MB_UART_TXD | GPIO23 | DI | + | Receive Data (RxD) | CONFIG_MB_UART_RXD | GPIO22 | RO | + | Request To Send (RTS) | CONFIG_MB_UART_RTS | GPIO18 | ~RE/DE | + | | | | | + | Ground | n/a | GND | GND | + ------------------------------------------------------------------------------------------------ +``` +The communication parameters of Modbus stack allow to configure it appropriately but usually it is enough to use default settings. +See the help string of parameters for more information. + +### Setup external Modbus slave devices or emulator +Option 1: +Configure the external Modbus master software according to port configuration parameters used in the example. The Modbus Slave application can be used with this example to emulate slave devices with its parameters. Use official documentation for software to setup emulation of slave devices. + +Option 2: +Other option is to have the modbus_slave example application flashed into ESP32 WROVER KIT board and connect boards together as showed on the Modbus connection schematic above. See the Modbus slave API documentation to configure communication parameters and slave addresses as defined in "Example parameters definition" table above. + +### Build and flash software of master device +Build the project and flash it to the board, then run monitor tool to view serial output: +``` +idf.py -p PORT flash monitor +``` + +(To exit the serial monitor, type ``Ctrl-]``.) + +See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. + +## Example Output +Example output of the application: +``` +I (9035) MASTER_TEST: Characteristic #0 Data_channel_0 (Volts) value = 1.120000 (0x3f8f5c29) read successful. +I (9045) MASTER_TEST: Characteristic #1 Humidity_1 (%rH) value = 5.539999 (0x40b147ac) read successful. +I (9045) MASTER_TEST: Characteristic #2 Temperature_1 (C) value = 2.340000 (0x4015c28f) read successful. +I (9055) MASTER_TEST: Characteristic #3 Humidity_2 (%rH) value = 2.560000 (0x4023d70a) read successful. +I (9065) MASTER_TEST: Characteristic #4 Temperature_2 (C) value = 3.560000 (0x4063d70a) read successful. +I (9075) MASTER_TEST: Characteristic #5 Humidity_3 (%rH) value = 3.780000 (0x4071eb85) read successful. +I (9085) MASTER_TEST: Characteristic #6 RelayP1 (on/off) value = OFF (0x55) read successful. +I (9095) MASTER_TEST: Characteristic #7 RelayP2 (on/off) value = OFF (0xaa) read successful. +I (9605) MASTER_TEST: Characteristic #0 Data_channel_0 (Volts) value = 1.120000 (0x3f8f5c29) read successful. +I (9615) MASTER_TEST: Characteristic #1 Humidity_1 (%rH) value = 5.739999 (0x40b7ae12) read successful. +I (9615) MASTER_TEST: Characteristic #2 Temperature_1 (C) value = 2.340000 (0x4015c28f) read successful. +I (9625) MASTER_TEST: Characteristic #3 Humidity_2 (%rH) value = 2.560000 (0x4023d70a) read successful. +I (9635) MASTER_TEST: Characteristic #4 Temperature_2 (C) value = 3.560000 (0x4063d70a) read successful. +I (9645) MASTER_TEST: Characteristic #5 Humidity_3 (%rH) value = 3.780000 (0x4071eb85) read successful. +I (9655) MASTER_TEST: Characteristic #6 RelayP1 (on/off) value = OFF (0x55) read successful. +I (9665) MASTER_TEST: Characteristic #7 RelayP2 (on/off) value = ON (0xff) read successful. +I (10175) MASTER_TEST: Alarm triggered by cid #7. +I (10175) MASTER_TEST: Destroy master... + +``` +The example reads the characteristics from slave device(s), while alarm is not triggered in the slave device (See the "Example parameters definition"). The output line describes Timestamp, Cid of characteristic, Characteristic name (Units), Characteristic value (Hex). + +Note: Refer to file below for more information about current implementation of Modbus: + +* `components/freemodbus/README.rst` + diff --git a/examples/protocols/modbus_slave/README.md b/examples/protocols/modbus_slave/README.md index 6d671781f..8efdb58be 100644 --- a/examples/protocols/modbus_slave/README.md +++ b/examples/protocols/modbus_slave/README.md @@ -69,5 +69,6 @@ HOLDING READ/WRITE: time_stamp(us):12104081, mb_addr:1, type:2, st_address:0x3ff ``` The output lines describe type of operation, its timestamp, modbus address, access type, storage address in parameter structure and number of registers accordingly. +Note: Refer to file below for more information about current implementation of Modbus: - +* `components/freemodbus/README.rst`