Microhomie

Microhomie is a MicroPython framework for Homie, a lightweight MQTT convention for the IoT. Main target for Microhomie is the ESP8266 device and has been well tested and used on ESP32.

Microhomie v3 implements Homie v4.0.0.

Read the Microhomie documentation to get started.

Learn from our examples until we have a "howto build nodes" section in the documentation or join the #microhomie channel on the MicroPython Slack community and chat with us.

Binaries can be verified with minisign and the following public key:

RWTwPeRvouNzP+mcL1t7QDTnKz96i3Kuf95fjpE28szMq8OTycMmiTzX

Update from v2

Microhomie v3 has some breaking changes you should be aware of before update.

• Microhomie v3 only supports the new LFS2 filesystem. For update you must erase and reflash your device.
• You may need to update your asyncio coroutines as of the new Micropython asyncio v3. Peter Hinch's has a great asyncio v3 update guide
• New asyncio V3 primitives from Peter Hinch micropython-async for switch and pushbutton.
• The utils module was refactored to homie.network.

MicroPython changes

• btree and vfat support disabled to save some space
• AccessPoint SSID changed to Microhomie-MAC with the secret microhomiE
• inisetup.py writes a custom boot.py

Install

Download the latest image and flash it like any MicroPython image to your ESP8266 device. I.E:

esptool --port PORT --baud 460800 write_flash --flash_size=detect --verify -fm dio 0x0 microhomie-esp8266-VERSION.bin

Make your changes in settings.example.py and copy this file as settings.py to your device. You can now test our example nodes from examples/, just copy the main.py to your device. Start with the examples/led node to turn on and off the on-board LED.

Example

This is a basic example to power the on-board LED from an ESP8266 development board:

import settings

from machine import Pin

from homie.node import HomieNode
from homie.device import HomieDevice
from homie.property import HomieProperty
from homie.constants import BOOLEAN, FALSE, TRUE


# Reversed values map for the esp8266 boards on-board LED
ONOFF = {FALSE: 1, TRUE: 0}


# Initialize the pin for the onboard LED
LED = Pin(2, Pin.OUT, value=1)


# The on_message handler to power the led
def toggle_led(topic, payload, retained):
    LED(ONOFF[payload])


def main():
    # Initialize the Homie device
    device = HomieDevice(settings)

    # Initialize the Homie node for the on-board LED
    led_node = HomieNode(id="led", name="On-board LED", type="LED",)

    # Initialize the Homie property to power on/off the led
    led_power = HomieProperty(
        id="power",
        name="Power",
        settable=True,
        datatype=BOOLEAN,
        default=FALSE,
        on_message=toggle_led,
    )

    # Add the power property to the node
    led_node.add_property(led_power)

    # Add the led node to the device
    device.add_node(led_node)

    # Run
    device.run_forever()


if __name__ == "__main__":
    main()

Build esp8266 image

To build your own Microhomie image for the ESP8266 device, run:

make bootstrap
make
make deploy PORT=/dev/ttyUSBX

Known issues

• No SSL support for now

Included libraries

• mqtt_as.py by Peter Hinch but we use the patched version from Kevin Köck. Kevins version has support for a keyword based configuration and unsubscribe.
• asyncio V3 primitives from Peter Hinch micropython-async repository.