This project consists of 3 main components:

  • the Microhomie sensor (hardware and software)
  • the MQTT server (selfhosted or you can use a service, see below)
  • the homie -> IOTA gateway (selfhosted)

First, take a look at this awesome architectural drawing:


This guide will take care of the purple ESP32 / Microhomie device with the requried hardware and software.

Install the MicroPython

For now, follow this tutorial (https://www.cnx-software.com/2017/10/16/esp32-micropython-tutorials/) to install MicroPython on the ESP. Please remember to use the latest version of the ESP software during the installation.


On some boards, the installation of MicroPython will fail with an “connection timeout” if you have any wires attached to the board. This depends on your board and you have to detach all wires except power for the basic installation to work. This is only relevant for the installation of MicroPython and not Microhomie.

Once the installation is successful and you are able to execute python code on the ESP32, you can install Microhomie.

Install Microhomie

Microhomie is split in two parts, the base package and a node package with additional functions. We require the DHT22 node from the node package for this tutorial.

We provide some example nodes in the https://github.com/microhomie/micropython-homie-nodes repository. Most of these nodes can be used out of the box to publish data.

The base package and the node package can be installed via PyPi or manual. As of the time of this writing, the PyPi way of installing is prefered.

Setup WIFI for installation

Microhomie handles WIFI setup for you, but for installation from PyPi you have to manual setup WIFI once from REPL.

>>> import network
>>> wlan = network.WLAN(network.STA_IF)
>>> wlan.active(True)
>>> wlan.connect('wifi-name', 'wifi-secret')
# wait a few seconds
>>> wlan.isconnected()  # test if wlan is connected
>>> wlan.ifconfig()  # get wlan interface config
('', '', '', '')


Microhomie use a settings.py file to configure the device. See settings.example.py as an example. Modify this file for your needs and copy it to your device root directory as settings.py.

Install with PyPi

We provide PyPi packages for easier installation on your device. Open the REPL from your device, make sure your device wlan is up and your device has access to the internet, import upip and install microhomie:

>>> import upip
>>> upip.install('microhomie')

Add files specific for your device

You now have Micropython adn Microhomie installed. The stage is set!

Please copy a new main.py file on the device:

import utime
import settings

from homie.node.dht22 import DHT22
from homie import HomieDevice

# Homie device setup
homie_device = HomieDevice(settings)
homie_device.add_node(DHT22(interval=60, pin=2))

while True:
    # Push the new data to MQTT
    # Sleep a little bit

Soldering it

You need the following hardware:

You don’t have to get the stuff on Amazon. Other places are cheaper, Amazon is just easier and for general reference.

Wire it all up:


The final result will look something like this. This includes the DHT22 for temperature and humidity AND the SDS011 for airquality which is not part of this quickstart but can be added later on as you can see:

Prepare MQTT

Checkout mosquitto MQTT Server (https://mosquitto.org/) if you want to host a server yourself or head over to IO Adafruit(https://io.adafruit.com/), createn an account and use their MQTT API(https://learn.adafruit.com/adafruit-io/mqtt-api).

If everything is setup correctly, the data will then be pushed to the MQTT server in the homie format. Take a look at the homie documentation(https://github.com/marvinroger/homie) to get an idea of the possibilities.

homie/686f6d6965/temperature/$type → temperature
homie/686f6d6965/temperature/$name → Bedroom Temperature Node
homie/686f6d6965/temperature/$properties → degrees
homie/686f6d6965/temperature/degrees/$settable → false
homie/686f6d6965/temperature/degrees/$unit → C
homie/686f6d6965/temperature/degrees/$datatype → float
homie/686f6d6965/temperature/degrees/$name → Bedroom Temperature
homie/686f6d6965/temperature/degrees/$format → -20.0:60
homie/686f6d6965/temperature/degrees → 12.07

homie/686f6d6965/humidity/$type → humidity
homie/686f6d6965/humidity/$name → Bedroom Humidity Node
homie/686f6d6965/humidity/$properties → percentage
homie/686f6d6965/humidity/percentage/$settable → false
homie/686f6d6965/humidity/percentage/$unit → %
homie/686f6d6965/humidity/percentage/$datatype → integer
homie/686f6d6965/humidity/percentage/$name → Bedroom Humidity
homie/686f6d6965/humidity/percentage/$format → 0:100
homie/686f6d6965/humidity/percentage → 79

Mobile App

You can chose from multiple Apps for Android / iOS / Desktop to display the sensor data. You have to subscribe to the topics you are interested in, for example homie/686f6d6965/humidity/percentage and homie/686f6d6965/temperature/degrees.