Introduction
When using the MQTT API with Cumulocity IoT, it’s important to understand how connection termination works. There are several circumstances in which Cumulocity IoT will notify a device of connection termination. Let us explain these circumstances and show you how to handle them.
This solution works for Cumulocity versions newer than 10.5
Inactive connections
If a device does not send messages within a defined keep-alive interval, Cumulocity IoT will consider the connection to be inactive and may terminate it. To avoid this, devices should send messages or heartbeats at regular intervals to keep the connection active. In most cases, the MQTT client will handle this automatically.
To handle inactive connections, you can implement a heartbeat mechanism in the code of the device. This will ensure that messages are sent at regular intervals to keep the connection active. The exact interval will depend on the specific use case, but it’s typically recommended to send heartbeats at least once per minute.
Rate limiting
If a tenant has defined a rate limit, Cumulocity IoT may disconnect a device if the limit is exceeded. This is to give the platform time to process messages and prevent overload. If a device reconnects but the rate limit is still exceeded, it will be disconnected again after the first message.
To deal with rate limiting, a good idea is to implement a backoff mechanism in your device’s code. The device will wait for a certain amount of time before reconnecting if rate limiting is the reason for the disconnect. The exact time will vary, depending on the specific use case and the rate limit set by the tenant.
Component restarts
In the communication between the platform and the device, there may be many components involved. If any of these components are shut down, Cumulocity IoT needs to terminate all connections explicitly. This includes any proxy, load balancer, and Core node itself. As most MQTT connections are IP hashed, the connection is targeted to a single Core node.
Implementing a reconnection mechanism in your device’s code is a great way to deal with component restarts. The device will automatically attempt to reconnect if it has been disconnected due to a component restart. The MQTT client should handle this automatically, but you should test the reconnection mechanism just to be sure that it works as expected.
Connection stealing
If two devices are trying to connect to the same tenant with the same MQTT client ID, they may start to steal each other’s connections. Cumulocity IoT will detect this and disconnect one of the devices to prevent further issues.
In order to prevent connection theft, you can implement a solution where every device is assigned a distinct MQTT client ID. This can be achieved by generating a unique identifier using the device’s MAC address or other identifiable details.