DOCSEARCHbyAlgolia
Submit Docs

libmodbus Documentation

repository·master·Indexed 26 days ago

https://github.com/stephane/libmodbus

A free software library written in C for sending and receiving data using the Modbus protocol. It supports serial port and Ethernet connections across multiple platforms, including Linux, Mac OS X, FreeBSD, Windows, and Embox RTOS. The library provides APIs for managing Modbus contexts (RTU, TCP, and TCP PI), reading and writing data as a client, handling requests as a server, and manipulating data using specialized macros.

Tokens
19.4K
Snippets
82
Records
130
Agent score
83%

What's inside libmodbus

  1. Create an RTU (Serial) context

    master

    The RTU (Remote Terminal Unit) backend is used for serial communication using a compact binary representation. In RTU mode, the master (client) always initiates communication.

    Important Note on Timing: The libmodbus RTU implementation sends bytes as fast as possible rather than being strictly time-based. You must ensure that the slave's response timeout is set to a value less than the master's response timeout to prevent other slaves from ignoring requests when one is unresponsive.

  3. Install libmodbus on Windows

    master

    There are two primary ways to build libmodbus on Windows:

    1. MinGW/MSYS: Install MinGW and MSYS, then select common packages including gcc, automake, and libtool.
    2. Microsoft Visual Studio: Follow the specific instructions located in ./src/win32/README.md to use the provided Visual C project.

  5. Install libmodbus from source

    master

    To compile and install libmodbus on Linux, Mac OS X, FreeBSD, or similar systems, you need automake, autoconf, libtool, and a C compiler (gcc or clang).

    If the configure script is missing, run ./autogen.sh first. Then, run the standard configuration and installation sequence. You can specify a custom installation directory using the --prefix option.

    ./autogen.sh
./configure --prefix=/usr/local/
make
make install

  6. Compile libmodbus in a Visual Studio Console App

    master

    To integrate libmodbus into a new Visual Studio Console Application, follow these steps:

    1. Prepare Source: Download the libmodbus source from GitHub and decompress it.
    2. Configure: Open a Windows terminal (cmd) in the src/win32 directory and run cscript configure.js.
    3. Setup Files:
      • Copy the generated config.h from src/win32 to the src directory.
      • Create a new 'Console App' project in Visual Studio.
      • Create a directory named libmodbus inside your VS project folder (at the same level as your .vcxproj file).
      • Copy all *.c and *.h files from the libmodbus src directory into your new libmodbus folder.
      • Copy modbus.rc into your VS project folder.
    4. Project Organization:
      • Add libmodbus/*.c files to Solution Explorer -> Source Files.
      • Add libmodbus/*.h files to Solution Explorer -> Header Files.
      • Add modbus.rc to Solution Explorer -> Resource Files.
      • Verify that modbus.rc includes #include "modbus-version.h".
    5. Project Configuration (via Property Pages):
      • C/C++ -> General -> Additional Include Directories: Add the libmodbus folder.
      • Resources -> Additional Include Directories: Add the libmodbus folder.
      • Linker -> Input: Define ws2_32.lib.
      • C/C++ -> Preprocessor -> Preprocessor Definitions: Add _CRT_SECURE_NO_WARNINGS if required.

  7. Create a libmodbus DLL

    master

    To build modbus.dll and the corresponding import library modbus.lib using Visual Studio, use the project files provided in the src/win32 directory.

    Before building, you must run the configuration script to generate necessary header files:

    1. Open a Windows terminal.
    2. Navigate to the src/win32 directory.
    3. Run cscript configure.js.

    This process generates:

    • config.h
    • modbus-version.h
    cscript configure.js

  10. Initialize a Modbus context

    master
    To use libmodbus, you must first allocate a modbus_t context using a function specific to your required backend. This context contains all necessary information to establish a connection. Once created, you can use the common API to read/write data or set timeouts, making it easy to switch backends (e.g., from RTU to TCP) without changing your core logic.

  11. Troubleshoot modbus_reply() errors

    master

    When modbus_reply() fails, it returns -1 and sets errno.

    Common error codes include:

    • EMBMDATA: Occurs when the actual sending of the response fails.
    • System errors: The function may also return errors from the underlying syscalls used to send the response (such as send or write).

  12. Troubleshoot modbus_write_bits() errors

    master

    When using modbus_write_bits(), the following error codes may be returned via errno if the function returns -1:

    • EINVAL: Occurs if ctx or src is NULL, or if nb is less than 1.
    • EMBXILVAL: Occurs if you attempt to write too many bits (i.e., nb is greater than MODBUS_MAX_WRITE_BITS).