|=====================================| | ArtiSLAVE API Protocol Version 1.05 | | Written by: Michel van Osenbruggen | | CopyRight 2026 ArtiLED B.V. | |=====================================| Firmware version : 1.04 Latest change : 25-03-2026 =============== | Description | =============== The ArtiLED Slave Controller HTTP REST API runs on port 80. All endpoints accept GET or POST parameters. All responses return JSON. The Slave Controller also receives LED commands via ArtiUDP (UDP port 1093). See ArtiUDP.txt for the binary LED protocol. ======================= | Protocol Definition | ======================= Protocol : HTTP Port : 80 URL : http:///api/... DATA : GET or POST with variables Authentication : token= parameter on each request |=============| | Error Codes | |=============| 1 : Login Failed (invalid username or password) 2 : Token Invalid 3 : Incomplete data (not all data supplied) 4 : Invalid data (data value incorrect) 5 : No valid config fields 6 : Command Invalid 7 : Unauthorized IP address (firewall) 8 : Already Bound / Already Adopted |====================| | Response Structure | |====================| All responses return JSON: { "success": 1, "error": 0, "error_text": "Success", "execution_time": 5, "data": {} } success : 1 = success, 0 = error error : error code (0 = none) error_text : human readable error description execution_time : milliseconds data : response data (varies per endpoint) |=================================| | Management Endpoints | |=================================| > /api/alive Parameters : none (firewall check only) Response data : {"name":"LEDS-001", "ident":"hje33knsjabdkrl"} Description : Health check — returns name and ident > /api/login Parameters : data={"username":"...","password":"..."} Response data : {"token":"..."} Description : Authenticate with username/password, returns token > /api/version Parameters : token= Response data : {"version":"1.00"} Description : Returns firmware version > /api/info Parameters : token= Response data : { "version": "1.04", "name": "LEDS-001", "hub": "0.0.0.0", "master": "0.0.0.0", "controller": "0.0.0.0", "hardware": 1, "leds": 120, "channels": 1, "max_brightness": 255, "max_brightness_mode": 0, "firewall_api": 0, "firewall_udp": 0, "uptime": 12345, "mac": "AA:BB:CC:DD:EE:FF", "serial": "ABCDEFGHIJ", "type": "LEDS-001", "free_heap": 198656, "min_free_heap": 195584, "link_speed": 100, "temperature": 48.3 } Description : Returns full device info hardware values : 1=SK6812, 2=WS2812B, 3=WS2811-BRG, 4=WS2811-GRB, 5=WS2811-RGB, 6=WS2813, 7=WS2815, 9=SK6815, 13=SK6812-GRBW max_brightness_mode : 0=Absolute (hard cap), 1=Relative (proportional scaling) > /api/config Parameters : token=, data= Request data : { "name": "Kitchen Counter", "hub": "192.168.14.2", "master": "192.168.14.3", "controller": "192.168.14.4", "num_leds": 120, "num_channels": 1, "hardware": 1, "max_brightness": 200, "max_brightness_mode": 0, "firewall_api": 1, "firewall_udp": 1 } Description : Remote configuration — only fields present in JSON are updated. Device reboots after saving. Returns error 5 if no valid config fields provided. Available from firmware v1.00+. > /api/rollback Parameters : token= Description : Reverts to the previous firmware on the inactive OTA partition and reboots. Uses ESP32 built-in dual partition rollback mechanism. Error 9 : Rollback not possible — no valid previous firmware on inactive partition. > /api/recovery Parameters : token= Description : Sets recovery flag in EEPROM and reboots. On next boot, firmware enters recovery mode: Ethernet + OTA only, no watchdog, no LED logic. Use this when OTA is blocked by a firmware issue. Upload new firmware via the recovery mode's ElegantOTA interface. Also triggers automatically after 3 consecutive failed boots. > /api/adopt Parameters : token=, data={"ident":"...", "hub":""} Description : Sets the Hub IP address (adopted by Hub) Error 8 : Rejected if already adopted (HUB already set). Orphan first. > /api/orphan Parameters : token=, data={"ident":"..."} Description : Clears the Hub IP address (orphaned by Hub) > /api/bind Parameters : token=, data={"ident":"...", "master":""} Description : Sets the Master/Controller IP address (bound) Error 8 : Rejected if already bound (MASTER already set). Release first. > /api/release Parameters : token=, data={"ident":"..."} Description : Clears the Master/Controller IP address (released) |===============================| | Light Command Endpoint | |===============================| Endpoint : /api/light Parameters : token=, data= The /api/light endpoint accepts JSON with one or more light control keys. Multiple keys can be combined in a single request (e.g., brightness + color). |=========================| | Light Control Commands | |=========================| --- STATE (on/off) --- $ Turn off (clear all LEDs): data={"state":0} --- CLEAR --- $ Clear all LEDs: data={"clear":1} --- BRIGHTNESS --- $ Set brightness: data={"brightness":128} brightness : 0-255 --- COLOR RGB --- $ Set strip to RGB color: data={"color_rgb":{"red":255, "green":128, "blue":0}} $ Set segment to RGB color: data={"segment":{"start":0, "end":30}, "color_rgb":{"red":255, "green":128, "blue":0}} red, green, blue : 0-255 start, end : LED index range --- COLOR RGBW --- $ Set strip to RGBW color: data={"color_rgbw":{"red":255, "green":128, "blue":0, "white":100}} $ Set segment to RGBW color: data={"segment":{"start":0, "end":30}, "color_rgbw":{"red":255, "green":128, "blue":0, "white":100}} red, green, blue, white : 0-255 Only effective on RGBW LED types (SK6812, SK6815, SK6812-GRBW) --- COLOR HSV --- $ Set strip to HSV color: data={"color_hsv":{"hue":128, "saturation":255, "value":200}} $ Set segment to HSV color: data={"segment":{"start":0, "end":30}, "color_hsv":{"hue":128, "saturation":255, "value":200}} hue : 0-255 (mapped to 0-360 degrees) saturation : 0-255 value : 0-255 --- WHITE (temperature) --- $ Set strip to white temperature: data={"color_w":{"temperature":128, "intensity":200}} $ Set segment to white temperature: data={"segment":{"start":0, "end":30}, "color_w":{"temperature":128, "intensity":200}} temperature : 0-255 (warm to cool) intensity : 0-255 --- PALETTE (built-in) --- $ Set strip to built-in palette: data={"palette":{ "palette_id": 1, "blend": 1, "scale": 10, "alternate": 0, "start_index": 0, "end_index": 255 }} $ Optional: add "clear":1 to clear strip before applying palette palette_id : palette number (see ArtiPALETTE.txt) blend : 0=no blend, 1=linear blend scale : 1-255 (color spread scale) alternate : 0=wrap around, 1=alternate direction start_index : 0-255 (palette start position) end_index : 0-255 (palette end position) Supports segment and part selection: - "segment":{"start":N, "end":N} — LED index range - "part":{"start":N, "end":N} — proportional range --- CUSTOM PALETTE (2-color gradient) --- $ Set strip to custom 2-color palette: data={"custom_palette":{ "start_color": {"red":255, "green":0, "blue":0}, "end_color": {"red":0, "green":0, "blue":255}, "blend": 1, "scale": 10, "alternate": 0, "start_index": 0, "end_index": 255 }} Same parameters as palette, with explicit start/end RGB colors. Supports segment and part selection. --- ADVANCED PALETTE (multi-color gradient) --- $ Set strip to multi-color palette: data={"advanced_palette":{ "color_array": [ [0, 255, 0, 0], [85, 0, 255, 0], [170, 0, 0, 255], [255, 255, 0, 0] ], "blend": 1, "scale": 10, "alternate": 0, "start_index": 0, "end_index": 255 }} color_array : array of [position, red, green, blue] entries position: 0-255 (gradient position) max 16 color entries Supports segment and part selection. |==================| | Firewall | |==================| When FIREWALL_API=1, HTTP API endpoints only accept connections from: - Registered Hub IP - Registered Master IP - Registered Controller IP The /api/adopt, /api/bind, and /api/login endpoints bypass the firewall (they need to be reachable before registration). When FIREWALL_UDP=1, UDP LED commands only accept packets from: - Registered Hub IP - Registered Master IP - Registered Controller IP |==================| | Web Pages | |==================| / : Info page (no auth) — device, network, hardware, system stats /system : System settings (basic auth) — type, serial, ident, token /config : Configuration (basic auth) — name, firewall, hub, master, controller, LEDs, channels, LED type, max brightness, mode /update : OTA firmware update (basic auth via ElegantOTA) |==================| | EEPROM Layout | |==================| Address Length Field 0 1 Initialization flag 1 8 TYPE 9 10 SERIAL_NUMBER 19 15 IDENT 34 25 TOKEN 59 2 NUM_LEDS (16-bit, LSB first) 61 1 HARDWARE_LEDS 62 15 HUB IP 77 15 MASTER IP 92 15 CONTROLLER IP 107 1 FIREWALL_API 108 1 FIREWALL_UDP 109 25 NAME 134 1 NUM_CHANNELS 135 1 MAX_BRIGHTNESS (0-255, default 255) 136 1 MAX_BRIGHTNESS_MODE (0=Absolute, 1=Relative) |==================| | Discovery | |==================| Protocol : UDP broadcast Port : 50083 Magic token : ui5Taif6 Interval : 30 seconds Message format : ui5Taif6|||| |==================| | Hardware | |==================| Platform : ESP32 (WT32-ETH01) Ethernet : LAN8720 PHY (ETH_ADDR=1, MDC=23, MDIO=18, CLK=GPIO0_IN, PWR=16) LED data pins : GPIO 2 (ch1), GPIO 4 (ch2), GPIO 12 (ch3), GPIO 14 (ch4) Max channels : 4 Supported LED types: 1 = SK6812 (RGBW, RGB order) 2 = WS2812B (RGB, GRB order) 3 = WS2811-BRG (RGB, BRG order) 4 = WS2811-GRB (RGB, GRB order) 5 = WS2811-RGB (RGB, RGB order) 6 = WS2813 (RGB, GRB order) 7 = WS2815 (RGB, GRB order, uses WS2813 driver) 9 = SK6815 (RGBW, GRB order) 13 = SK6812-GRBW (RGBW, RGB order, R/G swapped variant)