https://github.com/microhomie/microhomie

MicroPython implementation of the Homie MQTT convention for IoT.
https://github.com/microhomie/microhomie

conventions esp32 esp8266 framework home-automation homie iot micropython mqtt

Last synced: 3 days ago
JSON representation

MicroPython implementation of the Homie MQTT convention for IoT.

• Host: GitHub
• URL: https://github.com/microhomie/microhomie
• Owner: microhomie
• License: mit
• Created: 2017-12-18T10:38:23.000Z (almost 7 years ago)
• Default Branch: master
• Last Pushed: 2021-01-18T13:33:28.000Z (almost 4 years ago)
• Last Synced: 2024-04-22T12:33:05.041Z (7 months ago)
• Topics: conventions, esp32, esp8266, framework, home-automation, homie, iot, micropython, mqtt
• Language: Python
• Homepage: https://www.microhomie.com/en/master/
• Size: 959 KB
• Stars: 79
• Watchers: 12
• Forks: 19
• Open Issues: 3
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGELOG.rst
  • License: LICENSE

Awesome Lists containing this project

• awesome-micropython - microhomie - MicroPython implementation of the Homie MQTT convention for IoT. (Libraries / Communications)

README

        
==========

Microhomie

==========

|build-status|

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:

.. code-block::

    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:

.. code-block:: shell

    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:

.. code-block:: python

    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:

.. code-block:: shell

    make bootstrap

    make

    make deploy PORT=/dev/ttyUSBX

Known issues

------------

* No SSL support for now

.. |build-status| image:: https://readthedocs.org/projects/microhomie/badge/?version=master

    :target: http://microhomie.readthedocs.io/en/master/?badge=master

    :alt: Documentation Status

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.