Message Type Reference

§3 — Envelope

Every RCAN message uses the same JSON envelope regardless of type:

{
  "id":              "uuid-v4",          // msg_id — unique per message
  "type":            3,                  // MessageType integer (canonical v1.5)
  "priority":        1,                  // 0=LOW 1=NORMAL 2=HIGH 3=SAFETY
  "source":          "rcan://...",       // Sender RURI
  "target":          "rcan://...",       // Recipient RURI (wildcards allowed)
  "payload":         { ... },           // Type-specific data
  "timestamp":       1741000000.0,       // Unix epoch (seconds, required)
  "ttl":             0,                  // Seconds until expiry (0 = no expiry)
  "reply_to":        null,               // ID of message being replied to
  "scope":           ["control"],        // Required RBAC scopes
  "rcan_version":    "1.6",             // MUST be present; validated first
  "qos":             1,                  // 0=fire-and-forget 1=at-least-once 2=exactly-once
  "sender_type":     "human",           // "human"|"robot"|"cloud_function"|"system"
  "key_id":          "kid-abc123"       // Optional: signing key identifier (GAP-09)
}

§3.5 — Protocol Version Compatibility v1.5

RCAN version strings follow semantic versioning (MAJOR.MINOR). The rcan_version field MUST be the first field validated on any incoming message, before any other processing.

Compatibility Rules

Field Defaults for Missing v1.5 Fields

When a v1.5 receiver processes a v1.4 message missing new fields:

• delegation_chain missing → treat as no delegation (flat command)
• qos missing → default to 0 (fire-and-forget)
• sender_type missing → default to "human"
• key_id missing → validate against current (only) key in trust set

Version Negotiation (DISCOVER / STATUS)

DISCOVER and STATUS messages MUST include rcan_version in their payload. Peers record each other's protocol version on first contact and apply the lower version's rules for the session.

// DISCOVER payload (v1.5)
{
  "rcan_version": "1.5",
  "capabilities": ["control", "safety", "training"],
  "p66_conformance_pct": 87.0
}

§4 — Canonical MessageType Table (v1.5+)

This table is authoritative for v1.5 and v1.6. All SDKs MUST use these integer values. Integer values are listed for interop reference only — implementations MUST use named enum constants in code.

Priority Levels

§9.2 — CONFIG_UPDATE Wire Protocol v1.5

Gap: GAP-07 — MessageType CONFIG (5) existed with no payload schema. Any token holder could send arbitrary config payloads.

Required Payload Schema

All CONFIG (type 5) messages MUST include these fields:

{
  "config_hash":       "sha256:abc123...",  // SHA-256 of payload_b64 decoded
  "config_version":    "1.2.0",             // Semver of config being applied
  "diff_only":         false,               // true = payload is a diff patch only
  "payload_b64":       "eyJ...",            // Base64-encoded config JSON
  "requires_restart":  false,               // Robot must restart to apply
  "safety_overrides":  false               // true = modifies safety envelope params
}

Authorization Rules

Validation Sequence

1. Validate rcan_version (before any other field)
2. Verify JWT role meets minimum for the config change type
3. Decode payload_b64
4. Compute SHA-256 of decoded bytes; compare to config_hash
5. If hash mismatch → reject with CONFIG_HASH_MISMATCH error; write audit event
6. Check for forbidden fields (confidence gates); reject if found
7. Store current config as rollback snapshot (retain for rollback_grace_s, default 300s)
8. Apply config; write audit event with config_hash and config_version

CONFIG_ROLLBACK

Send a CONFIG message with payload_b64: "ROLLBACK" and no config_hash to restore the previous snapshot. Requires same JWT role as the update being rolled back. Rollback is unavailable after rollback_grace_s has elapsed.

§15 — Fleet Broadcast / Group Commands v1.5 SHOULD

Gap: GAP-13 — No RCAN message type for fleet broadcast; sequential HTTP calls take O(n) time for fleet ESTOP.

FLEET_COMMAND Payload

{
  "group_id":       "floor-3-bots",          // Fleet group identifier
  "rrn_list":       ["RRN-001", "RRN-002"],  // Explicit member list (optional override)
  "command":        "ESTOP",                  // Command name
  "params":         {},                       // Command parameters
  "require_ack_all": true,                    // Wait for ACK from all members
  "fleet_token":    "eyJ..."                  // JWT with fleet claim listing target RRNs
}

Addressing

• Local network: UDP multicast on 239.255.66.0/24 port 6600
• Fallback: TCP unicast to each robot in rrn_list
• Cloud: POST to /api/v1/fleets/{fleet_id}/command which fans out

Fleet ESTOP SLA

Fleet ESTOP MUST reach all members of a ≤100 robot fleet within 500ms on a local network. Implementations that cannot meet this SLA MUST fall back to individual unicast ESTOP messages in parallel.

Fleet JWT Claims

{
  "sub": "human-uuid",
  "aud": "rcan://fleet/floor-3-bots",
  "fleet": ["RRN-000001", "RRN-000002"],  // Robots this JWT authorizes
  "scope": ["control"],
  "exp": 1741003600
}

§8.8 — Observer Mode v1.5 SHOULD

Gap: GAP-15 — No read-only streaming; observers had to poll individual status endpoints.

Observer JWT Scope

The observer scope is read-only and MUST NOT be combined with any control scope (control, safety, training) in the same JWT. Servers MUST reject any write operation from an observer-scoped token, regardless of payload.

SUBSCRIBE / UNSUBSCRIBE

// SUBSCRIBE payload
{
  "stream": "status",          // "status" | "telemetry" | "audit"
  "filter": {"rrn": "RRN-001"} // Optional filter
}

// Server responds with COMMAND_ACK containing subscription ID
// Then delivers matching events as server-sent events or WebSocket frames

Streaming Endpoints

• GET /api/stream/status — robot status updates (SSE)
• GET /api/stream/telemetry — sensor data stream (SSE / WebSocket)
• GET /api/stream/audit — audit events (SSE, requires audit scope)

Observer connections are terminated when the JWT expires. The server MUST close the SSE connection and return HTTP 401.

§16 — Structured Fault Reporting v1.5 SHOULD

Gap: GAP-20 — Only a generic ERROR type existed; no fault taxonomy or safety manifest integration.

FAULT_REPORT Payload

{
  "fault_code":      "SENSOR_PROXIMITY_FAILURE",  // See taxonomy below
  "severity":        "critical",                   // "info"|"warning"|"error"|"critical"
  "subsystem":       "sensor",                     // subsystem prefix
  "description":     "Left IR sensor not responding",
  "affects_safety":  true,                         // Degrades P66 invariant?
  "safe_to_continue": false                        // Robot should halt?
}

Standard Fault Code Taxonomy

Safety Manifest Integration

Faults with affects_safety: true MUST update the Protocol 66 manifest with an active_faults list. The manifest's safe_to_continue aggregate is false if any active fault has safe_to_continue: false. Operators receive a push notification for severity: "critical" faults.

Migration from v1.4

Old spec integers that changed:

• DISCOVER: was 1 → now 9
• STATUS: was 2 → now 3
• COMMAND: was 3 → now 1
• TRANSPARENCY: was 18 → now 11
• HANDOFF: was 19 (reserved) → removed (deferred to v1.6)

rcan-py's internal enum (COMMAND=1, STATUS=3) was already closer to the v1.5 canonical table; only minor renaming is needed there (AUTH→SENSOR_DATA, AUTHORIZE→AUDIT). See docs/v1.5-tracking.md for SDK migration checklist.

Python Usage

from rcan.message import MessageType, RCANMessage, SPEC_VERSION

# Create a COMMAND message (type 1)
msg = RCANMessage.command(
    source="rcan://rcan.dev/acme/arm/v1/unit-001",
    target="rcan://rcan.dev/acme/arm/v1/unit-001",
    payload={"cmd": "move_forward", "speed": 0.5},
)

# SPEC_VERSION is the single source of truth — do not hardcode version strings
print(SPEC_VERSION)  # "1.10"

See Also

• Safety Conformance — ESTOP, Protocol 66, time sync, audit export
• QoS & Delivery Guarantees — retry semantics, ESTOP exactly-once
• Consent Wire Protocol — CONSENT_REQUEST / GRANT / DENY flows
• Replay Attack Prevention — msg_id seen-set, replay window
• Robot Identity Revocation — ROBOT_REVOCATION broadcast
• Command Delegation Chain — R2R command provenance
• Key Rotation — JWKS, key_id, grace period
• Offline Operation — cached keys, restricted mode
• Cloud Relay Identity — sender_type, cloud_provider
• Training Data Consent — EU AI Act Article 10
• Error Codes — full error code reference