{"id":109,"date":"2018-07-11T22:56:15","date_gmt":"2018-07-11T22:56:15","guid":{"rendered":"https:\/\/dev.foxtrackr.com\/?p=109"},"modified":"2019-09-15T19:39:15","modified_gmt":"2019-09-15T19:39:15","slug":"use-of-mqtt-to-receive-foxtrackr-data","status":"publish","type":"post","link":"https:\/\/dev.foxtrackr.com\/?p=109","title":{"rendered":"Use of MQTT to receive foxtrackr data"},"content":{"rendered":"<p>This post details how to connect your MQTT client on our MQTT infrastructure.<\/p>\n<p><!--more--><\/p>\n<h2>Connect to MQTT broker<\/h2>\n<p>MQTT is a protocol of communication dedicate to\u00a0 IoT. This protocol is managing non formatted message communication over the web. MQTT is an asynchronous communication solution managing Quality of Service.<\/p>\n<p>It is composed of clients (publishing and subscribing to topics) and a server (broker) used for routing and storing the messages during delivery.<\/p>\n<p>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.<\/p>\n<p>MQTT provides different protocol to connect with:<\/p>\n<ul>\n<li>MQTT standard protocol<\/li>\n<li>MQTT SSL protocol<\/li>\n<li>MQTT websocket protocol<\/li>\n<li>MQTT SSL websocket protocol<\/li>\n<\/ul>\n<p>We are actually supporting MQTT standard and SLL protocol for the communications.<\/p>\n<p>All the protocol are secured by login\/password authentification and right access control on the topics.<\/p>\n<p>A large list of MQTT client can be found on <a href=\"https:\/\/github.com\/mqtt\/mqtt.github.io\/wiki\/libraries\">MQTT.org website<\/a>.<\/p>\n<h3>MQTT Protocol<\/h3>\n<p>The MQTT Protocol is secured by login mechanism but transfert the informations in clear over the network. The configuration is the following:<\/p>\n<pre>Host : mqtt.foxtrackr.com\nPort : 1883\nID : id-*<\/pre>\n<p>You can test your connection with the standard mosquitto (open source implementation of MQTT) client:<\/p>\n<pre class=\"p1\"><span class=\"s1\">mosquitto_sub -h mqtt.foxtrackr.com<span class=\"Apple-converted-space\">\u00a0\\\n              -p 1883\n              <\/span>-t 'foxtrackr\/#' \\\n              -i <strong>id-<\/strong>given<strong>-nn<\/strong> \\\n              -c -q 2 \\\n              -u userName -P 'userPassword'<\/span><\/pre>\n<p>Here we have a specific option &#8220;-c&#8221; this option is for &#8220;&#8211;disable-clean-session&#8221; 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)<\/p>\n<p>The &#8220;-i&#8221; option allows to set a client id. This one is used for creating the persistent queue for this topic. it have to start by <strong>id-\u00a0<\/strong>then you need to use the given id (provided by us) and it is followed by <strong>-nn<\/strong>\u00a0This is an incremental number for each of your different clients.<\/p>\n<h3>MQTT SSL Protocol<\/h3>\n<p>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.<\/p>\n<p>Our certificates comes from Let&#8217;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.<\/p>\n<p>The client configuration is the following:<\/p>\n<pre>Host : mqtt.foxtrackr.com \nPort : 8883 \nID : id-*\nCA File : DST_Root_CA_X3.pem<\/pre>\n<p>You can test your connection<\/p>\n<p>with the standard mosquitto (open source implementation of MQTT) client:<\/p>\n<pre class=\"p1\"><span class=\"s1\">mosquitto_sub -h mqtt.foxtrackr.com<span class=\"Apple-converted-space\">\u00a0\\\n              -p 8883\n              --cafile \/etc\/ssl\/certs\/ca-bundle.trust.crt\n              <\/span>-t 'foxtrackr\/#' \\\n              -i <strong>id-<\/strong>given<strong>-nn<\/strong> \\\n              -c -q 2 \\\n              -u userName -P 'userPassword'<\/span><\/pre>\n<p>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\u00a0\u00a0DST_Root_CA_X3.pem certificate you can find <a href=\"https:\/\/www.identrust.com\/certificates\/trustid\/root-download-x3.html\" target=\"_blank\" rel=\"noopener noreferrer\">here<\/a>. The content is the following:<\/p>\n<pre><span class=\"s1\">-----BEGIN CERTIFICATE----- \n<\/span><span class=\"s1\">MIIDSjCCAjKgAwIBAgIQRK+wgNajJ7qJMDmGLvhAazANBgkqhkiG9w0BAQUFADA\/\nMSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT\nDkRTVCBSb290IENBIFgzMB4XDTAwMDkzMDIxMTIxOVoXDTIxMDkzMDE0MDExNVow\nPzEkMCIGA1UEChMbRGlnaXRhbCBTaWduYXR1cmUgVHJ1c3QgQ28uMRcwFQYDVQQD\nEw5EU1QgUm9vdCBDQSBYMzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB\nAN+v6ZdQCINXtMxiZfaQguzH0yxrMMpb7NnDfcdAwRgUi+DoM3ZJKuM\/IUmTrE4O\nrz5Iy2Xu\/NMhD2XSKtkyj4zl93ewEnu1lcCJo6m67XMuegwGMoOifooUMM0RoOEq\nOLl5CjH9UL2AZd+3UWODyOKIYepLYYHsUmu5ouJLGiifSKOeDNoJjj4XLh7dIN9b\nxiqKqy69cK3FCxolkHRyxXtqqzTWMIn\/5WgTe1QLyNau7Fqckh49ZLOMxt+\/yUFw\n7BZy1SbsOFU5Q9D8\/RhcQPGX69Wam40dutolucbY38EVAjqr2m7xPi71XAicPNaD\naeQQmxkqtilX4+U9m5\/wAl0CAwEAAaNCMEAwDwYDVR0TAQH\/BAUwAwEB\/zAOBgNV\nHQ8BAf8EBAMCAQYwHQYDVR0OBBYEFMSnsaR7LHH62+FLkHX\/xBVghYkQMA0GCSqG\nSIb3DQEBBQUAA4IBAQCjGiybFwBcqR7uKGY3Or+Dxz9LwwmglSBd49lZRNI+DT69\nikugdB\/OEIKcdBodfpga3csTS7MgROSR6cz8faXbauX+5v3gTt23ADq1cEmv8uXr\nAvHRAosZy5Q6XkjEGB5YGV8eAlrwDPGxrancWYaLbumR9YbK+rlmM6pZW87ipxZz\nR8srzJmwN0jP41ZL9c8PDHIyh8bwRLtTcm1D9SZImlJnt1ir\/md2cXjbDaJWFBM5\nJDGFoqgCWjBH4d1QB7wCCZAA62RjYJsWvIjJEubSfZGL+T0yjWW06XyxV3bqxbYo\nOb8VZRzI9neWagqNdwvYkQsEjgfbKbYK7p2CNTUQ\n-----END CERTIFICATE-----<\/span><\/pre>\n<h2>Topics organisation<\/h2>\n<p>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:<\/p>\n<pre>device-familly \/\n       device-id \/\n          version \/\n             type-of-data<\/pre>\n<ul>\n<li>The device-familly is &#8220;foxtrackr&#8221;<\/li>\n<li>Version is currently V3.0<\/li>\n<\/ul>\n<p>An exemple of topic is:<\/p>\n<pre>foxtrackr\/12345\/V3.0\/bat<\/pre>\n<p>For battery messages for devices 12345<\/p>\n<p>It&#8217;s also possible to access a Group of devices by its group name<\/p>\n<pre>foxtrackr\/<span style=\"color: #ff00ff;\">my_group_name<\/span>\/V3.0\/bat<\/pre>\n<p>We usually use joker to access the topic hierarchy:<\/p>\n<pre>foxtrackr\/#              \/\/ All messages\nfoxtrackr\/+\/V3.0\/bat     \/\/ All battery messages<\/pre>\n<p>The list of type of data is described above.<\/p>\n<h2>Message format &amp; topic list<\/h2>\n<p>Any message have a common structure and is json formated:<\/p>\n<pre>{\n  messageType = nn,         \/\/ type of message contains\n  deviceId = \"device-id\",   \/\/ the device id\n  version = nn,             \/\/ message format version (3)\n  timeMs = nn,              \/\/ Message Time in ms since Epoc UTC \n  ...\n}<\/pre>\n<table style=\"border-collapse: collapse; width: 100%;\" border=\"1\">\n<tbody>\n<tr style=\"height: 25px;\">\n<td style=\"width: 31.8966%; height: 25px;\">Topic<\/td>\n<td style=\"width: 68.1034%; height: 25px;\">Message format<\/td>\n<\/tr>\n<tr style=\"height: 254px;\">\n<td style=\"width: 31.8966%; height: 254px;\">foxtrackr\/+\/V3.0\/bat<\/td>\n<td style=\"width: 68.1034%; height: 254px;\">\n<pre>{\n  ...\n  battery : {\n   \/\/ see https:\/\/dev.foxtrackr.com\/swagger-api-foxtrackr\/\n   \/\/ FoxtrackPushMessage for details\n  }\n}<\/pre>\n<\/td>\n<\/tr>\n<tr style=\"height: 254px;\">\n<td style=\"width: 31.8966%; height: 254px;\">foxtrackr\/+\/V3.0\/temp<\/td>\n<td style=\"width: 68.1034%; height: 254px;\">\n<pre>{\n   ...\n   temperature : {\n      \/\/ see https:\/\/dev.foxtrackr.com\/swagger-api-foxtrackr\/\n      \/\/ FoxtrackPushMessage for details\n   }\n}<\/pre>\n<\/td>\n<\/tr>\n<tr style=\"height: 25px;\">\n<td style=\"width: 31.8966%; height: 25px;\">&#8230;<\/td>\n<td style=\"width: 68.1034%; height: 25px;\"><\/td>\n<\/tr>\n<tr style=\"height: 25px;\">\n<td style=\"width: 31.8966%; height: 25px;\"><\/td>\n<td style=\"width: 68.1034%; height: 25px;\"><\/td>\n<\/tr>\n<tr style=\"height: 25px;\">\n<td style=\"width: 31.8966%; height: 25px;\"><\/td>\n<td style=\"width: 68.1034%; height: 25px;\"><\/td>\n<\/tr>\n<tr style=\"height: 25px;\">\n<td style=\"width: 31.8966%; height: 25px;\"><\/td>\n<td style=\"width: 68.1034%; height: 25px;\"><\/td>\n<\/tr>\n<tr style=\"height: 25px;\">\n<td style=\"width: 31.8966%; height: 25px;\"><\/td>\n<td style=\"width: 68.1034%; height: 25px;\"><\/td>\n<\/tr>\n<tr style=\"height: 25px;\">\n<td style=\"width: 31.8966%; height: 25px;\"><\/td>\n<td style=\"width: 68.1034%; height: 25px;\"><\/td>\n<\/tr>\n<tr style=\"height: 25px;\">\n<td style=\"width: 31.8966%; height: 25px;\"><\/td>\n<td style=\"width: 68.1034%; height: 25px;\"><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n","protected":false},"excerpt":{"rendered":"<p>This post details how to connect your MQTT client on our MQTT infrastructure.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2}},"categories":[1],"tags":[],"class_list":["post-109","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/p9HKNr-1L","jetpack_likes_enabled":true,"jetpack-related-posts":[],"_links":{"self":[{"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=\/wp\/v2\/posts\/109","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=109"}],"version-history":[{"count":5,"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=\/wp\/v2\/posts\/109\/revisions"}],"predecessor-version":[{"id":132,"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=\/wp\/v2\/posts\/109\/revisions\/132"}],"wp:attachment":[{"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=109"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=109"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.foxtrackr.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=109"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}