haco/search/search_index.json

{"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":"<p>How Do I Get Started?</p> <p>See the Quick Start section.</p>"},{"location":"#haco-home-assistant-control-objects","title":"<code>haco</code> Home Assistant Control Objects","text":"<p><code>haco</code> 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.</p> <p>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.</p>"},{"location":"#why-mqtt","title":"Why MQTT?","text":"<p>You might wonder why we use MQTT instead of directly using Home Assistant's APIs. The reason is flexibility: using MQTT allows <code>haco</code> 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.</p>"},{"location":"#why-would-i-want-such-a-thing","title":"Why Would I Want Such a Thing?","text":"<p>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. <code>haco</code> handles the heavy lifting, letting you define your device and its controls in clean, declarative Python.</p> <p>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 <code>haco</code> useful.</p>"},{"location":"#how-it-works","title":"How it Works","text":"<p><code>haco</code> 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 <code>Device</code> with some <code>Controls</code> and start the <code>ClientHaco</code>.</p>"},{"location":"#documentation","title":"Documentation","text":"<p>See Documentation</p>"},{"location":"controls/","title":"Control Types","text":"<p><code>haco</code> provides several control types that correspond to Home Assistant platforms. Each control typically has a <code>state</code> and a <code>command</code> method that you can override to handle communication.</p>"},{"location":"controls/#supported-controls","title":"Supported Controls","text":""},{"location":"controls/#button","title":"Button","text":"<p>A button in Home Assistant that can be pressed to trigger an action in your script.</p> <ul> <li>Platform: <code>button</code></li> <li>Overridable Methods:<ul> <li><code>command(self, value)</code>: Called when the button is pressed in Home Assistant.</li> </ul> </li> </ul> <pre><code>from haco import Button\n\nclass MyButton(Button):\n    def command(self, value):\n        print(\"Button was pressed!\")\n</code></pre>"},{"location":"controls/#switch","title":"Switch","text":"<p>A toggle switch that can be turned on or off.</p> <ul> <li>Platform: <code>switch</code></li> <li>Overridable Methods:<ul> <li><code>state(self, value)</code>: Should return the current state of the switch (<code>True</code> for on, <code>False</code> for off).</li> <li><code>command(self, value)</code>: Called when the switch is toggled in Home Assistant.</li> </ul> </li> </ul> <pre><code>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</code></pre>"},{"location":"controls/#sensor","title":"Sensor","text":"<p>A read-only sensor that displays a value in Home Assistant.</p> <ul> <li>Platform: <code>sensor</code></li> <li>Overridable Methods:<ul> <li><code>state(self, value)</code>: Should return the current value of the sensor.</li> </ul> </li> </ul> <pre><code>from haco import Sensor\n\nclass MySensor(Sensor):\n    def state(self, value):\n        return 42  # Or some dynamic value\n</code></pre>"},{"location":"controls/#number","title":"Number","text":"<p>A slider or input box for numeric values.</p> <ul> <li>Platform: <code>number</code></li> <li>Overridable Methods:<ul> <li><code>state(self, value)</code>: Should return the current numeric value.</li> <li><code>command(self, value)</code>: Called when the value is changed in Home Assistant.</li> </ul> </li> </ul>"},{"location":"controls/#select","title":"Select","text":"<p>A dropdown list of options.</p> <ul> <li>Platform: <code>select</code></li> <li>Parameters: <code>options</code> (list of strings)</li> <li>Overridable Methods:<ul> <li><code>state(self, value)</code>: Should return the currently selected option.</li> <li><code>command(self, value)</code>: Called when a new option is selected in Home Assistant.</li> </ul> </li> </ul>"},{"location":"controls/#customizing-controls","title":"Customizing Controls","text":"<p>Most controls accept common parameters in their constructor:</p> <ul> <li><code>name</code>: The display name in Home Assistant.</li> <li><code>icon</code>: An optional MDI icon (e.g., <code>mdi:lightbulb</code> or just <code>lightbulb</code>).</li> </ul> <p>Example:</p> <pre><code>btn = Button(name=\"Panic Button\", icon=\"alert\")\n</code></pre>"},{"location":"controls/#advanced-custom-capabilities","title":"Advanced: Custom Capabilities","text":"<p>For more complex platforms like <code>climate</code>, <code>haco</code> uses \"Capabilities\". A capability groups a state and a command topic. You can see how these are implemented in <code>haco/climate.py</code>.</p>"},{"location":"quick-start/","title":"Quick Start","text":"<p>The easiest way to get started with <code>haco</code> is to define a simple device and run the client.</p>"},{"location":"quick-start/#installation","title":"Installation","text":"<p><code>haco</code> can be installed via pip:</p> <pre><code>pip install haco\n</code></pre> <p>MQTT Broker Required</p> <p><code>haco</code> communicates with Home Assistant via MQTT. Ensure you have an MQTT broker (like Mosquitto) running and accessible.</p>"},{"location":"quick-start/#basic-usage","title":"Basic Usage","text":"<p>Here is a minimal example that creates a device with a single button:</p> <pre><code>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</code></pre>"},{"location":"quick-start/#what-happens-next","title":"What Happens Next?","text":"<ol> <li>Discovery: When the script runs, it sends discovery messages to Home Assistant.</li> <li>Entity Created    : A new device named \"My Cool Device\" will appear in Home Assistant with a button entity named \"My Awesome Button\".</li> <li>Control: When you press the button in the Home Assistant UI,    <code>haco</code> will receive the command. You can then handle this command in your Python script by overriding the    <code>command</code> method or providing a callback (see Control Types for more details).</li> </ol>"},{"location":"changelog/0.3.0/","title":"0.3.0","text":"<ul> <li>Refactored core models from <code>dataclass</code> to Pydantic across active entities (<code>Base</code>, <code>Device</code>, <code>Control</code>, <code>Capability</code>, topic models, and concrete control types like <code>Switch</code>, <code>Climate</code>, <code>Sensor</code>, etc.).</li> <li>Replaced dataclass-specific field metadata (<code>metadata=dict(exclude=True)</code>, <code>field(...)</code>, <code>__post_init__</code>) with native Pydantic patterns (<code>Field(...)</code>, <code>model_post_init</code>, class inheritance from <code>corio.dm.Base</code>).</li> <li>Updated parent/back-reference handling to follow the parent-typing pattern, including explicit in-<code>__init__</code> imports for forward references (e.g. <code>Device.parent: ClientHaco | None</code>).</li> <li>Reworked <code>Base.model_dump()</code> to preserve discovery behavior by merging class <code>DATA</code>, defaulting to <code>exclude_none=True</code>, and excluding runtime extra attributes so dynamic callbacks do not leak into HA announce payloads.</li> <li>Cleaned up dataclass leftovers by removing the unused <code>Metadata</code> helper from <code>haco/utils.py</code> and simplifying related imports.</li> <li>Added packaging metadata and testing support updates: <code>pyproject.toml</code> project metadata/uv source config, <code>setup.py</code> test extras (<code>pytest</code>, <code>pytest-cov</code>), and initial <code>haco/tests</code> package scaffolding.</li> </ul>"}]}