跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

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 commands
  • ha-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.events holds what was seen. .data.truncated: true means the window ended at a LIMIT — either max_events or timeout_ms, the relay does not distinguish them — not that the stream stopped. Compare the event count with max_events to 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 retain flag: treat retain: true as broker state, not as evidence that the device is sending. For the question "is my device actually publishing?", only retain: false messages 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):

  1. Name the exact action and topic first, and ask if the user is ready.
  2. On "ready": announce "listening for the next ~10 s — act now" and open the window in the same turn.
  3. 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

  1. Clarify the topic. Prefer the narrowest one that answers the question (zigbee2mqtt/<device> beats zigbee2mqtt/#).
  2. 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.
  3. Device discovery/debug: WS {"type":"mqtt/device/debug_info","device_id":"<device_id>"} shows the subscribed topics and discovery payloads for one MQTT device (resolve device_id from the device registry, never guess it).
  4. Publishing (mutating): service mqtt.publish with topic, payload, qos, retain. There is no payload_template field in the current schema — render any template yourself and send the finished string as payload. (evaluate_payload: true only tells HA to evaluate a Python-literal payload for raw bytes; it is not a template switch.) Preview the exact topic + payload and confirm.
  5. Verify a command/set publish: 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
阅读完整来源 ↗