|======================================| | ArtiBlasterAPI Protocol Version 0.04 | | Written by: Michel van Osenbruggen | | CopyRight 2026 ArtiLED B.V. | |======================================| Latest change : 05-10-2026 Status : Review draft Controlled by : Control only (the Hub goes through Control) |=====================| | Protocol Definition | |=====================| Protocol : HTTP Port : 80 Method : POST (/api); OTA see OTA URL : http:///api/... Authentication : token= Data : data= IR request fields : ident, boot_id, session_id, command fields |=============| | Error Codes | |=============| 1 : Login failed 2 : Invalid token 3 : Incomplete data (no token, no data, no field) 4 : Invalid data (any invalid or unknown field; whole request rejected, nothing saved) 6 : Invalid command (unknown /api path or command) 7 : Unauthorized IP (firewall); HTTP status 403 9 : Rollback not possible Additional codes : TBD |====================| | Response Structure | |====================| success : 1 = success, 0 = error error : Numeric error code; 0 = none error_text : Error description execution_time : Request processing time, milliseconds data : Command-specific response fields Response : {"success":1,"error":0,"error_text":"Success", "execution_time":5,"data":{}} |=====================| | Management Commands | |=====================| > /api/alive : No token/data -> {"name":name,"ident":ident} > /api/login : data={"username":"...","password":"..."} -> {"token":token} > /api/version : token -> {"version":version,"protocol_version":version} > /api/info : token -> $ info > /api/config : token, data=$ config -> Saves the supplied fields, no reboot -> Returns the supplied fields as saved > /api/reset : token -> Returns {} -> Reboots > /api/rollback : token -> Returns {} -> Reboots into the previous firmware > /api/recovery : token -> Returns {} -> Reboots into recovery mode $ info : {"name":name,"ident":ident,"type":type,"serial":serial, "version":version,"protocol_version":version,"ip":ip, "mac":mac,"link_speed":mbps,"controller":ip, "firewall_api":0/1,"firewall_udp":0/1,"uptime":s, "boot_id":boot_id,"free_heap":bytes, "min_free_heap":bytes,"temperature":celsius, "capabilities":$ capabilities} $ config : {"name":name,"controller":ip,"firewall_api":0/1, "firewall_udp":0/1}; one or more fields Firewall : firewall_api=1 -> every /api path only from controller firewall_udp=1 -> UDP commands only from controller Recovery mode : OTA only; no /api $ capabilities : {"ir":{"outputs":n,"inputs":n}} Other keys: reserved |=====| | OTA | |=====| Authentication : HTTP basic auth, OTA login > /update : GET -> OTA page > /ota/start : GET ?mode=fr&hash= -> HTTP 200 -> Starts a firmware upload > /ota/upload : POST multipart: MD5=, firmware= -> HTTP 200, body OK -> Reboots |=============| | IR Commands | |=============| > /api/ir : token, data={ident,boot_id,session_id,command,...} send : request_id, sequence, output, format, code, repeats hold_start : request_id, sequence, hold_id, output, format, code hold_renew : request_id, sequence, hold_id hold_stop : request_id, sequence, hold_id Response data : request_id, state > /api/ir/session : token, data={command,...} open : event_port -> session_id, boot_id renew : session_id -> session_id close : session_id -> session_id Event destination : Authenticated caller IP + event_port > /api/ir/result : token, data={ident,boot_id,session_id,request_id} Response data : request_id, state > /api/ir/learn : token, data={ident,boot_id,session_id,command,...} start : learn_id, input, timeout_ms, carrier_hz status : learn_id -> state, capture_id cancel : learn_id -> state > /api/ir/capture : token, data={ident,boot_id,session_id,capture_id} Response data : capture_id, input, code, carrier_hz, carrier_source, overflow, capture metadata |===========| | Variables | |===========| name : 1-25 characters; no "|", no control characters controller : IPv4 address; 0.0.0.0 = none boot_id : 8 lowercase hex characters, random per boot uptime : Seconds since boot request_id : Unique operation ID; identical retry = no new transmission sequence : Increasing integer per session ident : Target device ident session_id : Current control session ID output : Transmitter number, 1-based input : Receiver number, 1-based format : pronto code : Pronto Hex, type 0000 repeats : Additional repeat sections, integer >= 0 Intro once + repeats repeat sections No intro: repeat section once + repeats No repeat section: repeats must be 0 hold_id : Unique held-button ID learn_id : Unique learning ID capture_id : Retained capture ID carrier_hz : Carrier frequency in Hz carrier_source : measured | supplied | assumed timeout_ms : Learning timeout, milliseconds state : accepted | transmitting | sent | stopped | expired | failed sent = waveform completed |===================| | Timing and Limits | |===================| Session expiry : 60 s; renew every 20 s Hold expiry : 750 ms; renew every 250 ms; maximum hold 30 s Hold repeat section : Required Hold stop boundary : End of current waveform; cycle limit TBD Learning timeout : Default 15000 ms; maximum 60000 ms Result retention : 128 operations / 60 s; active operations retained Capture retention : 8 captures / 60 s Active transmissions : 1; no hidden queue UDP initial reply wait : 250 ms; then HTTP result query, no automatic resend Event retransmission : 100 ms and 300 ms after first notification Receive during TX : Suppressed; post-TX recovery interval TBD Carrier/body limits : Advertised by /api/info; values TBD |===========| | Discovery | |===========| Protocol : UDP broadcast Port : 50085 Magic : mF7PXMTX Interval : 30 seconds Data : mF7PXMTX|ident|type|ip|name