nanoMODBUS Documentation

You can reduce the library's footprint by defining specific macros before including the headers. This is particularly useful for resource-constrained microcontrollers.

Disabling Client/Server Roles

• NMBS_CLIENT_DISABLED: Disables all client code.
• NMBS_SERVER_DISABLED: Disables all server code.

Disabling Specific Server Callbacks

If NMBS_SERVER_DISABLED is not set, you can still disable individual function codes:

• NMBS_SERVER_READ_COILS_DISABLED
• NMBS_SERVER_READ_DISCRETE_INPUTS_DISABLED
• NMBS_SERVER_READ_HOLDING_REGISTERS_DISABLED
• NMBS_SERVER_READ_INPUT_REGISTERS_DISABLED
• NMBS_SERVER_WRITE_SINGLE_COIL_DISABLED
• NMBS_SERVER_WRITE_SINGLE_REGISTER_DISABLED
• NMBS_SERVER_WRITE_MULTIPLE_COILS_DISABLED
• NMBS_SERVER_WRITE_MULTIPLE_REGISTERS_DISABLED
• NMBS_SERVER_READ_FILE_RECORD_DISABLED
• NMBS_SERVER_WRITE_FILE_RECORD_DISABLED
• NMBS_SERVER_READ_WRITE_REGISTERS_DISABLED
• NMBS_SERVER_READ_DEVICE_IDENTIFICATION_DISABLED

Other Size Optimizations

• NMBS_STRERROR_DISABLED: Disables the code that converts nmbs_error to strings.
• NMBS_BITFIELD_MAX: Sets the size of the nmbs_bitfield type (default is 2000).

Debugging

• NMBS_DEBUG: Enables debug prints for received and sent messages.

To use nanoMODBUS as a client, follow these steps:

1. Create a connection handle using your platform's networking stack.
2. Configure an nmbs_platform_conf object with the transport type (NMBS_TRANSPORT_TCP), your custom read and write functions, and your connection handle as the arg.
3. Create the client instance using nmbs_client_create.
4. Set timeouts using nmbs_set_read_timeout.
5. Call Modbus functions like nmbs_read_holding_registers or nmbs_write_multiple_registers.

Note: Byte-level timeouts are handled by your transport functions; nmbs_set_read_timeout sets the overall response timeout.

#include <stdio.h>
#include "nanomodbus.h"
#include "my_platform_stuff.h"

int main(int argc, char* argv[]) {
    // Set up the TCP connection
    void* conn = my_connect_tcp(argv[1], argv[2]);
    if (!conn) {
        fprintf(stderr, "Error connecting to server\n");
        return 1;
    }

    // my_transport_read() and my_transport_write() are implemented by the user 
    nmbs_platform_conf platform_conf;
    nmbs_platform_conf_create(&platform_conf);
    platform_conf.transport = NMBS_TRANSPORT_TCP;
    platform_conf.read = my_transport_read;
    platform_conf.write = my_transport_write;
    platform_conf.arg = conn;    // Passing our TCP connection handle to the read/write functions

    // Create the modbus client
    nmbs_t nmbs;
    nmbs_error err = nmbs_client_create(&nmbs, &platform_conf);
    if (err != NMBS_ERROR_NONE) {
        fprintf(stderr, "Error creating modbus client\n");
        return 1;
    }

    // Set only the response timeout. Byte timeout will be handled by the TCP connection
    nmbs_set_read_timeout(&nmbs, 1000);

    // Write 2 holding registers at address 26
    uint16_t w_regs[2] = {123, 124};
    err = nmbs_write_multiple_registers(&nmbs, 26, 2, w_regs);
    if (err != NMBS_ERROR_NONE) {
        fprintf(stderr, "Error writing register at address 26 - %s", nmbs_strerror(err));
        return 1;
    }

    // Read 2 holding registers from address 26
    uint16_t r_regs[2];
    err = nmbs_read_holding_registers(&nmbs, 26, 2, r_regs);
    if (err != NMBS_ERROR_NONE) {
        fprintf(stderr, "Error reading 2 holding registers at address 26 - %s\n", nmbs_strerror(err));
        return 1;
    }
    
    // Close the TCP connection
    my_disconnect(conn);
    
    return 0;
}

nanoMODBUS is platform-agnostic and requires you to provide two platform-specific functions to handle data transport (e.g., over a serial port or TCP connection). These are passed via the nmbs_platform_conf structure.

Function Signatures

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);

Implementation Requirements

• Blocking Behavior: Both methods should block until either count bytes are processed or byte_timeout_ms expires.
• Timeout Handling:
  • byte_timeout_ms < 0: Infinite timeout.
  • byte_timeout_ms == 0: Non-blocking; read/write once and return immediately.
• Return Values:
  • Return the number of bytes actually read/written.
  • Return < 0 in case of an error.
  • A return value between 0 and count - 1 is treated as a timeout.
  • Any other value is treated as a transport error.