MQTT API
The MQTT API is the interface that the IoT Connector, the firmware on RFD40 and RFD90 readers, provides for managing a reader, controlling RFID inventory, and receiving events and tag data. Every exchange travels over MQTT 3.1.1 through a broker that you operate. This reference describes version 1.22.0 of the API contract.
This documentation covers the RFD40 Premium, RFD40 Premium Plus, RFD40-M Premium Plus and RFD90 (RFD9030 and RFD9090), which reach the broker over Wi-Fi 6 or a communication cradle, and the RFD40 Standard, which has no Wi-Fi and reaches it only through a communication cradle. The minimum firmware depends on the reader and the endpoint type.
Who Takes Part
An exchange involves up to five parties. The reader and your applications never address each other directly: each is an MQTT client of the same broker.
| Party | Role in the MQTT API |
|---|---|
| Reader (RFD40 or RFD90) | The hardware. It holds the endpoint configuration that tells the IoT Connector which broker to use, and it reaches the broker over its own Wi-Fi, or over Ethernet in a communication cradle. No host application or SDK is needed in the MQTT path. See The Reader Is Its Own MQTT Client. |
| IoT Connector | The firmware on the reader. For each active endpoint, it opens its own MQTT client session to the broker named in that endpoint. Depending on the endpoint type, it subscribes to the endpoint's command topic and publishes responses, events, connection state, or tag data. |
| Broker | Your MQTT 3.1.1 broker. It relays messages between the reader and your applications. The broker address is part of the reader's endpoint configuration; the API has no default broker. If the reader's session ends without a clean disconnect, the broker publishes the Last Will that the reader registered when it connected. |
| Host application | The application that controls the reader. It publishes commands to the reader's command topic and subscribes to the response topic, pairing each reply with its request by requestId. |
| Consuming applications | Applications that subscribe to events, connection state, and tag data. A consuming application can be the host application or a separate service. Tag data arrives on a DATA1 endpoint; DATA2 is currently not supported. |
123RFID Desktop enters the reader's first endpoint configuration during bootstrap. Later endpoints can be added over MQTT with config_endpoint.
How Messages Flow
Host application -- commands ----> Broker -- commands ----> Reader (IoT Connector)
Host application <-- responses --- Broker <-- responses --- Reader (IoT Connector)
Consuming app <-- events ------ Broker <-- events ------ Reader (IoT Connector)
Consuming app <-- tag data ---- Broker <-- tag data ---- Reader (IoT Connector)
Consuming app <-- Last Will --- Broker
The flow shows who publishes and who subscribes, not a network path. Events include the CONNECTED form of mqttConnEVT; the broker publishes the DISCONNECTED form as the reader's Last Will. A host application can also subscribe to events and tag data. The contract describes the IoT Connector on readers connected over Wi-Fi and Ethernet; which interface carries a given session is not specified in the available sources.
Three kinds of message cross the broker:
| Kind | Direction | Correlation | Where it is specified |
|---|---|---|---|
| Commands and their responses | Your application publishes a command; the reader publishes one reply | requestId, echoed in the reply | Message Envelopes and Correlation, Correlation and Request/Response Pairing |
Events: mqttConnEVT, heartBeatEVT, alerts | The reader publishes; your application subscribes | None: an event answers no request | Events |
Tag data: dataEVT | The reader publishes during an inventory; your application subscribes | None | dataEVT |
Choose Where to Start
| If you want to… | Go to |
|---|---|
| Exchange one command with a reader that is already connected | Send Your First Command |
| See the whole setup, from a new reader to its first tag data | The Connection Path |
| Understand how the reader reaches your broker, and how its session behaves | Connection and Session |
| Encrypt and authenticate the connection | TLS and Authentication |
| Build topics, messages, and correlation logic | Protocol |
| Query or configure the reader | Management |
| Configure reading and start or stop an inventory | Control |
| Handle what the reader publishes without being asked | Events and dataEVT |
| Validate payloads or look up a type | Schemas |
Interpret a response.code | Response Codes |
| Look up the documented limits | Limits |
| See what changed between API versions | Changelog |
In This Reference
Overview
How to read the reference, versioning, and the changelog.
Protocol
The rules of the wire: connection, security, topics, messages and delivery.
Management
Commands that query and configure the reader — device info and status, network.
Control
Control-plane commands that configure how the reader reads and run inventory.
Events
What the reader emits unprompted: connectivity, health and alerts.
Telemetry
The tag-read stream the reader emits during active inventory, on the data plane.
Response Codes
Every response code: what it means, and which commands return it.
Limits
Every supported limit in one table, with the code each one returns.
Schemas
The named types the MQTT API exchanges, by domain.