Core Classes

This section provides detailed documentation for the core classes in libmodbus.

📊 Data Model Classes

ModbusDataModel

The primary data storage class for all Modbus data types.

class ModbusDataModel

Configurable Modbus data model with support for all four data types.

This class implements a complete Modbus data model that stores:

Coils (read/write discrete outputs)
Discrete Inputs (read-only discrete inputs)
Holding Registers (read/write 16-bit registers)
Input Registers (read-only 16-bit registers)

The implementation uses vectors for dynamic sizing and supports both default limits that comply with Modbus specifications and custom limits for specialized applications.

🖥️ Server Classes

ModbusBaseServer

Abstract base class for all Modbus server implementations.

class ModbusBaseServer

Abstract base class for all Modbus server implementations.

This class provides the foundation for Modbus server implementations across different transport protocols (RTU, ASCII, TCP). It manages the data model and command registry that are common to all protocols.

The class uses the Command pattern to handle different function codes, with each function code mapped to a specific command implementation. This design allows for easy extension and modification of supported function codes.

Note

This is an abstract base class. Use the protocol-specific derived classes (ModbusRtuServer, etc.) for actual server implementation.

Subclassed by ModbusRtuServer

Public Functions

inline ModbusBaseServer()

Constructor initializes the command registry.

Registers all supported Modbus function codes with their corresponding command implementations. Currently supports:

FC 01: Read Coils
FC 02: Read Discrete Inputs
FC 03: Read Holding Registers
FC 04: Read Input Registers
FC 05: Write Single Coil
FC 06: Write Single Register
FC 08: Diagnostics
FC 15: Write Multiple Coils
FC 16: Write Multiple Registers

inline virtual std::vector<uint8_t> process(const std::vector<uint8_t> &requestData)

Process a Modbus request and generate a response.

This is the main entry point for request processing. Each protocol-specific derived class must implement this method to handle the protocol-specific frame formatting and validation.

Note

The base implementation returns an empty vector. Derived classes must override this method to provide actual functionality.

Parameters:: requestData – Raw request data as received from the transport layer
Returns:: Raw response data to be sent back, or empty vector if no response

Public Members

ModbusDataModel data

Modbus data model instance.

Contains all four types of Modbus data: coils, discrete inputs, holding registers, and input registers. This data model is shared across all command implementations.

std::map<ModbusFunctionCode, std::unique_ptr<ModbusCommand>> commands

Command registry mapping function codes to command implementations.

This map contains the association between Modbus function codes and their corresponding command implementations. New function codes can be supported by adding entries to this map.

ModbusRtuServer

RTU protocol-specific server implementation.

class ModbusRtuServer : public ModbusBaseServer 

Modbus RTU server implementation.

Implements the Modbus RTU (Remote Terminal Unit) protocol for serial communication. This class handles RTU-specific frame processing including:

CRC validation and generation
Slave address checking
Binary frame formatting
Exception response generation

The RTU protocol uses binary encoding and CRC-16 checksums for error detection. Frames are transmitted without start/stop delimiters, relying on timing gaps for frame synchronization.

Note

This server is configured to respond to slave address 1 by default. Broadcast messages (address 0) are processed but no response is sent.

Public Functions

virtual std::vector<uint8_t> process(const std::vector<uint8_t> &requestData)

Process an RTU request and generate an RTU response.

This method handles the complete RTU request processing pipeline:

Frame validation (minimum size, CRC check)
Slave address verification
Function code lookup and command execution
Response frame generation and CRC calculation

The method performs the following validations:

Minimum frame size (4 bytes: address + function + CRC)
CRC integrity check
Slave address matching (responds to address 1 only)
Function code support check

Exception responses are generated for:

Unsupported function codes
Invalid request parameters
Data access errors

Note

No response is generated for:

Invalid CRC
Wrong slave address
Broadcast messages (address 0)

Parameters:: requestData – Raw RTU frame data including slave address and CRC
Returns:: Complete RTU response frame, or empty vector if no response needed

🖼️ Frame Classes

ModbusFrame

Core Protocol Data Unit (PDU) implementation.

class ModbusFrame

Core Modbus Protocol Data Unit (PDU) implementation.

This class represents the core Modbus PDU that is common to all Modbus variants (RTU, ASCII, TCP). It contains the function code, frame data, and exception information. The PDU is embedded within the various transport-specific frame formats.

The frame structure is:

Function Code (1 byte)
Data (0-252 bytes)
Exception Code (1 byte, only for exception frames)

Public Functions

inline ModbusFrame()

Default constructor.

Creates an uninitialized frame with NONE type, NONE function code, and no exception code.

inline ModbusFrame(ModbusFrameType type, ModbusFunctionCode func)

Constructor with frame type and function code.

Parameters:

type – The type of frame (REQUEST, RESPONSE, or EXCEPTION)
func – The Modbus function code

Public Members

ModbusFrameType frameType: Type of frame (request/response/exception)

ModbusFunctionCode functionCode: Modbus function code.

std::vector<uint8_t> frameData: Frame data payload.

ModbusExceptionCode exceptionCode: Exception code (only used for exception frames)

ModbusRtuFrame

RTU protocol-specific frame implementation.

class ModbusRtuFrame

Modbus RTU (Remote Terminal Unit) frame implementation.

Implements the Modbus RTU frame format used for serial communication. RTU frames use binary encoding and CRC-16 checksums for error detection.

Note

The CRC is calculated using the Modbus CRC-16 algorithm over all bytes except the CRC itself, with low byte transmitted first.

Public Functions

inline ModbusRtuFrame()

Default constructor.

Creates an RTU frame with slave address 0 and checksum 0.

inline ModbusRtuFrame(uint8_t addr)

Constructor with slave address.

Parameters:: addr – Slave address (1-247, 0 for broadcast)

std::vector<uint8_t> serialize()

Serialize the RTU frame to a byte vector.

Converts the RTU frame to its binary representation suitable for transmission over a serial link. The function automatically calculates and appends the CRC-16 checksum.

Note

The CRC is calculated using the Modbus CRC-16 algorithm

Returns:: Vector of bytes representing the serialized frame

void deserialize(ModbusFrameType frameType, const std::vector<uint8_t> &data)

Deserialize a byte vector into an RTU frame.

Parses a received byte vector and populates the RTU frame fields. The function extracts the slave address, function code, data, and CRC.

Note

This function does not validate the CRC - that should be done by the caller before calling this function.

Parameters:

frameType – Expected frame type (REQUEST, RESPONSE, or EXCEPTION)
data – Byte vector containing the raw frame data

Public Members

uint8_t slaveaddr: Slave address (1-247, 0 for broadcast)

ModbusFrame pdu: Protocol Data Unit.

uint16_t checksum: CRC-16 checksum.

ModbusAsciiFrame

ASCII protocol frame implementation (planned).

class ModbusAsciiFrame

Modbus ASCII frame implementation.

Implements the Modbus ASCII frame format used for serial communication. ASCII frames use hexadecimal character encoding and LRC checksums.

Note

ASCII frames are longer than RTU frames but are human-readable and less susceptible to transmission errors.

Warning

ASCII implementation is currently incomplete (TODO)

Public Functions

std::vector<uint8_t> serialize()

Serialize the ASCII frame to a byte vector.

Todo:: This method is not yet implemented

Returns:: Vector of bytes representing the serialized frame

void deserialize(const std::vector<uint8_t> &data)

Deserialize a byte vector into an ASCII frame.

Todo:: This method is not yet implemented

Parameters:: data – Byte vector containing the raw frame data

Public Members

uint8_t start: Start character (always ‘:’)

uint8_t address: Slave address.

ModbusFrame pdu: Protocol Data Unit.

uint16_t checksum: LRC checksum.

uint16_t end: End characters (CR LF)

ModbusTcpFrame

TCP protocol frame implementation (planned).

class ModbusTcpFrame

Modbus TCP frame implementation.

Implements the Modbus TCP frame format used for Ethernet communication. TCP frames include an MBAP header followed by the PDU. No checksum is needed as TCP provides reliable delivery.

Frame structure: | MBAP Header (7 bytes) | PDU (1-253 bytes) |

Warning

TCP implementation is currently incomplete (TODO)

Public Functions

std::vector<uint8_t> serialize()

Serialize the TCP frame to a byte vector.

Todo:: This method is not yet implemented

Returns:: Vector of bytes representing the serialized frame

void deserialize(const std::vector<uint8_t> &data)

Deserialize a byte vector into a TCP frame.

Todo:: This method is not yet implemented

Parameters:: data – Byte vector containing the raw frame data

Public Members

MbapHeader mbapHeader: MBAP header.

ModbusFrame pdu: Protocol Data Unit.

MbapHeader

MBAP header for Modbus TCP frames.

class MbapHeader

Modbus Application Protocol (MBAP) header for TCP frames.

The MBAP header is used in Modbus TCP to provide transaction identification, protocol identification, length information, and unit identification.

Public Functions

inline MbapHeader()

Default constructor.

Creates an MBAP header with all fields set to 0.

inline MbapHeader(uint16_t transactionId, uint16_t protocolId, uint16_t length, uint8_t unitId)

Constructor with all header fields.

Parameters:

transactionId – Transaction identifier
protocolId – Protocol identifier (should be 0 for Modbus)
length – Length of following bytes
unitId – Unit identifier

Public Members

uint16_t transactionId: Transaction identifier for matching requests/responses.

uint16_t protocolId: Protocol identifier (always 0 for Modbus)

uint16_t length: Number of following bytes (PDU length + 1)

uint8_t unitId: Unit identifier (slave address equivalent)

🎮 Command Classes

ModbusCommand

Abstract base class for all command implementations.

class ModbusCommand

Abstract base class for all Modbus command implementations.

This class defines the interface for Modbus command processing using the Command pattern. Each specific function code has its own derived command class that implements the execute() method.

The class also provides common validation methods that are used by multiple command implementations to ensure consistent error handling and compliance with Modbus specifications.

Subclassed by DiagnosticsCommand, ReadCoilCommand, ReadDiscreteInputCommand, ReadHoldingRegisterCommand, ReadInputRegisterCommand, WriteCoilCommand, WriteHoldingRegisterCommand, WriteMultipleCoilsCommand, WriteMultipleRegistersCommand

Public Functions

virtual ~ModbusCommand() = default: Virtual destructor for proper polymorphic destruction.

virtual ModbusFrame execute(ModbusDataModel &data, const ModbusFrame &request) = 0

Execute the command with given data model and request.

This is the main entry point for command execution. Each derived class implements this method to handle its specific function code.

Parameters:

data – Reference to the Modbus data model
request – The incoming Modbus request frame

Returns:

Response frame (normal response or exception)

Read Command Classes

class ReadCoilCommand : public ModbusCommand 

Implementation of Read Coils function (FC 01)

Reads the status of coils (discrete outputs) from the data model. Returns a bit-packed response where each bit represents one coil state.

Request format:

Starting Address (2 bytes)
Quantity of Coils (2 bytes)

Response format:

Byte Count (1 byte)
Coil Status (n bytes, bit-packed)

Note

Coils are packed 8 per byte, LSB first

Public Functions

virtual ModbusFrame execute(ModbusDataModel &data, const ModbusFrame &request)

Execute the Read Coils command.

Parameters:

data – Reference to the Modbus data model
request – The incoming request frame

Returns:

Response frame containing coil status or exception

class ReadDiscreteInputCommand : public ModbusCommand 

Implementation of Read Discrete Inputs function (FC 02)

Reads the status of discrete inputs from the data model. Returns a bit-packed response where each bit represents one input state.

Request format:

Starting Address (2 bytes)
Quantity of Inputs (2 bytes)

Response format:

Byte Count (1 byte)
Input Status (n bytes, bit-packed)

Note

Inputs are packed 8 per byte, LSB first

Public Functions

virtual ModbusFrame execute(ModbusDataModel &data, const ModbusFrame &request)

Execute the Read Discrete Inputs command.

Parameters:

data – Reference to the Modbus data model
request – The incoming request frame

Returns:

Response frame containing input status or exception

class ReadHoldingRegisterCommand : public ModbusCommand 

Implementation of Read Holding Registers function (FC 03)

Reads holding register values from the data model. Returns register values in big-endian format.

Request format:

Starting Address (2 bytes)
Quantity of Registers (2 bytes)

Response format:

Byte Count (1 byte)
Register Values (n*2 bytes, big-endian)

Public Functions

virtual ModbusFrame execute(ModbusDataModel &data, const ModbusFrame &request)

Execute the Read Holding Registers command.

Parameters:

data – Reference to the Modbus data model
request – The incoming request frame

Returns:

Response frame containing register values or exception

class ReadInputRegisterCommand : public ModbusCommand 

Implementation of Read Input Registers function (FC 04)

Reads input register values from the data model. Returns register values in big-endian format.

Request format:

Starting Address (2 bytes)
Quantity of Registers (2 bytes)

Response format:

Byte Count (1 byte)
Register Values (n*2 bytes, big-endian)

Public Functions

virtual ModbusFrame execute(ModbusDataModel &data, const ModbusFrame &request)

Execute the Read Input Registers command.

Parameters:

data – Reference to the Modbus data model
request – The incoming request frame

Returns:

Response frame containing register values or exception

Write Command Classes

class WriteCoilCommand : public ModbusCommand 

Implementation of Write Single Coil function (FC 05)

Writes a single coil value to the data model.

Request format:

Output Address (2 bytes)
Output Value (2 bytes: 0x0000 for OFF, 0xFF00 for ON)

Response format:

Echo of the complete request

Public Functions

virtual ModbusFrame execute(ModbusDataModel &data, const ModbusFrame &request)

Execute the Write Single Coil command.

Parameters:

data – Reference to the Modbus data model
request – The incoming request frame

Returns:

Response frame (echo of request) or exception

class WriteHoldingRegisterCommand : public ModbusCommand 

Implementation of Write Single Register function (FC 06)

Writes a single holding register value to the data model.

Request format:

Register Address (2 bytes)
Register Value (2 bytes)

Response format:

Echo of the complete request

Public Functions

virtual ModbusFrame execute(ModbusDataModel &data, const ModbusFrame &request)

Execute the Write Single Register command.

Parameters:

data – Reference to the Modbus data model
request – The incoming request frame

Returns:

Response frame (echo of request) or exception

class WriteMultipleCoilsCommand : public ModbusCommand 

Implementation of Write Multiple Coils function (FC 15)

Writes multiple coil values to the data model. Coil values are transmitted as bit-packed bytes.

Request format:

Starting Address (2 bytes)
Quantity of Outputs (2 bytes)
Byte Count (1 byte)
Outputs Value (n bytes, bit-packed)

Response format:

Starting Address (2 bytes)
Quantity of Outputs (2 bytes)

Note

Coils are packed 8 per byte, LSB first

Public Functions

virtual ModbusFrame execute(ModbusDataModel &data, const ModbusFrame &request)

Execute the Write Multiple Coils command.

Parameters:

data – Reference to the Modbus data model
request – The incoming request frame

Returns:

Response frame containing address and quantity or exception

class WriteMultipleRegistersCommand : public ModbusCommand 

Implementation of Write Multiple Registers function (FC 16)

Writes multiple holding register values to the data model. Register values are transmitted in big-endian format.

Request format:

Starting Address (2 bytes)
Quantity of Registers (2 bytes)
Byte Count (1 byte)
Registers Value (n*2 bytes, big-endian)

Response format:

Starting Address (2 bytes)
Quantity of Registers (2 bytes)

Public Functions

virtual ModbusFrame execute(ModbusDataModel &data, const ModbusFrame &request)

Execute the Write Multiple Registers command.

Parameters:

data – Reference to the Modbus data model
request – The incoming request frame

Returns:

Response frame containing address and quantity or exception

Diagnostic Command Classes

class DiagnosticsCommand : public ModbusCommand 

Implementation of Diagnostics function (FC 08)

Provides a series of diagnostic and testing functions for Modbus communication. Currently supports basic sub-functions like Return Query Data and communication restart.

Request format:

Sub-function (2 bytes)
Data (2 bytes, sub-function specific)

Response format:

Sub-function (2 bytes, echo)
Data (2 bytes, sub-function specific)

Note

Only basic diagnostic sub-functions are currently implemented

Public Functions

virtual ModbusFrame execute(ModbusDataModel &data, const ModbusFrame &request)

Execute the Diagnostics command.

Parameters:

data – Reference to the Modbus data model
request – The incoming request frame

Returns:

Response frame containing diagnostic response or exception

🧮 Utility Classes

Checksum

Static utility class for checksum calculations.

class Checksum

Static utility class for Modbus checksum calculations.

This class provides static methods for calculating checksums used in different Modbus transport protocols. The checksums are essential for error detection in serial communications where data corruption can occur.

Note

All methods are static and the class is not meant to be instantiated.

Public Static Functions

static uint8_t calculateLRC(const uint8_t *pucFrame, uint16_t usLen)

Calculate LRC (Longitudinal Redundancy Check) for Modbus ASCII.

Calculates the LRC checksum used by Modbus ASCII protocol. The LRC is computed by adding all bytes in the message and taking the two’s complement of the result.

Algorithm:

Add all bytes in the frame (excluding the LRC itself)
Take the two’s complement of the sum
Return the result as a single byte

Note

The LRC is calculated over the binary representation of the ASCII characters, not the ASCII characters themselves.

Parameters:

pucFrame – Pointer to the frame data
usLen – Length of the frame data in bytes

Returns:

LRC checksum value (8-bit)

static uint16_t calculateCRC16(const uint8_t *buffer, uint16_t length)

Calculate CRC-16 checksum for Modbus RTU.

Calculates the CRC-16 checksum used by Modbus RTU protocol. This implementation uses the standard Modbus CRC-16 algorithm with polynomial 0xA001 (reversed representation of 0x8005).

Algorithm:

Initialize CRC register to 0xFFFF
For each byte: a. XOR byte with low byte of CRC register b. For each bit (8 iterations):
- If LSB of CRC is 1: shift right and XOR with 0xA001
- If LSB of CRC is 0: shift right only
Return final CRC value

Note

The CRC is transmitted LSB first in RTU frames. This function returns the CRC in native byte order; the caller is responsible for proper byte ordering.

Note

This is the standard Modbus CRC-16 algorithm as specified in the Modbus over Serial Line Specification and Implementation Guide V1.02.

Parameters:

buffer – Pointer to the data buffer
length – Length of the data buffer in bytes

Returns:

CRC-16 checksum value (16-bit)