src/modbus.h

   1 /*
   2  * Copyright © Stéphane Raimbault <stephane.raimbault@gmail.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-or-later
   5  */
   6
   7 #ifndef MODBUS_H
   8 #define MODBUS_H
   9
  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
  15
  16 #ifndef _MSC_VER
  17 # include <stdint.h>
  18 #else
  19 # include "stdint.h"
  20 #endif
  21
  22 #include "modbus-version.h"
  23
  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
  34
  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
  43
  44 MODBUS_BEGIN_DECLS
  45
  46 #ifndef FALSE
  47 #define FALSE 0
  48 #endif
  49
  50 #ifndef TRUE
  51 #define TRUE 1
  52 #endif
  53
  54 #ifndef OFF
  55 #define OFF 0
  56 #endif
  57
  58 #ifndef ON
  59 #define ON 1
  60 #endif
  61
  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
  75
  76 #define MODBUS_BROADCAST_ADDRESS 0
  77
  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)
  82  */
  83 #define MODBUS_MAX_READ_BITS  2000
  84 #define MODBUS_MAX_WRITE_BITS 1968
  85
  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)
  92  */
  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
  97
  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.
 102  */
 103 #define MODBUS_MAX_PDU_LENGTH 253
 104
 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.
 112  */
 113 #define MODBUS_MAX_ADU_LENGTH 260
 114
 115 /* Random number to avoid errno conflicts */
 116 #define MODBUS_ENOBASE 112345678
 117
 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
 132 };
 133
 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)
 144
 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)
 152
 153 extern const unsigned int libmodbus_version_major;
 154 extern const unsigned int libmodbus_version_minor;
 155 extern const unsigned int libmodbus_version_micro;
 156
 157 typedef struct _modbus modbus_t;
 158
 159 /*! Memory layout in tab_xxx arrays is processor-endianness.
 160     When receiving modbus data, it is converted to processor-endianness,
 161     see read_registers().
 162 */
 163 typedef struct _modbus_mapping_t {
 164     int nb_bits;
 165     int start_bits;
 166     int nb_input_bits;
 167     int start_input_bits;
 168     int nb_input_registers;
 169     int start_input_registers;
 170     int nb_registers;
 171     int start_registers;
 172     uint8_t *tab_bits;
 173     uint8_t *tab_input_bits;
 174     uint16_t *tab_input_registers;
 175     uint16_t *tab_registers;
 176 } modbus_mapping_t;
 177
 178 typedef enum {
 179     MODBUS_ERROR_RECOVERY_NONE = 0,
 180     MODBUS_ERROR_RECOVERY_LINK = (1 << 1),
 181     MODBUS_ERROR_RECOVERY_PROTOCOL = (1 << 2)
 182 } modbus_error_recovery_mode;
 183
 184 typedef enum {
 185     MODBUS_QUIRK_NONE = 0,
 186     MODBUS_QUIRK_MAX_SLAVE = (1 << 1),
 187     MODBUS_QUIRK_REPLY_TO_BROADCAST = (1 << 2),
 188     MODBUS_QUIRK_ALL = 0xFF
 189 } modbus_quirks;
 190
 191 MODBUS_API int modbus_set_slave(modbus_t *ctx, int slave);
 192 MODBUS_API int modbus_get_slave(modbus_t *ctx);
 193 MODBUS_API int modbus_set_error_recovery(modbus_t *ctx,
 194                                          modbus_error_recovery_mode error_recovery);
 195 MODBUS_API int modbus_set_socket(modbus_t *ctx, int s);
 196 MODBUS_API int modbus_get_socket(modbus_t *ctx);
 197
 198 MODBUS_API int
 199 modbus_get_response_timeout(modbus_t *ctx, uint32_t *to_sec, uint32_t *to_usec);
 200 MODBUS_API int
 201 modbus_set_response_timeout(modbus_t *ctx, uint32_t to_sec, uint32_t to_usec);
 202
 203 MODBUS_API int
 204 modbus_get_byte_timeout(modbus_t *ctx, uint32_t *to_sec, uint32_t *to_usec);
 205 MODBUS_API int modbus_set_byte_timeout(modbus_t *ctx, uint32_t to_sec, uint32_t to_usec);
 206
 207 MODBUS_API int
 208 modbus_get_indication_timeout(modbus_t *ctx, uint32_t *to_sec, uint32_t *to_usec);
 209 MODBUS_API int
 210 modbus_set_indication_timeout(modbus_t *ctx, uint32_t to_sec, uint32_t to_usec);
 211
 212 MODBUS_API int modbus_get_header_length(modbus_t *ctx);
 213
 214 MODBUS_API int modbus_connect(modbus_t *ctx);
 215 MODBUS_API void modbus_close(modbus_t *ctx);
 216
 217 MODBUS_API void modbus_free(modbus_t *ctx);
 218
 219 MODBUS_API int modbus_flush(modbus_t *ctx);
 220 MODBUS_API int modbus_set_debug(modbus_t *ctx, int flag);
 221
 222 MODBUS_API const char *modbus_strerror(int errnum);
 223
 224 MODBUS_API int modbus_read_bits(modbus_t *ctx, int addr, int nb, uint8_t *dest);
 225 MODBUS_API int modbus_read_input_bits(modbus_t *ctx, int addr, int nb, uint8_t *dest);
 226 MODBUS_API int modbus_read_registers(modbus_t *ctx, int addr, int nb, uint16_t *dest);
 227 MODBUS_API int
 228 modbus_read_input_registers(modbus_t *ctx, int addr, int nb, uint16_t *dest);
 229 MODBUS_API int modbus_write_bit(modbus_t *ctx, int coil_addr, int status);
 230 MODBUS_API int modbus_write_register(modbus_t *ctx, int reg_addr, const uint16_t value);
 231 MODBUS_API int modbus_write_bits(modbus_t *ctx, int addr, int nb, const uint8_t *data);
 232 MODBUS_API int
 233 modbus_write_registers(modbus_t *ctx, int addr, int nb, const uint16_t *data);
 234 MODBUS_API int
 235 modbus_mask_write_register(modbus_t *ctx, int addr, uint16_t and_mask, uint16_t or_mask);
 236 MODBUS_API int modbus_write_and_read_registers(modbus_t *ctx,
 237                                                int write_addr,
 238                                                int write_nb,
 239                                                const uint16_t *src,
 240                                                int read_addr,
 241                                                int read_nb,
 242                                                uint16_t *dest);
 243 MODBUS_API int modbus_report_slave_id(modbus_t *ctx, int max_dest, uint8_t *dest);
 244
 245 MODBUS_API modbus_mapping_t *
 246 modbus_mapping_new_start_address(unsigned int start_bits,
 247                                  unsigned int nb_bits,
 248                                  unsigned int start_input_bits,
 249                                  unsigned int nb_input_bits,
 250                                  unsigned int start_registers,
 251                                  unsigned int nb_registers,
 252                                  unsigned int start_input_registers,
 253                                  unsigned int nb_input_registers);
 254
 255 MODBUS_API modbus_mapping_t *modbus_mapping_new(int nb_bits,
 256                                                 int nb_input_bits,
 257                                                 int nb_registers,
 258                                                 int nb_input_registers);
 259 MODBUS_API void modbus_mapping_free(modbus_mapping_t *mb_mapping);
 260
 261 MODBUS_API int
 262 modbus_send_raw_request(modbus_t *ctx, const uint8_t *raw_req, int raw_req_length);
 263
 264 MODBUS_API int modbus_send_raw_request_tid(modbus_t *ctx,
 265                                            const uint8_t *raw_req,
 266                                            int raw_req_length,
 267                                            int tid);
 268
 269 MODBUS_API int modbus_receive(modbus_t *ctx, uint8_t *req);
 270
 271 MODBUS_API int modbus_receive_confirmation(modbus_t *ctx, uint8_t *rsp);
 272
 273 MODBUS_API int modbus_reply(modbus_t *ctx,
 274                             const uint8_t *req,
 275                             int req_length,
 276                             modbus_mapping_t *mb_mapping);
 277 MODBUS_API int
 278 modbus_reply_exception(modbus_t *ctx, const uint8_t *req, unsigned int exception_code);
 279 MODBUS_API int modbus_enable_quirks(modbus_t *ctx, unsigned int quirks_mask);
 280 MODBUS_API int modbus_disable_quirks(modbus_t *ctx, unsigned int quirks_mask);
 281
 282 /**
 283  * UTILS FUNCTIONS
 284  **/
 285
 286 #define MODBUS_GET_HIGH_BYTE(data) (((data) >> 8) & 0xFF)
 287 #define MODBUS_GET_LOW_BYTE(data)  ((data) & 0xFF)
 288 #define MODBUS_GET_INT64_FROM_INT16(tab_int16, index)                                  \
 289     (((int64_t) tab_int16[(index)] << 48) | ((int64_t) tab_int16[(index) + 1] << 32) | \
 290      ((int64_t) tab_int16[(index) + 2] << 16) | (int64_t) tab_int16[(index) + 3])
 291 #define MODBUS_GET_INT32_FROM_INT16(tab_int16, index) \
 292     (((int32_t) tab_int16[(index)] << 16) | (int32_t) tab_int16[(index) + 1])
 293 #define MODBUS_GET_INT16_FROM_INT8(tab_int8, index) \
 294     (((int16_t) tab_int8[(index)] << 8) | (int16_t) tab_int8[(index) + 1])
 295 #define MODBUS_SET_INT16_TO_INT8(tab_int8, index, value)            \
 296     do {                                                            \
 297         ((int8_t *) (tab_int8))[(index)] = (int8_t) ((value) >> 8); \
 298         ((int8_t *) (tab_int8))[(index) + 1] = (int8_t) (value);    \
 299     } while (0)
 300 #define MODBUS_SET_INT32_TO_INT16(tab_int16, index, value)              \
 301     do {                                                                \
 302         ((int16_t *) (tab_int16))[(index)] = (int16_t) ((value) >> 16); \
 303         ((int16_t *) (tab_int16))[(index) + 1] = (int16_t) (value);     \
 304     } while (0)
 305 #define MODBUS_SET_INT64_TO_INT16(tab_int16, index, value)                  \
 306     do {                                                                    \
 307         ((int16_t *) (tab_int16))[(index)] = (int16_t) ((value) >> 48);     \
 308         ((int16_t *) (tab_int16))[(index) + 1] = (int16_t) ((value) >> 32); \
 309         ((int16_t *) (tab_int16))[(index) + 2] = (int16_t) ((value) >> 16); \
 310         ((int16_t *) (tab_int16))[(index) + 3] = (int16_t) (value);         \
 311     } while (0)
 312
 313 MODBUS_API void modbus_set_bits_from_byte(uint8_t *dest, int idx, const uint8_t value);
 314 MODBUS_API void modbus_set_bits_from_bytes(uint8_t *dest,
 315                                            int idx,
 316                                            unsigned int nb_bits,
 317                                            const uint8_t *tab_byte);
 318 MODBUS_API uint8_t modbus_get_byte_from_bits(const uint8_t *src,
 319                                              int idx,
 320                                              unsigned int nb_bits);
 321 MODBUS_API float modbus_get_float(const uint16_t *src);
 322 MODBUS_API float modbus_get_float_abcd(const uint16_t *src);
 323 MODBUS_API float modbus_get_float_dcba(const uint16_t *src);
 324 MODBUS_API float modbus_get_float_badc(const uint16_t *src);
 325 MODBUS_API float modbus_get_float_cdab(const uint16_t *src);
 326
 327 MODBUS_API void modbus_set_float(float f, uint16_t *dest);
 328 MODBUS_API void modbus_set_float_abcd(float f, uint16_t *dest);
 329 MODBUS_API void modbus_set_float_dcba(float f, uint16_t *dest);
 330 MODBUS_API void modbus_set_float_badc(float f, uint16_t *dest);
 331 MODBUS_API void modbus_set_float_cdab(float f, uint16_t *dest);
 332
 333 #include "modbus-rtu.h"
 334 #include "modbus-tcp.h"
 335
 336 MODBUS_END_DECLS
 337
 338 #endif /* MODBUS_H */