Client type

TBMQ classifies every connecting client as either DEVICE or APPLICATION. This distinction drives message routing, persistence strategy, and resource allocation — ensuring each client type gets the behavior best suited to its role in an IoT deployment.

• DEVICE clients primarily publish data and subscribe to a limited number of topics with moderate traffic. They represent IoT sensors, actuators, and embedded devices that send telemetry to the broker.

• APPLICATION clients subscribe to high-rate topics and are expected to process every message reliably, even after an offline period. They represent analytics services, rule engines, or backend processors that consume data from the broker.

For example, a temperature sensor publishing readings every second is a DEVICE client, while a cloud analytics service subscribing to data from thousands of sensors is an APPLICATION client.

TBMQ resolves the client type during MQTT CONNECT packet processing, based on the credentials used:

• When authentication is disabled, every client is assigned the DEVICE type.
• When Basic or X.509 Certificate Chain authentication is enabled, TBMQ reads the client type from the clientType field of the matched MQTT credential.

For details on client authentication, see the Security overview. For instructions on creating credentials with a specific client type, see the MQTT client credentials guide.

All published messages are written to the tbmq.msg.all Kafka topic. How messages are forwarded from there depends on the client type and whether the client uses a persistent session.

A Kafka consumer polls the tbmq.msg.all topic and forwards messages to their subscribers:

• Non-persistent clients — messages are delivered directly to the connected client. No state is retained. See Non-persistent client in the architecture overview.
• Persistent clients — the session survives disconnections. Messages published while the client is offline are stored and delivered on reconnect. The handling differs by client type (see sections below). See Persistent client in the architecture overview.

There is one exception: if a persistent subscriber uses QoS 0, or if the publisher sends at QoS 0, messages are delivered without additional persistence steps. This is a result of QoS downgrading.

DEVICE clients can be persistent or non-persistent, depending on the CONNECT packet settings.

For persistent DEVICE clients, matching messages are forwarded to the tbmq.msg.persisted Kafka topic. A dedicated Kafka consumer reads this topic and persists the messages in Redis before delivering them to online subscribers. When an offline DEVICE client reconnects, it receives the messages stored in Redis.

The maximum number of persisted messages delivered on reconnect is controlled by:

MQTT_PERSISTENT_SESSION_DEVICE_PERSISTED_MESSAGES_LIMIT

If an APPLICATION client connects with a non-persistent session, messages are still delivered while connected, but no persistence mechanism is applied — messages can be lost if the client disconnects.

TBMQ displays a warning on the session details page when it detects this configuration:

For persistent APPLICATION clients, TBMQ creates a dedicated Kafka topic per client:

tbmq.msg.app.$CLIENT_ID

TBMQ creates this topic automatically when the client authenticates as APPLICATION type with a persistent session. A dedicated Kafka consumer per client polls this topic and delivers messages to the client in its own thread, providing isolated, high-throughput delivery.

Client IDs with special characters — if the client ID contains characters outside the alphanumeric range, a hash of the client ID is used instead:

tbmq.msg.app.$CLIENT_ID_HASH

This behavior is controlled by the TB_APP_PERSISTED_MSG_CLIENT_ID_VALIDATION environment variable (enabled by default). Disabling it means Kafka topics will not be created for clients with special characters in their ID.