MQTT Topics¶

velux2mqtt publishes cover position state, calibration progress, health information, and errors to a set of MQTT topics under the velux2mqtt/ prefix. Each cover is a separate device with its own command and state topics.

Topic Overview¶

Each cover (e.g. blind, window) gets its own set of topics. The table below uses blind as an example.

Payload Schemas¶

Cover Position¶

Topic: velux2mqtt/{cover}/state

Published after every movement completes and on startup (after homing, if enabled).

{
  "position": 75
}

Position is estimated from travel time --- there is no physical feedback sensor. See Architecture for how the position tracker works.

Cover Commands¶

Topic: velux2mqtt/{cover}/set

Accepts multiple command formats for compatibility with Home Assistant and manual MQTT clients.

open       # move to 100% (up)
up         # move to 100% (up)
close      # move to 0% (down)
down       # move to 0% (down)
stop       # stop immediately

42         # move to 42%
0          # fully close
100        # fully open

{"position": 42}

{"command": "open"}

Calibration State¶

Topic: velux2mqtt/{cover}/calibrate/state

Published after every calibration action. Tracks the state machine progress so external UIs can display calibration status.

{
  "state": "TIMING",
  "run": 2,
  "total_runs": 3,
  "direction": "OPEN"
}

{
  "state": "IDLE"
}

Calibration Result¶

Topic: velux2mqtt/{cover}/calibrate/result

Published once when calibration completes. Contains the averaged measurements that should be transferred to the cover configuration.

{
  "avg_close": 22.15,
  "avg_open": 24.03
}

{
  "avg_close": 22.15,
  "avg_open": 24.03,
  "avg_offset": 0.82,
  "avg_dead_band": 1.35,
  "dead_band_pct": 5.6
}

Calibration Commands¶

Topic: velux2mqtt/{cover}/calibrate/set

Calibration commands are JSON payloads with a "phase" key, sent to the dedicated /calibrate/set sub-topic. During active calibration, normal cover commands (on {cover}/set) are blocked. The calibrate/availability topic is published "online" while calibration is active and "offline" otherwise.

{"phase": "start"}

{"phase": "start", "runs": 5, "measure_offset": true, "measure_dead_band": true, "starting_state": "closed"}

{"phase": "go"}

{"phase": "mark"}

{"phase": "cancel"}

See Calibration for the full step-by-step procedure.

Availability¶

Topics: velux2mqtt/{cover}/availability

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

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

Status (Heartbeat)¶

Topic: velux2mqtt/status

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

{
  "status": "online",
  "uptime": 3600.0,
  "version": "0.0.0",
  "devices": {
    "blind": { "status": "online" },
    "window": { "status": "online" }
  }
}

Error¶

Topic: velux2mqtt/error

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

{
  "type": "OSError",
  "message": "GPIO access failed",
  "device": "blind",
  "timestamp": 1700000000.0
}

Framework Topics¶

Alongside the velux2mqtt-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 (velux2mqtt/_meta/registry)¶

The canonical AsyncAPI document describing every channel velux2mqtt 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 (velux2mqtt/_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¶

velux2mqtt follows the cosalette topic convention:

{prefix}/{device}/{channel}

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

velux2mqtt/status
velux2mqtt/error

The topic prefix can be changed via VELUX2MQTT_MQTT__TOPIC_PREFIX.