Skip to content

Commit 9b803dd

Browse files
stephanestephane
committed
Add documentation for many functions and tweak argument names
Add macros in libmodbus.txt and: - modbus_get_byte_from_bits.txt - modbus_get_float.txt - modbus_reply.txt - modbus_reply_exception.txt - modbus_set_bits_from_byte.txt - modbus_set_bits_from_bytes.txt - modbus_set_float.txt
1 parent fb89fa3 commit 9b803dd

13 files changed

+332
-15
lines changed

‎NEWS

+3-2
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,9 @@ libmodbus 2.9.5 (2011-06-XX)
1010
* modbus_read_and_write_registers -> modbus_write_and_read_registers
1111
The function name was confusing because the write operation is performed
1212
before the read. Take care to swap the arguments in the migration process.
13-
- Documentation of modbus_write_and_read_registers, modbus_mapping_new/free
14-
and report_slave_id.
13+
- Documentation of modbus_write_and_read_registers, modbus_mapping_new/free,
14+
report_slave_id. modbus_get_byte_from_bits, modbus_set_bits_from_byte(s),
15+
modbus_[gs]et_float, modbus_reply and modbus_reply_exception.
1516
- Enhanced report slave ID
1617

1718
libmodbus 2.9.4 (2011-06-05)

‎doc/Makefile.am

+7
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ MAN3 = \
44
modbus_flush.3 \
55
modbus_free.3 \
66
modbus_get_byte_timeout.3 \
7+
modbus_get_byte_from_bits.3 \
8+
modbus_get_float.3 \
9+
modbus_set_float.3 \
710
modbus_get_header_length.3 \
811
modbus_get_socket.3 \
912
modbus_get_response_timeout.3 \
@@ -20,10 +23,14 @@ MAN3 = \
2023
modbus_receive_confirmation.3 \
2124
modbus_receive_from.3 \
2225
modbus_report_slave_id.3 \
26+
modbus_reply.3 \
27+
modbus_reply_exception.3 \
2328
modbus_rtu_get_serial_mode.3 \
2429
modbus_rtu_set_serial_mode.3 \
2530
modbus_send_raw_request.3 \
2631
modbus_set_byte_timeout.3 \
32+
modbus_set_bits_from_byte.3 \
33+
modbus_set_bits_from_bytes.3 \
2734
modbus_set_debug.3 \
2835
modbus_set_error_recovery.3 \
2936
modbus_set_slave.3 \

‎doc/libmodbus.txt

+21
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,23 @@ A libmodbus 'context' is thread safe and may be shared among as many application
120120
threads as necessary, without any additional locking required on the part of the
121121
caller.
122122

123+
Macros for data manipulation::
124+
MODBUS_GET_HIGH_BYTE(data), extracts the high byte from a byte
125+
MODBUS_GET_LOW_BYTE(data), extracts the low byte from a byte
126+
MODBUS_GET_INT32_FROM_INT16(tab_int16, index), builds an int32 from the two
127+
first int16 starting at tab_int16[index]
128+
MODBUS_GET_INT16_FROM_INT8(tab_int8, index), builds an int16 from the two
129+
first int8 starting at tab_int8[index]
130+
MODBUS_SET_INT16_TO_INT8(tab_int8, index, value), set an int16 value into
131+
the two first bytes starting at tab_int8[index]
132+
133+
Functions for data manipulation::
134+
linkmb:modbus_set_bits_from_byte[3]
135+
linkmb:modbus_set_bits_from_bytes[3]
136+
linkmb:modbus_get_byte_from_bits[3]
137+
linkmb:modbus_get_float[3]
138+
linkmb:modbus_set_float[3]
139+
123140

124141
Connection
125142
~~~~~~~~~~
@@ -162,6 +179,9 @@ Raw requests::
162179
linkmb:modbus_send_raw_request[3]
163180
linkmb:modbus_receive_confirmation[3]
164181

182+
Reply an exception::
183+
linkmb:modbus_reply_exception[3]
184+
165185

166186
Server
167187
~~~~~~
@@ -178,6 +198,7 @@ Receive::
178198

179199
Reply::
180200
linkmb:modbus_reply[3]
201+
linkmb:modbus_reply_exception[3]
181202

182203

183204
ERROR HANDLING

‎doc/modbus_get_byte_from_bits.txt

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
modbus_get_byte_from_bits(3)
2+
============================
3+
4+
NAME
5+
----
6+
modbus_get_byte_from_bits - get the value from many bits
7+
8+
9+
SYNOPSIS
10+
--------
11+
*uint8_t modbus_get_byte_from_bits(const uint8_t *'src', int 'index', unsigned int 'nb_bits');*
12+
13+
14+
DESCRIPTION
15+
-----------
16+
The _modbus_get_byte_from_bits()_ function shall extract a value from many
17+
bits. All 'nb_bits' bits from 'src' at position 'index' will be read as a
18+
single value. To obtain a full byte, set nb_bits to 8.
19+
20+
21+
RETURN VALUE
22+
------------
23+
The _modbus_get_byte_from_bits()_ function shall return a byte containing the
24+
bits read.
25+
26+
27+
SEE ALSO
28+
--------
29+
linkmb:modbus_set_bits_from_byte[3]
30+
linkmb:modbus_set_bits_from_bytes[3]
31+
32+
33+
AUTHORS
34+
-------
35+
The libmodbus documentation was written by Stéphane Raimbault
36+
<stephane.raimbault@gmail.com>

‎doc/modbus_get_float.txt

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
modbus_get_float(3)
2+
===================
3+
4+
5+
NAME
6+
----
7+
modbus_get_float - get a float value
8+
9+
10+
SYNOPSIS
11+
--------
12+
*float modbus_get_float(const uint16_t *'src');*
13+
14+
15+
DESCRIPTION
16+
-----------
17+
The _modbus_get_float()_ function shall get a float from 4 bytes in Modbus
18+
format. The 'src' array must be pointer on two 16 bits values, for example,
19+
if the first word is set to 0x4465 and the second to 0x229a, the float value
20+
read will be 916.540649.
21+
22+
23+
RETURN VALUE
24+
------------
25+
The _modbus_get_float()_ function shall return a float.
26+
27+
28+
SEE ALSO
29+
--------
30+
linkmb:modbus_set_float[3]
31+
32+
33+
AUTHORS
34+
-------
35+
The libmodbus documentation was written by Stéphane Raimbault
36+
<stephane.raimbault@gmail.com>

‎doc/modbus_reply.txt

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
modbus_reply(3)
2+
===============
3+
4+
NAME
5+
----
6+
modbus_reply - send a reponse to the received request
7+
8+
9+
SYNOPSIS
10+
--------
11+
*int modbus_reply(modbus_t *'ctx', const uint8_t *'req', int 'req_length', modbus_mapping_t *'mb_mapping');
12+
13+
14+
DESCRIPTION
15+
-----------
16+
The _modbus_reply()_ function shall send a response to received request. The
17+
request 'req' given in argument is analyzed, a response is then built and sent
18+
by using the information of the modbus context 'ctx'.
19+
20+
If the request indicates to read or write a value the operation will done in the
21+
modbus mapping 'mb_mapping' according to the type of the manipulated data.
22+
23+
If an error occurs, an exception response will be sent.
24+
25+
This function is designed for Modbus server.
26+
27+
28+
RETURN VALUE
29+
------------
30+
The _modbus_reply()_ function shall return the length of the response sent if
31+
successful. Otherwise it shall return -1 and set errno.
32+
33+
34+
ERRORS
35+
------
36+
EMBMDATA::
37+
Sending has failed
38+
39+
See also the errors returned by the syscall used to send the response (eg. send
40+
or write).
41+
42+
43+
SEE ALSO
44+
--------
45+
linkmb:modbus_reply_exception[3]
46+
linkmb:libmodbus[7]
47+
48+
49+
AUTHORS
50+
-------
51+
The libmodbus documentation was written by Stéphane Raimbault
52+
<stephane.raimbault@gmail.com>

‎doc/modbus_reply_exception.txt

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
modbus_reply_exception(3)
2+
=========================
3+
4+
NAME
5+
----
6+
modbus_reply_exception - send an exception reponse
7+
8+
9+
SYNOPSIS
10+
--------
11+
*int modbus_reply_exception(modbus_t *'ctx', const uint8_t *'req', unsigned int 'exception_code');
12+
13+
14+
DESCRIPTION
15+
-----------
16+
The _modbus_reply_exception()_ function shall send an exception response based
17+
on the 'exception_code' in argument.
18+
19+
The libmodbus provides the following exception codes:
20+
21+
* MODBUS_EXCEPTION_ILLEGAL_FUNCTION (1)
22+
* MODBUS_EXCEPTION_ILLEGAL_DATA_ADDRESS (2)
23+
* MODBUS_EXCEPTION_ILLEGAL_DATA_VALUE (3)
24+
* MODBUS_EXCEPTION_SLAVE_OR_SERVER_FAILURE (4)
25+
* MODBUS_EXCEPTION_ACKNOWLEDGE (5)
26+
* MODBUS_EXCEPTION_SLAVE_OR_SERVER_BUSY (6)
27+
* MODBUS_EXCEPTION_NEGATIVE_ACKNOWLEDGE (7)
28+
* MODBUS_EXCEPTION_MEMORY_PARITY (8)
29+
* MODBUS_EXCEPTION_NOT_DEFINED (9)
30+
* MODBUS_EXCEPTION_GATEWAY_PATH (10)
31+
* MODBUS_EXCEPTION_GATEWAY_TARGET (11)
32+
33+
The initial request 'req' is required to build a valid response.
34+
35+
36+
RETURN VALUE
37+
------------
38+
The _modbus_reply_exception()_ function shall return the length of the response sent if
39+
successful. Otherwise it shall return -1 and set errno.
40+
41+
42+
ERRORS
43+
------
44+
EINVAL::
45+
The exception code is invalid
46+
47+
48+
SEE ALSO
49+
--------
50+
linkmb:modbus_reply[3]
51+
linkmb:libmodbus[7]
52+
53+
54+
AUTHORS
55+
-------
56+
The libmodbus documentation was written by Stéphane Raimbault
57+
<stephane.raimbault@gmail.com>

‎doc/modbus_set_bits_from_byte.txt

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
modbus_set_bits_from_byte(3)
2+
============================
3+
4+
5+
NAME
6+
----
7+
modbus_set_bits_from_byte - set many bits from a single byte value
8+
9+
10+
SYNOPSIS
11+
--------
12+
*void modbus_set_bits_from_byte(uint8_t *'dest', int 'index', const uint8_t 'value');*
13+
14+
15+
DESCRIPTION
16+
-----------
17+
The _modbus_set_bits_from_byte_ function shall set many bits from a single byte.
18+
All 8 bits from the byte 'value' will be written to 'dest' array starting at
19+
'index' position.
20+
21+
22+
RETURN VALUE
23+
------------
24+
There is no return values.
25+
26+
27+
SEE ALSO
28+
--------
29+
linkmb:modbus_set_bits_from_byte[3]
30+
linkmb:modbus_set_bits_from_bytes[3]
31+
32+
33+
AUTHORS
34+
-------
35+
The libmodbus documentation was written by Stéphane Raimbault
36+
<stephane.raimbault@gmail.com>

‎doc/modbus_set_bits_from_bytes.txt

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
modbus_set_bits_from_bytes(3)
2+
============================
3+
4+
5+
NAME
6+
----
7+
modbus_set_bits_from_bytes - set many bits from an array of bytes
8+
9+
10+
SYNOPSIS
11+
--------
12+
*void modbus_set_bits_from_bytes(uint8_t *'dest', int 'index', unsigned int 'nb_bits', const uint8_t *'tab_byte');*
13+
14+
15+
DESCRIPTION
16+
-----------
17+
The _modbus_set_bits_from_bytes_ function shall set bits by reading an array of
18+
bytes. All the bits of the bytes read from the first position of the array
19+
'tab_byte' are written as bits in the 'dest' array starting at position 'index'.
20+
21+
22+
RETURN VALUE
23+
------------
24+
There is no return values.
25+
26+
27+
SEE ALSO
28+
--------
29+
linkmb:modbus_set_bits_from_byte[3]
30+
linkmb:modbus_get_byte_from_bits[3]
31+
32+
33+
AUTHORS
34+
-------
35+
The libmodbus documentation was written by Stéphane Raimbault
36+
<stephane.raimbault@gmail.com>

‎doc/modbus_set_float.txt

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
modbus_set_float(3)
2+
===================
3+
4+
5+
NAME
6+
----
7+
modbus_set_float - set a float value
8+
9+
10+
SYNOPSIS
11+
--------
12+
*void modbus_set_float(float 'f', uint16_t *'dest');*
13+
14+
15+
DESCRIPTION
16+
-----------
17+
The _modbus_set_float()_ function shall set a float to 4 bytes in Modbus
18+
format. The 'dest' array must be pointer on two 16 bits values to be able to
19+
store the full result of the conversion.
20+
21+
22+
RETURN VALUE
23+
------------
24+
The is no return values.
25+
26+
27+
SEE ALSO
28+
--------
29+
linkmb:modbus_set_float[3]
30+
31+
32+
AUTHORS
33+
-------
34+
The libmodbus documentation was written by Stéphane Raimbault
35+
<stephane.raimbault@gmail.com>

0 commit comments

Comments
 (0)