This post details how to connect your MQTT client on our MQTT infrastructure.
Connect to MQTT broker
MQTT is a protocol of communication dedicate to IoT. This protocol is managing non formatted message communication over the web. MQTT is an asynchronous communication solution managing Quality of Service.
It is composed of clients (publishing and subscribing to topics) and a server (broker) used for routing and storing the messages during delivery.
The messages are relayed on topics. Topics are a kind of mailbox you can subscribes to to be immediately alerted on reception of new messages. Topics are a hierarchy allowing to subscribes to detailed or aggregated level.
MQTT provides different protocol to connect with:
- MQTT standard protocol
- MQTT SSL protocol
- MQTT websocket protocol
- MQTT SSL websocket protocol
We are actually supporting MQTT standard and SLL protocol for the communications.
All the protocol are secured by login/password authentification and right access control on the topics.
A large list of MQTT client can be found on MQTT.org website.
MQTT Protocol
The MQTT Protocol is secured by login mechanism but transfert the informations in clear over the network. The configuration is the following:
Host : mqtt.foxtrackr.com Port : 1883 ID : id-*
You can test your connection with the standard mosquitto (open source implementation of MQTT) client:
mosquitto_sub -h mqtt.foxtrackr.com \
-p 1883
-t 'foxtrackr/#' \
-i id-given-nn \
-c -q 2 \
-u userName -P 'userPassword'
Here we have a specific option “-c” this option is for “–disable-clean-session” basically this means the messages will be kept stored in the topic if the session has been broken. This is important to receive (once reconnected) messages transmitted during a period where your server receiving the data has been disconnected. (The topics are automatically cleared after 7days)
The “-i” option allows to set a client id. This one is used for creating the persistent queue for this topic. it have to start by id- then you need to use the given id (provided by us) and it is followed by -nn This is an incremental number for each of your different clients.
MQTT SSL Protocol
To secure your communication and protect your data privacy we are implementing SSL communication. To configure your client you need to specify a CA Authority.
Our certificates comes from Let’s Encrypt and the CA to be used should be part of your standard CA bundle. Eventually you can find a CA to be used below.
The client configuration is the following:
Host : mqtt.foxtrackr.com Port : 8883 ID : id-* CA File : DST_Root_CA_X3.pem
You can test your connection
with the standard mosquitto (open source implementation of MQTT) client:
mosquitto_sub -h mqtt.foxtrackr.com \
-p 8883
--cafile /etc/ssl/certs/ca-bundle.trust.crt
-t 'foxtrackr/#' \
-i id-given-nn \
-c -q 2 \
-u userName -P 'userPassword'
Please take a look to the MQTT Protocol paragraph to get details on common options. Here we have specified a cafile, it can be a bundle of CA certificate like in this case or it can be the DST_Root_CA_X3.pem certificate you can find here. The content is the following:
-----BEGIN CERTIFICATE----- MIIDSjCCAjKgAwIBAgIQRK+wgNajJ7qJMDmGLvhAazANBgkqhkiG9w0BAQUFADA/ MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT DkRTVCBSb290IENBIFgzMB4XDTAwMDkzMDIxMTIxOVoXDTIxMDkzMDE0MDExNVow PzEkMCIGA1UEChMbRGlnaXRhbCBTaWduYXR1cmUgVHJ1c3QgQ28uMRcwFQYDVQQD Ew5EU1QgUm9vdCBDQSBYMzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB AN+v6ZdQCINXtMxiZfaQguzH0yxrMMpb7NnDfcdAwRgUi+DoM3ZJKuM/IUmTrE4O rz5Iy2Xu/NMhD2XSKtkyj4zl93ewEnu1lcCJo6m67XMuegwGMoOifooUMM0RoOEq OLl5CjH9UL2AZd+3UWODyOKIYepLYYHsUmu5ouJLGiifSKOeDNoJjj4XLh7dIN9b xiqKqy69cK3FCxolkHRyxXtqqzTWMIn/5WgTe1QLyNau7Fqckh49ZLOMxt+/yUFw 7BZy1SbsOFU5Q9D8/RhcQPGX69Wam40dutolucbY38EVAjqr2m7xPi71XAicPNaD aeQQmxkqtilX4+U9m5/wAl0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNV HQ8BAf8EBAMCAQYwHQYDVR0OBBYEFMSnsaR7LHH62+FLkHX/xBVghYkQMA0GCSqG SIb3DQEBBQUAA4IBAQCjGiybFwBcqR7uKGY3Or+Dxz9LwwmglSBd49lZRNI+DT69 ikugdB/OEIKcdBodfpga3csTS7MgROSR6cz8faXbauX+5v3gTt23ADq1cEmv8uXr AvHRAosZy5Q6XkjEGB5YGV8eAlrwDPGxrancWYaLbumR9YbK+rlmM6pZW87ipxZz R8srzJmwN0jP41ZL9c8PDHIyh8bwRLtTcm1D9SZImlJnt1ir/md2cXjbDaJWFBM5 JDGFoqgCWjBH4d1QB7wCCZAA62RjYJsWvIjJEubSfZGL+T0yjWW06XyxV3bqxbYo Ob8VZRzI9neWagqNdwvYkQsEjgfbKbYK7p2CNTUQ -----END CERTIFICATE-----
Topics organisation
The messages are sent over topics your client can subscribe to. Topic are storing messages until they are pulled by client. The Topic organization is a hierarchy following the structure:
device-familly / device-id / version / type-of-data
- The device-familly is “foxtrackr”
- Version is currently V3.0
An exemple of topic is:
foxtrackr/12345/V3.0/bat
For battery messages for devices 12345
It’s also possible to access a Group of devices by its group name
foxtrackr/my_group_name/V3.0/bat
We usually use joker to access the topic hierarchy:
foxtrackr/# // All messages foxtrackr/+/V3.0/bat // All battery messages
The list of type of data is described above.
Message format & topic list
Any message have a common structure and is json formated:
{ messageType = nn, // type of message contains deviceId = "device-id", // the device id version = nn, // message format version (3) timeMs = nn, // Message Time in ms since Epoc UTC ... }
Topic | Message format |
foxtrackr/+/V3.0/bat |
{ ... battery : { // see https://dev.foxtrackr.com/swagger-api-foxtrackr/ // FoxtrackPushMessage for details } } |
foxtrackr/+/V3.0/temp |
{ ... temperature : { // see https://dev.foxtrackr.com/swagger-api-foxtrackr/ // FoxtrackPushMessage for details } } |
… | |