DCENT_OS Notifications Reference: MQTT, Home Assistant and Webhooks

MQTT: DCENT_OS is a client, not a broker

This is worth stating plainly because the opposite is easy to assume. DCENT_OS does not run a broker. It connects to one you already have — the broker key is an address it dials. The module is titled "MQTT publisher with Home Assistant auto-discovery" (dcentrald-api/src/mqtt.rs:1). Verified (in source).

Retained repository configuration example; check the installed configuration (Verified (shipped config) — dcentrald.toml:160-167):

[mqtt]
enabled = false                       # master switch for the MQTT publisher + subscriber
broker = "mqtt://203.0.113.100:1883"  # broker URL (mqtt:// or mqtts://)
topic_prefix = "dcentrald"            # base topic; entities live under <prefix>/<name>
discovery = true                      # publish HA MQTT-discovery configs on connect
# username = "homeassistant"          # optional broker credentials
# password = "secret"
publish_interval_s = 10               # stats publish cadence (seconds)

Note the key is topic_prefix and its shipped value is dcentrald. If you have seen topicPrefix or a dcentos prefix written down somewhere, that is a different spelling from the dashboard layer and it will not match the daemon's topic tree.

Two numbers exist for the publish cadence and both are real: the code default is 5 s (default_mqtt_interval() in config.rs), and the dcentrald.toml that ships in the repository overrides it to 10 s (dcentrald.toml:167). Your installed active configuration determines the cadence; the repository sample alone does not establish an image default. We print both so that seeing "5" somewhere else does not read as a contradiction.

What auto-discovery creates in Home Assistant

On connect, with discovery = true, the daemon publishes retained discovery configs to homeassistant/<domain>/dcentrald_<mac_id>/<entity_id>/config. All entities share one device block: manufacturer "D-Central Technologies", model from the unit's platform stamp (falling back to "Antminer"), and a configuration_url resolved from the live management IP, then the hostname, then http://dcentos.local (mqtt.rs:760-767, :98-107).

The energy sensor carries device_class: energy and state_class: total_increasing in kWh — the exact shape Home Assistant's Energy dashboard requires, which is what makes a mining heater's kWh/day and cost/day graphable without a template sensor (mqtt.rs:894-906).

The part worth copying: it refuses to show a modelled number as a measured one

Three of those sensors — power, BTU/h and efficiency — are derived from wall wattage, and wall wattage can be modelled rather than measured. The firmware handles this the hard way:

• They fail closed. Each value template resolves to none unless the daemon has published live_power_available: e.g. {{ (value_json.wall_watts | round(0)) if value_json.live_power_available else none }} (mqtt.rs:802, and the same guard at :810, :826). A blank reading, not a plausible invented one. Verified (in source).
• Provenance rides along as attributes. Power, BTU and efficiency each get json_attributes_template carrying power_source, power_source_detail, power_modeled, power_calibrated and power_note (mqtt.rs:742, :883-886) — in the source's own words, "so a modeled reading is never displayed as if it were a wall-meter measurement" (mqtt.rs:879-882).
• There is a sensor whose only job is to explain another sensor. "Power Provenance" is a diagnostic-category text entity whose value is the human-readable reason a power reading may be unknown (mqtt.rs:925-942).
• The heater's current temperature is the measured chain temperature, not an invented room temperature — stated as such at mqtt.rs:1031-1033.

The four provenance notes the daemon can emit are fixed strings (dcentrald-api/src/lib.rs:706-737): "Miner load is sourced from live measured power telemetry." · "Miner load is modeled from live runtime state with an operator wall-meter calibration." · "Miner load is modeled from the live dispatcher estimate." · "Live miner power has not published a positive wall-power reading."

Letting Home Assistant write back — three setpoints, hard-clamped

The command surface is exactly three values, and they only appear when the daemon supplies a validated-setter sink. There is no profile switch, no night-mode toggle and no reboot over MQTT on the Antminer side.

Each has a matching <prefix>/…/state topic where the daemon echoes the value it actually applied after clamping — not the value you asked for (mqtt.rs:989). The clamp behaviour, all Verified (in source):

• Commands are routed through the same validated setters the local REST API uses; the subscriber "NEVER opens a new unclamped path" (mqtt.rs:144-148).
• The fan ceiling of 30 % is the home safety cap and is "pinned equal" to dcentrald_hal::fan::PWM_SAFETY_MAX by a test (mqtt.rs:125-127). Publishing a higher number does not raise it — it is clamped (mqtt.rs:127-128).
• The 60 °C temperature ceiling is chosen so a remote setpoint "can never park the PID target at or above the danger line" (mqtt.rs:138-141).
• Non-numeric and non-finite payloads are rejected before dispatch (mqtt.rs:232-247).
• Retained messages on a /set topic are ignored (mqtt.rs:561-568) — otherwise a retained setpoint would silently re-apply itself on every reconnect.

Availability: a dead miner shows as dead

The daemon registers offline as the broker-side Last Will on <prefix>/availability, the same topic every discovery entity gates on, and publishes a retained online when it connects (mqtt.rs:28-38, :392-410). A crash or a power cut therefore flips every Home Assistant entity to unavailable rather than freezing them on the last good reading. Verified (in source).

The connect sequence is deliberate and documented at mqtt.rs:328-336: subscribe first, then retained discovery configs at QoS 1, then retained online, then the latest state at QoS 0 and not retained.

Broker URLs are passed through the pool-URL sanitiser before they reach any log line or error string (mqtt.rs:441, :668), so credentials embedded in a broker URL are masked.

[mqtt]
enabled = true
broker = "mqtt://broker.example:1883"
topic_prefix = "dcentos/heater-01"
discovery = true
username = "YOUR_BROKER_USERNAME"
password = "YOUR_BROKER_PASSWORD"
publish_interval_s = 10

jq '{hashrate_ghs, live_power_available, wall_watts,
     energy_kwh, power_modeled, power_note}' state.json

[webhook]
enabled = true
url = "https://receiver.example/dcentos-hook"
format = "generic"
events = ["share_milestone", "lucky_share"]

Webhook contracts: declared events and actual wired producers

Retained repository configuration example; check the installed configuration (Verified (shipped config) — dcentrald.toml:172-176):

[webhook]
enabled = false
url = "https://example.com/dcentos-hook"
# events = ["share_milestone", "lucky_share"]
# miner label comes from [general].hostname; miner_name is not a valid webhook key

An empty or absent events list means all events (webhook.rs:463-465).

The table above describes declared event vocabulary, not proof that every variant is emitted. The production mining-sync bridge is source-traced for share_milestone and lucky_share; the separate inline alert path must be assessed separately. An older alert path, AlertEvent (dcentrald/src/runtime/notifications.rs:395-446), emits 8 names of its own — seven of which the table above also covers, plus one it does not: emergency_shutdown.

The three chat formats are delivered natively, with no relay or proxy in between (webhook.rs:286-287).

Your wallet address does not leave the miner in a webhook

Stratum pool strings routinely carry the worker — often a wallet address — and the password as URL components. The dispatcher handles this at a single chokepoint, all Verified (in source):

• Redaction runs inside the dispatcher, before serialization, so no caller can skip it (webhook.rs:606-607); it is documented as idempotent (:210).
• Pool strings are reduced to host and port: scheme dropped, then any user:pass@, then any path or query — and the remainder is still run through a wallet-address scanner as a second pass (webhook.rs:252-275).
• Free-text fields — the mining_stopped reason and the ota phase — are wallet-scanned too (:217, :227).
• A Telegram bot token lives in the URL path by Telegram's design, so the dispatcher logs the event name and HTTP status and never the URL (webhook.rs:305-309).

Queued dispatcher limits and separate inline alert delivery

The following queue/retry limits apply to the event-bus dispatcher. The mining-sync bridge is source-traced for share_milestone and lucky_share. Declared variants alone do not prove emission; the separate inline AlertEvent sender performs its own POST loop without these retries. Delivery is best effort, not a supervision guarantee.

Enqueue never blocks: a full queue drops the event and logs it at debug level (webhook.rs:490-491, :502-520). The enqueue result is explicitly documented as informational, with the instruction that callers "should never branch mining behaviour on it" (:500-501). Configuration changes — enable, URL, event list — take effect through a watch channel with no daemon restart (:526-529). With webhooks disabled or no URL set, events are dropped before any network I/O happens at all (:596-600).

The Bitaxe side is a second implementation, not the same one

DCENT_axe carries its own Home Assistant discovery builder. The source is explicit that this is deliberate: "This is a fresh esp-idf-runtime implementation — the TOPIC/PAYLOAD shape is shared, the code is not" (DCENT_OS_ESP/dcentaxe/src/mqtt_ha.rs:22-25). Verified (in source). Do not assume a behaviour transfers between them.

The 60 °C and 95 °C ceilings are not an inconsistency — different silicon, different thermal ladders. They are listed side by side precisely so nobody merges them into one number.

The two notification vocabularies are also not disjoint, and it would be easy to assume they are: share_milestone and ota appear in both, while thermal and failover are ESP-only spellings with no exact counterpart in the Antminer union (the Antminer names for the same territory are thermal_safety / thermal_restart and pool_failover). If you are writing one receiver for both platforms, treat the two name sets as overlapping-but-different, not as one vocabulary. Verified (in source) — the intersection is computed by script from both enum definitions.

What this page does not tell you

• Whether any of it works against a real broker. No bench verification. This is a reading of the source and of the shipped configuration file.
• The REST endpoint schemas. The repository publishes no OpenAPI specification. We name GET /api/mqtt/status only because the shipped configuration file names it (dcentrald.toml:159); we do not print a route table we have not resolved against the router. See API & ports for what is published.
• The full thermal ladder. Two layers of the source name different hot/dangerous thresholds, so we state only the clamp that is actually asserted: a remote Home Assistant setpoint cannot exceed 60 °C on an Antminer.

Which control boards this has evidence on is a separate question from what the firmware is written to do; see hardware status for the per-lane picture. Nearby: all documentation.