cl_modbus_tcp_relay

SMACC2 client library for controlling Modbus TCP relay boards, specifically designed for the Waveshare 8-Channel POE ETH Relay.

Overview

This client library provides a SMACC2-compatible interface for controlling relay boards via Modbus TCP protocol. It uses the libmodbus C library for communication and follows SMACC2’s pure component-based architecture.

Target Hardware

• Device: Waveshare 8-Channel POE ETH Relay (or compatible)
• Protocol: Modbus TCP
• Default IP: 192.168.1.254
• Default Port: 502
• Slave ID: 0x01
• Coil Addresses: 0x0000-0x0007 (channels 1-8)

Dependencies

System Dependencies

sudo apt install libmodbus-dev

ROS2 Dependencies

• smacc2

Architecture

Client: ClModbusTcpRelay

Pure orchestrator that creates and configures components during initialization. Configuration is loaded from YAML parameters.

Components

CpModbusConnection

Manages libmodbus context lifecycle, TCP connection, and heartbeat monitoring.

Responsibilities:

• Create/destroy modbus_t context
• Manage TCP connection state
• Periodic heartbeat via ISmaccUpdatable
• Emit connection state change signals
• Thread-safe connection access via mutex

Signals:

• onConnectionLost_ - Emitted when heartbeat fails
• onConnectionRestored_ - Emitted when reconnection succeeds
• onConnectionError_ - Emitted on connection errors

CpModbusRelay

Handles Modbus coil read/write operations for the 8-channel relay.

Methods:

• writeCoil(int channel, bool state) - Write single channel (1-8)
• writeAllCoils(bool state) - Write all channels ON or OFF
• writeAllCoils(uint8_t mask) - Write all channels with bitmask
• readCoil(int channel) - Read single channel state
• readAllCoils() - Read all channel states

Client Behaviors

Events

// Connection events (source: CpModbusConnection)
EvConnectionLost<CpModbusConnection, OrRelay>
EvConnectionRestored<CpModbusConnection, OrRelay>

// Relay operation events (source: CpModbusRelay)
EvRelayWriteSuccess<CpModbusRelay, OrRelay>
EvRelayWriteFailure<CpModbusRelay, OrRelay>

Configuration

Configuration is loaded from ROS2 parameters (typically via YAML config file):

your_state_machine:
  ros__parameters:
    modbus_relay:
      ip_address: "192.168.1.254"    # Relay board IP address
      port: 502                       # Modbus TCP port
      slave_id: 1                     # Modbus slave ID
      heartbeat_interval_ms: 1000     # Heartbeat check interval
      connect_on_init: true           # Auto-connect on initialization

File truncated at 100 lines see the full file