mqtt
Use when debugging or working with MQTT in Home Assistant — listening to topics to see what devices actually publish, inspecting MQTT device discovery, or publishing a message — through HA NOVA Relay.
markusleben · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add markusleben/ha-nova --skill mqtt技能说明
name: mqtt description: Use when debugging or working with MQTT in Home Assistant — listening to topics to see what devices actually publish, inspecting MQTT device discovery, or publishing a message — through HA NOVA Relay. license: MIT compatibility: Requires the ha-nova CLI (run 'ha-nova setup' first) and the HA NOVA Relay in Home Assistant (App, or standalone container on Container/Core).
HA NOVA MQTT
Scope
MQTT work through Home Assistant's own MQTT integration:
- listen to a topic for a bounded window to see what is actually being published (the "is my device even talking?" question)
- inspect MQTT discovery/debug info for a device
- publish a message to a topic
Not in scope: the MQTT broker's own configuration, Zigbee2MQTT's web UI, or creating MQTT-based automations (ha-nova:write).
Bootstrap (once per session)
Read and follow ../ha-nova/session-bootstrap.md.
Verify relay CLI: ha-nova relay health
If this fails: ha-nova setup
Bounded subscription windows are guaranteed by the skills' enforced relay floor (skills/ha-nova/relay-api.md -> Bounded Event Collection). If a relay-outdated warning appeared, have the user update the NOVA Relay instead of working around it — an older relay silently ignores on_limit, which turns a normal quiet window into a hard error.
Requires the mqtt integration: check GET /api/components for mqtt. If it is absent, say so — this skill cannot add it.
Relay Contract
ha-nova relay ws --data-file <payload-file>for WS commandsha-nova relay core --method POST --path /api/services/mqtt/publish --body-file <payload-file>to publish--out <result-file>for large windows;--jq-file <filter-file>for filtering
Listening (bounded window)
MQTT topics never emit a "finish" event, so a listen is a WINDOW, not a request. Use the envelope in window mode:
{
"message": { "type": "mqtt/subscribe", "topic": "zigbee2mqtt/#" },
"collect_events": { "max_events": 50, "timeout_ms": 8000, "on_limit": "return" }
}
- The relay unsubscribes when the window closes; nothing keeps running.
.data.eventsholds what was seen..data.truncated: truemeans the window ended at a LIMIT — eithermax_eventsortimeout_ms, the relay does not distinguish them — not that the stream stopped. Compare the event count withmax_eventsto tell them apart: at the cap it hit the event limit (there may be more traffic); below it the window simply ran out of time, which is the normal ending for a quiet topic.- An EMPTY result is a real answer ("nothing published on that topic in 8 seconds"), not a failure — report it as such. That is often the actual diagnosis.
- Retained messages are NOT live traffic. The broker replays every retained message to a new subscriber immediately, so a message can arrive in the first milliseconds of the window even though the device published it days ago and is now silent. Each event carries a
retainflag: treatretain: trueas broker state, not as evidence that the device is sending. For the question "is my device actually publishing?", onlyretain: falsemessages count — and if all you saw were retained ones, say exactly that (the device is silent; the broker is holding its last value). - Keep windows short (<= 10 s, the relay's ceiling) and topics as narrow as possible;
#on the root is noise, not evidence.
User-Assisted Capture
When the traffic needs the user to act (press the remote, trip the sensor), the window cannot wait for them — it starts with the call and the relay caps it at ~10 s (context skill → User-Assisted Readiness):
- Name the exact action and topic first, and ask if the user is ready.
- On "ready": announce "listening for the next ~10 s — act now" and open the window in the same turn.
- A missed capture after the action — an empty window OR one holding only retained replays (
retain: true) — means re-arm and retry once before reporting "nothing arrived"; never call the device silent on one missed window.
Never instruct the physical action before the ready-check, and never claim monitoring is active without an open window.
Zigbee2MQTT Bridge Observability (read-only)
Zigbee2MQTT publishes its network state on retained zigbee2mqtt/bridge/... topics (bridge/devices, bridge/info, bridge/state). A bounded listen on one of them returns the retained replay immediately — here retain: true IS the answer (broker-held state), not a liveness signal. Use it for "which devices does my Zigbee network have / is the bridge online" questions. Bridge WRITES (rename, permit_join) are not covered here. ZHA and Z-Wave setups have no MQTT surface — route them to ha-nova:fallback (Zigbee / Z-Wave network status).
Flow
- Clarify the topic. Prefer the narrowest one that answers the question (
zigbee2mqtt/<device>beatszigbee2mqtt/#). - Listen in a bounded window (above). Summarize: which topics appeared, how many messages, and — separately — how many were live (
retain: false) versus retained replays. Quote at most a few payloads. - Device discovery/debug: WS
{"type":"mqtt/device/debug_info","device_id":"<device_id>"}shows the subscribed topics and discovery payloads for one MQTT device (resolvedevice_idfrom the device registry, never guess it). - Publishing (mutating): service
mqtt.publishwithtopic,payload,qos,retain. There is nopayload_templatefield in the current schema — render any template yourself and send the finished string aspayload. (evaluate_payload: trueonly tells HA to evaluate a Python-literal payload for raw bytes; it is not a template switch.) Preview the exact topic + payload and confirm. - Verify a command/
setpublish: when the topic belongs to an HA-known device, read the affected entity's state back after a moment — a broker accept is not device confirmation; if HA shows no corresponding change, say so. For topics HA does not mirror, state plainly that HA-side verification is not p