Control Wire Protocol CDDL
Control Wire Protocol CDDL
This page embeds the normative CDDL specification used by firmware control request/response parsing and encoding.
Source file:
; PacketRF Control Protocol (arrays-first, compact protocol keys)
; Normative wire schema for inner CBOR payload across control transports
; (currently CoAP and serial control line).
; =========================
; Enums (integer on wire)
; =========================
; status
; 0 = ok
; 1 = error
status = 0 / 1
; kind
; 0 = schema_catalog
; 1 = schema_target
; 2 = data
; 3 = list
kind = 0 / 1 / 2 / 3
; auth policy
; 0 = public_read
; 1 = signed
; 2 = admin_only
auth-policy = 0 / 1 / 2
; match mode
; 0 = exact
; 1 = prefix
match-mode = 0 / 1
; access mode
; 0 = read_only
; 1 = write_only
; 2 = read_write
access-mode = 0 / 1 / 2
; wire type
; 0 = bool
; 1 = int64
; 2 = uint64
; 3 = double
; 4 = string
; 5 = bytes
; 6 = ip4
wire-type = 0 / 1 / 2 / 3 / 4 / 5 / 6
; =========================
; Primitive/domain types
; =========================
; Domain field values (config/runtime values) are scalar-only.
; Arrays/maps are intentionally not allowed as domain field values.
domain-scalar = bool / int / float / tstr / bstr
path = tstr
name = tstr
; =========================
; Request
; =========================
; request keys:
; 0 = path (tstr)
; 1 = args (map of domain key -> scalar)
command-request = {
0: path,
? 1: { * tstr => domain-scalar }
}
; =========================
; Shared response envelope
; =========================
; response common keys:
; 0 = status
; 1 = kind
; 2 = path
; 3 = error_code (required, status=1)
; 4 = error_detail (optional, status=1)
;
; numbering convention:
; - 0..9: shared envelope
; - 10..19: schema_catalog payload
; - 20..29: schema_target payload
; - 30..39: data payload
; - 40..49: list payload
control-response = ok-response / error-response
ok-response = schema-catalog-response /
schema-target-response /
data-response /
list-response
error-response = {
0: 1,
2: path,
3: uint,
? 4: tstr,
? 1: kind
}
; =========================
; Schema responses
; =========================
; descriptor keys:
; 0 = path
; 1 = auth
; 2 = match
descriptor = {
0: tstr,
1: auth-policy,
2: match-mode
}
; schema-catalog payload keys:
; 10 = descriptors
; 11 = groups
schema-catalog-response = {
0: 0,
1: 0,
2: path,
10: [* descriptor],
? 11: [* tstr]
}
; field-meta keys:
; 0 = name
; 1 = type
; 2 = access
field-meta = {
0: name,
1: wire-type,
2: access-mode
}
; schema-target payload keys:
; 20 = targets
; 21 = fields
schema-target-response = {
0: 0,
1: 1,
2: path,
? 20: [* tstr],
21: [* field-meta]
}
; =========================
; Data/list responses
; =========================
; data payload key:
; 30 = values
; values map keys stay textual domain names.
data-response = {
0: 0,
1: 2,
2: path,
30: { * tstr => domain-scalar }
}
; Recommended for /system/status values map:
; - "schema_id": uint ; opaque compile-time schema identity (uint64)
; - "schema_profile": int ; opaque runtime profile selector
; - "serial_number": tstr ; RP2350 unique serial number (hex)
list-item = {
* tstr => domain-scalar
}
; list payload key:
; 40 = items
list-response = {
0: 0,
1: 3,
2: path,
40: [* list-item]
}
; =========================
; Implementation constraints (firmware profile)
; =========================
;
; The current firmware enforces these limits outside of CDDL:
; - max inner payload: 1400 bytes
; - max request args: 16
; - max request path length: 96 bytes
; - max domain key length: 64 bytes
; - hard caps for schema/list counts: 64