src/modbus.h

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