Creation of modbus tcp client and state machine (#699)

* Creation of modbus tcp client and state machine

* Fixing Pre-commit format error

Author: brettpac

docs/cl_modbus_tcp_relay_plan.md

@@ -0,0 +1,75 @@
+cmake_minimum_required(VERSION 3.5)
+project(cl_modbus_tcp_relay)
+
+# Default to C++17
+if(NOT CMAKE_CXX_STANDARD)
+  set(CMAKE_CXX_STANDARD 17)
+endif()
+
+if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  add_compile_options(-Wall -Wextra -Wpedantic)
+endif()
+
+# find dependencies
+find_package(ament_cmake REQUIRED)
+find_package(rclcpp REQUIRED)
+find_package(smacc2 REQUIRED)
+find_package(PkgConfig REQUIRED)
+
+# Find libmodbus - prefer system-installed, fallback to workspace source
+pkg_check_modules(MODBUS libmodbus)
+
+if(NOT MODBUS_FOUND)
+  # Check if libmodbus source exists in workspace
+  set(LIBMODBUS_WORKSPACE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../../../libmodbus/src")
+  if(EXISTS "${LIBMODBUS_WORKSPACE_PATH}/modbus.h")
+    message(STATUS "Using workspace libmodbus source at: ${LIBMODBUS_WORKSPACE_PATH}")
+    set(MODBUS_INCLUDE_DIRS ${LIBMODBUS_WORKSPACE_PATH})
+    # Note: When using workspace source, libmodbus must be built separately
+    # For full functionality, install libmodbus-dev: sudo apt install libmodbus-dev
+    set(MODBUS_LIBRARIES "modbus")
+    set(MODBUS_FOUND TRUE)
+  else()
+    message(FATAL_ERROR "libmodbus not found. Install with: sudo apt install libmodbus-dev")
+  endif()
+endif()
+
+set(dependencies
+  rclcpp
+  smacc2
+)
+
+include_directories(
+  include
+  ${MODBUS_INCLUDE_DIRS}
+)
+
+add_library(${PROJECT_NAME} SHARED
+  src/${PROJECT_NAME}/cl_modbus_tcp_relay.cpp
+  src/${PROJECT_NAME}/components/cp_modbus_connection.cpp
+  src/${PROJECT_NAME}/components/cp_modbus_relay.cpp
+)
+
+target_link_libraries(${PROJECT_NAME}
+  ${MODBUS_LIBRARIES}
+)
+
+ament_target_dependencies(${PROJECT_NAME}
+  ${dependencies}
+)
+
+ament_export_include_directories(include)
+ament_export_libraries(${PROJECT_NAME})
+ament_export_dependencies(${dependencies})
+
+install(TARGETS ${PROJECT_NAME}
+  ARCHIVE DESTINATION lib
+  LIBRARY DESTINATION lib
+  RUNTIME DESTINATION bin
+)
+
+install(DIRECTORY include/
+  DESTINATION include/
+)
+
+ament_package()

smacc2_client_library/cl_modbus_tcp_relay/CMakeLists.txt

@@ -0,0 +1,240 @@
+# 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
+
+```bash
+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
+
+| Behavior | Description |
+|----------|-------------|
+| `CbRelayOn` | Turn on a specific relay channel (1-8) |
+| `CbRelayOff` | Turn off a specific relay channel (1-8) |
+| `CbAllRelaysOn` | Turn on all 8 relay channels |
+| `CbAllRelaysOff` | Turn off all 8 relay channels |
+| `CbRelayStatus` | Read the status of relay channels |
+
+### Events
+
+```cpp
+// 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):
+
+```yaml
+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
+```
+
+### Default Values
+
+| Parameter | Default |
+|-----------|---------|
+| `ip_address` | "192.168.1.254" |
+| `port` | 502 |
+| `slave_id` | 1 |
+| `heartbeat_interval_ms` | 1000 |
+| `connect_on_init` | true |
+
+## Usage
+
+### Orthogonal Definition
+
+```cpp
+#include <cl_modbus_tcp_relay/cl_modbus_tcp_relay.hpp>
+
+class OrRelay : public smacc2::Orthogonal<OrRelay>
+{
+public:
+  void onInitialize() override
+  {
+    // Configuration loaded from YAML parameters
+    auto relay_client = this->createClient<cl_modbus_tcp_relay::ClModbusTcpRelay>();
+  }
+};
+```
+
+### State Definition
+
+```cpp
+#include <cl_modbus_tcp_relay/client_behaviors/cb_relay_on.hpp>
+#include <cl_modbus_tcp_relay/client_behaviors/cb_relay_off.hpp>
+
+struct StActivateRelay : smacc2::SmaccState<StActivateRelay, SmExample>
+{
+  using SmaccState::SmaccState;
+
+  typedef mpl::list<
+    Transition<EvCbSuccess<CbRelayOn, OrRelay>, StNextState>,
+    Transition<EvCbFailure<CbRelayOn, OrRelay>, StError>,
+    Transition<EvConnectionLost<CpModbusConnection, OrRelay>, StReconnect>
+  > reactions;
+
+  static void staticConfigure()
+  {
+    // Turn on channel 1
+    configure_orthogonal<OrRelay, cl_modbus_tcp_relay::CbRelayOn>(1);
+  }
+};
+```
+
+### Launch File
+
+```python
+from launch import LaunchDescription
+from launch_ros.actions import Node
+from ament_index_python.packages import get_package_share_directory
+import os
+
+def generate_launch_description():
+    config_file = os.path.join(
+        get_package_share_directory('your_state_machine'),
+        'config',
+        'your_config.yaml'
+    )
+
+    return LaunchDescription([
+        Node(
+            package='your_state_machine',
+            executable='your_state_machine_node',
+            name='your_state_machine',
+            output='screen',
+            parameters=[config_file]
+        )
+    ])
+```
+
+## Manual Testing with mbpoll
+
+For debugging and manual testing, you can use the `mbpoll` command-line tool:
+
+```bash
+# Install mbpoll
+sudo apt install mbpoll
+
+# Read all 8 coil states
+mbpoll -m tcp -a 1 -t 0 -r 1 -c 8 192.168.1.254
+
+# Write single coil ON (channel 1)
+mbpoll -m tcp -a 1 -t 0 -r 1 192.168.1.254 1
+
+# Write single coil OFF (channel 1)
+mbpoll -m tcp -a 1 -t 0 -r 1 192.168.1.254 0
+
+# Write all coils ON
+mbpoll -m tcp -a 1 -t 0 -r 1 -c 8 192.168.1.254 1 1 1 1 1 1 1 1
+
+# Write all coils OFF
+mbpoll -m tcp -a 1 -t 0 -r 1 -c 8 192.168.1.254 0 0 0 0 0 0 0 0
+```
+
+### mbpoll Options Reference
+
+| Option | Description |
+|--------|-------------|
+| `-m tcp` | Use Modbus TCP protocol |
+| `-a 1` | Slave address (1) |
+| `-t 0` | Data type: coil (0) |
+| `-r 1` | Starting reference (1 = address 0x0000) |
+| `-c 8` | Number of coils to read/write |
+
+## Modbus Protocol Reference
+
+| Operation | Function Code | Address Range |
+|-----------|---------------|---------------|
+| Read Coils | 0x01 | 0x0000-0x0007 |
+| Write Single Coil | 0x05 | 0x0000-0x0007 |
+| Write Multiple Coils | 0x0F | 0x0000 (8 coils) |
+
+### Coil Values
+
+- ON: 0xFF00 (function 0x05) or 1 (function 0x0F)
+- OFF: 0x0000
+
+## Building
+
+```bash
+# From workspace root
+colcon build --packages-select cl_modbus_tcp_relay
+```
+
+## Test State Machine
+
+See `sm_modbus_tcp_relay_test_1` for a complete test state machine that exercises all behaviors.
+
+## License
+
+Apache-2.0