No mandatory cloud
The broker, panel and devices can operate entirely on the local network.
One panel, many branches, real-time control.
Each NetRelay card connects to the MQTT broker with its own account. The server shows online devices, sends commands only to the selected device, stores state changes in SQLite, and isolates each account to its own topic namespace.
Electrical safety
Work involving mains voltage must only be performed by qualified personnel. Disconnect power, use suitable protection and enclosures, and verify the electrical limits of your exact hardware model.
Per-device topics
Each card listens only to netrelay/<username>/command.
Input and relay events
State, uptime, hostname, IP, voltage and temperature are normalized by the server.
Changes, not heartbeat noise
Repeated five-second status packets are ignored unless a meaningful value changes.
How data moves through the system.
| Component | Responsibility |
|---|---|
| NetRelay firmware | Connects to the broker, publishes status/events, receives QoS 1 commands and prevents duplicate commandId execution. |
| MQTT Server | Authenticates accounts, enforces topic ACLs, processes automation and exposes the web panel and REST API. |
| SQLite | Stores MQTT/web users, history, audit records, rules, schedules, groups, API keys and settings. |
| Web/mobile clients | Read authorized state and issue commands without direct access to device credentials. |
Default ports
MQTT: 1883, MQTT TLS: 8883, web panel/API: 3000 unless changed in the environment settings.
Connect every card with a unique identity.
1
Create an MQTT user
Open System → MQTT Users, create a strong unique username/password and keep the account enabled.
2
Configure the card
Enter the broker IP or hostname, port, username and password in the NetRelay MQTT settings. Use a different account for every branch/card.
3
Verify connectivity
The device must appear under Online Devices. Open Device I/O to inspect relays, inputs, voltage, temperature and the last JSON packet.
4
Test safely
Use a safe low-voltage test load first. Toggle Relay 1, trigger an input and verify both state changes in the panel and History page.
Accounts and topic contract.
| Topic | Purpose |
|---|---|
netrelay/<username>/command | QoS 1 relay, sync, restart, queue and OTA commands sent to one device. |
netrelay/<username>/events | Device status, relay event and input event messages published by the card. |
homeassistant/.../config | Retained MQTT Discovery definitions published by the server. |
Topic enforcement should remain enabled. A normal device account cannot publish commands to, or subscribe to events from, another username. The configured Home Assistant account receives only the additional integration permissions it requires.
Reliable, targeted JSON commands.
Relay command
{
"type": "netrelay",
"command": "set",
"commandId": "unique-id",
"targetUsername": "biga_sube",
"relays": [1, 2],
"position": 1,
"delay": 0
}Relay numbers are 1–4, position is 0 or 1, and delay is measured in seconds. Restart and sync use the same envelope with command: "restart" or command: "sync". Commands use QoS 1; current firmware uses commandId to avoid applying redelivered commands twice.
State changes are normalized and stored.
Input event example
{
"type": "netrelay_input_event",
"mqttUsername": "biga_sube",
"input": 1,
"inputName": "Door Contact",
"io": 1,
"voltage": 12.42,
"deviceUptimeMs": 724500
}| Field | Meaning |
|---|---|
io | Actual digital input level, 0 or 1. |
position | Actual relay output level, 0 or 1. |
deviceUptimeMs | Milliseconds since device boot. |
serverReceivedAt | ISO timestamp added by the server. |
Operations, automation and security in one interface.
Dashboard and Device I/O
Online state, stale-device detection, uptime, inputs, relays, voltage, temperature, sync and restart.
Schedules and rules
Cron/sunrise/sunset tasks and input, temperature or voltage rules with relay, e-mail and Netgsm SMS actions.
Group control and queues
Send one command to several branches and queue commands for offline devices.
Events and audit records
Filter SQLite history by multiple MQTT users, export CSV, and track who changed settings or sent commands.
Backup and log rotation
Download/restore database settings, archive old logs and run the server as a Windows service.
Role-based panel users
Section permissions, login lockout and an invariant that always keeps at least one active administrator.
Build a group-scoped mobile control application.
The API base URL is https://server-address/api/v1. Create a device group first, then create a read or control key under System → REST API. A key can see and control only cards belonging to its assigned groups.
Authentication
Authorization: Bearer nr_YOUR_TOKEN| Endpoint | Purpose |
|---|---|
GET /health | Public server health/version check. |
GET /devices | Online devices within the key's groups. |
GET /devices/:username | Live state of one authorized device. |
GET /history | Authorized device event history. |
GET /device-groups | Groups assigned to the key. |
POST /devices/:username/relays | Relay control; requires control. |
POST /devices/:username/sync | Request current device state. |
POST /devices/:username/restart | Restart an online device. |
POST /device-groups/:id/relays | Group command with optional offline queue. |
Mobile/JavaScript relay request
await fetch(`${baseUrl}/devices/biga_sube/relays`, {
method: 'POST',
headers: {
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ relays: [1], position: 1, delay: 0 })
});Protect mobile tokens
Use Android Keystore or iOS Keychain. Never hard-code a shared token in a publicly distributed app. Use a user-authenticated backend for public app-store deployments. Requests are limited to 120 per minute; handle 401, 403, 404, 409 and 429 responses explicitly.
Discover four relays and four inputs automatically.
No Home Assistant-specific value is entered in the NetRelay card. The device only needs current firmware, its own MQTT account, and working status/event publishing.
1
Create the integration account
Under System → MQTT Users, create an enabled user named homeassistant with a strong password.
2
Publish Discovery
Open System → REST API. In the Home Assistant card, keep the recommended homeassistant Discovery prefix, enable Discovery and click Save and publish.
3
Add MQTT to Home Assistant
Go to Settings → Devices & services → Add integration → MQTT. Enter the NetRelay broker IP/hostname, port 1883 or TLS port 8883, and the homeassistant credentials.
4
Verify entities
Under the MQTT integration, each NetRelay <username> device should contain Relay 1–4 switches and Input 1–4 binary sensors.
| Problem | Check |
|---|---|
| Connection rejected | Account enabled state, password, broker address/port and blacklist logs. |
| Devices missing | Discovery enabled, matching prefix, then Save and publish again and reload MQTT. |
| Relay state stale | Device online/current firmware; send Sync from Device I/O and inspect event messages. |
| Inputs not updating | Verify netrelay_device_status and netrelay_input_event traffic. |
Automatic least-privilege ACL
The configured Home Assistant MQTT user receives only Discovery subscription, NetRelay event subscription and command publication permissions. Do not add every device password to Home Assistant.
Server source and current firmware.
MQTT Server source
Source, release history and installation documents are available on GitHub.
Current device software
Download the correct firmware for your hardware/partition model from the official software page.
Protect field control systems.
Unique credentials
Use a separate strong MQTT account for each device and rotate exposed secrets.
IoT VLAN and VPN
Isolate devices and never expose port 1883 directly to the internet.
Verify certificates
Use MQTT TLS 1.2+, CA validation and optional client certificates; use HTTPS for the panel/API.
Keep device namespaces isolated
Leave topic enforcement enabled so one branch cannot see or control another.
Protect backups
Never commit .env, SQLite databases, private keys or backup archives to Git.
Least privilege
Assign only required groups and scopes, revoke unused keys and never log full tokens.
Quick diagnostic checklist.
| Symptom | Check |
|---|---|
| Device not online | Broker address/port, gateway, cable/PoE, MQTT mode and credentials. |
Not authorized | Account enabled state, password and whether the device uses only its own topic namespace. |
| Command not received | Current firmware, command topic subscription, QoS 1 and server logs. |
| Wrong device receives command | Unique usernames per branch and the selected target in the panel/API. |
| Input event missing | Input wiring, input name configuration, event messages and the 30 ms stability filter. |
| API returns 404 | The device/group may be outside the key's assigned group scope; this is intentional isolation. |