RMS MQTT Configuration API Reference

This is the provisioning flow for QwantiFi: how RMS retrieves the latest QwantiFi configuration from the Magensa Gateway, generates the device command list, and hands it back so a client can apply it to a reader and report the result. For the architecture and server configuration behind this API, see the Web RMS Service.

The Flow at a Glance

Client POST Request: Request a Ronfiguration

The client requests one of three configuration names — DynaFlexMqtt (MQTT only), DynaFlexTrust (Trust/TLS only), or DynaFlexMqttAll (both).

POST {{RMSV2Url}}/V2/Configs

Request

{
    "ProductName": "DYNAFLEX",
    "ProfileName": "MagTek_MQTT",
    "ConfigurationName": "DynaFlexMqttAll",
    "Version": null,
    "FirmwareID": "1000009711-AC2-PCI",
    "DeviceSerialNumber": "B563215",
    "BillingLabel": "Test",
    "InterfaceType": "USB",
    "DownloadPayload": true,
    "RawCommands": true,
    "Authentication": null,
    "AdditionalParameters": {
        "KSN": "9070020B56C3AEE00000",
        "Boot1FirmwareID": "",
        "WifiFirmwareID": "",
        "ResellerID": "13204",
        "CustomerID": "2026213",
        "DeviceNickname": "Store 101 Front Counter",
        "Street1": "3674 Tyler Ave",
        "Street2": "Suite 200",
        "City": "El Monte",
        "State": "CA",
        "ZipCode": "91731",
        "ZipPlus4": "2506",
        "Country": "US"
    }
}

ResellerID, CustomerID, and the Location fields are passed through in AdditionalParameters.

Gateway Returns the Device's MQTT Hash and Status

RMS checks the device's current provisioning state against the Magensa Gateway.

GET {{gatewayUrl}}/MagensaMQTT/api/device-check?deviceSN={{deviceSn}}

Response

{
    "recordExists": true,
    "mqttProvisioned": true,
    "status": "Provisioned",
    "deviceMqttHash": "8ebbeadebdc88d1ae6098179fe1940629d7ed2b9ba85c7eb3afb227d7d73257d"
}

MQTT Configuration Version Control

• If request.Version is 0, perform a forced update and return all configuration commands.

• Otherwise, compare the version-store hash with the database hash.

• If the hashes are identical, return a status of Up To Date.

• If the hashes differ, return the commands required to update the device.

Gateway Returns Credentials

POST {{gatewayUrl}}/MagensaMQTT/api/credentials

Request

{
  "deviceSn": "B56C3AE",
  "resellerId": "13204",
  "customerId": "2026213",
  "ksn": "9070020B56C3AEE00000",
  "firmware": { "boot1": "1000008593-A1-PCI", "main": "1000008594-AA4-PRD", "wifi": "1000007537-AB2-PCI" },
  "location": { "street1": "Pennsylvania Plaza", "street2": "", "city": "New York", "state": "New York", "zipCode": "10001", "zipPlus4": "", "country": "US" },
  "nickname": "B56C3AE"
}

Response

{
    "deviceSn": "B563215",
    "status": "PROVISIONED",
    "mqttConfig": {
        "broker": "10.0.5.151",
        "port": 1883,
        "peerCommonName": "",
        "qos": 1,
        "clientId": "B563215",
        "username": "13204-2026213-B563215",
        "password": "EXAMPLE-DUMMY-DEVICE-PASSWORD",
        "subscribeTopic": "MagTek/13204/2026213/B563215/#",
        "publishTopic": "MagTek/13204/2026213/device/publish/B563215",
        "operatingMode": "mqtt"
    }
}

Device credentials vs. integrated application credentials. The credential above is a device credential — a per-device username and a plain password, with single subscribe/publish topics. This is different by design from anintegrated application credential (a short-lived JWT + refresh token, scope-wide wildcard topics). See the QwantiFi Credential Model for how the two differ.

RMS Response to Client: The Commands

When the MQTT configuration differs from the device's configuration, the API returns the commands required to update the device. The Commands array contains the device commands (DISPLAYMESSAGE, SENDCOMMAND, WAIT, and optionally SENDFILE, RESETDEVICE) needed to apply the update.

{
    "Claims": {
        "WlanProtocol": "00",
        "Broker": "dev-mqtt.magensa.dev",
        "Port": "8883",
        "QoS": "1",
        "SubscribeTopic": "MagTek/13204/2026213/B563215/SendCommand",
        "PublishTopic": "MagTek/13204/2026213/device/publish/B563215",
        "ClientId": "B563215",
        "Username": "13204-2026213-B563215",
        "Password": "******",
        "PeerCommonName": "dev-mqtt.magensa.dev",
        "OperatingMode": "mqtt"
    },
    "Name": "DynaFlex MQTT and Trust Configuration",
    "Version": 3,
    "ResultCode": 0,
    "Result": "Success",
    "MagTranIDs": [ "34cf8363-13c2-49b8-a70e-118d7529d452" ],
    "Commands": [
        "DISPLAYMESSAGE,Beginning DynaFlex MQTT Update...",
        "SENDCOMMAND,AA0081040155D1118410D1118501018704020201018903D10100",   // Updating WlanProtocol to 00
        "SENDCOMMAND,AA0081040155D111844FD11185010187040202010289…",           // Updating BrokerAddress
        "SENDCOMMAND,AA0081040155D1118411D11185010187040202010289…",           // Updating Port to 8883
        "…",                                                                    // QoS, SubscribeTopic, PublishTopic, ClientId, Username, Password, PeerCommonName
        "DISPLAYMESSAGE,Updating Trust 05000100",
        "WAIT,100",
        "SENDCOMMAND,AA0081040101D8128444D812810405000100…",                    // Trust config command
        "WAIT,100",
        "SENDCOMMAND,AA00810804…<TLS certificate payload>…",                    // Trust certificate (abbreviated)
        "DISPLAYMESSAGE,Finished DynaFlex MQTT Update"
    ],
    "ReleaseNotes": null
}

NOTE: Command bytes abbreviated. The live Commands array is long: it repeats one SENDCOMMAND per setting and includes a full TLS certificate payload in the Trust command. It has been abbreviated here with … and inline comments. The commands are generated by RMS; integrators execute them as-is and do not author them by hand. Note also that the generated command list encodes the device password.

Do not log or publish the raw command list!

The settable configuration properties (Broker, Port, QoS, topics, Trust, etc.) are documented in QwantiFi Device Configuration Commands.

The Trust-only response (ConfigurationName: DynaFlexTrust) has the same shape but a much shorter Commands array — the Trust/TLS command(s) only.

Client Confirms Device Update Status

After applying the commands, the client reports success or failure back to RMS.

POST {{RMSV2Url}}/V2/Configs/UpdateDeviceStatus

Request

{
    "ProductName": "DYNAFLEX",
    "ProfileName": "MagTek_MQTT",
    "ConfigurationName": "DynaFlexMqttAll",
    "FirmwareID": "1000009712-AC3-PRD",
    "DeviceSerialNumber": "B62CA5F",
    "Operation": "UpdateMQTTConfigurations",
    "Authentication": null,
    "AdditionalParameters": { "ResellerID": "13204", "CustomerID": "2026213" },
    "ResultCode": 0,
    "Result": "Success",
    "ResultDetails": "",
    "MagTranIDs": [ "0455ef05-4b00-45d9-a312-92877b5f0b04" ]
}

On success, RMS updates the version store with the latest configuration version and MQTT hash, and records the update status in the log.

Trust Version control

For Trust configuration:

• If request.Version is 0, perform a forced update and return all configuration commands.

• Otherwise, compare the device version with the configuration file version.

• If request.Version is null, use the stored version as the device version for comparison.

• If the device version matches the configuration version, return a status of Up To Date.

• If the device version is lower, return the commands required to update to the latest configuration.

Gateway Confirms Device Status

RMS marks the device's status in the Gateway database.

PATCH {{gatewayUrl}}/api/confirm-device-status

Request

{ "deviceSn": "B56C3AE" }