|=====================================|
| ArtiBridgeAPI Protocol Version 0.03 |
| Written by: Michel van Osenbruggen  |
| CopyRight 2026 ArtiLED B.V.         |
|=====================================|

Latest change          : 26-09-2026
Status                 : Review draft

|=====================|
| Protocol Definition |
|=====================|

Protocol               : HTTP
Port                   : 80
Method                 : POST
URL                    : http://<device_ip>/api/...
Authentication         : token=<token>
Data                   : data=<JSON>
IR request fields      : ident, boot_id, session_id, command fields

|=============|
| Error Codes |
|=============|

1                      : Login failed
2                      : Invalid token
3                      : Incomplete data
4                      : Invalid data
6                      : Invalid command
7                      : Unauthorized IP
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, ident
> /api/login           : data={"username":"...","password":"..."} -> token
> /api/version         : token -> version, protocol_version
> /api/info            : token -> identity, network, uptime, boot_id, capabilities
> /api/config          : token, data={fields} -> updated fields

Configuration fields   : name, controller, firewall_api, firewall_udp
Update                 : Only supplied fields

|=============|
| 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 |
|===========|

request_id             : Unique operation ID; identical retry = no new transmission
sequence               : Increasing integer per session
ident                  : Target device ident
boot_id                : Current device boot ID
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                   : 50086
Magic                  : 67543Orw
Interval               : 30 seconds
Data                   : 67543Orw|ident|type|ip|name