Skip to content

EAGrahamJr/ha-minimqtt

Repository files navigation

ha-minimqtt

HomeAssistant abstraction for use with MQTT. Specifically aimed at using CircuitPython on microcontrollers with asyncio and minimqtt, but should be playable on other platforms.

Note: I really just wanted an "easy" learning IR remote, but not apparently available open-source.

  • Defines HA entities so that actual MQTT communication is abstracted
  • Uses the HA discovery mechanism to register and un-register entities
  • Wraps an MQTT client with delegation
    • Swap out clients easier
    • Allows use with things like asyncio without modifying entities
    • Testing!

How to Use This Library

The CircuitPython Client contains a static factory that creates a "wrapper" that can be used with the HA entities.

Sample settings.toml

CIRCUITPY_WIFI_SSID="MY SSID"
CIRCUITPY_WIFI_PASSWORD="MY PASSWORD"
HAMM_BROKRE="192.168.1.4"

# default values
HAMM_BROKER_PORT = 1883     # int
HAMM_LOOP_SLEEP = 0.1       # seconds as float
HAMM_LOOP_TIMEOUT = 1.0     # seconds as float
HAMM_RECONNECT_DELAY = 5.0  # seconds as float

# if not set, will use CircuitPython defaults
# (really should be set)
HAMM_CLIENT_ID = "my_name"

Sample Code

  1. Copy the utils.py file to your CIRCUITPY drive
  2. Copy the appropriate example file to CIRCUITPY/code.py
  3. Should be running

Note that updating handlers/entities "states" via public methods should follow up by manually invoking the entity send_current_state.

Design Philosophy

  • This is not intended to replace ESPHome, but rather provide an easier programming interface for HA.
  • It is primarily intended for the CircuitPython environment, but should (?) work elsewhere.
    • This module is heavily "class-based" as state needs to be preserved and consistent across all the things.
  • State should be settable from the system and should be appropriately formatted and "automagically" published to HA where possible.
  • Entities that receive from HA should use delegation (e.g. CommandHandler) to interface with the other systems.
  • Everything is extensible: this is a start -- I do not have all 20+ MQTT entities currently supported by HA, so ... have fun?

Current Status

I think I have the project set up correctly?

Origin

Since I come from an Object-Oriented and functional background, I originally crafted these classes in Kotlin. I ran across a situation where I could not run a JVM, so I turned to the "next easiest thing" that seemed logical and went with Python. And, since I am more familiar with and using CircuitPython, a conversion of sorts seemed pretty straight-forward.

This is where it got interesting -- I used a couple of different "AI code converters" to migrate the Kotlin code to Python. It was a decent starting point, but it is not anywhere near complete, nor does it actually capture the complexities of the Python language. (Throw in pylint and you've got a right nightmare.)

About

HomeAssistant abstraction for use with minimqtt and asyncio

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published