firmware-base/docs-c/modbus/ModbusTCP.md

title	description	keywords
ModbusTCP Class Documentation	Documentation for the ModbusTCP class that manages Modbus TCP communication in an industrial environment	ESP32 ModbusTCP Modbus Server Industrial Communication

ModbusTCP

Path: src/modbus/ModbusTCP.h

Revision History: Initial documentation

The ModbusTCP class manages Modbus TCP communication, acting as a Server/Slave. It listens for Modbus TCP requests, finds the target component, and uses the Component's network interface (read/mb_tcp_write) to process the request.

REQUIREMENTS

• ESP32 with TCP/IP connectivity
• ModbusServerTCPasync instance (from eModbus library)
• Component hierarchy with a parent owner component (typically PHApp)

PROVIDES

• ModbusTCP Class: Main class for managing Modbus TCP server functionality
• Address Mapping Functionality: Maps Modbus addresses to component functions

FEATURES

• Handles Modbus TCP slave/server functionality
• Supports standard Modbus function codes:
  • Read Coils (01)
  • Read Holding Registers (03)
  • Write Single Coil (05)
  • Write Single Register (06)
  • Write Multiple Coils (15)
  • Write Multiple Registers (16)
• Manages address mapping between Modbus addresses and components
• Routes Modbus requests to appropriate component handlers
• Provides component registration system for Modbus address ranges
• Maps internal errors to Modbus exception codes

DEPENDENCIES

• Component.h
• enums.h
• config-modbus.h
• ArduinoLog.h
• Vector.h
• ModbusServerTCPasync.h
• ModbusTypes.h

graph TD
    ModbusTCP --> Component
    ModbusTCP --> enums
    ModbusTCP --> ModbusTypes
    ModbusTCP --> ModbusServerTCPasync
    ModbusTCP --> Vector
    ModbusTCP --> ArduinoLog
    ModbusTCP --> configmodbus[config-modbus.h]

BEHAVIOUR

sequenceDiagram
    participant Client as Modbus TCP Client
    participant Server as ModbusTCP Server
    participant Component as Component
    
    Client->>Server: TCP Connection
    Client->>Server: Modbus Request (Function Code + Address)
    Server->>Server: Find component for address
    alt Component found
        Server->>Component: mb_tcp_read() or mb_tcp_write()
        Component->>Server: Return data/status
        Server->>Client: Modbus Response with data
    else No component or mapping found
        Server->>Client: Exception Response
    end

EXAMPLE

#include "ModbusTCP.h"

// Create ModbusServerTCPasync instance
ModbusServerTCPasync mbTCPServer;

// Create and initialize ModbusTCP
ModbusTCP modbusTCP(appComponent, &mbTCPServer);

// Register component with Modbus address block
MB_Registers tempSensorRegisters = {
    .startAddress = 1000,
    .count = 10,
    .type = FN_READ_HOLD_REGISTER,
    .access = MB_ACCESS_READ_WRITE,
    .componentId = 0  // Will be filled by ModbusTCP
};
modbusTCP.registerModbus(temperatureComponent, tempSensorRegisters);

// Setup and start the Modbus TCP manager
modbusTCP.setup();

// Call this regularly in the main loop
modbusTCP.loop();

TODOS

PERFORMANCE

• Consider implementing a more efficient lookup method for address mappings (e.g., hash map) for projects with many components
• Add optional caching for frequently read values to reduce component calls
• Optimize byte packing/unpacking for multi-coil operations

SECURITY

• Add IP filtering capability to restrict access to authorized clients
• Implement authentication mechanism for Modbus TCP connections
• Consider adding encrypted Modbus TCP support for sensitive applications

COMPLIANCE

• Ensure full compliance with Modbus Application Protocol Specification V1.1b3
• Add support for other function codes (Read Input Registers, Read Discrete Inputs) if needed

RECOMMENDATIONS

• Create unit tests to validate mapping and routing functionality
• Maintain detailed logs of Modbus communications for debugging
• Implement a strict mode that returns exceptions for unmapped addresses (currently configurable)
• Consider adding diagnostic counters for monitoring communication quality