Topics and Channels
ReferenceAudience: API consumerUse: build the exact topic to publish to or subscribe to, and configure an endpoint's topics correctly
Every topic that the reader publishes to or subscribes to has three segments. You configure the middle one; the reader supplies the other two.
<tenantId>/<base topic>/<serial>
For example, with the tenant zebra, the base topic MDM/clients/cmnd and the reader RFD40-212735201D0053, the reader subscribes to zebra/MDM/clients/cmnd/RFD40-212735201D0053. This is the pattern the RFD40/RFD90 IoT API specification describes for every command, response, event and Last Will topic.
Segments
| Segment | Source | Rules |
|---|---|---|
<tenantId> | The endpoint's tenantId. The reader adds it to the front of the topic. | At most 48 characters. Case is not normalized. |
<base topic> | The topic value of an entry in the endpoint's mqttParams.publishTopics or mqttParams.subscribeTopics | May contain /. A publish entry must not contain + or #. |
<serial> | The reader's serial number in its model-prefixed form, for example RFD40-212735201D0053. The reader adds it to the end of the topic. | See Serial Number Forms. |
Don't write the tenant ID or the serial number into a topic value. The reader adds both, so a value such as acme/MGMT/clients/cmnd/<serial> produces acme/acme/MGMT/clients/cmnd/<serial>/<serial>, a topic that nothing subscribes to. The contract calls this the most common configuration mistake with this API.
Serial Number Forms
The serial segment is the model-prefixed serial number: the model, a hyphen and the serial, for example RFD40-212735201D0053. The RFD40/RFD90 IoT API specification uses this form in every topic example. It is also the value the reader reports as deviceSerialNo in mqttConnEVT: readerVersion.model and readerVersion.serialNumber from get_version, joined by a hyphen.
The contract's examples also show a bare serial and a shorter compact form in other fields. Don't use those in topics. To address every reader in a tenant, subscribe with the single-level wildcard + in the serial position.
Direction
The two topic arrays are named from the reader's point of view, which is the opposite of what your application does with them:
| Endpoint array | The reader… | Your application… |
|---|---|---|
subscribeTopics | Subscribes, and receives commands | Publishes commands |
publishTopics | Publishes responses, events, connection state, or tag data | Subscribes |
Topic Slots
The reader decides what to publish on each topic by the topic's position in publishTopics, not by its name. Names such as resp, event, and rfid are conventions only.
| Slot | Carries |
|---|---|
subscribeTopics[0] | Commands to the reader. It is the only topic the reader receives on. |
publishTopics[0] | Command responses |
publishTopics[1] | Events such as heartBeatEVT and alerts. On a data endpoint, tag data instead. |
publishTopics[2] | mqttConnEVT, and the Last Will that the broker publishes |
What to configure depends on the endpoint type:
epType | subscribeTopics[0] | publishTopics[0] | publishTopics[1] | publishTopics[2] |
|---|---|---|---|---|
MGMT, MDM | Required: commands | Required: responses | Recommended: events | Recommended: mqttConnEVT and Last Will |
CTRL | Required: control commands | Required: control responses | Optional: stored, but not used for events | Optional: mqttConnEVT and Last Will |
MGMT_EVT | Required: events are published on this topic | Not used | Not used | Optional: Last Will |
DATA1 | Not used | Not used for tag data | Required: tag data | Optional: Last Will |
A slot marked Not used can still be sent and is stored, but it carries nothing for that endpoint type. DATA2 is currently not supported, so DATA1 is the only data endpoint type.
MGMT_EVTA MGMT_EVT endpoint currently publishes its events on its subscribe topic, not on publishTopics[1]. The contract records this as a firmware defect that the API owners intend to correct. Confirm the behavior on the firmware you target before you depend on it.
Rules for the Arrays
- Position routes traffic. Swapping two entries sends live traffic to different topics, and the configuration stays valid.
- The array is read from index 0. You can't configure only
publishTopics[1]. To reach slot 1, send an entry in slot 0 as well. - Data endpoints need two entries. A data endpoint with a single
publishTopicsentry puts it in the response slot: the endpoint is created, the command succeeds, and no tag data arrives. Use a filler entry in slot 0, as in the data endpoint example. - Read-backs are positional too.
get_endpoint_configreturns the entries in slot order. A read-back with fewer than three entries does not say which slots are unused.
Default Topics
The reader firmware's default endpoint configurations use these base topics. They show the conventional layout for each endpoint type; a dash means the slot is empty by default.
| Default endpoint | subscribeTopics[0] | publishTopics[0] | publishTopics[1] | publishTopics[2] (Last Will) |
|---|---|---|---|---|
MGMT_EP | MGMT/clients/cmnd | MGMT/clients/resp | — | MGMT/clients/rfid |
MDM_EP | MDM/clients/cmnd | MDM/clients/resp | MDM/clients/event | MDM/clients/rfid |
CTRL_EP | CTRL/clients/cmnd | CTRL/clients/resp | CTRL/clients/event | CTRL/clients/rfid |
DATA1_EP | — | — | DATA/clients/data1event | — |
DATA2_EP | — | — | DATA/clients/data2event | — |
MGMT_EVT | — | — | — | MGMTEVT/clients/event |
In the defaults, every topic uses QoS 0 and only the Last Will topic is retained. The two default data endpoints batch tag data with a reportingInterval of 1000 ms and a maxPayloadSizePerReport of 1024 bytes. DATA2 is currently not supported.
Conventional Base Topics
The contract's topic addresses follow the pattern <endpoint base>/clients/<token>. They are a convention, not a requirement: you can choose your own base topics.
| Token | Slot | Direction |
|---|---|---|
cmnd | subscribeTopics[0] | Application → reader |
resp | publishTopics[0] | Reader → application |
event | publishTopics[1] | Reader → application |
rfid | publishTopics[2]; also tag data when inventory output goes to a management or control endpoint | Reader → application |
data1event | publishTopics[1] on a DATA1 endpoint, under the base DATA. (data2event belongs to DATA2, which is currently not supported.) | Reader → application |
The endpoint bases in the contract's topic addresses are MGMT, MGMT_EVT, CTRL, MDM, and DATA. The reference test device used MDM as its management base rather than MGMT.
Worked Example
This config_endpoint request adds a management endpoint with the tenant ZEBRA and the conventional management topics.
On the reader RFD40-211545201D0034, the endpoint uses these topics:
| Traffic | Slot | Topic | Your application |
|---|---|---|---|
| Commands | subscribeTopics[0] | ZEBRA/MGMT/clients/cmnd/RFD40-211545201D0034 | Publishes |
| Responses | publishTopics[0] | ZEBRA/MGMT/clients/resp/RFD40-211545201D0034 | Subscribes |
| Events | publishTopics[1] | ZEBRA/MGMT/clients/event/RFD40-211545201D0034 | Subscribes |
mqttConnEVT and Last Will | publishTopics[2] | ZEBRA/MGMT/clients/rfid/RFD40-211545201D0034 | Subscribes |
To receive responses from every reader in the tenant, subscribe to ZEBRA/MGMT/clients/resp/+.
Data Endpoint Example
A DATA1 endpoint puts a filler entry in slot 0 so that the tag-data topic lands in slot 1. Every DATA1 example in the contract uses this publishTopics array. The filler topic needs no delivery guarantee.
With the tenant ZEBRA, tag data then arrives on ZEBRA/DATA/clients/data1event/RFD40-211545201D0034. DATA2 is currently not supported.
Topic Limits
| Limit | Value | If exceeded |
|---|---|---|
| Publish topics per endpoint | 3 | config_endpoint returns code 25 |
| Subscribe topics per endpoint | 1 | config_endpoint returns code 26. Some published read-backs report three subscribe topics, so don't reject a read-back that has more than one. |
tenantId length | 48 characters | config_endpoint returns code 27 |
| Topic length | At least 1 character; at most 65,535 bytes when UTF-8 encoded | Not specified in the available sources |
| Wildcards | + and # are not allowed in publish topics. Subscribe topic filters may use them. | Not specified in the available sources |
Not Specified
- The topic the reader uses when
tenantIdis empty. - Whether an endpoint accepts commands that belong to another endpoint type, for example a control command on a
MGMTendpoint.
Related: 📕 Broker Connection · 📕 Message Envelopes and Correlation · 📕 config_endpoint · 📕 MQTT Endpoints · 📕 Endpoints and Topic Slots