Skip to content

Commit 304cf5b

Browse files
hansuhansu
committed
docs: created mb2hal doc based on sample ini file
1 parent f9d6871 commit 304cf5b

1 file changed

Lines changed: 160 additions & 3 deletions

File tree

‎docs/src/drivers/mb2hal.txt‎

Lines changed: 160 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
= MB2HAL
44

5+
== Introduction
6+
57
MB2HAL is a generic userspace HAL component to communicate with one or more Modbus devices.
68
So far, there are two options to comunicate with a Modbus device:
79

@@ -16,13 +18,168 @@ Consider using Mb2hal if:
1618
* You have to write a new driver and you don't know anything about programming.
1719
* You need to use Classic Ladder "only" to manage the Modbus connections.
1820
* You have to discover and configure first time the Modbus transactions. Mb2hal have debug levels to facilitate the low level protocol debug.
19-
* You have more than one device to connect. Mb2hal is very efficient managing multiple devices, transactions and links. Currently i am monitoring two axis drivers using a Rs232 port, a VFD driver using another Rs232 port, and a remote I/O using TCP/IP.
21+
* You have more than one device to connect. Mb2hal is very efficient managing multiple devices, transactions and links. Currently i am
22+
monitoring two axis drivers using a Rs232 port, a VFD driver using another Rs232 port, and a remote I/O using TCP/IP.
2023
* You want a protocol to connect your Arduino to HAL. Look the included sample configuration file, sketch and library for Arduino Modbus.
2124

25+
== Usage
26+
27+
. Create a config file from the example below
28+
. Set component name (optional)
29+
+
30+
Set `HAL_MODULE_NAME=mymodule` (default `HAL_MODULE_NAME=mb2hal`)
31+
+
32+
. Load the modbus HAL userspace component
33+
.. Default component name: `loadusr -W mb2hal config=config_file.ini`
34+
.. Custom component name: `loadusr -Wn mymodule mb2hal config=config_file.ini`
35+
36+
37+
== Options
38+
39+
=== Init Section
40+
`[MB2HAL_INIT]`
41+
42+
[options="header", cols="12,8,13,70", frame="none", grid="none"]
43+
|=======================
44+
|Value | Type | Required | Description
45+
|`INIT_DEBUG`| Integer | No | Debug level of init and INI file parsing.
46+
47+
0 = silent +
48+
1 = error messages (default) +
49+
2 = OK confirmation messages +
50+
3 = debugging messages +
51+
4 = maximum debugging messages (only in transactions) +
52+
53+
|`HAL_MODULE_NAME` | String | No | HAL module (component) name. Defaults to "mb2hal".
54+
55+
|`SLOWDOWN` | Float | No | Insert a delay of "FLOAT seconds" between transactions in order to not to have a lot of logging
56+
and facilitate the debugging.
57+
Useful when using `DEBUG=3` (NOT `INIT_DEBUG=3`). It affects ALL transactions. Use "0.0" for normal activity.
58+
59+
| `TOTAL_TRANSACTIONS` | Integer | Yes | The number of total Modbus transactions. There is no maximum.
60+
61+
|=======================
62+
63+
64+
=== Transaction Sections
65+
66+
One transaction section is required per transaction, starting at `[TRANSACTION_00]` and counting up sequentially.
67+
If there is a new link (not transaction), you must provide the REQUIRED parameters 1st time.
68+
Warning: Any OPTIONAL parameter not specified are copied from the previous transaction.
69+
70+
[options="header", cols="12,8,13,70", frame="none", grid="none"]
71+
|=======================
72+
|Value | Type | Required | Description
73+
|`LINK_TYPE` | String | Yes | You must specify either a "serial" or "tcp" link for the first transaction.
74+
Later transactions will use the previous transaction link if not specified.
75+
|`TCP_IP` | IP address | If `LINK_TYPE=tcp` | The Modbus slave device IP address. Ignored if `LINK_TYPE=serial`.
76+
|`TCP_PORT` | Integer | No | The Modbus slave device TCP port. Defaults to 502. Ignored if `LINK_TYPE=serial`.
77+
|`SERIAL_PORT` | String | If `LINK_TYPE=serial` | The serial port. For example "/dev/ttyS0". Ignored if `LINK_TYPE=tcp`.
78+
|`SERIAL_BAUD` | Integer | If `LINK_TYPE=serial` | The baud rate. Ignored if `LINK_TYPE=tcp`.
79+
|`SERIAL_BITS` | Integer | If `LINK_TYPE=serial` | Data bits. One of 5,6,7,8. Ignored if `LINK_TYPE=tcp`.
80+
|`SERIAL_PARITY` | String | If `LINK_TYPE=serial` | Data parity. One of: even, odd, none. Ignored if `LINK_TYPE=tcp`.
81+
|`SERIAL_STOP` | Integer | If `LINK_TYPE=serial` | Stop bits. One of 1, 2. Ignored if `LINK_TYPE=tcp`.
82+
|`SERIAL_DELAY_MS`| Integer | If `LINK_TYPE=serial` | Serial port delay in ms between transactions of this section only.
83+
In ms. Defaults to 0. Ignored if `LINK_TYPE=tcp`.
84+
|`MB_SLAVE_ID` | Integer | Yes | Modbus slave number.
85+
|`FIRST_ELEMENT` | Integer | Yes | The first element address.
86+
|`NELEMENTS` | Integer | Unless `PIN_NAMES` is specified | The number of elements. It is an error to specify both
87+
`NELEMENTS` and `PIN_NAMES`. The pin names will be sequential numbers e.g. `mb2hal.plcin.01`
88+
|`PIN_NAMES` | List | Unless `NELEMENTS` is specified | A list of element names.
89+
These names will be used for the pin names, e.g. mb2hal.plcin.cycle_start.
90+
NOTE: there must be no white space characters in the list.
91+
Example: `PIN_NAMES=cycle_start,stop,feed_hold`
92+
|`MB_TX_CODE` | String | Yes |
93+
94+
Modbus transaction function code (see link:https://modbus.org/specs.php[specifications]):
95+
96+
• fnct_01_read_coils +
97+
• fnct_02_read_discrete_inputs +
98+
• fnct_03_read_holding_registers +
99+
• fnct_04_read_input_registers +
100+
• fnct_05_write_single_coil +
101+
• fnct_06_write_single_register +
102+
• fnct_15_write_multiple_coils +
103+
• fnct_16_write_multiple_registers +
104+
105+
|`MB_RESPONSE_TIMEOUT_MS`| Integer | No |
106+
Response timeout for this transaction. In ms. Defaults to 500 ms. This is how much to wait for 1st byte before raise an error.
107+
|`MB_BYTE_TIMEOUT_MS` | Integer | No | Byte timeout for this transaction. In ms. Defaults to 500 ms. This is how much to
108+
wait from byte to byte before raise an error.
109+
|`HAL_TX_NAME` | String | No | Instead of giving the transaction number, use a name. Example: `mb2hal.00.01`
110+
could become `mb2hal.plcin.01`. The name must not exceed 28 characters. NOTE: when using names be careful that
111+
you don't end up with two transactions using the same name.
112+
|`MAX_UPDATE_RATE`| Float | No | Maximum update rate in Hz. Defaults to 0.0 (0.0 = as soon as available = infinit).
113+
NOTE: This is a maximum rate and the actual rate may be lower. If you want to calculate it in ms use (1000 / required_ms).
114+
Example: 100 ms = `MAX_UPDATE_RATE=10.0`, because 1000.0 ms / 100.0 ms = 10.0 Hz.
115+
|`DEBUG` | String | No | Debug level for this transaction only. See `INIT_DEBUG` parameter above.
116+
117+
|=======================
118+
119+
=== Error codes
120+
While debugging transactions, note the returned "`ret[]`" value correspond to:
121+
122+
Modbus protocol exceptions:
123+
124+
* 0x01 - ILLEGAL_FUNCTION - the FUNCTION code received in the query is not allowed or invalid.
125+
* 0x02 - ILLEGAL_DATA_ADDRESS - the DATA ADDRESS received in the query is not an allowable address for the slave or is invalid.
126+
* 0x03 - ILLEGAL_DATA_VALUE - a VALUE contained in the data query field is not an allowable value or is invalid.
127+
* 0x04 - SLAVE_DEVICE_FAILURE - SLAVE (or MASTER) device unrecoverable FAILURE while attempting to perform the requested action.
128+
* 0x04 - SERVER_FAILURE - (see above).
129+
* 0x05 - ACKNOWLEDGE - This response is returned to PREVENT A TIMEOUT in the master.
130+
A long duration of time is required to process the request in the slave.
131+
* 0x06 - SLAVE_DEVICE_BUSY - The slave (or server) is BUSY. Retrasmit the request later.
132+
* 0x06 - SERVER_BUSY - (see above).
133+
* 0x07 - NEGATIVE_ACKNOWLEDGE - Unsuccessful programming request using function code 13 or 14.
134+
* 0x08 - MEMORY_PARITY_ERROR - SLAVE parity error in MEMORY.
135+
* 0x0A (-10) - GATEWAY_PROBLEM_PATH - Gateway path(s) not available.
136+
* 0x0B (-11) - GATEWAY_PROBLEM_TARGET - The target device failed to repond (generated by master, not slave).
137+
138+
Program or connection:
139+
140+
* 0x0C (-12) - COMM_TIME_OUT
141+
* 0x0D (-13) - PORT_SOCKET_FAILURE
142+
* 0x0E (-14) - SELECT_FAILURE
143+
* 0x0F (-15) - TOO_MANY_DATAS
144+
* 0x10 (-16) - INVALID_CRC
145+
* 0x11 (-17) - INVALID_EXCEPTION_CODE
22146

23147
== Example config file
24148
Click link:mb2hal_HOWTO.ini[here] to download.
25-
[source,ini]
149+
[source,{basebackend@docbook:'':ini}]
26150
----
27151
include::../../../src/hal/user_comps/mb2hal/mb2hal_HOWTO.ini[]
28-
----
152+
----
153+
154+
== Pins
155+
156+
=== fnct_02_read_discrete_inputs
157+
* mb2hal.m.n _bit out_
158+
159+
=== fnct_03_read_holding_registers
160+
* mb2hal.m.n.float _float out_
161+
* mb2hal.m.n.int _s32 out_
162+
163+
=== fnct_04_read_input_registers
164+
* mb2hal.m.n.float _float out_
165+
* mb2hal.m.n.int _s32 out_
166+
167+
=== fnct_06_write_single_register
168+
* mb2hal.m.n _float in_
169+
170+
`NELEMENTS` needs to be 1 or `PIN_NAMES` must contain just one name.
171+
172+
=== fnct_15_write_multiple_coils
173+
* mb2hal.m.n _bit in_
174+
175+
=== fnct_16_write_multiple_registers
176+
* mb2hal.m.n _float in_
177+
178+
==========================
179+
m = `HAL_TX_NAME` or transaction number if not set, n = element number (`NELEMENTS`) or name from `PIN_NAMES`
180+
181+
Example:
182+
183+
* `mb2hal.00.01.<type>` (transaction=00, second register=01 (00 is the first one))
184+
* `mb2hal.TxName.01.<type>` (HAL_TX_NAME=TxName, second register=01 (00 is the first one))
185+
==========================

0 commit comments

Comments
 (0)