|=====================================|
| ArtiBridgeUDP 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               : UDP unicast
Command port           : TBD
Control event port     : TBD
Encoding               : UTF-8 JSON; one object per datagram
Protocol marker        : ArtiBridgeUDP
Wire version           : 1
Maximum datagram       : 1200 bytes, including envelope
Oversize code          : HTTP; no fragmentation
Authentication         : token in requests
Response/event auth    : Session MAC; encoding/key derivation TBD

|================|
| Request Fields |
|================|

protocol               : Protocol marker
version                : 1
kind                   : request
ident                  : Target device ident
boot_id                : Current device boot ID
session_id             : Current control session ID
token                  : Device token
data                   : {command,request_id,sequence,...}

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

1                      : Login failed
2                      : Invalid token
3                      : Incomplete data
4                      : Invalid data
6                      : Invalid command
7                      : Unauthorized IP
Additional codes       : TBD

|=================|
| Response Fields |
|=================|

kind                   : response
Identity fields        : protocol, version, ident, boot_id, session_id
Correlation            : request_id
Result fields          : success, error, error_text, execution_time, data
Destination            : Request source IP/port

|====================|
| 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":{}}

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

|=============|
| IR Commands |
|=============|

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

|==============|
| Event Fields |
|==============|

kind                   : event
Identity fields        : protocol, version, ident, boot_id, session_id
event_id               : Increasing integer per boot
event                  : Event name
uptime                 : Device uptime
data                   : Event-specific fields
auth                   : Session MAC; encoding TBD
Destination            : Registered Control event listener
ACK                    : event_id; exact envelope TBD

ir.received            : input, capture_id
ir.learned             : learn_id, capture_id
ir.learn_timeout       : learn_id
ir.sent                : request_id
ir.stopped             : request_id, hold_id
ir.error               : request_id or learn_id, error details

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