Skip to content

fix(mtp): MQTT 3.1.1 agent compatibility for mqtt broker and mqtt-adapter - #407

Open
DevenDucommun wants to merge 1 commit into
OktopUSP:devfrom
DevenDucommun:fix/mqtt311-agent-compat
Open

fix(mtp): MQTT 3.1.1 agent compatibility for mqtt broker and mqtt-adapter#407
DevenDucommun wants to merge 1 commit into
OktopUSP:devfrom
DevenDucommun:fix/mqtt311-agent-compat

Conversation

@DevenDucommun

Copy link
Copy Markdown

Problem

MQTT 3.1.1 USP agents (e.g. OB-USP-Agent / obuspa configured with ProtocolVersion 3.1.1) can't use the MQTT 5.0 Response Topic or User Properties features. Per the USP MQTT binding, they instead encode the reply topic as a reply-to=<url-encoded topic> suffix appended to the publish topic. Against current dev, such an agent connects to the broker but cannot complete any USP exchange:

  • the adapter panics (nil pointer) on the agent's initial MqttConnect record;
  • the broker's online/offline status events never publish (they rely on MQTT5 User Properties), so auto-discovery never fires;
  • the literal string reply-to=... leaks into NATS subjects and MongoDB device IDs;
  • API requests (Get/Set/...) always time out: agents answer on their controller topic with a reply-to= suffix, which is both the wrong routing path for the API waiter and one topic level deeper than the bridge's subscription filters, so the reply is silently never delivered.

Fixes (all in this PR, one per bullet)

  • adapter: guard nil NoSessionContext when parsing device-info records; Record_MqttConnect has no payload — register the device with basic info instead of panicking.
  • mqtt broker: in OnSubscribed/OnDisconnect, fall back to the MQTT client ID when no MQTT5 User Properties are present, so 3.1.1 devices still get status events (client ID is the agent's configured ClientID).
  • mqtt-adapter: decode reply-to= segments when extracting the device ID from incoming topics, and when resolving the agent topic for outgoing publishes.
  • mqtt-adapter: embed the api response topic as a reply-to= suffix on downlink publishes (3.1.1 agents can't see the MQTT5 ResponseTopic property) so agent replies route back to the API waiter.
  • mqtt-adapter: subscribe additionally to oktopus/usp/+/api/+/+ and oktopus/usp/+/controller/+/+ — agent replies carry the reply-to= suffix as an extra topic level, one deeper than the existing filters.

MQTT 5.0 agents are unaffected: User Properties still take precedence in the broker hooks, the MQTT5 ResponseTopic property is still set, and the extra subscriptions/decoding only engage when a reply-to= segment is actually present.

Testing

Validated end-to-end against a real OB-USP-Agent (obuspa) in MQTT 3.1.1 mode on Linksys router hardware, with the compose stack (nats controller adapter mqtt frontend profiles):

  • device auto-registers with a clean endpoint ID (no reply-to= artifacts in MongoDB);
  • USP Get round-trip returns live parameter values; Set applies and returns OperSuccess;
  • a ValueChange subscription Notify (triggered by a controller-side Set) was captured delivering through broker → mqtt-adapter → NATS;
  • all three services build clean (docker build on each service's build/Dockerfile).

Happy to split this into separate PRs per service if you prefer.

…pter

MQTT 3.1.1 USP agents (e.g. OB-USP-Agent/obuspa in 3.1.1 mode) cannot
use MQTT 5.0 Response Topic or User Properties, and encode their reply
topic as a 'reply-to=<url-encoded topic>' suffix appended to the
publish topic instead. Against current dev, such agents connect but
cannot complete any USP exchange. Five fixes, verified end-to-end
against a real obuspa 3.1.1 agent on Linksys hardware:

- adapter: guard nil NoSessionContext when parsing device info records
  (MqttConnect records have no payload; previously panicked) and
  register the device with basic info instead.
- mqtt broker: fall back to the MQTT client ID in OnSubscribed and
  OnDisconnect status events when no MQTT5 User Properties are present,
  so 3.1.1 devices still get online/offline status published.
- mqtt-adapter: resolve 'reply-to=' encoded segments when mapping
  incoming MQTT topics to NATS subjects (device ID extraction) and
  outgoing NATS subjects to MQTT topics (agent topic resolution);
  previously the literal 'reply-to=...' string leaked into NATS
  subjects and MongoDB device IDs.
- mqtt-adapter: embed the api response topic as a 'reply-to=' suffix on
  downlink publishes, since 3.1.1 agents cannot see the MQTT5
  ResponseTopic property; without it agents answer on their controller
  topic and API requests time out.
- mqtt-adapter: additionally subscribe 'oktopus/usp/+/api/+/+' and
  'oktopus/usp/+/controller/+/+' — 3.1.1 agent replies carry the
  reply-to suffix as an extra topic level, one deeper than the existing
  filters, so the broker never delivered them to the bridge.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant