diff --git a/changelog/index.html b/changelog/index.html new file mode 100644 index 0000000..b7088fe --- /dev/null +++ b/changelog/index.html @@ -0,0 +1,369 @@ + + + + + + + + + + + + + + + + + + + + + + Changelog - haco + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + +

Changelog

+ +
    +
  • Refactored core models from dataclass to Pydantic across active entities (Base, Device, Control, Capability, topic models, and concrete control types like Switch, Climate, Sensor, etc.).
    • +
  • Replaced dataclass-specific field metadata (metadata=dict(exclude=True), field(...), __post_init__) with native Pydantic patterns (Field(...), model_post_init, class inheritance from corio.dm.Base).
    • +
  • Updated parent/back-reference handling to follow the parent-typing pattern, including explicit in-__init__ imports for forward references (e.g. Device.parent: ClientHaco | None).
    • +
  • Reworked 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.
    • +
  • Cleaned up dataclass leftovers by removing the unused Metadata helper from haco/utils.py and simplifying related imports.
    • +
  • Added packaging metadata and testing support updates: pyproject.toml project metadata/uv source config, setup.py test extras (pytest, pytest-cov), and initial haco/tests package scaffolding.
    • +
+ + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/search/search_index.json b/search/search_index.json index 5824ae0..6b97dc2 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":"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.

"},{"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).
"}]} \ 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 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":"changelog/","title":"Changelog","text":""},{"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.

"},{"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).
"}]} \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index 2e04518..1256f85 100644 Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ