🛰 S4K Modbus Relay Control

A lightweight, zero-dependency Python utility for controlling Ethernet/PoE Modbus Relays (specifically tested with Waveshare modules).
Designed for stability in production environments where reliability is key.

📋 Features

Direct Socket Communication: No heavy libraries like pymodbus required.
Instance Protection: Uses fcntl file locking to prevent race conditions during concurrent executions.
Health Checks: Integrated ICMP ping check before command execution.
Configurable: All parameters (IP, Port, Channels) are stored in an external .ini file.
Detailed Logging: Full audit trail of all ON/OFF/TOGGLE actions.

💻 Requirements

Requirement	Value
OS	Linux (Ubuntu, Debian, LMDE, etc.)
Python	3.6+
Permissions	Write access to log/lock paths

⚙️ Configuration (`config.ini`)

Section	Parameter	Description	Default
`[modbus]`	`host`	IP address of the relay	`192.168.X.X`
`[modbus]`	`port`	TCP port (Waveshare: `4196`)	`4196`
`[modbus]`	`unit`	Modbus Unit ID	`1`
`[modbus]`	`coil_base`	Channel base num (`0` or `1`)	`1`
`[modbus]`	`timeout`	Socket timeout (sec) (only view)	`1`
`[modbus]`	`max_channel`	Max channel index (e.g., `7`). `7` for `coil_base=1` too.	`7`
`[paths]`	`lock_file`	Path to `.lock` file	`/tmp/modbus.lock`
`[paths]`	`log_file`	Path to `.log` file	`/tmp/modbus.log`

⚙️ Installation & Setup

Clone the repository:

git clone https://github.com/andsyrovatko/s4k-modbus-relay-controller.git
cd s4k-modbus-relay-controller

Configure the tool: Copy the example config and edit it with your device details:
```
cp config.ini.example config.ini
nano config.ini
```
Set executable permissions:
```
chmod +x modbus_controller.py
```

🚀 Usage

Use via cli or call from another soft:

# Get script help/usage info
python3 modbus_controller.py
# Output: modbus_controller.py <status|on|off|toggle> <channel>

# Get channel status
python3 modbus_controller.py status 8
# Output: Channel 8 is OFF

# Turn a specific channel ON or OFF
python3 modbus_controller.py on 8
# Output: Channel 8 is turned ON

# Toggle channel state
python3 modbus_controller.py toggle 8
# Output: Channel 8 is turned ON

⚠️ Important Note

[!IMPORTANT]
This version currently supports Linux only due to the use of fcntl for process locking. Windows support is planned for future releases.

⚠️ Disclaimer

Use at your own risk! These scripts are designed for administrative tasks and may perform destructive actions (like killing processes or deleting config files). The author is not responsible for any data loss or system instability. Always test in a sandbox environment first.

⚖️ License

This project is licensed under the MIT License - see the LICENSE file for details.

3.2 KiB Raw Permalink Blame History