Modbus Bridge

Master bridge for Modbus/TCP and Modbus/RTU communication with industrial devices.

Overview

Modbus is a widely-used industrial communication standard for fieldbus communications. The Modbus Bridge enables OpenEMS to communicate with all kinds of hardware devices like photovoltaic inverters, electric meters, battery systems, and other industrial equipment that support Modbus protocol.

The bridge manages: * Modbus task execution scheduling and prioritization * Read and write request coordination across all Modbus components * Automatic defective component handling and retry logic * Cycle-synchronized communication timing * Detailed logging and debugging capabilities

Two transport protocols are supported: * Modbus/TCP - Network-based communication via TCP/IP * Modbus/RTU - Serial-based communication via RS485 or RS232

Components

Bridge Modbus/TCP

Name: Bridge Modbus/TCP

Factory-PID: Bridge.Modbus.Tcp

Purpose: Master bridge for Modbus/TCP network communication.

Use Cases: * Network-connected industrial devices * Distributed systems across network segments * Devices with native Ethernet interfaces * Preferred for modern installations

Configuration:

  • id (String): Unique bridge identifier; default: "modbusTcp0"

  • ip (String): IP address of Modbus master; default: "192.168.1.100"

  • port (Integer): TCP port number; default: 502 (standard Modbus port)

  • logVerbosity (LogVerbosity): Logging detail level; default: NONE

  • unitId (Integer): Default Modbus Unit-ID; default: 1

Bridge Modbus/RTU Serial

Name: Bridge Modbus/RTU

Factory-PID: Bridge.Modbus.Serial

Purpose: Master bridge for Modbus/RTU serial communication via RS485 or RS232.

Use Cases: * Legacy equipment with serial interfaces * Short-distance installations (under 1km) * Isolated systems without network connectivity * Multi-drop serial bus configurations

Configuration:

  • id (String): Unique bridge identifier; default: "modbusSerial0"

  • serialPort (String): Serial port name; examples: "/dev/ttyUSB0", "COM3"

  • baudRate (Integer): Baud rate; default: 9600 (typical: 9600, 19200, 38400)

  • stopBits (Integer): Stop bits (1 or 2); default: 1

  • parity (String): Parity (NONE, ODD, EVEN); default: NONE

  • logVerbosity (LogVerbosity): Logging detail level; default: NONE

Architecture

ModbusComponent Integration

Components that use Modbus communication must:

  1. Implement the ModbusComponent interface

  2. Provide a ModbusProtocol that defines read/write tasks

  3. Register with the bridge at startup

  4. Handle Modbus responses and errors

Example:

public class MyDevice implements ModbusComponent {
  @Override
  protected ModbusProtocol defineModbusProtocol() {
    return new ModbusProtocol(this, //
      new FC3ReadRegistersTask(0x0000, Priority.HIGH, //
        m(Channel1, new UnsignedWordElement(0x0000)), //
        m(Channel2, new SignedWordElement(0x0001)) //
      ) //
    );
  }
}

Task Execution Model

The ModbusWorker manages task execution:

Write Tasks

  • Executed as early as possible (directly after EXECUTE_WRITE event)

  • Always HIGH priority

  • Ensures set-points applied immediately

  • Defective components delay all writes to them

Read Tasks

  • Executed as late as possible (just before BEFORE_PROCESS_IMAGE event)

  • Prioritized by configured Priority level

  • Cycle delay automatically learned to optimize timing

  • Defective components gradually delay up to 5 minutes

Priority Levels: * HIGH - Executed every cycle (typical for control feedback) * LOW - Round-robin execution (one LOW task per cycle per component)

Defective Component Handling

If a component repeatedly fails:

  1. Bridge marks component as "defective"

  2. Read tasks gradually delayed (backoff up to 5 minutes)

  3. Prevents defective components from blocking entire bus

  4. Component can request retry via retryModbusCommunication()

  5. After successful retry, normal scheduling resumes

Cycle Management

Channels Provided by Bridge:

  • CycleTimeIsTooShort - Indicates global cycle-time is too short for all tasks

  • CycleDelay - Auto-learned delay time (in ms) for optimal read timing

  • Task count - Number of active read/write tasks

Timing Optimization:

The ModbusWorker "learns" an ideal delay time each cycle: * Measures time to execute all write tasks * Calculates when read tasks should start * Automatically applies CycleDelay for just-in-time reads

Logging and Debugging

LogVerbosity Levels

Configure via the LogVerbosity parameter (can be changed at runtime):

  • NONE - No logs (default)

  • DEBUG_LOG - Basic logging via Controller.Debug.Log

  • READS_AND_WRITES - Log all read and write requests

  • READS_AND_WRITES_VERBOSE - Include hex/binary values in logs

  • READS_AND_WRITES_DURATION - Include execution time per request

  • READS_AND_WRITES_DURATION_TRACE_EVENTS - Full trace including internal state machine

Per-Task Debug Logging

Enable in ModbusProtocol definition:

new FC3ReadRegistersTask(0x0000, Priority.HIGH, //
  m(MyChannel, new UnsignedWordElement(0x0000)) //
).debug()  // Enable debug logging for this task

Prerequisites

  • For Modbus/TCP:

  • Network connectivity to device

  • Device must accept Modbus/TCP connections on port 502 (or configured port)

  • Firewall rules allowing outbound TCP connections

  • For Modbus/RTU:

  • Serial port available on system (/dev/ttyUSB0, COM3, etc.)

  • Correct baud rate, parity, and stop bits configured

  • RS485 or RS232 cabling properly terminated

  • Single master on serial bus (Modbus RTU limitation)

Features

  • Dual transport support (TCP and RTU)

  • Automatic cycle-delay optimization for minimal latency

  • Priority-based task scheduling (HIGH/LOW)

  • Graceful defective component handling

  • Runtime logging level adjustment

  • Modbus function code flexibility (FC1-FC6, FC15-FC16)

Use Cases

  • Energy Management - Read/write to battery inverters and ESS systems

  • Monitoring - Continuous polling of meters and inverters

  • Control - Setting power setpoints and operating parameters

  • Data Collection - Gathering historical data from industrial devices

  • Legacy Integration - Connecting older devices with Modbus-only interfaces

Source Code