MQTT for beginners

Although there are ample ready made programs for the ESP8266 to connect to
MQTT, I still get questions of people on how to do it. So I will explain it step by step here. If you already know exactly on how to do this, you may just as well skip this post, although there might be some things of a more general interest towards the end.

For those who really have no idea what MQTT actually is, it is a lightweight protocol for machine to machine communication. It consists of a topic and a message (also called payload) that is used often in iot and homeautomation projects. In short, and pulling it a bit in absurdum, with MQTT your refrigerator can talk to your oven and your coffee-maker, provided these are all ‘smart devices. However, they do not talk directly to eachother, they do that via a ‘broker’. A broker is a machine that keeps track of all the MQTT traffic and knows what messages need to go to what device. That means that when your fridge
wants to talk to the coffee maker, there is no need for the oven to listen to that message.

So first of all you need an MQTT broker. That could be a public broker or your own broker that you run locally (for instance on a Raspberry Pi). Mosquitto is a popular broker to run yourself (check here how). If you do not want to run your own broker you have options like, CloudMQTT, HiveMQ, MQTT Dashboard (though that uses Hive), RabbitMQ and io.adafruit . To get up and running fast, is the easiest. However, it is a completely open test broker. There is no security on it whatsoever so it is adviseable to change to a private or password protected broker as soon as you have your mqtt up and running.

For the ESP8266 program that we will be making, there will be 4 important credentials that we need. Those are the server, the user, the password and the port. Mind you that “” does not require a user log-in and also when you are running your own broker you do not need (but can set) a log-in, but I will introduce these two variables in the program for when you decide you need/want a log in.

The ESP8266 using the MQTT protocol is considered a ‘client’ of the ‘broker’. To let the ESP8266 talk to the broker there is very popular library called PubSubClient. It is called ‘PubSub’ because it allows the ESP to ‘publish’ MQTT messages to the broker and to ‘Subscribe’ to MQTT messages of the broker. Do you remember I said the oven des not need to listen to the fridge talking to the coffeemaker? Well that is what the ‘subscription’ is for: The specific ESP8266 is only getting messages that it ‘subscribed’ to. The library can be installed via Arduino IDE library manager.

The code

Like in all programs, we begin by including the libraries that are needed for all the functionality we want/need. We need the ESP8266WiFi library, for the ESP8266 to connect to a WiFi network, and the PubSubClient library, for the ESP8266 to connect to a MQTT broker and publish/subscribe messages in topics.

#include <ESP8266WiFi.h>
#include <PubSubClient.h>

Next, we will declare the global variables for our connections. We need the WiFi credentials, to connect to the WiFi network.

constchar* ssid = "YourWiFiSSID"; constchar* password = "YourWiFiPassword";

Next we need the information of the MQTT server. As explained earlier, you will need the server address, the port, the username and the password, but for our test we can leave the user and password empty. In most MQTT brokers, the port is 1883

constchar* mqttServer = “”; constintmqttPort = 1883; constchar* mqttUser = “YourMQTTUsername”; constchar* mqttPassword = “YourMQTTPassword”;

Next we will declare two ‘objects’ (like with all libraries): the WiFiClient object establishes a connection to a specific IP and port. The PubSubClient receives input of the WiFiClient that we just created

We will keep the PubSubclient object simple with just one argument, but it can receive more arguments. For that you may want to check the the API documentation.

WiFiClient espClient;
PubSubClient client(espClient);

In the setup function we connect to the WiFi network and for convenience we print the progress to the serial monitor

WiFi.begin(ssid, password);

Serial.print("Connecting to WiFi..");
Serial.println("Connected to the WiFi network");

Then we set the address and the port of the MQTT server. We do this with the setServer method of the PubSubClient object.

client.setServer(mqttServer, mqttPort);

We are almost there, but we still need to tell the program what to do with incoming MQTT messages. For that we use the setCallback method of the PubSub object to set a function that is executed when a MQTT message is received. Traditionally this function is called ‘callback’, but you can give it any other name


Now, we need the Setup function to connect to the MQTT server. Preferably we do this in a loop till we get succes.

(!client.connected()) {
Serial.println("Connecting to MQTT...");
if (client.connect("ESP8266Client", mqttUser, mqttPassword )) {
Serial.print("failed with state ");

The setup function is a good place to publish our first MQTT message to tell the world we are there. Kind of an “Hello World” to let the broker know we are on line. We do this with the publish method, that takes a topic and a message as arguments. As a topic we choose “test/esp8266”, and for a message “Hello ESP world”.

client.publish("test/esp8266","Hello ESP world");

Leaves us to subscribe to a topic to let the broker know what messages from other publishers we like top receive. We do that with the subscribe method, with the topic name as argument. We can take any topic we desire, but for now lets subscribe to the same topic as we publish.


The full setup function now looks like this:

  while(WiFi.status() != WL_CONNECTED) {
    Serial.println("Connecting to WiFi..");
  Serial.println("Connected to the WiFi network");
  client.setServer(mqttServer, mqttPort);
  while(!client.connected()) {
    Serial.println("Connecting to MQTT...");
    if(client.connect("ESP8266Client", mqttUser, mqttPassword )) {
      Serial.print("failed with state ");
  client.publish("test/esp8266", "Hello ESP world");

The Topic

This would be a good moment to say some words about the format of the topic. In its smallest form, the topic only needs to be one character long.
Traditionally though, topics have a hierarchy that is defined by backslashes. A topic for instance could be “home\garden\lawn\sprinkler”. This hierarchie allows
subscription on several levels. You could for instance subscribe to the topic “home\#” to get all the messages that deal with ‘home’. You could subscribe to the topic “home\garden\#” to get all the messages that have to do with your garden etc. etc. Often you will see a topic starting with a backslash, like
“\home\garden\lawn\sprinkler” There is absolutely no gain in starting a topic with a backslash.

The callback function

The callback function receives the MQTT messages (topic + payload) that our ESP PubSub client has subscribed*) to. The arguments of the callback function are the name of the topic, the payload and the length of that payload.

As illustration, we will setup the function to print
the topic to the serial port, and then print the received payload.
Since we also have the length of the payload as argument of the
function, this can be easily done in a loop.

voidcallback(char* topic, byte* payload, unsigned intlength)

  Serial.print("Message arrived in topic: ");
  for(inti = 0; i < length; i++) {

*) To be precise: the subscription is to a topic, the client then receives the topic + the payload coming with that topic. The payload is sometimes called ‘the message’ but confusingly the topic+payload is sometimes also called “the message”

In the above example we have only subscribed to one specific topic:

The topic “test/esp8266/node1” for instance, will not arrive. For that we would need to specify a wildcard “#”

The main loop

In the main loop function, we use the loop method of the PubSubClient. This function is called to allow the client to process incoming messages and maintain its connection to the server.


The full code

The full code now is as follows:

#include <ESP8266WiFi.h>
#include <PubSubClient.h>
constchar* ssid = "YourWiFiSSID ";
constchar* password =  "YourWiFiPassword";
constchar* mqttServer = "";
constintmqttPort =1883;
constchar* mqttUser = "YourMQTTUsername";
constchar* mqttPassword = "YourMQTTPassword";
WiFiClient espClient;
PubSubClient client(espClient);
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    Serial.println("Connecting to WiFi..");
  Serial.println("Connected to the WiFi network");
  client.setServer(mqttServer, mqttPort);
  while (!client.connected()) {
    Serial.println("Connecting to MQTT...");
    if(client.connect("ESP8266Client", mqttUser, mqttPassword )) 
      Serial.print("failed with state ");
  client.publish("test/esp8266","Hello ESP World");
  client.subscribe("test/esp8266");// here is where you later add a wildcard
voidcallback(char* topic, byte* payload, unsigned intlength)
  Serial.print("Message arrived in topic: ");
  for(int i = 0; i < length; i++) {


To test the code, upload and run it on your ESP8266. Open the Arduino IDE serial monitor to print the output.

The ESP8266 will send the “Hello ESP World” message, however, that will not be printed on the serial monitor, but as the program also subscribed to that same topic, it will receive that same messages, coming back from the broker and then print it on the serial monitor.

If any other client would send message to the “test/esp8266” topic, then that also will be printed in the serial monitor

Now if it does not work and you are sure the code is OK, is very wise to have MQTT-Spy installed on your computer. MQTT-spy monitors the MQTT traffic on your network and it can publish and subscribe to any desired MQTT topic.

OK, so now what? How do I send a variable?

After your initial joy that everything is working you immediately would want to send something useful for instance that reading of a DHT22 or a DS18B20 sensor and suddenly you need to make the step of the string “Hello World” to a temperature variable. Ofcourse you will try and just insert the variable in place of the “Hello World” string and hope for the best, but that will fail, as the PubSub library (and the MQTT protocol) will only accept strings.
You will see it will not even accept a string variable, so what to do? Well there are several ways to put a variable in the MQTT payload:

1- take another library.
There is a fork of the PubSubClient library by Ian Tester. It will accept variables if defined like this:
client.publish("topic", String (variable));
However, it is often not a drop in replacement, you will need to make minor adjustments in setting up the various calls.

2-use some C++language
Suppose you want to publish some interger variable  called ‘temperature’

sprintf(buff_msg, "%d", temperature);
client.publish("topic", buff_msg);

ofcourse you will need to set up the buff_msg buffer in your global variable declarations like this:

buff_msg[32]; // mqtt message

A very frequently used  payload to send will be OFF or ON. Although often it  might be just as easy to define an IF statement for your payload like this:

if (status==1){client.publish("topic","ON");}
if (status==0){client.publish("topic","OFF");}

it is also possible to do that with  the sprintf command:

sprintf(buff_msg, "%d",  status);

So, can I send a JSON with MQTT?

Sure you can. I am pretty sure it works with the above method, after all a JSON is just some type of string. However, I prefer another method for a JSON.

Suppose I want to send the following JSON:
do that as follows:

String payload="{\"garden\":temperature\",\"data\":["+String(temperature_outside)+","+String(temperature_greenhouse)+","+String(temperature_compost)+","+String(temperature_coldframe)+","+String(temperature_soil)+"]}";

payload.toCharArray(data, (payload.length() + 1));

I like to send my IP number as MQTT, is that possible?

Ofcourse. There are several methods and in the end all roads lead to Rome. Using c_str is sometimes advised but I prefer the following.

in your general variable declaration declare:
String IP;

Then after  you connect to WiFi  state:
IP = WiFi.localIP().toString();

Then where you handle your publishing, do the following:

for (i = 0; i < 16; i++) {
buff_msg[i] = IP[i];
buff_msg[i] = '\0';
client.publish("topic", buff_msg);

Can I send variables in the topic?

Yes you can. This is in fact not so different from sending variables in the payload:
In your variable declaraion  declare a buffer:
buff_topic[30]; // mqtt topic

Now suppose you want to send the ID number or the name of your  ESP8266 as part of the topic and an error as the payload:

in your  global declarations you have defined the number or name of your ESP:
#define nodeId 13 // node ID

and then where you send your  messages do:

sprintf(buff_topic, "home/nb/node%02d/error", nodeId);
sprintf(buff_msg, "syntax error %d", error);
client.publish(buff_topic, buff_msg);

What about receiving MQTT messages?

Well, I spoke about the callback function that handles the incoming messages, but I admitt that just waiting for one standard solitary “Hello World” message isn’t very useful.
To subscribe to more than one message we need to use a wildcard, so
this will catch  messages such as:
The most obvious way to use these would be to check the incoming topics is it Light1 or Light2, then check the incoming payload (is it “ON” or “OFF”) and then act upon the content of the payload.

Especially if you have MQTT  topics with varying lengths this requires quite some checking of possibly long topics.
Say you have:

Although it is very well possible to check for all these messages and then determine what the payload is, it is memory consuming.
A more elegant way is to keep the MQTT messages all the same length and only say vary the last 2 characters of the topic to indicate what it is about. That gives room for 100 different topics, while uou only have to check the last 2 characters, rather than a long string.
Lets give an example:
Suppose your MQTT messages all have the format:  “home/nodeID/devID” or -in practice:

Your subscription then would be to: “home/node13/#”
and you would only have to check on the last two digits.

An example of  your callback then would be

void callBack(char* topic, byte* payload, unsigned int length) { // receive and handle MQTT messages
int i;
for (int i = 0; i < length; i++) {
if (strlen(topic) == 17) { // correct topic length ?
DID = (topic[15] - '0') * 10 + topic[16] - '0'; // extract device ID from MQTT topic
payload[length] = '\0'; // terminate string with '0'
String strPayload = String((char*)payload); // convert to string
if (length == 0) {
error = 2; // no payload sent
}else {
if (DID == 0) {
device0 = true;
if (DID == 1) {
device1 = true;
if (DID == 2) {
device2 = true;
if (DID == 99) {
device99 = true;

What the code does here is to just look at the last 2 digits (DID = Device ID) and then set a flag (device0 -device 99) that can be checked in the main loop upon which action can be taken, depending on the content of  the ‘strPayload’  string.

For an extensive example of this check the gateway projects of Computourist on github.


OpenHab GPIO Example

I know this might not directly be Arduino or ESP8266 related, but I thought I’d publish it anyway as it may come in handy with openhab

First of all, install the GPIO binding in the PaperUI. After one has done that, there isnt really much else to do on that binding. There is no services/gpio.cfg although some of the documentation mentions that file.

Before I go further it is good to note that I used the openhabian distro and I presume a lot of things are already OK in that, but if you did a manual install, it might be good to check if the user ‘openhab’ is member of ‘gpio’ and if not, set that with

sudo adduser openhab gpio

That’s basically all one needs to do.
Let’s setup an ‘input’ which in openhab is a ‘Contact’ and an ‘output’, which in openhab is a Switch. In fact, those are the only states the binding allows.

There is no pressing need to define anything in your sitemap file if e.g. you add the items to a group in your itemsfile, but if you prefer a sitemap then add this to your sitemap file:

Switch item=GPIO_LAMP

Let’s pick some pins to use. It is easiest to use pins on the Raspberry header that are close to a ground pin.

Looking at the pin out of the raspi, we see that for instance GPIO pins 21,13,5, 7, 10, 27,22,24,25,12,16,26, 3, 4, 8 and 17 are next to a ground pin, but some of those have reserved functions so i stayed away from those.
I picked GPIO23 and GPIO24 as that one is also close to a 3V3 pin and when using that as input one can always decide later to make that have a HIGH or a LOW input.The configuration string for the binding is defined as follows:

gpio="pin:PIN_NUMBER [debounce:DEBOUNCE_INTERVAL] [activelow:yes|no] [force:yes|no] [initialValue:high|low]"

for those who consider this as double dutch, it will become clear in the items definition:

Add this to your items file:

Switch GPIO_LAMP "Lamp" (LivingRoom) { gpio="pin:23 force:yes" }
Contact GPIO_BUTTON "Button [%s]" (LivingRoom) { gpio="pin:24 activelow:yes" }

The group ‘LivingRoom’ is not mandatory if you have defined your sitemap and of course you may use another group that suits you more.

The Switch that I set up is quite simple. In fact it already would be enough if it would have been:

Switch GPIO_LAMP "Lamp" {gpio="pin:23"}.

But with ‘force:yes’ we force the use of the pin even if it would have been in use by another process. Obviously that might not be the most elegant way to do it, but as i am pretty sure I am not using it for another process, I just wanted to make sure Openhab would have the pin available.

The current of a GPIO pin is far to small to drive any significant load as it can deliver some 60mA I think.
But the output can drive a small LED to test it… but use a 330 ohm series resistor, no matter what other websites tell you: you dont want to fry your GPIO pin. Eventually it would be more useful to drive a small relay module as long as it has a separate transistor to drive the relay (I know, I am cautious)

The configuration allows for some other parameters.
i already mentioned ‘force:yes|no

activelow yes|no  this means that when the switch is off, there is no voltage on the pin
initialValue:high:low determines the state the pin will take during initialisation.
debounce:interval is used to set the debounce value for the switch in milisecs

If we look at the output, I have not added an activelow because I thought that was the default value (but correct me if I am wrong)
If we look at our input, I set that to activelow, because the way the button works is it applies voltage to trigger the pin and I added it because I was not sure about the default
I did not set a debounce for the contact, but you could state:

Contact GPIO_BUTTON "Button [%s]" (LivingRoom) { gpio="pin:24 debounce:10 activelow:yes" }


Using the 18 bits MCP3421 I2C ADC with Arduino.

A while ago, I published a post about expanding the ESP8266 ADC capacities with the PCF8591 8 bits I2C ADC multiplexer. 8 Bits is really enough for most work I would guess, but if you need more accuracy, say 18 bits for a  high precision Digital Voltmeter, there is the (relatively expensive) MCP3421. I say ‘relatively coz it is still cheaper (and easier to use)  than the LTC2400 (controlled by SPI). This is only a one channel chip, so if you want more channels, you would think you have to get more (which is OK as generally they are sold in webstores in a lot of say 5 or 10), but the chip has no address selection. It has a fixed address of 0x68.
If you do not like soldering though, there is also an ‘evaluation module’ available.

The MCP3421 has an in-program sample rate selection from 12-18 bits and in inbuild Programmable Gain Amplifier that can also be controlled from  your program. There is a library available, several in fact which makes using the chip very easy. If one channel is not enough, try the MCP3424 18-bit, 4-channel, multi-address ADC

Arduino Watchdog timer

I will not go too much into the benefits of a Watchdog timer as I presume those are known, but in short a Watchdog timer resets a processor  when it hasn’t seen any activity of that processor for a while. This is  specifically handy for processors  that are in a less accessible space, where otherwise you’d have to go to, get access and  press reset.

Basically there are 2 types of  Watchdog timers: Hardware and Software. About Software WDT’s I can be brief, they work, but  as the very goal of a WDT is to reset in case of software failure, using a software WDT seems a bit counterintuitive. If however you opt for a software timer, you will find a good article here.

Many of the Atmel chips, such as theAtmega328 in the Arduino UNO have an internal hardware Watchdog timer. In reality that watchdog timer is just a simple counter that gives a pulse when it counts up. This pulse can be used either to generate interrupt or simply reset MCU (or both). The watchdog timer can be reset to zero at any time with the WDR command.

The Internal Watchdog timer of the Atmeag328 is set by by programming WDTON fuse when flashing the MCU. You will find more information here.

Other than having to set fuses when flashing your chip, this internal hardware timer has a drawback similar to the software WDT: If you make a mistake, your chip could get into near continuous reset which makes it hard to re-use it again.

From that point of view an External Hardware WDT might be a better option. If you dont need it anymore, or made a mistake, you simply disconnect it.
There are specific  WDT chips available, but the good old NE555 can be used as well.

Watchdog timer
Watchdog timer

The workings are as follows:
In this circuit the 555 is configured as an astable oscillator. When free running it will charge C2 till about 2/3rds of Vcc (so about 3.33V) and then generate a negative pulse on pin 3 that is connected to the RST of the Arduino (or other chip). Diode D1 is not essential, but it does protect the Arduino.
The frequency, and thus period of the oscillator is determined by R2, R3 and C2. In its current config the time period til reset is about 69 seconds. At the end of that period the  circuit will generate a LOW pulse that  will reset the attached microprocessor. As the dutycycle of the circuit is far from symmetrical (fortunately) the LOW pulse will take some 15 mSec which is a useful time. Not too short, not too long.

However, we do not want the processor to restart every 69 seconds, we just want it ro  do its thing unless it hangs and therefore we let the processor restart the  555 oscillator continuously to signal that it is still alive and kicking. We do that by discharging C2 via R1 and we do that simply by using an output pin that we make LOW. So if during each loop of the firmware in the processor we pull that Output pin LOW, the Watchdog knows the processor is still doing its work and only when the program hangs, the watchdog will do a reset after 69 seconds.

It is not sufficient to just make the Output pin LOW to restart the timer, but afterwards it needs to be set HIGH again. However, even if an output pin is HIGH, there still is an internal impedance that could drain C2. Therefore after setting it as OUTPUT and LOW, we set it back to INPUT mode again, because as input the I/O pins of the Arduino have a fairly high impedance.

R1 limits the current that can flow through the sinking pin to abt 9mA (in reality some 6mA). Ofcourse R1 adds to the  time needed to discharge C2, but that does not pose a problem here. (If not given enough time though, the Watchdog will need less than 69 seconds before it is able to send a reset signal again.)

int HeartbeatPin = 8;

void heartbeat() {
// Sink current to drain C2
pinMode(HeartbeatPin, OUTPUT);
digitalWrite(HeartbeatPin, LOW);
// Set pin back to High Impedance
pinMode(HeartbeatPin, INPUT);

void setup() {
// Send an initial heartbeat.

void loop() {
//your code

The above is just a very simple example. Ofcourse it is also possible to check specific sections of the program such as say succeeding an internetconnection or  attaching to a serial port. That way you could avoid  that only part of the program (e.g. connecting to internet)  failed, while the processor is still happily kicking the dog on every loop
The end result however will always be a total reset

Reverse polarity protection with a P-MOSFET

Reverse voltage protection with P-FET
Reverse voltage protection with P-FET

Reverse polarity protection can easily be done with a single diode. The problem with that however is the voltage drop (usually 600mV) that with  large currents can mean a substantial powerdissipation. Using a Skottky diode for its smaller voltage drop is risky as the reverse current through a Skottky is not negligable.
A better way is to use a P-MOSFET as shown in the circuit above. This method is explained very well  in an Afroman youtube video.
Though the direction of the P-Fet may seem a bit counterintuitive, but realise that when the Vgs is in conductive range, the FET will  basically operate as a Switch or in fact a  resistor with very low resistive value, allowing current in both directions.
However you need to pick a FET with low VGS(threshold) so that the device is still offering a tiny volt drop at low battery voltages AND you’ll need a FET with low RDS(on) so that at  your peak current  the FET is dropping less than say 100mV. Other than the FQP4706 the DMG3415U may be a good pick. With 1.8V gate drive it has 0.071Ω resistance.

Switching a humidity sensor off and on

Gardeners who use a resistive moisture sensor to measure the moisture of the soil, sooner or later get faced with corrosion of their metal sensor. Though practically all metals corrode in the soil, in this case it is sped up by the fact that a current flows through the sensor, causing electrolysis.

Several solutions are suggested to solve that like: ‘you have to feed them with AC’ but those solutions are not always practical.

There is however a fairly simple method to minimize the electrolysis and that is to switch off current through the sensor when you do not need it.
Moist soils do not need constant measuring, maybe 3-4 times a day is enough, so if you switch off the sensor except for the say 3x a milisecond or so that makes a big difference.

Easiest might be to use an I/O pin to feed the sensor, but not everybody feels comfortable doing that and not all microcontrollers are suitable for that (although the arduino probably is with 40mA per pin).

But it is in fact quite easy to use a transistor -controlled by an I/O pin- to switch the sensor on and off. Figure 1 gives an example of how to do that with either low side switching or high side switching.

Figure 1a is a very basic transistor switch: Pull the base of the transistor HIGH and current will flow through the sensor, pull it LOW and the current will be switched off. Remember there will be a slight voltage drop (say 250-450 mVolt) over the transistor.

Fig 1b is also a rather basic transistor configuration, it is the emitter-follower or common collector that is often used in voltage buffering. Here also a LOW on the base will switch the transistor OFF and a HIGH will switch it on. Also here one has to take a voltage drop into account (basically the voltage on the I/O pin minus 0.6 Volt). Mind you that Fig 1&2 just give a basic circuit. You’ll need to add a base resistor and possibly a pull-down or pull-up  resistor, depending on  what state you want the circuit to start in.

Figure 2 shows two other circuits you may be considering to try, but that’s not necessarily a good idea.
Fig 2A is basically identical to Fig 1A, but with the sensor and series resistor switched position in the voltage divider.
That does not work because even when the transistor is switched off, there still could be a current flowing through the sensor via the internal impedance of the microcontroller input.
Figure 2B shows a PNP transistor used. That should work right? After all it is basically figure 1A but then reversed in polarity. Well, it is not that simple. The I/O pin is tied to a microcontroller running at say 5V, so its voltage level will vary between 0 and a bit less than 5 Volt. At best it might be 4.2 Volt.*

To keep the PNP transistor switched off, we need to keep the base voltage at nearly the same level as that “+” line and that is hard  in this configuration. Therefore opening the transistor is not a problem, but closing it might, although it will ‘probably’ work

Mind you that Fig 1 and 2 just give a basic circuit. You’ll need to add a base resistor and possibly a pull-down or pull-up  resistor, depending on  what state you want the circuit to start in.

*A pFET on the other hand is quite suitable for high side switching



JSON, MQTT, PubSub and OpenHAB

Usually I communicate between my various nodes (arduino, esp8266) with MQTT and OpenHAB being the interface. Simple, just one string command per message. Now there comes a moment that it seems better or more convenient, to send more commands in one MQTT message, and that is where JSON comes in. JSON messages are basically an organized string and MQTT is good in sending strings.
Author of the Pubsub library Nick O’Leary’s advice on sending JSON’s is as follows:

However, you need a few tricks before you can send a string variable.

I started off by using the ArduinoJson library to make my JSON’s, but I was not quite happy with that. There are various ways to do it and you end up with some sort of data/char array.

Supposedly you could send that with "client.publish(topic, (char*) payload.c_str())". But for various reasons that didnt suit me so I used another method.

As I was a bit unhappy about adding the ArduinoJson library just to make a JSON string, I thought it would be  best to simply compile the string myself and send that. I am not saying there is no better way… and if there is, please do tell, but this worked for me.

Anyway, let’s start with something simple, I have a LiPo battery feeding an ESP8266 and in openHAB I like to keep track of the voltage of the battery, but I also like to display the Percentage of the battery charged. Ofcourse I can calculate the latter in OpenHAB, but i prefer to have the ESP8266 do that.
Note: the below calculation is for a Wemos D1, with a 100k  resistor  in series with A0. Together with the  residing voltage divider it makes a 100k/(100k+220k+100k) = 1/4.2 voltage divider,  reducing a 4.2Volt voltage to 1 Volt. Therefore a reading of 1023 (=1V) on the A0 port correlates with 4.2 Volt on the LiPo battery)

voltage=analogRead(A0);// (mind you, this is 1 V max)
voltage=voltage/1023.0;// so 1V max renders "1" here
voltage=voltage*4.2;// We want a max of 4.2, so multiply
percent=100*voltage/4.2;// and calculate percentage

The JSON string I need to make, will look as follows

{"Voltage": voltage_value,"Percent": percent_value}

to insert a quote in a string you need to use the backslash as an escape character, so, we make the JSON string as follows:

String payload="{\"Voltage\":"+String(voltage)+ ",\"Percent\":"+String(percent)+"} ";

So now we have the Stringvariable “payload” that we have to send via PubSub.

There may be various ways to do that, I did it as follows:

payload.toCharArray(data, (payload.length() + 1));

You could probably also use: client.publish("home/battery", payload.c_str());, but I didn’t*).
So, once in openHAB it is quite easy to process the the JSON, once the proper transformation Add-on is installed.

In the items file it then looks like this:

Number battery_garden "Battery Garden [%.1f V]"  (Back_Garden, batteries) {mqtt="<[mosquitto:home/battery:state:JSONPATH($.Voltage)]"}
Number battery_garden_pct "Battery Garden [%.0f %%]"  (Back_Garden, batteries) {mqtt="<[mosquitto:home/battery:state:JSONPATH($.Percent)]"}

And on screen like this:

OK, let’s try that with the reading results of a DHT11. Sure, there might be many reasons why you would want to send the humidity reading and temperature reasing as two different MQTT strings, but for arguments sake let’ s try it as a JSON.

We will first read the DHT11 sensor,then we will create a JSON that looks like {“Temperature”: 20.0, “Humidity”: 68}  with 20.0 and 68 of course just snapshot  examples. Subsequently we will create the MQTT message and display it in openHAB

float humid_coop = dht.readHumidity();
float temp_coop = dht.readTemperature();
String payload="{\"Humidity\":"+String(humid_coop)+ ",\"Temperature\":"+String(temp_coop)+"} ";
payload.toCharArray(data, (payload.length() + 1));
client.publish("home/coop", data);

and then in the itemsfile:

Number Humidity_Coop "Humidity Coop [%.0f %%]" (coop) {mqtt="<[mosquitto:home/coop:state:JSONPATH($.Humidity)]"}
Number Temperature_coop "Temperatuur [%.2f °C]" (coop) {mqtt="<[mosquitto:home/coop:state:JSONPATH($.Temperature)]"}

Let’s now have a look at sending more than just two data  values. Suppose you have an I/O chip (or more) that lets you read 12 channels at the same time, you could ofcourse make a JSON like this: {“channel1” : value1, “channel2″:value2,  ……..”channel12”: value12}, but that seems to send a lot of unnecessary data, so we will create the following JSON:

We do that as follows

String payload="{\"data\":["+String(ana0)+","+String(ana1)+","+String(ana2)+","+String(ana3)+","+String(ana4)+","+String(ana5)+","+String(ana6)+","+String(ana7)+","+String(ana8)+","+String(ana9)+","+String(ana10)+","+String(ana11)+ "]}";
payload.toCharArray(data, (payload.length() + 1));
client.publish("home/json", data);

in the MQTT channel in the items file we will now use a slightly different JSON format. The data will now be read by index number like:


the full itemsfile then will be

Number Moisture1 "Moisture 1 [%.0f]" <plantbed> (Garden_moist) {mqtt="<[mosquitto:home/json:state:JSONPATH($.data[0])]"}
Number Moisture2 "Moisture 2 [%.0f]" <plantbed> (Garden_moist) {mqtt="<[mosquitto:home/json:state:JSONPATH($.data[1])]"}
Number Moisture3 "Moisture 3 [%.0f]" <plantbed> (Garden_moist) {mqtt="<[mosquitto:home/json:state:JSONPATH($.data[2])]"}
Number Moisture4 "Moisture 4 [%.0f]" <plantbed> (Garden_moist) {mqtt="<[mosquitto:home/json:state:JSONPATH($.data[3])]"}
Number Moisture5 "Moisture 5 [%.0f]" <plantbed> (Garden_moist) {mqtt="<[mosquitto:home/json:state:JSONPATH($.data[4])]"}
Number Moisture6 "Moisture 6 [%.0f]" <plantbed> (Garden_moist) {mqtt="<[mosquitto:home/json:state:JSONPATH($.data[5])]"}
Number Moisture7 "Moisture 7 [%.0f]" <plantbed> (Garden_moist) {mqtt="<[mosquitto:home/json:state:JSONPATH($.data[6])]"}
Number Moisture8 "Moisture 8 [%.0f]" <plantbed> (Garden_moist) {mqtt="<[mosquitto:home/json:state:JSONPATH($.data[7])]"}
Number Moisture9 "Moisture 9 [%.0f]" <plantbed> (Garden_moist) {mqtt="<[mosquitto:home/json:state:JSONPATH($.data[8])]"}
Number Moisture10 "Moisture 10 [%.0f]" <plantbed> (Garden_moist) {mqtt="<[mosquitto:home/json:state:JSONPATH($.data[9])]"}
Number Moisture11 "Moisture 11 [%.0f]" <plantbed> (Garden_moist) {mqtt="<[mosquitto:home/json:state:JSONPATH($.data[10])]"}
Number Moisture12 "Moisture 12 [%.0f]" <plantbed> (Garden_moist) {mqtt="<[mosquitto:home/json:state:JSONPATH($.data[11])]"}

and look like:

There is nothing stopping you from including data from more than 1 sensor in a JSON and send that all in one MQTT message. This way you could for instance put all the sensor data from say one room, or the entire garden in one MQTT message and send it.
Beware though that the default packet size supported by the PubSub client is 128 bytes. You can increase this limit by editing the value of MQTT_MAX_PACKET_SIZE in PubSubClient.h.
*)There is a fork of Nick O’Leary’s PubSub library, by Imroy, that will happily send:
client.publish(topic, String (value));