nx_mqtt_shim.nx
buildroot/runtime/shims/nx_mqtt_shim.nx
about
nx_mqtt_shim.nx -- MQTT 3.1.1 protocol shim.
WHEELER-IMPLEMENTATION-OF-CANONICAL-SPEC.
Wire-spec source (re-implemented clean-room from published spec;
no external code imported per sovereignty audit):
- OASIS MQTT Version 3.1.1 Plus Errata 01 (29 October 2015)
- Optional V2+: OASIS MQTT Version 5.0 (07 March 2019)
Third protocol shim per INTEROPERABILITY_CHARTER.md §5.5 (cloud).
Opens the cloud-pub/sub family. MQTT is the IoT-standard pub/sub
wire protocol; once this ships, the substrate's nx_telemetry bus
can publish anomaly verdicts to an MQTT broker -> operator
dashboards / mobile alerts / cloud aggregation, instead of just
stdout NDJSON.
Status: SEED v0.1.0. 2026-05-27.
WINNER-TIER: BASELINE-C provisional
INCUMBENTS: Mosquitto v2.x (broker; ISC),
Eclipse Paho C v1.3.x (client; EPL),
mqtt.js v5.x (JavaScript client; MIT),
HiveMQ Cloud (commercial broker),
AWS IoT Core (commercial cloud broker),
Aedes (Node.js broker)
NUMBERS: V1 ships framing + publish/subscribe + ping; paired
throughput + connection-stability bench vs Paho C
pending real broker fixture
GAP: Paho has feature breadth (TLS, MQTT 5.0 properties,
persistent session, will/retain); V1 covers the
~70% subset that publishes telemetry from substrate
to broker. Nishi adds value via sealed verdict
surface + telemetry-bus integration (Paho is
string-keyed; loses type safety)
PLAN: M-next: paired bench vs Paho on 10K-publish burst
latency + broker reconnection storm; add MQTT 5.0
properties + TLS wrap when nx_tls_shim lands
EXEMPTION REASON: n/a; provisional pending measurement
V1 SCOPE:
- CONNECT / CONNACK (client-side; clean-session only V1)
dependencies 1 imports · 1 importers
imports: nx_syscalls.nx
imported by: nx_mqtt_sink_for_telemetry.nx
structs
| 128 | struct NxMqttShim |
consts
| 63 | const NX_SHIM_OK: i64 = 0 |
| 64 | const NX_SHIM_BAD_FRAME: i64 = 1 |
| 65 | const NX_SHIM_PROTOCOL_VIOLATION: i64 = 2 |
| 66 | const NX_SHIM_TIMEOUT: i64 = 3 |
| 67 | const NX_SHIM_BACKPRESSURE: i64 = 4 |
| 68 | const NX_SHIM_UNSUPPORTED_PID: i64 = 5 // here: unsupported control packet type |
| 69 | const NX_SHIM_NO_WIRE: i64 = 6 |
| 72 | const NX_MQTT_VERDICT_BASE: i64 = 300 |
| 73 | const NX_MQTT_BAD_PROTO_NAME: i64 = 300 // CONNECT proto name != "MQTT" |
| 74 | const NX_MQTT_BAD_PROTO_LEVEL: i64 = 301 // CONNECT proto level != 4 (v3.1.1) |
| 75 | const NX_MQTT_BAD_VLI: i64 = 302 // var-len-int > 4 bytes (spec max) |
| 76 | const NX_MQTT_BAD_QOS: i64 = 303 // QoS out of 0..2 |
| 77 | const NX_MQTT_BAD_TOPIC: i64 = 304 // topic name violates §4.7 |
| 78 | const NX_MQTT_UNSUPPORTED_QOS2: i64 = 305 // V1 doesn't implement QoS 2 |
| 79 | const NX_MQTT_CONNACK_REJECTED: i64 = 306 // broker rejected connection (CONNACK rc != 0) |
| 80 | const NX_MQTT_TRUNCATED: i64 = 307 |
| 83 | const NX_MQTT_PKT_RESERVED_0: i64 = 0x00 |
| 84 | const NX_MQTT_PKT_CONNECT: i64 = 0x10 // client -> server |
| 85 | const NX_MQTT_PKT_CONNACK: i64 = 0x20 // server -> client |
| 86 | const NX_MQTT_PKT_PUBLISH: i64 = 0x30 // bidirectional |
| 87 | const NX_MQTT_PKT_PUBACK: i64 = 0x40 // QoS 1 ack |
| 88 | const NX_MQTT_PKT_PUBREC: i64 = 0x50 // QoS 2 step 1 (V2+) |
| 89 | const NX_MQTT_PKT_PUBREL: i64 = 0x60 // QoS 2 step 2 (V2+) |
| 90 | const NX_MQTT_PKT_PUBCOMP: i64 = 0x70 // QoS 2 step 3 (V2+) |
| 91 | const NX_MQTT_PKT_SUBSCRIBE: i64 = 0x80 |
| 92 | const NX_MQTT_PKT_SUBACK: i64 = 0x90 |
| 93 | const NX_MQTT_PKT_UNSUBSCRIBE: i64 = 0xA0 |
| 94 | const NX_MQTT_PKT_UNSUBACK: i64 = 0xB0 |
| 95 | const NX_MQTT_PKT_PINGREQ: i64 = 0xC0 |
| 96 | const NX_MQTT_PKT_PINGRESP: i64 = 0xD0 |
| 97 | const NX_MQTT_PKT_DISCONNECT: i64 = 0xE0 |
| 100 | const NX_MQTT_CONNECT_FLAG_CLEAN_SESSION: i64 = 0x02 |
| 101 | const NX_MQTT_CONNECT_FLAG_WILL: i64 = 0x04 |
| 102 | const NX_MQTT_CONNECT_FLAG_WILL_QOS_1: i64 = 0x08 |
| 103 | const NX_MQTT_CONNECT_FLAG_WILL_QOS_2: i64 = 0x10 |
| 104 | const NX_MQTT_CONNECT_FLAG_WILL_RETAIN: i64 = 0x20 |
| 105 | const NX_MQTT_CONNECT_FLAG_PASSWORD: i64 = 0x40 |
| 106 | const NX_MQTT_CONNECT_FLAG_USERNAME: i64 = 0x80 |
| 109 | const NX_MQTT_CONNACK_OK: i64 = 0 |
| 110 | const NX_MQTT_CONNACK_UNSUPPORTED_PROTOCOL: i64 = 1 |
| 111 | const NX_MQTT_CONNACK_BAD_CLIENT_ID: i64 = 2 |
| 112 | const NX_MQTT_CONNACK_SERVER_UNAVAILABLE: i64 = 3 |
| 113 | const NX_MQTT_CONNACK_BAD_AUTH: i64 = 4 |
| 114 | const NX_MQTT_CONNACK_NOT_AUTHORIZED: i64 = 5 |
| 117 | const NX_MQTT_EVT_CONNECTED: i64 = 400 // v0=session_present; v1=connack_rc |
| 118 | const NX_MQTT_EVT_MESSAGE_RX: i64 = 401 // v0=packet_id; v1=qos; v2=payload_len |
| 120 | const NX_MQTT_EVT_PUBACK_RX: i64 = 402 // v0=packet_id (matches our prior PUBLISH) |
| 121 | const NX_MQTT_EVT_SUBSCRIBED: i64 = 403 // v0=packet_id; v1=granted_qos |
| 122 | const NX_MQTT_EVT_PING_RX: i64 = 404 // server-side PINGRESP received |
| 123 | const NX_MQTT_EVT_DISCONNECTED: i64 = 405 // server initiated DISCONNECT |
| 124 | const NX_MQTT_EVT_REJECTED: i64 = 406 // v0=connack_rc reason |
functions
| 140 | func nx_mqtt_shim_init(s: *NxMqttShim) -> i64 |
| 159 | func nx_mqtt_vli_decode(buf: *u8, off: i64, out_value: *i64) -> i64 called by 1: nx_mqtt_rx_fn |
| 176 | func nx_mqtt_vli_encode(value: i64, out: *u8, out_off: i64) -> i64 |
| 197 | func nx_mqtt_read_u16_be(buf: *u8, off: i64) -> i64 called by 1: nx_mqtt_rx_fn |
| 203 | func nx_mqtt_write_u16_be(buf: *u8, off: i64, value: i64) -> i64 |
| 209 | func nx_mqtt_write_string(buf: *u8, off: i64, str: *u8, str_len: i64) -> i64 called by 3: nx_mqtt_build_connectnx_mqtt_build_publishnx_mqtt_build_subscribe calls 1: nx_mqtt_write_u16_be |
| 226 | func nx_mqtt_build_connect(s: *NxMqttShim, client_id: *u8, client_id_len: i64, |
| 272 | func nx_mqtt_build_publish(s: *NxMqttShim, topic: *u8, topic_len: i64, |
| 319 | func nx_mqtt_build_subscribe(s: *NxMqttShim, topic_filter: *u8, topic_filter_len: i64, |
| 348 | func nx_mqtt_build_pingreq(s: *NxMqttShim, out: *u8, out_cap: i64) -> i64 |
| 356 | func nx_mqtt_build_disconnect(s: *NxMqttShim, out: *u8, out_cap: i64) -> i64 |
| 370 | func nx_mqtt_rx_fn(s: *NxMqttShim, frame: *u8, frame_len: i64, |
| 478 | func nx_mqtt_diag_fn(s: *NxMqttShim, out_vec: *i64) -> i64 |