🔌 Waveshare Modbus POE ETH Relay WebUI & REST API Controller

A lightweight Node.js Express Server & WebUI designed to control the Waveshare Modbus POE ETH Relay (8-Channel) via Modbus TCP. Features a clean web control interface, persistent JSON configurations, and standard REST API endpoints for easy IoT and home automation integration.

---

🌟 Key Features

• 8-Channel Relay Control: Manage all 8 relay channels independently.
• Dual Operation Modes:
  • Hold Mode: Toggles relay state and retains it until the next command.
  • Pulse Mode: Momentary switching with customizable duration (50ms – 10000ms) and switching state (ON→OFF→ON or OFF→ON→OFF).
• RESTful API: Integrate seamlessly with Home Assistant, Node-RED, or custom software.
• Web UI Included: Embedded responsive Web Interface (served from /public) for easy browser control.
• Safe Write Verification: Automatically reads back coil states after writing to verify execution.
• Persistent Settings: Stores configuration in relayConfig.json across server restarts.

---

🏗 System Architecture

[ Web Browser / API Client ] 
             │
             ▼ (HTTP / REST API)
[ Node.js + Express Server ] ◄──► [ Config File: relayConfig.json ]
             │
             ▼ (Modbus TCP / Port 502)
[ Waveshare POE ETH Relay ]

---

🚀 Quick Start Guide

Prerequisites

• Node.js (v14 or higher)
• Waveshare Modbus POE ETH Relay Module connected to the same local network.

Installation

1. Clone the repository:

   git clone https://github.com/Llein-Dev/Waveshare-Modbus-POE-ETH-Relay-WebUI-API-Controller.git
   cd Waveshare-Modbus-POE-ETH-Relay-WebUI-API-Controller

2. Install dependencies:

   npm install

3. Configure Connection: Ensure the default Modbus TCP parameters in your configuration match your physical device:

   • Default IP: 192.168.1.200
   • Default Port: 502
   • Unit ID: 1

4. Start the server:

   npm start

5. Access the WebUI: Open your browser and navigate to http://localhost:3000 (or your configured port).

---

📡 REST API Reference

1. Get System Status & Config

Retrieves current coil states and channel configurations.

• Endpoint: GET /api/status
• Response Example:

  {
    "coils": [true, false, false, false, false, false, false, false],
    "config": {
      "0": { "mode": "hold" },
      "1": { "mode": "pulse", "ms": 1000, "type": "on" }
    }
  }

---

2. Trigger Relay Action

Executes an action on a target relay based on its configured mode.

• Endpoint: POST /api/relay/:id/action
• Path Parameters:
  • id (number): Relay channel ID (0 to 7)

---

3. Update Relay Configuration

Updates the operation mode and parameters for a specific relay channel.

• Endpoint: POST /api/config/:id
• Path Parameters:
  • id (number): Relay channel ID (0 to 7)
• Request Body Example (Hold Mode):

  {
    "mode": "hold"
  }

• Request Body Example (Pulse Mode):

  {
    "mode": "pulse",
    "ms": 1000,
    "type": "on"
  }

---

⚙️ Parameter Constraints

Parameter	Type	Allowed Values	Description
Relay ID	Number	0 – 7	Target relay channel index.
Mode	String	hold | pulse	Relay execution logic mode.
Pulse ms	Number	50 – 10000	Pulse duration in milliseconds.
Pulse type	String	on | off	on: OFF→ON→OFF | off: ON→OFF→ON

---

📂 Project Structure

├── public/              # Static Frontend WebUI
├── relayConfig.json     # Saved configurations
├── server.js            # Express server & Modbus logic
├── package.json         # Dependencies and scripts
└── README.md            # Documentation

---

🛠 Tech Stack

• Language: JavaScript (Node.js)
• Frontend: HTML5, CSS3
• Backend: Express.js
• Protocol: ModbusRTU / Modbus TCP

---

📄 License

Distributed under the MIT License. See LICENSE for more information.