About this article

• Audience: Integrators wiring edge shadows to a central SOC or Phantom proxy
• Goal: Understand the hierarchical topic namespaces before implementing publishers or subscribers
• Type: Concept

Summary

Ghost Protocol shadows publish on devices/{device_id}/… with a parallel shadow/{device_id}/… telemetry mirror. The Phantom proxy subscribes to fleet wildcards, caches latest payloads, and exposes them over HTTP. This page describes namespace intent; field-level schemas live in the MQTT reference.

Prerequisites

• MQTT broker reachable from edge and proxy (default port 1883 on the Phantom host stack)
• Device IDs as role labels (site-role-a, site-role-b)
• Glossary for device_id and precomp

Namespace model

devices/{device_id}/
  ├── status          (retained lifecycle)
  ├── health          (periodic fleet summary)
  ├── telemetry       (~10 Hz precomp + die temp)
  ├── dets            (RF-DETR detection batches)
  ├── data_manifest   (recording index)
  ├── responses       (command acknowledgements)
  ├── events/{type}   (incidents, automation, plugin)
  └── cmd/…           (ingress commands)

shadow/{device_id}/   (telemetry mirror for legacy consumers)
casper/{device_id}/   (LED and accessory telemetry)

Direction convention: Edge → SOC for telemetry and events; SOC → Edge for commands under cmd/.

Core lifecycle topics

Topic	Direction	Purpose
devices/{id}/status	Edge → SOC	Retained online/offline with firmware version; LWT on disconnect
devices/{id}/health	Edge → SOC	CPU, RAM, DSP temperature, storage health summary
devices/{id}/telemetry	Edge → SOC	High-frequency die temp, fps, embedded detection list

Status and health establish fleet presence before alert pipelines consume dets.

AI and event streams

Topic	Direction	Purpose
devices/{id}/dets	Edge → SOC	RF-DETR precomp batches (~10 Hz)
devices/{id}/events/threat_detected	Edge → SOC	VLM-classified incidents with clip reference
devices/{id}/events/incident	Edge → SOC	Proxy-triggered video-understanding pulls
devices/{id}/events	Edge → SOC	Plugin and automation events (door, relay, custom)

Detection payloads use compact keys (c, p, b, optional track_id and spatial x/y/z). Threat events carry analysis text and a chunk filename reference — not raw video bytes.

Recording and manifest workflow

Topic	Direction	Purpose
devices/{id}/cmd/get_manifest	SOC → Edge	Request scan of local recording directory
devices/{id}/data_manifest	Edge → SOC	Available chunk catalog response
devices/{id}/commands	SOC → Edge	Upload triggers (cmd: upload, filename)

This pairs with the justified recording contract: the proxy pulls or streams chunks after manifest negotiation.

OTA and model updates

Topic	Direction	Purpose
devices/{id}/model/update	SOC → Edge	Model URL and hash for hot-swap
devices/{id}/upgrade/status	Edge → SOC	Download and flash progress
devices/{id}/upgrade/result	Edge → SOC	Success or failure with new version string

Aligns with A/B rollback policy in requirements.

Accessories and automation

Topic	Direction	Purpose
casper/{id}/led/color	SOC → Edge	RGB status LED control
casper/{id}/led/effect	SOC → Edge	Strobe and timed effects
casper/{id}/telemetry/can	Edge → SOC	M8 CAN adapter decoded frames
casper/{id}/telemetry/wifi	Edge → SOC	WLAN fallback RSSI and state
casper/{id}/telemetry/controller	Edge → SOC	M8 GPIO and relay state

Plugin commands also use devices/{id}/cmd/plugins and devices/{id}/cmd/m8 — see plugin system.

Next steps

• MQTT reference — schemas, QoS, proxy ingest at https://<phantom-proxy>:8788
• API quick reference — /fleet/mqtt/latest and HTTP surfaces
• Plugin system — plugin command topics

Operator depth

Live topic captures, TAP traces, and broker ACL configs live in private operator handoff (not published).