Instructions to build libmodbus in a VS project
[libmodbus.git] / src / modbus.h
blob55ef08a0d50137ef2a1dcb5fc453b0b572353c1d
1 /*
2 * Copyright © Stéphane Raimbault <stephane.raimbault@gmail.com>
4 * SPDX-License-Identifier: LGPL-2.1-or-later
5 */
7 #ifndef MODBUS_H
8 #define MODBUS_H
10 // clang-format off
11 /* Add this for macros that defined unix flavor */
12 #if (defined(__unix__) || defined(unix)) && !defined(USG)
13 # include <sys/param.h>
14 #endif
16 #ifndef _MSC_VER
17 # include <stdint.h>
18 #else
19 # include "stdint.h"
20 #endif
22 #include "modbus-version.h"
24 #if defined(_MSC_VER)
25 # if defined(DLLBUILD)
26 /* define DLLBUILD when building the DLL */
27 # define MODBUS_API __declspec(dllexport)
28 # else
29 # define MODBUS_API __declspec(dllimport)
30 # endif
31 #else
32 # define MODBUS_API
33 #endif
35 #ifdef __cplusplus
36 # define MODBUS_BEGIN_DECLS extern "C" {
37 # define MODBUS_END_DECLS }
38 #else
39 # define MODBUS_BEGIN_DECLS
40 # define MODBUS_END_DECLS
41 #endif
42 // clang-format on
44 MODBUS_BEGIN_DECLS
46 #ifndef FALSE
47 #define FALSE 0
48 #endif
50 #ifndef TRUE
51 #define TRUE 1
52 #endif
54 #ifndef OFF
55 #define OFF 0
56 #endif
58 #ifndef ON
59 #define ON 1
60 #endif
62 /* Modbus function codes */
63 #define MODBUS_FC_READ_COILS 0x01
64 #define MODBUS_FC_READ_DISCRETE_INPUTS 0x02
65 #define MODBUS_FC_READ_HOLDING_REGISTERS 0x03
66 #define MODBUS_FC_READ_INPUT_REGISTERS 0x04
67 #define MODBUS_FC_WRITE_SINGLE_COIL 0x05
68 #define MODBUS_FC_WRITE_SINGLE_REGISTER 0x06
69 #define MODBUS_FC_READ_EXCEPTION_STATUS 0x07
70 #define MODBUS_FC_WRITE_MULTIPLE_COILS 0x0F
71 #define MODBUS_FC_WRITE_MULTIPLE_REGISTERS 0x10
72 #define MODBUS_FC_REPORT_SLAVE_ID 0x11
73 #define MODBUS_FC_MASK_WRITE_REGISTER 0x16
74 #define MODBUS_FC_WRITE_AND_READ_REGISTERS 0x17
76 #define MODBUS_BROADCAST_ADDRESS 0
78 /* Modbus_Application_Protocol_V1_1b.pdf (chapter 6 section 1 page 12)
79 * Quantity of Coils to read (2 bytes): 1 to 2000 (0x7D0)
80 * (chapter 6 section 11 page 29)
81 * Quantity of Coils to write (2 bytes): 1 to 1968 (0x7B0)
83 #define MODBUS_MAX_READ_BITS 2000
84 #define MODBUS_MAX_WRITE_BITS 1968
86 /* Modbus_Application_Protocol_V1_1b.pdf (chapter 6 section 3 page 15)
87 * Quantity of Registers to read (2 bytes): 1 to 125 (0x7D)
88 * (chapter 6 section 12 page 31)
89 * Quantity of Registers to write (2 bytes) 1 to 123 (0x7B)
90 * (chapter 6 section 17 page 38)
91 * Quantity of Registers to write in R/W registers (2 bytes) 1 to 121 (0x79)
93 #define MODBUS_MAX_READ_REGISTERS 125
94 #define MODBUS_MAX_WRITE_REGISTERS 123
95 #define MODBUS_MAX_WR_WRITE_REGISTERS 121
96 #define MODBUS_MAX_WR_READ_REGISTERS 125
98 /* The size of the MODBUS PDU is limited by the size constraint inherited from
99 * the first MODBUS implementation on Serial Line network (max. RS485 ADU = 256
100 * bytes). Therefore, MODBUS PDU for serial line communication = 256 - Server
101 * address (1 byte) - CRC (2 bytes) = 253 bytes.
103 #define MODBUS_MAX_PDU_LENGTH 253
105 /* Consequently:
106 * - RTU MODBUS ADU = 253 bytes + Server address (1 byte) + CRC (2 bytes) = 256
107 * bytes.
108 * - TCP MODBUS ADU = 253 bytes + MBAP (7 bytes) = 260 bytes.
109 * so the maximum of both backend in 260 bytes. This size can used to allocate
110 * an array of bytes to store responses and it will be compatible with the two
111 * backends.
113 #define MODBUS_MAX_ADU_LENGTH 260
115 /* Random number to avoid errno conflicts */
116 #define MODBUS_ENOBASE 112345678
118 /* Protocol exceptions */
119 enum {
120 MODBUS_EXCEPTION_ILLEGAL_FUNCTION = 0x01,
121 MODBUS_EXCEPTION_ILLEGAL_DATA_ADDRESS,
122 MODBUS_EXCEPTION_ILLEGAL_DATA_VALUE,
123 MODBUS_EXCEPTION_SLAVE_OR_SERVER_FAILURE,
124 MODBUS_EXCEPTION_ACKNOWLEDGE,
125 MODBUS_EXCEPTION_SLAVE_OR_SERVER_BUSY,
126 MODBUS_EXCEPTION_NEGATIVE_ACKNOWLEDGE,
127 MODBUS_EXCEPTION_MEMORY_PARITY,
128 MODBUS_EXCEPTION_NOT_DEFINED,
129 MODBUS_EXCEPTION_GATEWAY_PATH,
130 MODBUS_EXCEPTION_GATEWAY_TARGET,
131 MODBUS_EXCEPTION_MAX
134 #define EMBXILFUN (MODBUS_ENOBASE + MODBUS_EXCEPTION_ILLEGAL_FUNCTION)
135 #define EMBXILADD (MODBUS_ENOBASE + MODBUS_EXCEPTION_ILLEGAL_DATA_ADDRESS)
136 #define EMBXILVAL (MODBUS_ENOBASE + MODBUS_EXCEPTION_ILLEGAL_DATA_VALUE)
137 #define EMBXSFAIL (MODBUS_ENOBASE + MODBUS_EXCEPTION_SLAVE_OR_SERVER_FAILURE)
138 #define EMBXACK (MODBUS_ENOBASE + MODBUS_EXCEPTION_ACKNOWLEDGE)
139 #define EMBXSBUSY (MODBUS_ENOBASE + MODBUS_EXCEPTION_SLAVE_OR_SERVER_BUSY)
140 #define EMBXNACK (MODBUS_ENOBASE + MODBUS_EXCEPTION_NEGATIVE_ACKNOWLEDGE)
141 #define EMBXMEMPAR (MODBUS_ENOBASE + MODBUS_EXCEPTION_MEMORY_PARITY)
142 #define EMBXGPATH (MODBUS_ENOBASE + MODBUS_EXCEPTION_GATEWAY_PATH)
143 #define EMBXGTAR (MODBUS_ENOBASE + MODBUS_EXCEPTION_GATEWAY_TARGET)
145 /* Native libmodbus error codes */
146 #define EMBBADCRC (EMBXGTAR + 1)
147 #define EMBBADDATA (EMBXGTAR + 2)
148 #define EMBBADEXC (EMBXGTAR + 3)
149 #define EMBUNKEXC (EMBXGTAR + 4)
150 #define EMBMDATA (EMBXGTAR + 5)
151 #define EMBBADSLAVE (EMBXGTAR + 6)
153 extern const unsigned int libmodbus_version_major;
154 extern const unsigned int libmodbus_version_minor;
155 extern const unsigned int libmodbus_version_micro;
157 typedef struct _modbus modbus_t;
159 typedef struct _modbus_mapping_t {
160 int nb_bits;
161 int start_bits;
162 int nb_input_bits;
163 int start_input_bits;
164 int nb_input_registers;
165 int start_input_registers;
166 int nb_registers;
167 int start_registers;
168 uint8_t *tab_bits;
169 uint8_t *tab_input_bits;
170 uint16_t *tab_input_registers;
171 uint16_t *tab_registers;
172 } modbus_mapping_t;
174 typedef enum {
175 MODBUS_ERROR_RECOVERY_NONE = 0,
176 MODBUS_ERROR_RECOVERY_LINK = (1 << 1),
177 MODBUS_ERROR_RECOVERY_PROTOCOL = (1 << 2)
178 } modbus_error_recovery_mode;
180 typedef enum {
181 MODBUS_QUIRK_NONE = 0,
182 MODBUS_QUIRK_MAX_SLAVE = (1 << 1),
183 MODBUS_QUIRK_REPLY_TO_BROADCAST = (1 << 2),
184 MODBUS_QUIRK_ALL = 0xFF
185 } modbus_quirks;
187 MODBUS_API int modbus_set_slave(modbus_t *ctx, int slave);
188 MODBUS_API int modbus_get_slave(modbus_t *ctx);
189 MODBUS_API int modbus_set_error_recovery(modbus_t *ctx,
190 modbus_error_recovery_mode error_recovery);
191 MODBUS_API int modbus_set_socket(modbus_t *ctx, int s);
192 MODBUS_API int modbus_get_socket(modbus_t *ctx);
194 MODBUS_API int
195 modbus_get_response_timeout(modbus_t *ctx, uint32_t *to_sec, uint32_t *to_usec);
196 MODBUS_API int
197 modbus_set_response_timeout(modbus_t *ctx, uint32_t to_sec, uint32_t to_usec);
199 MODBUS_API int
200 modbus_get_byte_timeout(modbus_t *ctx, uint32_t *to_sec, uint32_t *to_usec);
201 MODBUS_API int modbus_set_byte_timeout(modbus_t *ctx, uint32_t to_sec, uint32_t to_usec);
203 MODBUS_API int
204 modbus_get_indication_timeout(modbus_t *ctx, uint32_t *to_sec, uint32_t *to_usec);
205 MODBUS_API int
206 modbus_set_indication_timeout(modbus_t *ctx, uint32_t to_sec, uint32_t to_usec);
208 MODBUS_API int modbus_get_header_length(modbus_t *ctx);
210 MODBUS_API int modbus_connect(modbus_t *ctx);
211 MODBUS_API void modbus_close(modbus_t *ctx);
213 MODBUS_API void modbus_free(modbus_t *ctx);
215 MODBUS_API int modbus_flush(modbus_t *ctx);
216 MODBUS_API int modbus_set_debug(modbus_t *ctx, int flag);
218 MODBUS_API const char *modbus_strerror(int errnum);
220 MODBUS_API int modbus_read_bits(modbus_t *ctx, int addr, int nb, uint8_t *dest);
221 MODBUS_API int modbus_read_input_bits(modbus_t *ctx, int addr, int nb, uint8_t *dest);
222 MODBUS_API int modbus_read_registers(modbus_t *ctx, int addr, int nb, uint16_t *dest);
223 MODBUS_API int
224 modbus_read_input_registers(modbus_t *ctx, int addr, int nb, uint16_t *dest);
225 MODBUS_API int modbus_write_bit(modbus_t *ctx, int coil_addr, int status);
226 MODBUS_API int modbus_write_register(modbus_t *ctx, int reg_addr, const uint16_t value);
227 MODBUS_API int modbus_write_bits(modbus_t *ctx, int addr, int nb, const uint8_t *data);
228 MODBUS_API int
229 modbus_write_registers(modbus_t *ctx, int addr, int nb, const uint16_t *data);
230 MODBUS_API int
231 modbus_mask_write_register(modbus_t *ctx, int addr, uint16_t and_mask, uint16_t or_mask);
232 MODBUS_API int modbus_write_and_read_registers(modbus_t *ctx,
233 int write_addr,
234 int write_nb,
235 const uint16_t *src,
236 int read_addr,
237 int read_nb,
238 uint16_t *dest);
239 MODBUS_API int modbus_report_slave_id(modbus_t *ctx, int max_dest, uint8_t *dest);
241 MODBUS_API modbus_mapping_t *
242 modbus_mapping_new_start_address(unsigned int start_bits,
243 unsigned int nb_bits,
244 unsigned int start_input_bits,
245 unsigned int nb_input_bits,
246 unsigned int start_registers,
247 unsigned int nb_registers,
248 unsigned int start_input_registers,
249 unsigned int nb_input_registers);
251 MODBUS_API modbus_mapping_t *modbus_mapping_new(int nb_bits,
252 int nb_input_bits,
253 int nb_registers,
254 int nb_input_registers);
255 MODBUS_API void modbus_mapping_free(modbus_mapping_t *mb_mapping);
257 MODBUS_API int
258 modbus_send_raw_request(modbus_t *ctx, const uint8_t *raw_req, int raw_req_length);
260 MODBUS_API int modbus_receive(modbus_t *ctx, uint8_t *req);
262 MODBUS_API int modbus_receive_confirmation(modbus_t *ctx, uint8_t *rsp);
264 MODBUS_API int modbus_reply(modbus_t *ctx,
265 const uint8_t *req,
266 int req_length,
267 modbus_mapping_t *mb_mapping);
268 MODBUS_API int
269 modbus_reply_exception(modbus_t *ctx, const uint8_t *req, unsigned int exception_code);
270 MODBUS_API int modbus_enable_quirks(modbus_t *ctx, unsigned int quirks_mask);
271 MODBUS_API int modbus_disable_quirks(modbus_t *ctx, unsigned int quirks_mask);
274 * UTILS FUNCTIONS
277 #define MODBUS_GET_HIGH_BYTE(data) (((data) >> 8) & 0xFF)
278 #define MODBUS_GET_LOW_BYTE(data) ((data) &0xFF)
279 #define MODBUS_GET_INT64_FROM_INT16(tab_int16, index) \
280 (((int64_t) tab_int16[(index)] << 48) | ((int64_t) tab_int16[(index) + 1] << 32) | \
281 ((int64_t) tab_int16[(index) + 2] << 16) | (int64_t) tab_int16[(index) + 3])
282 #define MODBUS_GET_INT32_FROM_INT16(tab_int16, index) \
283 (((int32_t) tab_int16[(index)] << 16) | (int32_t) tab_int16[(index) + 1])
284 #define MODBUS_GET_INT16_FROM_INT8(tab_int8, index) \
285 (((int16_t) tab_int8[(index)] << 8) | (int16_t) tab_int8[(index) + 1])
286 #define MODBUS_SET_INT16_TO_INT8(tab_int8, index, value) \
287 do { \
288 ((int8_t *) (tab_int8))[(index)] = (int8_t) ((value) >> 8); \
289 ((int8_t *) (tab_int8))[(index) + 1] = (int8_t) (value); \
290 } while (0)
291 #define MODBUS_SET_INT32_TO_INT16(tab_int16, index, value) \
292 do { \
293 ((int16_t *) (tab_int16))[(index)] = (int16_t) ((value) >> 16); \
294 ((int16_t *) (tab_int16))[(index) + 1] = (int16_t) (value); \
295 } while (0)
296 #define MODBUS_SET_INT64_TO_INT16(tab_int16, index, value) \
297 do { \
298 ((int16_t *) (tab_int16))[(index)] = (int16_t) ((value) >> 48); \
299 ((int16_t *) (tab_int16))[(index) + 1] = (int16_t) ((value) >> 32); \
300 ((int16_t *) (tab_int16))[(index) + 2] = (int16_t) ((value) >> 16); \
301 ((int16_t *) (tab_int16))[(index) + 3] = (int16_t) (value); \
302 } while (0)
304 MODBUS_API void modbus_set_bits_from_byte(uint8_t *dest, int idx, const uint8_t value);
305 MODBUS_API void modbus_set_bits_from_bytes(uint8_t *dest,
306 int idx,
307 unsigned int nb_bits,
308 const uint8_t *tab_byte);
309 MODBUS_API uint8_t modbus_get_byte_from_bits(const uint8_t *src,
310 int idx,
311 unsigned int nb_bits);
312 MODBUS_API float modbus_get_float(const uint16_t *src);
313 MODBUS_API float modbus_get_float_abcd(const uint16_t *src);
314 MODBUS_API float modbus_get_float_dcba(const uint16_t *src);
315 MODBUS_API float modbus_get_float_badc(const uint16_t *src);
316 MODBUS_API float modbus_get_float_cdab(const uint16_t *src);
318 MODBUS_API void modbus_set_float(float f, uint16_t *dest);
319 MODBUS_API void modbus_set_float_abcd(float f, uint16_t *dest);
320 MODBUS_API void modbus_set_float_dcba(float f, uint16_t *dest);
321 MODBUS_API void modbus_set_float_badc(float f, uint16_t *dest);
322 MODBUS_API void modbus_set_float_cdab(float f, uint16_t *dest);
324 #include "modbus-rtu.h"
325 #include "modbus-tcp.h"
327 MODBUS_END_DECLS
329 #endif /* MODBUS_H */