MQTT Topics¶

suncast publishes shadow visualizations, health information, and errors to a set of MQTT topics under the suncast/ prefix. suncast is a pure telemetry service — there are no inbound command topics.

Topic Overview¶

Payload Schemas¶

Status (Heartbeat)¶

Topic: suncast/status

Periodic heartbeat published by the cosalette health reporter. Also used as the Last Will and Testament (LWT) — the broker publishes "offline" if suncast disconnects unexpectedly.

{
  "status": "online",
  "uptime": 3600.5,
  "version": "0.1.0",
  "devices": {
    "shadow": { "status": "online", "last_seen": 1700000000.0 }
  }
}

Shadow SVG¶

Topic: suncast/shadow/svg

Raw SVG string. Published every poll cycle. Subscribe and render directly in your dashboard (e.g. Home Assistant picture-elements card, Grafana HTML panel).

Shadow PNG¶

Topic: suncast/shadow/png

Base64-encoded PNG image. Only published when SUNCAST_PNG_ENABLED=true. Requires the png extra:

pip install suncast[png]

Shadow State¶

The shadow device publishes visualization data via the svg and png channels rather than the standard state topic. The telemetry handler returns None, so no suncast/shadow/state message is published by the framework.

Availability¶

Topic: suncast/shadow/availability

Each device publishes its availability status. The cosalette framework manages these automatically.

"online"     # device is running
"offline"    # device has stopped (or app shutting down)

Error¶

Topics: suncast/error, suncast/shadow/error

Published (not retained) when a device encounters an error. The cosalette framework deduplicates consecutive identical errors.

{
  "type": "OSError",
  "message": "Geometry file not found",
  "device": "shadow",
  "timestamp": 1700000000.0
}

Topic Naming Convention¶

suncast follows the cosalette topic convention:

{prefix}/{device}/{channel}

Global topics (status, error) omit the device segment:

suncast/status
suncast/error