Use of MQTT to receive foxtrackr data

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
   }
}

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.