MQTT Topics¶

caldates2mqtt publishes calendar event data, health information, and errors to a set of MQTT topics under the caldates2mqtt/ prefix. Each configured calendar gets its own device topics.

Topic Overview¶

{calendar} is the key from the calendar configuration (e.g. garbage, birthday).

Payload Schemas¶

Calendar State¶

Topic: caldates2mqtt/{calendar}/state

Published after each successful CalDAV poll. Contains a list of upcoming all-day events sorted by date.

{
  "events": [
    {"title": "Gelber Sack", "date": "2026-04-01"},
    {"title": "Restmuell", "date": "2026-04-08"},
    {"title": "Biomuell", "date": "2026-04-10"}
  ]
}

The number of events is limited by the per-calendar entries setting (default: 5, maximum: 50), and only events within the days lookahead window are included (default: 14 days, maximum: 365). Titles longer than 100 characters are cut to 100 characters.

Re-Read Command¶

Topic: caldates2mqtt/{calendar}/set

Trigger an immediate re-read of a specific calendar. Accepts an empty payload or a JSON object with optional parameter overrides.

# Re-read with defaults
mosquitto_pub -h localhost -t "caldates2mqtt/garbage/set" -m ""

# Re-read with overrides
mosquitto_pub -h localhost -t "caldates2mqtt/garbage/set" -m '{"entries":10,"days":30}'

Overrides apply only to this single re-read; the next scheduled poll uses the configured defaults.

Availability¶

Topic: caldates2mqtt/{calendar}/availability

Managed automatically by the cosalette framework. Published when the device comes online or goes offline.

"online"     # device is running and reachable
"offline"    # device has stopped or is unreachable

Status (Heartbeat)¶

Topic: caldates2mqtt/status

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

{
  "status": "online",
  "uptime": 3600.0,
  "version": "0.1.0",
  "devices": {
    "garbage": { "status": "online" },
    "birthday": { "status": "online" }
  }
}

Error¶

Topic: caldates2mqtt/error

Published (not retained) when an error occurs. The cosalette framework deduplicates consecutive identical errors. CalDAV-specific errors (authentication failures, connection timeouts) are the most common.

{
  "type": "CalDavConnectionError",
  "message": "Failed to connect to cloud.example.com",
  "device": "garbage",
  "timestamp": 1700000000.0
}

Framework Topics¶

Alongside the caldates2mqtt-specific topics above, cosalette itself publishes two framework-owned topics. Both are always on — no setting disables them — retained, QoS 1, and republished byte-identically on every broker connect.

Registry (caldates2mqtt/_meta/registry)¶

The canonical AsyncAPI document describing every channel caldates2mqtt publishes and subscribes to. Inbound command channels are stripped from the published copy so the command surface is not exposed to anyone who can subscribe on a shared broker.

State Model Drift (caldates2mqtt/_meta/state_model_drift)¶

A machine-readable snapshot of state_model declaration drift (ADR-069): a handler whose state_model= argument disagrees with its return type annotation. The topic is published even when there is no drift — a clean app publishes drift_count: 0 rather than omitting the topic, so "no drift" is distinguishable from "never ran a version that publishes this topic".

{
  "schema_version": 1,
  "drift_count": 0,
  "entries": []
}

mosquitto_sub -t '+/_meta/state_model_drift'

ACL guidance¶

Both topics disclose handler names, channel addresses, and payload schemas. If you run a production broker ACL file, protect _meta/# the same way you protect _meta/registry. Every mosquitto.conf shipped in this repo is dev-only (allow_anonymous true, no ACL file), so there is nothing to change in-repo — this note only applies if you deploy your own broker ACLs.

Topic Naming Convention¶

caldates2mqtt follows the cosalette topic convention:

{prefix}/{device}/{channel}

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

caldates2mqtt/status
caldates2mqtt/error

The topic prefix is configurable via CALDATES2MQTT_MQTT__TOPIC_PREFIX. See Configuration for details.