nanomodbus.h

Go to the documentation of this file.

/*
    nanoMODBUS - A compact MODBUS RTU/TCP C library for microcontrollers
 
    MIT License
 
    Copyright (c) 2024 Valerio De Benedetto (@debevv)
 
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
 
    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.
 
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.
*/
 
 
#ifndef NANOMODBUS_H
#define NANOMODBUS_H
 
#include <stdbool.h>
#include <stdint.h>
#include <string.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef enum nmbs_error {
    // Library errors
    NMBS_ERROR_INVALID_REQUEST = -8,  
    NMBS_ERROR_INVALID_UNIT_ID = -7,  
    NMBS_ERROR_INVALID_TCP_MBAP = -6, 
    NMBS_ERROR_CRC = -5,              
    NMBS_ERROR_TRANSPORT = -4,        
    NMBS_ERROR_TIMEOUT = -3,          
    NMBS_ERROR_INVALID_RESPONSE = -2, 
    NMBS_ERROR_INVALID_ARGUMENT = -1, 
    NMBS_ERROR_NONE = 0,              
    // Modbus exceptions
    NMBS_EXCEPTION_ILLEGAL_FUNCTION = 1,      
    NMBS_EXCEPTION_ILLEGAL_DATA_ADDRESS = 2,  
    NMBS_EXCEPTION_ILLEGAL_DATA_VALUE = 3,    
    NMBS_EXCEPTION_SERVER_DEVICE_FAILURE = 4, 
} nmbs_error;
 
 
#define nmbs_error_is_exception(e) ((e) > 0 && (e) < 5)
 
#ifndef NMBS_BITFIELD_MAX
#define NMBS_BITFIELD_MAX 2000
#endif
 
/* check coil count divisible by 8 */
#if ((NMBS_BITFIELD_MAX & 7) > 0)
#error "NMBS_BITFIELD_MAX must be divisible by 8"
#endif
 
#define NMBS_BITFIELD_BYTES_MAX (NMBS_BITFIELD_MAX / 8)
 
typedef uint8_t nmbs_bitfield[NMBS_BITFIELD_BYTES_MAX];
 
typedef uint8_t nmbs_bitfield_256[32];
 
#define nmbs_bitfield_read(bf, b) ((bool) ((bf)[(b) >> 3] & (0x1 << ((b) & (8 - 1)))))
 
#define nmbs_bitfield_set(bf, b) (((bf)[(b) >> 3]) = (((bf)[(b) >> 3]) | (0x1 << ((b) & (8 - 1)))))
 
#define nmbs_bitfield_unset(bf, b) (((bf)[(b) >> 3]) = (((bf)[(b) >> 3]) & ~(0x1 << ((b) & (8 - 1)))))
 
#define nmbs_bitfield_write(bf, b, v) ((bf)[(b) >> 3] = ((bf)[(b) >> 3] & ~(1 << ((b) & 7))) | ((v) << ((b) & 7)))
#define nmbs_bitfield_reset(bf) memset(bf, 0, sizeof(bf))
 
typedef enum nmbs_transport {
    NMBS_TRANSPORT_RTU = 1,
    NMBS_TRANSPORT_TCP = 2,
} nmbs_transport;
 
 
typedef struct nmbs_platform_conf {
    nmbs_transport transport; 
    int32_t (*read)(uint8_t* buf, uint16_t count, int32_t byte_timeout_ms,
                    void* arg); 
    int32_t (*write)(const uint8_t* buf, uint16_t count, int32_t byte_timeout_ms,
                     void* arg); 
    uint16_t (*crc_calc)(const uint8_t* data, uint32_t length,
                         void* arg); 
    void* arg;                       
    uint32_t initialized; 
} nmbs_platform_conf;
 
 
typedef struct nmbs_callbacks {
#ifndef NMBS_SERVER_DISABLED
#ifndef NMBS_SERVER_READ_COILS_DISABLED
    nmbs_error (*read_coils)(uint16_t address, uint16_t quantity, nmbs_bitfield coils_out, uint8_t unit_id, void* arg);
#endif
 
#ifndef NMBS_SERVER_READ_DISCRETE_INPUTS_DISABLED
    nmbs_error (*read_discrete_inputs)(uint16_t address, uint16_t quantity, nmbs_bitfield inputs_out, uint8_t unit_id,
                                       void* arg);
#endif
 
#if !defined(NMBS_SERVER_READ_HOLDING_REGISTERS_DISABLED) || !defined(NMBS_SERVER_READ_WRITE_REGISTERS_DISABLED)
    nmbs_error (*read_holding_registers)(uint16_t address, uint16_t quantity, uint16_t* registers_out, uint8_t unit_id,
                                         void* arg);
#endif
 
#ifndef NMBS_SERVER_READ_INPUT_REGISTERS_DISABLED
    nmbs_error (*read_input_registers)(uint16_t address, uint16_t quantity, uint16_t* registers_out, uint8_t unit_id,
                                       void* arg);
#endif
 
#ifndef NMBS_SERVER_WRITE_SINGLE_COIL_DISABLED
    nmbs_error (*write_single_coil)(uint16_t address, bool value, uint8_t unit_id, void* arg);
#endif
 
#ifndef NMBS_SERVER_WRITE_SINGLE_REGISTER_DISABLED
    nmbs_error (*write_single_register)(uint16_t address, uint16_t value, uint8_t unit_id, void* arg);
#endif
 
#ifndef NMBS_SERVER_WRITE_MULTIPLE_COILS_DISABLED
    nmbs_error (*write_multiple_coils)(uint16_t address, uint16_t quantity, const nmbs_bitfield coils, uint8_t unit_id,
                                       void* arg);
#endif
 
#if !defined(NMBS_SERVER_WRITE_MULTIPLE_REGISTERS_DISABLED) || !defined(NMBS_SERVER_READ_WRITE_REGISTERS_DISABLED)
    nmbs_error (*write_multiple_registers)(uint16_t address, uint16_t quantity, const uint16_t* registers,
                                           uint8_t unit_id, void* arg);
#endif
 
#ifndef NMBS_SERVER_READ_FILE_RECORD_DISABLED
    nmbs_error (*read_file_record)(uint16_t file_number, uint16_t record_number, uint16_t* registers, uint16_t count,
                                   uint8_t unit_id, void* arg);
#endif
 
#ifndef NMBS_SERVER_WRITE_FILE_RECORD_DISABLED
    nmbs_error (*write_file_record)(uint16_t file_number, uint16_t record_number, const uint16_t* registers,
                                    uint16_t count, uint8_t unit_id, void* arg);
#endif
 
#ifndef NMBS_SERVER_READ_DEVICE_IDENTIFICATION_DISABLED
#define NMBS_DEVICE_IDENTIFICATION_STRING_LENGTH 128
    nmbs_error (*read_device_identification)(uint8_t object_id, char buffer[NMBS_DEVICE_IDENTIFICATION_STRING_LENGTH]);
    nmbs_error (*read_device_identification_map)(nmbs_bitfield_256 map);
#endif
#endif
 
    void* arg;               // User data, will be passed to functions above
    uint32_t initialized;    // Reserved, workaround for older user code not calling nmbs_callbacks_create()
} nmbs_callbacks;
 
 
typedef struct nmbs_t {
    struct {
        uint8_t buf[260];
        uint16_t buf_idx;
 
        uint8_t unit_id;
        uint8_t fc;
        uint16_t transaction_id;
        bool broadcast;
        bool ignored;
        bool complete;
    } msg;
 
    nmbs_callbacks callbacks;
 
    int32_t byte_timeout_ms;
    int32_t read_timeout_ms;
 
    nmbs_platform_conf platform;
 
    uint8_t address_rtu;
    uint8_t dest_address_rtu;
    uint16_t current_tid;
} nmbs_t;
 
static const uint8_t NMBS_BROADCAST_ADDRESS = 0;
 
void nmbs_set_read_timeout(nmbs_t* nmbs, int32_t timeout_ms);
 
void nmbs_set_byte_timeout(nmbs_t* nmbs, int32_t timeout_ms);
 
void nmbs_platform_conf_create(nmbs_platform_conf* platform_conf);
 
void nmbs_set_platform_arg(nmbs_t* nmbs, void* arg);
 
#ifndef NMBS_SERVER_DISABLED
void nmbs_callbacks_create(nmbs_callbacks* callbacks);
 
nmbs_error nmbs_server_create(nmbs_t* nmbs, uint8_t address_rtu, const nmbs_platform_conf* platform_conf,
                              const nmbs_callbacks* callbacks);
 
nmbs_error nmbs_server_poll(nmbs_t* nmbs);
 
void nmbs_set_callbacks_arg(nmbs_t* nmbs, void* arg);
#endif
 
#ifndef NMBS_CLIENT_DISABLED
nmbs_error nmbs_client_create(nmbs_t* nmbs, const nmbs_platform_conf* platform_conf);
 
void nmbs_set_destination_rtu_address(nmbs_t* nmbs, uint8_t address);
 
nmbs_error nmbs_read_coils(nmbs_t* nmbs, uint16_t address, uint16_t quantity, nmbs_bitfield coils_out);
 
nmbs_error nmbs_read_discrete_inputs(nmbs_t* nmbs, uint16_t address, uint16_t quantity, nmbs_bitfield inputs_out);
 
nmbs_error nmbs_read_holding_registers(nmbs_t* nmbs, uint16_t address, uint16_t quantity, uint16_t* registers_out);
 
nmbs_error nmbs_read_input_registers(nmbs_t* nmbs, uint16_t address, uint16_t quantity, uint16_t* registers_out);
 
nmbs_error nmbs_write_single_coil(nmbs_t* nmbs, uint16_t address, bool value);
 
nmbs_error nmbs_write_single_register(nmbs_t* nmbs, uint16_t address, uint16_t value);
 
nmbs_error nmbs_write_multiple_coils(nmbs_t* nmbs, uint16_t address, uint16_t quantity, const nmbs_bitfield coils);
 
nmbs_error nmbs_write_multiple_registers(nmbs_t* nmbs, uint16_t address, uint16_t quantity, const uint16_t* registers);
 
nmbs_error nmbs_read_file_record(nmbs_t* nmbs, uint16_t file_number, uint16_t record_number, uint16_t* registers,
                                 uint16_t count);
 
nmbs_error nmbs_write_file_record(nmbs_t* nmbs, uint16_t file_number, uint16_t record_number, const uint16_t* registers,
                                  uint16_t count);
 
nmbs_error nmbs_read_write_registers(nmbs_t* nmbs, uint16_t read_address, uint16_t read_quantity,
                                     uint16_t* registers_out, uint16_t write_address, uint16_t write_quantity,
                                     const uint16_t* registers);
 
nmbs_error nmbs_read_device_identification_basic(nmbs_t* nmbs, char* vendor_name, char* product_code,
                                                 char* major_minor_revision, uint8_t buffers_length);
 
nmbs_error nmbs_read_device_identification_regular(nmbs_t* nmbs, char* vendor_url, char* product_name, char* model_name,
                                                   char* user_application_name, uint8_t buffers_length);
 
nmbs_error nmbs_read_device_identification_extended(nmbs_t* nmbs, uint8_t object_id_start, uint8_t* ids, char** buffers,
                                                    uint8_t ids_length, uint8_t buffer_length,
                                                    uint8_t* objects_count_out);
 
nmbs_error nmbs_read_device_identification(nmbs_t* nmbs, uint8_t object_id, char* buffer, uint8_t buffer_length);
 
nmbs_error nmbs_send_raw_pdu(nmbs_t* nmbs, uint8_t fc, const uint8_t* data, uint16_t data_len);
 
nmbs_error nmbs_receive_raw_pdu_response(nmbs_t* nmbs, uint8_t* data_out, uint8_t data_out_len);
#endif
 
uint16_t nmbs_crc_calc(const uint8_t* data, uint32_t length, void* arg);
 
#ifndef NMBS_STRERROR_DISABLED
const char* nmbs_strerror(nmbs_error error);
#endif
 
#ifdef __cplusplus
}    // extern "C"
#endif
 
#endif    //NANOMODBUS_H