{"id":42,"date":"2017-04-04T17:47:46","date_gmt":"2017-04-04T06:47:46","guid":{"rendered":"http:\/\/bakke.online\/?p=42"},"modified":"2017-04-04T17:47:46","modified_gmt":"2017-04-04T06:47:46","slug":"adding-persisted-messages-to-adafruits-mqtt-library","status":"publish","type":"post","link":"https:\/\/www.bakke.online\/index.php\/2017\/04\/04\/adding-persisted-messages-to-adafruits-mqtt-library\/","title":{"rendered":"Adding retained messages to Adafruit's MQTT library"},"content":{"rendered":"

\"\"<\/p>\n

Recently, when building a weather station based on Adafruit’s Huzzah ESP8266<\/a> breakout board, I needed the ability to send messages that should be retained on the MQTT server.<\/p>\n

I am using mosquitto<\/a> on my home server, acting as a message broker. \u00a0My weather stations send messages to it and these are then forwarded to the subscribers who have signed up for them. \u00a0At the moment, these subscribers are a weather logging system, a current weather display panel on the different computers at home, and, occasionally, a command-line client used for troubleshooting.<\/p>\n

As the weather stations are battery powered, they will not run always on, always connected, but they wake up every few minutes, check the weather, and transmit the results to the MQTT server before they go to sleep again.<\/p>\n

Any subscribers will receive these messages as soon as they are sent. \u00a0However, when a subscriber starts running and connects to the MQTT server, it will not receive any messages until the relevant weather station sends one. \u00a0By default, there’s no concept of the most recent values. \u00a0This is kind of inconvenient for the weather panel application on the computers, as they will not show any values until the next time the weather station wakes up. \u00a0Depending on the battery levels and configuration, that could be quite a while…<\/p>\n

To do that, MQTT supports retained messages. \u00a0These are messages that have a special flag set which tells the server they can be retained. \u00a0A subscriber that connects will then get the most recent retained message as soon as the connection has been established, and then receive updates whenever the weather station sends them through.<\/p>\n

Adafruit’s MQTT library makes the MQTT communication bit incredibly easy, but unfortunately it does not support retained messages out of the box as of the time of writing. \u00a0There are a number of pull-requests for this feature on their github page, so it is possible this situation will change. \u00a0For the same reason, I have not requested a pull of my changes.<\/p>\n

I decided to add this feature to a forked version of their library, mainly as an exercise and also to learn the inner workings of the library better. \u00a0MQTT is an open standard and the documentation for the protocol can be found on the OASIS <\/a>server.<\/p>\n

My forked version can be found on github, at\u00a0https:\/\/github.com\/erikbakke\/Adafruit_MQTT_Library<\/a>.<\/p>\n

In Adafruit_MQTT.h<\/h3>\n

Let’s start with the class declarations in the header file Adafruit_MQTT.h. \u00a0In the Adafruit_MQTT class there are two main publish methods, one which takes a string payload, and one which takes a pointer to binary data as well as the length of the binary data buffer. \u00a0I added a new uint8_t parameter to control whether the published message should be retained:<\/p>\n

bool<\/span> publish<\/span>(const<\/span> char<\/span> *topic, const<\/span> char<\/span> *payload, uint8_t<\/span> qos = 0<\/span>, <\/span>uint8_t<\/span> retain = <\/span>0<\/span><\/span>);\nbool<\/span> publish<\/span>(const<\/span> char<\/span> *topic, uint8_t<\/span> *payload, uint16_t<\/span> bLen, uint8_t<\/span> qos = 0<\/span>, <\/span>uint8_t<\/span> retain = <\/span>0<\/span><\/span>);<\/pre>\n
These methods build the actual MQTT packet data and then pass this to publishPacket(), which is where the control header fields get added and the packet sent to the server. \u00a0As the retain flag is in one of these header fields, I also needed to add the flag as a parameter here.<\/p>\n
uint16_t<\/span> publishPacket<\/span>(uint8_t<\/span> *packet, const<\/span> char<\/span> *topic, uint8_t<\/span> *payload, uint16_t<\/span> bLen, uint8_t<\/span> qos, <\/span>uint8_t<\/span> retain<\/span><\/span>);<\/pre>\n
In the Adafruit_MQTT_Publish class, the retain parameter is added to the constructor class, so the behaviour can be controlled per\u00a0feed.<\/p>\n
Adafruit_MQTT_Publish<\/span>(Adafruit_MQTT *mqttserver, const<\/span> char<\/span> *feed, uint8_t<\/span> qos = 0<\/span>, <\/span>uint8_t<\/span> retain = <\/span>0<\/span><\/span>);<\/pre>\n
This needs to be backed by a member variable, which I added to the bottom of the class declaration.<\/p>\n
uint8_t<\/span> retain;<\/span><\/pre>\n
That’s it for the class declarations\u00a0so let’s move on to the definitions, which are found in the Adafruit_MQTT.cpp file.<\/p>\n
In Adafruit_MQTT.cpp<\/h3>\n
In Adafruit_MQTT, the const char* based publish() method is modified to take the retain parameter and pass it on to the binary buffer based method.<\/p>\n
bool<\/span> Adafruit_MQTT::publish<\/span>(const<\/span> char<\/span> *topic, const<\/span> char<\/span> *data, uint8_t<\/span> qos, <\/span>uint8_t<\/span> retain<\/span><\/span>) {\n\n\u00a0 \u00a0 return<\/span> publish<\/span>(topic, (uint8_t<\/span>*)(data), strlen<\/span>(data), qos, retain<\/span>);\n}<\/pre>\n
That constructor is also modified to take the additional parameter and\u00a0pass it to the publishPacket() method.<\/p>\n
bool<\/span> Adafruit_MQTT::publish<\/span>(const<\/span> char<\/span> *topic, uint8_t<\/span> *data, uint16_t<\/span> bLen, uint8_t<\/span> qos, <\/span>uint8_t<\/span> retain<\/span><\/span>) {\n \u00a0 \u00a0 uint16_t<\/span> len = publishPacket<\/span>(buffer, topic, data, bLen, qos, retain<\/span>);\n\n\u00a0 \u00a0 if<\/span> (!sendPacket<\/span>(buffer, len))\n\u00a0 \u00a0 \u00a0 \u00a0 return<\/span> false<\/span>;\n...<\/pre>\n
publishPacket(), in turn, takes that parameter…<\/p>\n
uint16_t<\/span> Adafruit_MQTT::publishPacket<\/span>(uint8_t<\/span> *packet, const<\/span> char<\/span> *topic,\n                                      uint8_t<\/span> *data, uint16_t<\/span> bLen, uint8_t<\/span> qos, <\/span>uint8_t<\/span> retain<\/span><\/span>) {<\/pre>\n
…and puts it into the header field.<\/p>\n
\/\/<\/span> Now you can start generating the packet!\np[0<\/span>] = MQTT_CTRL_PUBLISH << 4<\/span> | qos << 1<\/span> | retain<\/span>;\np++;<\/pre>\n
In the Adafruit_MQTT_Publish class, the constructor has been modified to take the new retain parameter and stuff it into a member variable.<\/p>\n
Adafruit_MQTT_Publish::Adafruit_MQTT_Publish<\/span>(Adafruit_MQTT *mqttserver,\nconst<\/span> char<\/span> *feed, uint8_t<\/span> q, <\/span>uint8_t<\/span> r<\/span><\/span>) {\n    mqtt = mqttserver;\n    topic = feed;\n    qos = q;\n    retain = r;<\/span>\n}<\/pre>\n
Next, each of the publish() methods are modified to pass the retain flag to mqtt->publish().<\/p>\n
return<\/span> mqtt->publish<\/span>(topic, payload, qos, retain<\/span>);<\/pre>\n
Or a more detailed example, which has been adapted from one of Adafruit’s MQTT library examples:<\/p>\n
void<\/span> MQTT_uploadToServer( float<\/span> temp, float<\/span> humidity, float<\/span> voltage )\n{\n  WiFiClient<\/span> client;\n  float<\/span> temp = -500; \/\/ Use this as a flag, as -500 degrees is physically impossible, it is below absolute zero<\/span>\n  int8_t<\/span> ret;\n\n  Adafruit_MQTT_Client<\/strong><\/span> mqtt( &client, MQTT_SERVER, MQTT_SERVERPORT, MQTT_USERNAME, MQTT_PASSWD );\n  Adafruit_MQTT_Publish<\/strong><\/span> publish_temp = Adafruit_MQTT_Publish<\/strong><\/span>( &mqtt, MQTT_USERNAME \"\/feeds\/<\/span>\" MQTT_NAME \"\/temp<\/span>\", MQTT_QOS_0, 1 );\n  Adafruit_MQTT_Publish<\/strong><\/span> publish_humidity = Adafruit_MQTT_Publish<\/strong><\/span>( &mqtt, MQTT_USERNAME \"\/feeds\/<\/span>\" MQTT_NAME \"\/humidity<\/span>\", MQTT_QOS_0, 1 );\n  Adafruit_MQTT_Publish<\/strong><\/span> publish_voltage = Adafruit_MQTT_Publish<\/strong><\/span>( &mqtt, MQTT_USERNAME \"\/feeds\/<\/span>\" MQTT_NAME \"\/voltage<\/span>\", MQTT_QOS_0, 1 );\n\n  Serial<\/strong><\/span>.print<\/span>(\"Connecting to MQTT...<\/span> \");\n\n  uint8_t<\/span> retries = 3;\n  while<\/span> ((ret = mqtt.connect<\/span>()) != 0) { \/\/ connect will return 0 for connected<\/span>\n    Serial<\/strong><\/span>.println<\/span>(mqtt.connectErrorString<\/span>(ret));\n    Serial<\/strong><\/span>.println<\/span>(\"Retrying MQTT connection in 5 seconds...<\/span>\");\n    mqtt.disconnect<\/span>();\n    delay<\/span>(5000); \/\/ wait 5 seconds<\/span>\n    retries--;\n    if<\/span> (retries == 0) {\n      \/\/ basically die and wait for WDT to reset me<\/span>\n      while<\/span> (1);\n    }\n  }\n  Serial<\/strong><\/span>.println<\/span>(\"MQTT Connected!<\/span>\");\n\n  if<\/span>( !isnan( temp ) )\n  {\n    publish_temp.publish<\/span>( temp );\n  }\n  if<\/span>( !isnan( humidity ) )\n  {\n    publish_humidity.publish<\/span>( humidity );\n  }\n  if<\/span>( !isnan( voltage ) )\n  {\n    publish_voltage.publish<\/span>( voltage );\n  }\n\n  mqtt.disconnect<\/span>();\n}<\/pre>\n
If the example code doesn’t compile, make sure your copy of the MQTT library supports the additional retain flag.<\/p>\n
In closing<\/h3>\n
The library can be used in the same way as the official Adafruit library, and it is 100% source compatible. \u00a0Unless you explicitly add an r-parameter value of 1 when creating the Adafruit_MQTT_Publish feed object, the library will behave exactly as the standard one. \u00a0Pass a value of 1, however, and the MQTT server will persist the message, eliminating the startup delay for subscribers to the topic.<\/p>\n
My changes can be found on github<\/a>, and a diff of my changes relative to the official version are here<\/a>.<\/p>\n
 <\/p>\n","protected":false},"excerpt":{"rendered":"
Recently, when building a weather station based on Adafruit’s Huzzah ESP8266 breakout board, I needed the ability to send messages that should be retained on the MQTT server. I am using mosquitto on my home server, acting as a message broker. \u00a0My weather stations send messages to it and these are then forwarded to the … Continue reading “Adding retained messages to Adafruit's MQTT library”<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7,1],"tags":[8,9,10],"class_list":["post-42","post","type-post","status-publish","format-standard","hentry","category-arduino","category-uncategorized","tag-arduino","tag-esp8266","tag-mqtt"],"_links":{"self":[{"href":"https:\/\/www.bakke.online\/index.php\/wp-json\/wp\/v2\/posts\/42","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.bakke.online\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.bakke.online\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.bakke.online\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.bakke.online\/index.php\/wp-json\/wp\/v2\/comments?post=42"}],"version-history":[{"count":0,"href":"https:\/\/www.bakke.online\/index.php\/wp-json\/wp\/v2\/posts\/42\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.bakke.online\/index.php\/wp-json\/wp\/v2\/media?parent=42"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.bakke.online\/index.php\/wp-json\/wp\/v2\/categories?post=42"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.bakke.online\/index.php\/wp-json\/wp\/v2\/tags?post=42"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}