MQTT

MQTT aims at being The Standard for IoT Messaging.

MQTT is an OASIS standard messaging protocol for the Internet of Things (IoT). It is designed as an extremely lightweight publish/subscribe messaging transport that is ideal for connecting remote devices with a small code footprint and minimal network bandwidth. MQTT today is used in a wide variety of industries, such as automotive, manufacturing, telecommunications, oil and gas, etc.

MQTT is pretty handy if you need to integrate existing automations or devices connected to computers in your home, because you can quickly and easily write with minimal effort some lines of code to start sending and receiving messages with your Home Assistant.

Without getitng too much involved in how MQTT works, you need a broker. A Broker is a software that the other MQTT paricipants can connect to and which will send/receive topics between publishers and subscribers.

The most common broker is Mosquitto, which is also open-source.and provides free easy to use and well documented APIs.

Each topic is a message. The name of the topic is in the form of:

one/two/three

you can specify levels in your topic name, by separating them with a / sign.

I tend to assign three levels:

floor/room/sensor

so for example a temperature sensor locate on the ground floor in the kitchen will publish a topic called ground/kitchen/room_temperature.

The payload of the topic can be a wide range of formats, i tent to prefer JSON because it's easily parsed in Home Assistant.

Each entity participating in the MQTT network can be a published or a subscriber of a topic. Usually your sensors will be publishers, while more complex devices an be subscribers to receive topics.

As an example, i have a small Pi device in my kitchen with a 1wire temperature sensor. This sensor can be calibrated from another temperature reading, which is connected via ZigBee. The Pi reads the sensor and publish a topic called ground/kitchen/room_temperature after applying a correction calue which is received from Home Assistant as topic ground/kitched/delta_temp.

In this case, my Pi acts as a publisher for the first and a subscriber for the second.

In Home Assistant you can choose more than one MQTT broker. I choose the Mosquitto Broker which can be installed from Settings → Devices → Add Integration.

Installing is just a few clicks, and you can also send and receive topics directly from the page, for debug purposes.

Adding MQTT based entities in Home Assistant is done by directly editing the configuration.yaml file.

This is my example:

mqtt:
  sensor:
    - name: "Kitchenn Temperature "
      state_topic: "ground/kitchen/room_temperature"
      device_class: "temperature"
      value_template: "{{ value_json.temperature | round(1) }}"
      unique_id: "temp_ext"
      unit_of_measurement: "°C"
  binary_sensor:
    - name: "Gas Stove On"
      state_topic: "ground/kitches/gas_stove"
      device_class: "power"
      value_template: "{{ value_json.on }}"
      payload_on: 1
      payload_off: 0
      unique_id: "pellet_on"

On my Pi i have installed the various Mosquitto packages:

sudo apt-get install  mosquitto-clients
sudo apt-get install mosquitto-dev
sudo apt-get install libmosquitto-dev

then you can use both python and C bindings.

This link has a very comprehensive documentation on Mosquitto APIs