|=====================================| | ArtiRELAY Protocol Version 1.00 | | Written by: Michel van Osenbruggen | | CopyRight 2026 ArtiLED B.V. | |=====================================| Firmware version : 1.00 Latest change : 20-03-2026 =============== | Description | =============== The ArtiLED Relay Controller is an ESP32-based device with up to 8 relay outputs. It is controlled via a TCP text protocol on port 1094. Relay controllers are discovered via UDP broadcast on port 50084 (magic: aqu9Seek). See ArtiRelayAPI.txt for the HTTP REST API on port 80. Hardware : ESP32 with LAN8720 Ethernet Type : RELC-001 Max relay outputs : 8 (GPIO 2, 4, 12, 14, 15, 32, 33, 17) Default relay delay : 1 second (configurable) ======================= | Protocol Definition | ======================= Protocol : TCP raw text Port : 1094 Commands : One command per line (case insensitive) Line ending : \n or \r --------------------- | ArtiRELAY start | --------------------- > Telnet 'IP Address' 1094 > TOKEN -> Authenticate (token is case sensitive) Response: 1 = authenticated, 0 = failed (disconnects) ------------------- | ArtiRELAY end | ------------------- > QUIT -> Disconnects > Empty line -> Disconnects |============================| | Protocol Answer Formatting | |============================| 0 = Error : Error or invalid command 1 = Success : Command executed successfully |===================| | Relay Commands | |===================| --- SET (persistent on/off) --- SET OUTPUT<1-8> HIGH -> 1 (set relay on) SET OUTPUT<1-8> LOW -> 1 (set relay off) SET ALL HIGH -> 1 (all relays on) SET ALL LOW -> 1 (all relays off) --- TOGGLE (flip current state) --- TOGGLE OUTPUT<1-8> -> 1 (toggle relay: HIGH->LOW or LOW->HIGH) TOGGLE ALL -> 1 (toggle all relays to opposite state) --- PULSE (momentary) --- PULSE OUTPUT<1-8> HIGH -> 1 (pulse relay high then low) PULSE OUTPUT<1-8> LOW -> 1 (pulse relay low then high) PULSE OUTPUT<1-8> HIGH -> 1 (pulse with custom duration) PULSE OUTPUT<1-8> LOW -> 1 (pulse with custom duration) Pulse sets the relay to the given state, waits duration seconds (or RELAY_DELAY if no duration specified), then sets to the opposite state. --- SEQUENCE (sequential switching) --- SEQUENCE UP HIGH/LOW -> 1 (relays 1->N, with delay between each) SEQUENCE UP HIGH/LOW -> 1 (with custom delay between each) SEQUENCE DOWN HIGH/LOW -> 1 (relays N->1, with delay between each) SEQUENCE DOWN HIGH/LOW -> 1 (with custom delay between each) Delay between each relay defaults to RELAY_DELAY seconds. Optional seconds parameter overrides for this command only. --- TIMED (non-blocking auto-off timer) --- TIMED 1 HIGH 300 -> 1 (relay 1 ON, auto OFF after 300 seconds) TIMED 3 LOW 60 -> 1 (relay 3 OFF, auto ON after 60 seconds) Format: TIMED Duration: 1-86400 seconds (max 24 hours) Non-blocking — device stays responsive. Timer checked in main loop. A new timed command on the same relay replaces the previous timer. --- CUSTOM SEQUENCE (user-defined order and delays) --- CUSTOM R:S:D,R:S:D,... -> 1 (custom sequence) R = relay number (1-8), S = state (0/1), D = delay in seconds after step Last step delay is ignored. Example: CUSTOM 3:1:2,1:1:0,5:1:5,2:0:0 (relay 3 ON, wait 2s, relay 1 ON, no wait, relay 5 ON, wait 5s, relay 2 OFF) |========================| | Configuration Commands | |========================| SET DELAY TIME <1-99> -> 1 (set relay delay in seconds, saved to EEPROM) SET RELAYS <1-8> -> 1 (set number of active relays, saved to EEPROM) SET RESTORE <0|1> -> 1 (0=all OFF on boot, 1=restore last state, saved to EEPROM) SET INTERLOCK -> 1 (pair two relays as mutually exclusive, saved to EEPROM) CLEAR INTERLOCK -> 1 (remove interlock pair containing relay N) |=================| | Query Commands | |=================| GET VERSION -> "1.00" GET RELAYS -> "8" GET DELAY TIME -> "1" GET STATUS -> "0,1,0,0,0,0,0,0" (comma-separated state per relay, 0=LOW 1=HIGH) GET RESTORE -> "0" or "1" (0=all OFF on boot, 1=restore last state) GET INTERLOCK -> "1:2,3:4" (active pairs, or "none") HELP -> prints all available commands |===================| | Control Commands | |===================| RESET -> 1 (reboots ESP32) QUIT -> disconnects |==================| | Firewall | |==================| When FIREWALL_TCP=1, only connections from registered Hub, Master, or Controller IP addresses are accepted. Others are disconnected. |==================| | EEPROM Layout | |==================| Address Length Field 0 1 Initialization flag (0xA5) 1 8 TYPE 9 10 SERIAL_NUMBER 19 15 IDENT 34 25 TOKEN 59 1 MAX_RELAYS 60 1 NUM_RELAYS 61 1 RELAY_DELAY 62 15 HUB IP 77 15 MASTER IP 92 15 CONTROLLER IP 107 1 FIREWALL_API 108 1 FIREWALL_TCP 109 25 NAME 134 1 RELAY_RESTORE (0=all OFF on boot, 1=restore last state) 135 1 RELAY_STATE (8 bits, one per relay, used when RELAY_RESTORE=1) 136 8 INTERLOCK pairs (4 pairs x 2 bytes: relayA, relayB; 0 = unused) |==================| | GPIO Pin Mapping | |==================| Relay 1 : GPIO 2 Relay 2 : GPIO 4 Relay 3 : GPIO 12 Relay 4 : GPIO 14 Relay 5 : GPIO 15 Relay 6 : GPIO 32 Relay 7 : GPIO 33 Relay 8 : GPIO 17 Ethernet : LAN8720 (ETH_ADDR=1, MDC=23, MDIO=18, CLK=GPIO0_IN, PWR=16)