From 10fbb343fcdb084ae0f8cc2004432da8174a9e02 Mon Sep 17 00:00:00 2001 From: Edward Brown Date: Sat, 15 Aug 2026 12:35:18 +0100 Subject: [PATCH] Release documentation version 0.3.10-alpha000 --- index.html | 2 +- search/search_index.json | 2 +- sitemap.xml.gz | Bin 127 -> 127 bytes 3 files changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index b8d09b0..8cfff37 100644 --- a/index.html +++ b/index.html @@ -602,7 +602,7 @@

See the Quick Start section.

haco Home Assistant Control Objects

-

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.

+

haco greatly simplifies 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.

Why MQTT?

You might wonder why we use MQTT instead of directly using Home Assistant's APIs. The reason is flexibility: using MQTT allows diff --git a/search/search_index.json b/search/search_index.json index c82a505..ef4cb2a 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Home","text":"

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.

"},{"location":"#why-would-i-want-such-a-thing","title":"Why Would I Want Such a Thing?","text":"

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.

"},{"location":"#how-it-works","title":"How it Works","text":"

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.

"},{"location":"#documentation","title":"Documentation","text":"

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.

"},{"location":"controls/#supported-controls","title":"Supported Controls","text":""},{"location":"controls/#button","title":"Button","text":"

A button in Home Assistant that can be pressed to trigger an action in your script.

from haco import Button\n\nclass MyButton(Button):\n    def command(self, value):\n        print(\"Button was pressed!\")\n
"},{"location":"controls/#switch","title":"Switch","text":"

A toggle switch that can be turned on or off.

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'}\")\n
"},{"location":"controls/#sensor","title":"Sensor","text":"

A read-only sensor that displays a value in Home Assistant.

from haco import Sensor\n\nclass MySensor(Sensor):\n    def state(self, value):\n        return 42  # Or some dynamic value\n
"},{"location":"controls/#number","title":"Number","text":"

A slider or input box for numeric values.

"},{"location":"controls/#select","title":"Select","text":"

A dropdown list of options.

"},{"location":"controls/#customizing-controls","title":"Customizing Controls","text":"

Most controls accept common parameters in their constructor:

Example:

btn = Button(name=\"Panic Button\", icon=\"alert\")\n
"},{"location":"controls/#advanced-custom-capabilities","title":"Advanced: Custom Capabilities","text":"

For 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.

"},{"location":"quick-start/","title":"Quick start","text":"

The easiest way to get started with haco is to define a simple device and run the client.

"},{"location":"quick-start/#installation","title":"Installation","text":"

haco can be installed via pip:

pip install haco\n

MQTT Broker Required

haco communicates with Home Assistant via MQTT. Ensure you have an MQTT broker (like Mosquitto) running and accessible.

"},{"location":"quick-start/#basic-usage","title":"Basic Usage","text":"

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())\n
"},{"location":"quick-start/#what-happens-next","title":"What Happens Next?","text":"
  1. Discovery: When the script runs, it sends discovery messages to Home Assistant.
  2. Entity Created : A new device named \"My Cool Device\" will appear in Home Assistant with a button entity named \"My Awesome Button\".
  3. Control: When you press the button in the Home Assistant UI, haco 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).
"},{"location":"changelog/0.3.0/","title":"0.3.0","text":""},{"location":"changelog/0.3.4/","title":"0.3.4","text":""}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Home","text":"

How Do I Get Started?

See the Quick Start section.

"},{"location":"#haco-home-assistant-control-objects","title":"haco Home Assistant Control Objects","text":"

haco greatly simplifies 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.

"},{"location":"#why-would-i-want-such-a-thing","title":"Why Would I Want Such a Thing?","text":"

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.

"},{"location":"#how-it-works","title":"How it Works","text":"

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.

"},{"location":"#documentation","title":"Documentation","text":"

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.

"},{"location":"controls/#supported-controls","title":"Supported Controls","text":""},{"location":"controls/#button","title":"Button","text":"

A button in Home Assistant that can be pressed to trigger an action in your script.

from haco import Button\n\nclass MyButton(Button):\n    def command(self, value):\n        print(\"Button was pressed!\")\n
"},{"location":"controls/#switch","title":"Switch","text":"

A toggle switch that can be turned on or off.

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'}\")\n
"},{"location":"controls/#sensor","title":"Sensor","text":"

A read-only sensor that displays a value in Home Assistant.

from haco import Sensor\n\nclass MySensor(Sensor):\n    def state(self, value):\n        return 42  # Or some dynamic value\n
"},{"location":"controls/#number","title":"Number","text":"

A slider or input box for numeric values.

"},{"location":"controls/#select","title":"Select","text":"

A dropdown list of options.

"},{"location":"controls/#customizing-controls","title":"Customizing Controls","text":"

Most controls accept common parameters in their constructor:

Example:

btn = Button(name=\"Panic Button\", icon=\"alert\")\n
"},{"location":"controls/#advanced-custom-capabilities","title":"Advanced: Custom Capabilities","text":"

For 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.

"},{"location":"quick-start/","title":"Quick start","text":"

The easiest way to get started with haco is to define a simple device and run the client.

"},{"location":"quick-start/#installation","title":"Installation","text":"

haco can be installed via pip:

pip install haco\n

MQTT Broker Required

haco communicates with Home Assistant via MQTT. Ensure you have an MQTT broker (like Mosquitto) running and accessible.

"},{"location":"quick-start/#basic-usage","title":"Basic Usage","text":"

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())\n
"},{"location":"quick-start/#what-happens-next","title":"What Happens Next?","text":"
  1. Discovery: When the script runs, it sends discovery messages to Home Assistant.
  2. Entity Created : A new device named \"My Cool Device\" will appear in Home Assistant with a button entity named \"My Awesome Button\".
  3. Control: When you press the button in the Home Assistant UI, haco 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).
"},{"location":"changelog/0.3.0/","title":"0.3.0","text":""},{"location":"changelog/0.3.4/","title":"0.3.4","text":""}]} \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index 7a87a36260cfb17d467121c42bdf0b50287c5de9..d240d53a38bf83f4e1976065c5477c6a68e9751f 100644 GIT binary patch delta 13 Ucmb=gXP58h;9yu&Kasrx02<>1`v3p{ delta 13 Ucmb=gXP58h;9y|ooXB1Q02Rmr-T(jq