Modbus RTU Relay Control

Production-focused Python package and tools for controlling Waveshare Modbus RTU relay boards, with an optional MQTT bridge.

What This Repo Contains

• Relay control library under src/modbus_relay_control/
• Interactive CLI (relay-cli)
• MQTT bridge module (modbus_relay_control.mqtt_bridge)
• Integration smoke test at tests/integration/mqtt_smoketest.ps1
• Deployment assets under config/ and scripts/

Installation

uv sync

Usage

Interactive CLI

# Auto-detect serial port
uv run relay-cli

# Explicit serial port
uv run relay-cli --port COM4

# Linux example
uv run relay-cli --port /dev/ttyUSB0 --baud 9600 --slave 1 --verbose

MQTT Bridge

uv run python -m modbus_relay_control.mqtt_bridge \
  --port COM4 \
  --baud 9600 \
  --slave 1 \
  --mqtt-host localhost \
  --mqtt-port 1883 \
  --mqtt-base-topic modbus/relay

Windows Smoke Test

uv run pwsh -NoProfile -File .\tests\integration\mqtt_smoketest.ps1 -Port COM4

Library Example

from modbus_relay_control.modbus_adapter import connect_relay_controller
from modbus_relay_control.relay_core import ModbusConfig, RelayState, create_default_board

config = ModbusConfig(port="COM4", baudrate=9600, slave_id=1)
board = create_default_board()

with connect_relay_controller(config, board) as controller:
    controller.set_relay("fan", RelayState.ON)
    controller.blink("green_led", on_duration_ms=250, count=2)

Default Relay Channels

• fan (CH1)
• green_led (CH2)
• buzzer (CH3)
• red_led (CH4)
• alarm (CH5)
• pir_gate (CH8)

Development

uv run ruff check .
uv run ruff format .
uv run python -m compileall -q src
uv run python -c "import modbus_relay_control"

Hardware verification remains manual (requires connected relay board):

uv run pwsh -NoProfile -File .\tests\integration\mqtt_smoketest.ps1 -Port COM4

Deployment Docs

• Deployment runbook (Jetson): docs/deployment/DEPLOYMENT.md

Technical References

• Waveshare + Modbus + client-library references: docs/REFERENCES.md

Automation

• CI matrix for Python 3.10-3.13: lint, format check, compile/import smoke
• Security audit workflow (pip-audit) on PRs, pushes, and weekly schedule
• Dependabot updates weekly for Python deps and GitHub Actions
• PR triage automation: path labels + PR size labels
• Dependabot patch/minor PRs auto-approved and auto-merged after checks pass
• Stale issue/PR lifecycle automation (scheduled)
• Copilot review comments on PR threads auto-replied and auto-resolved
• PR gets copilot-threads-resolved label when all Copilot review threads are resolved
• Dependabot auto-merge is gated on copilot-threads-resolved
• Open PR labels are re-synced every 30 minutes (plus on PR/review events)
• PRs with unresolved Copilot threads get a sticky blocker comment; it is removed when resolved

One-time repo/org toggles for full autopilot mode are documented in .github/AUTOMATION_RUNBOOK.md.