Add NotificationMechanism::Mqtt and implement MQTT subscription transport (OpenADR 3.1)

[purcell-lab]

Add NotificationMechanism::Mqtt and implement MQTT subscription transport (OpenADR 3.1)

Background

OpenADR 3.1.0 (2025) explicitly adds MQTT message-queue notifications as an alternative to webhook subscriptions, specifically to support in-home VENs that cannot expose an inbound HTTP callback:

"Supports data push via Webhook Subscription and message queue. … Notifications via message queues for in-home VENs — NEW in version 3.1"

The OpenADR Alliance's own OpenADR 3 introduction webinar goes further and recommends "PUSH with MQTT encouraged" for the home/edge case, framing MQTT as the canonical transport when VENs sit behind NAT, mobile networks, or otherwise can't host a webhook endpoint.

The Alliance's DER architecture paper ("OpenADR 3 and DER Management" v1.0, p.14) treats webhook and MQTT as equivalent push options:

"a VEN client may be notified immediately upon creation of the event (using webhook or message queue (MQTT) notification)."

Current state in openleadr-rs

The Subscription data model in openleadr-wire/src/subscription.rs defines:

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, Default)]
#[serde(rename_all = "UPPERCASE")]
pub enum NotificationMechanism {
    #[default]
    Webhook,
    Websocket,
}

There is no Mqtt variant, even though:

• The doc-comment one module up references MQTT as a notional transport ("multiple subscribers can get the same ID, possibly over different notification channels (webhook, websocket, MQTT)").
• The repo's CI workflow (.github/workflows/docker.yml) explicitly skips the Alliance spec test suite's tests/oadr310/vtn/mqtt directory — --ignore=tests/oadr310/vtn/mqtt — which confirms MQTT coverage is intentionally absent.
• The README still scopes supported features to OpenADR 3.0, while the top-of-README badge says "OpenADR 3.1 in Rust" — the 3.1 MQTT subscription transport is the most visible 3.0→3.1 gap.

#356 (Subscriptions) tracks the broader webhook subscription work but does not commit to MQTT specifically; there are zero open or closed issues in this repo mentioning MQTT.

Proposal

1. Wire type: extend NotificationMechanism with an Mqtt variant and add the MQTT-specific subscription fields per OpenADR 3.1 (broker URL / topic template / QoS / auth descriptor — TBD against the spec text). Keep Webhook as default for back-compat.
2. VTN side: when a subscription with mechanism: MQTT is created, the VTN should publish object lifecycle notifications (Create / Update / Delete on Programs, Events, Reports, VENs, Resources) to the MQTT broker on the agreed topic structure.
3. VEN side: the openleadr-client library should grow an opt-in MQTT subscription helper (paho-mqtt or rumqttc) so Rust VEN consumers get push without rolling their own MQTT plumbing.
4. Test coverage: re-enable tests/oadr310/vtn/mqtt in docker.yml once the implementation lands. This is the official Alliance suite — passing it is the certification path.
5. Documentation: update the "Supported features" section of the README to call out MQTT as supported (alongside webhook once Subscriptions #356 lands), and clarify the 3.0 vs 3.1 scope.

Why this matters — downstream motivation

I maintain an Australian VTN (https://openleadr-vtn-au.fly.dev) bridging 20 NEM tariffs with PT5M live ticks and PT30M forecasts. Consumers of this VTN are Home Assistant instances behind residential NAT — exactly the in-home VEN case the 3.1 MQTT path was added for. Without VTN-side MQTT push, those VENs fall back to HTTP polling, which is observably broken at the consumer end: see grid-coordination/openadr3-ven-hass#11 where the HA VEN's coordinator stays stale by 60+ minutes because there's no signal to trigger a refresh on event modification. MQTT push from the VTN is the cleanest fix for that whole class of bug — modificationDateTime change → MQTT publish → VEN refresh, instead of polling-cadence guesswork.

I'd happily run the AU VTN as a permanent integration target for any MQTT prototype, and I'd consider sponsoring or contributing if there's a maintainer signal that this is wanted.

Related

• Subscriptions #356 — Subscriptions (webhook). This issue is the MQTT companion; ideally the two land together so all three 3.1 transport variants (Webhook, Websocket, MQTT) are shippable.
• .github/workflows/docker.yml — the --ignore=tests/oadr310/vtn/mqtt line is the cleanest "this is missing" marker for tracking progress.

[purcell-lab]

Under active development #442

[stefanvi]

Thank you for your interest in the project. Pull request #442 was merged yesterday and a new version of openleadr-rs was released alongside it. That means that v0.2.4 now does support MQTT. Let us know if this works for your use case!

• We appreciate your feedback; the README could have been clearer on what features are (or aren't) supported. I have now added MQTT as a supported feature.

• The repo's CI workflow (.github/workflows/docker.yml) explicitly skips the Alliance spec test suite's tests/oadr310/vtn/mqtt directory — --ignore=tests/oadr310/vtn/mqtt — which confirms MQTT coverage is intentionally absent.

  I will unignore these tests, as they pass locally now. Do note that this is not the OpenADR test suite, but rather a complementary test suite provided by Elaad in their Openadr3-client.

  We cannot test against the official OpenADR spec test suite, as this is not open source. See also our readme:

  In addition to the tests we developed ourselves, there exists a test suite maintained by the OpenADR alliance. As it is closed source, we cannot integrate this test suite with the CI, unfortunately. Nevertheless, we executed the tests locally to check for incompatibilities. Currently, all except for two of the 168 test cases that are applicable for us pass.