mqtt.yaml

The machine-readable contract. Source of truth: spec/mqtt.yaml.

spec_version: "0.1.0"
title: meshtrap hub ↔ central service MQTT contract
status: skeleton
companion_prose_doc: ../docs/server/README.md

# Topic structure and message schemas for traffic between a hub and a
# central service. Skeleton only — concrete schemas land alongside the
# central-service implementation phase.

conventions:
  encoding: JSON                # for v1; consider CBOR later if size matters
  topic_separator: "/"
  topic_components:
    - meshtrap                  # constant root
    - "{org_id}"                # organisation that owns the network
    - "{network_id}"            # the network
    - "{region_id}"             # the region within the network (one hub)
    - "{direction}"             # 'up' (hub → server) or 'dn' (server → hub)
    - "{topic}"                 # leaf topic, see topics

  qos_defaults:
    telemetry: 0                # fire-and-forget; high volume, loss-tolerant
    alerts:    1                # at-least-once; matters but idempotent
    commands:  2                # exactly-once

topics:
  # Hub → central service
  up:
    status:           {qos: telemetry, description: "per-node STATUS rollups"}
    trigger:          {qos: alerts,    description: "trigger events, immediate"}
    health:           {qos: telemetry, description: "router/hub health, battery, RSSI matrices"}
    announce:         {qos: alerts,    description: "JOINs and ANNOUNCE updates"}
    audit:            {qos: alerts,    description: "command application logs"}

  # Central service → hub
  dn:
    command:          {qos: commands,  description: "queued COMMAND to deliver to a node"}
    key_rollover:     {qos: commands,  description: "K_group rollover material"}
    policy:           {qos: commands,  description: "RBAC / config changes for this hub"}
    sync:             {qos: telemetry, description: "metadata refresh requests"}

  # Bidirectional
  control:
    ping:             {qos: telemetry, description: "liveness check"}

authentication:
  scheme: per_hub_credentials   # never embed in shipped firmware
  rotation_supported: true
  transport: TLS                # mandatory for non-loopback brokers

schemas:
  # Concrete JSON schemas land here. Each topic gets a schema entry with
  # examples and validation rules. For v1 the rough shapes are:

  status:
    status: pending
    rough_shape:
      node_id: "AAAABBBB"
      network_id: "..."
      ts: "ISO-8601"
      flags: 0
      batt_mv: 3250
      uptime_h: 1234
      trigger_age_s: 0
      seq: 12345

  trigger:
    status: pending
    rough_shape:
      node_id: "AAAABBBB"
      network_id: "..."
      ts: "ISO-8601"
      flags: 0x02
      seq: 12346

  command:
    status: pending
    rough_shape:
      target_node_id: "AAAABBBB"
      cmd_type: 0x01
      cmd_seq: 1234
      cmd_payload: "base64..."
      admin_mic: "base64..."