How Do I Get Started?
See the Quick Start section.
"},{"location":"#haco-home-assistant-control-objects","title":"haco Home Assistant Control Objects","text":"haco is a to greatly simplify the process of exposing Home Assistant controls (e.g. Pull-down Lists, Number Sliders, Sensors, etc.) from a device - and handling the communication between both sides.
While the current implementation is in Python, the capability definitions for controls are designed to be shared across different languages. Support for additional languages (namely native support for Tasmota Berry) is planned.
"},{"location":"#why-mqtt","title":"Why MQTT?","text":"You might wonder why we use MQTT instead of directly using Home Assistant's APIs. The reason is flexibility: using MQTT allows haco to target any device or environment that has an MQTT client, not just those that can easily make HTTP requests or run a full HA integration. This makes it ideal for lightweight embedded systems and cross-platform utility.
Integrating custom hardware or scripts with Home Assistant often involves a lot of boilerplate: defining MQTT topics, crafting JSON payloads for discovery, and managing state updates. haco handles the heavy lifting, letting you define your device and its controls in clean, declarative Python.
If you're building a custom IoT device, a script to monitor your system, or just want a simpler way to bridge your code to Home Assistant, then you might find haco useful.
haco uses MQTT to communicate with Home Assistant. It automatically generates the discovery configurations required for Home Assistant to \"see\" your device and its entities. All you need to do is define a Device with some Controls and start the ClientHaco.
See Documentation
"},{"location":"controls/","title":"Control Types","text":"haco provides several control types that correspond to Home Assistant platforms. Each control typically has a state and a command method that you can override to handle communication.
A button in Home Assistant that can be pressed to trigger an action in your script.
buttoncommand(self, value): Called when the button is pressed in Home Assistant.from haco import Button\n\nclass MyButton(Button):\n def command(self, value):\n print(\"Button was pressed!\")\nA toggle switch that can be turned on or off.
switchstate(self, value): Should return the current state of the switch (True for on, False for off).command(self, value): Called when the switch is toggled in Home Assistant.from haco import Switch\n\nclass MySwitch(Switch):\n def __init__(self, **kwargs):\n super().__init__(**kwargs)\n self._on = False\n\n def state(self, value):\n return self._on\n\n def command(self, value):\n self._on = value\n print(f\"Switch is now {'ON' if self._on else 'OFF'}\")\nA read-only sensor that displays a value in Home Assistant.
sensorstate(self, value): Should return the current value of the sensor.from haco import Sensor\n\nclass MySensor(Sensor):\n def state(self, value):\n return 42 # Or some dynamic value\nA slider or input box for numeric values.
numberstate(self, value): Should return the current numeric value.command(self, value): Called when the value is changed in Home Assistant.A dropdown list of options.
selectoptions (list of strings)state(self, value): Should return the currently selected option.command(self, value): Called when a new option is selected in Home Assistant.Most controls accept common parameters in their constructor:
name: The display name in Home Assistant.icon: An optional MDI icon (e.g., mdi:lightbulb or just lightbulb).Example:
btn = Button(name=\"Panic Button\", icon=\"alert\")\nFor more complex platforms like climate, haco uses \"Capabilities\". A capability groups a state and a command topic. You can see how these are implemented in haco/climate.py.
The easiest way to get started with haco is to define a simple device and run the client.
haco can be installed via pip:
pip install haco\nMQTT Broker Required
haco communicates with Home Assistant via MQTT. Ensure you have an MQTT broker (like Mosquitto) running and accessible.
Here is a minimal example that creates a device with a single button:
import asyncio\nfrom haco import Button, Device, ClientHaco\n\nasync def main():\n # 1. Define your controls\n btn = Button(name=\"My Awesome Button\")\n\n # 2. Group them into a device\n device = Device(name=\"My Cool Device\", controls=[btn])\n\n # 3. Create and start the client\n # Replace 'mqtt.service' with your MQTT broker's address\n client = ClientHaco(hostname='mqtt.service', device=device)\n\n print(\"Starting haco client...\")\n await client.start()\n\nif __name__ == \"__main__\":\n asyncio.run(main())\nhaco will receive the command. You can then handle this command in your Python script by overriding the command method or providing a callback (see Control Types for more details).dataclass to Pydantic across active entities (Base, Device, Control, Capability, topic models, and concrete control types like Switch, Climate, Sensor, etc.).metadata=dict(exclude=True), field(...), __post_init__) with native Pydantic patterns (Field(...), model_post_init, class inheritance from corio.dm.Base).__init__ imports for forward references (e.g. Device.parent: ClientHaco | None).Base.model_dump() to preserve discovery behavior by merging class DATA, defaulting to exclude_none=True, and excluding runtime extra attributes so dynamic callbacks do not leak into HA announce payloads.Metadata helper from haco/utils.py and simplifying related imports.pyproject.toml project metadata/uv source config, setup.py test extras (pytest, pytest-cov), and initial haco/tests package scaffolding.corio module refactors by switching imports to current paths (corio.iterator, corio.jsn, corio.datatype, and corio.logs) across capabilities, control serialization, converters, and logging setup.haco/tests/test_pydantic_models.py coverage to verify Home Assistant announce payload shape for Switch and Climate, runtime-attribute exclusion from model_dump(), and parent/subscription wiring behavior.How Do I Get Started?
See the Quick Start section.
"},{"location":"#haco-home-assistant-control-objects","title":"haco Home Assistant Control Objects","text":"haco is a to greatly simplify the process of exposing Home Assistant controls (e.g. Pull-down Lists, Number Sliders, Sensors, etc.) from a device - and handling the communication between both sides.
While the current implementation is in Python, the capability definitions for controls are designed to be shared across different languages. Support for additional languages (namely native support for Tasmota Berry) is planned.
"},{"location":"#why-mqtt","title":"Why MQTT?","text":"You might wonder why we use MQTT instead of directly using Home Assistant's APIs. The reason is flexibility: using MQTT allows haco to target any device or environment that has an MQTT client, not just those that can easily make HTTP requests or run a full HA integration. This makes it ideal for lightweight embedded systems and cross-platform utility.
Integrating custom hardware or scripts with Home Assistant often involves a lot of boilerplate: defining MQTT topics, crafting JSON payloads for discovery, and managing state updates. haco handles the heavy lifting, letting you define your device and its controls in clean, declarative Python.
If you're building a custom IoT device, a script to monitor your system, or just want a simpler way to bridge your code to Home Assistant, then you might find haco useful.
haco uses MQTT to communicate with Home Assistant. It automatically generates the discovery configurations required for Home Assistant to \"see\" your device and its entities. All you need to do is define a Device with some Controls and start the ClientHaco.
See Documentation
"},{"location":"controls/","title":"Controls","text":"haco provides several control types that correspond to Home Assistant platforms. Each control typically has a state and a command method that you can override to handle communication.
A button in Home Assistant that can be pressed to trigger an action in your script.
buttoncommand(self, value): Called when the button is pressed in Home Assistant.from haco import Button\n\nclass MyButton(Button):\n def command(self, value):\n print(\"Button was pressed!\")\nA toggle switch that can be turned on or off.
switchstate(self, value): Should return the current state of the switch (True for on, False for off).command(self, value): Called when the switch is toggled in Home Assistant.from haco import Switch\n\nclass MySwitch(Switch):\n def __init__(self, **kwargs):\n super().__init__(**kwargs)\n self._on = False\n\n def state(self, value):\n return self._on\n\n def command(self, value):\n self._on = value\n print(f\"Switch is now {'ON' if self._on else 'OFF'}\")\nA read-only sensor that displays a value in Home Assistant.
sensorstate(self, value): Should return the current value of the sensor.from haco import Sensor\n\nclass MySensor(Sensor):\n def state(self, value):\n return 42 # Or some dynamic value\nA slider or input box for numeric values.
numberstate(self, value): Should return the current numeric value.command(self, value): Called when the value is changed in Home Assistant.A dropdown list of options.
selectoptions (list of strings)state(self, value): Should return the currently selected option.command(self, value): Called when a new option is selected in Home Assistant.Most controls accept common parameters in their constructor:
name: The display name in Home Assistant.icon: An optional MDI icon (e.g., mdi:lightbulb or just lightbulb).Example:
btn = Button(name=\"Panic Button\", icon=\"alert\")\nFor more complex platforms like climate, haco uses \"Capabilities\". A capability groups a state and a command topic. You can see how these are implemented in haco/climate.py.
The easiest way to get started with haco is to define a simple device and run the client.
haco can be installed via pip:
pip install haco\nMQTT Broker Required
haco communicates with Home Assistant via MQTT. Ensure you have an MQTT broker (like Mosquitto) running and accessible.
Here is a minimal example that creates a device with a single button:
import asyncio\nfrom haco import Button, Device, ClientHaco\n\nasync def main():\n # 1. Define your controls\n btn = Button(name=\"My Awesome Button\")\n\n # 2. Group them into a device\n device = Device(name=\"My Cool Device\", controls=[btn])\n\n # 3. Create and start the client\n # Replace 'mqtt.service' with your MQTT broker's address\n client = ClientHaco(hostname='mqtt.service', device=device)\n\n print(\"Starting haco client...\")\n await client.start()\n\nif __name__ == \"__main__\":\n asyncio.run(main())\nhaco will receive the command. You can then handle this command in your Python script by overriding the command method or providing a callback (see Control Types for more details).dataclass to Pydantic across active entities (Base, Device, Control, Capability, topic models, and concrete control types like Switch, Climate, Sensor, etc.).metadata=dict(exclude=True), field(...), __post_init__) with native Pydantic patterns (Field(...), model_post_init, class inheritance from corio.dm.Base).__init__ imports for forward references (e.g. Device.parent: ClientHaco | None).Base.model_dump() to preserve discovery behavior by merging class DATA, defaulting to exclude_none=True, and excluding runtime extra attributes so dynamic callbacks do not leak into HA announce payloads.Metadata helper from haco/utils.py and simplifying related imports.pyproject.toml project metadata/uv source config, setup.py test extras (pytest, pytest-cov), and initial haco/tests package scaffolding.corio module refactors by switching imports to current paths (corio.iterator, corio.jsn, corio.datatype, and corio.logs) across capabilities, control serialization, converters, and logging setup.haco/tests/test_pydantic_models.py coverage to verify Home Assistant announce payload shape for Switch and Climate, runtime-attribute exclusion from model_dump(), and parent/subscription wiring behavior.