Add prototype doc

This commit is contained in:
Edward Brown 2026-04-29 10:47:13 +01:00
parent 8dc96d708d
commit f42becceb0
24 changed files with 657 additions and 51 deletions

99
docs/controls.md Normal file
View file

@ -0,0 +1,99 @@
`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.
# Supported Controls
## Button
A button in Home Assistant that can be pressed to trigger an action in your script.
- **Platform**: `button`
- **Overridable Methods**:
- `command(self, value)`: Called when the button is pressed in Home Assistant.
```python
from haco import Button
class MyButton(Button):
def command(self, value):
print("Button was pressed!")
```
## Switch
A toggle switch that can be turned on or off.
- **Platform**: `switch`
- **Overridable Methods**:
- `state(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.
```python
from haco import Switch
class MySwitch(Switch):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self._on = False
def state(self, value):
return self._on
def command(self, value):
self._on = value
print(f"Switch is now {'ON' if self._on else 'OFF'}")
```
## Sensor
A read-only sensor that displays a value in Home Assistant.
- **Platform**: `sensor`
- **Overridable Methods**:
- `state(self, value)`: Should return the current value of the sensor.
```python
from haco import Sensor
class MySensor(Sensor):
def state(self, value):
return 42 # Or some dynamic value
```
## Number
A slider or input box for numeric values.
- **Platform**: `number`
- **Overridable Methods**:
- `state(self, value)`: Should return the current numeric value.
- `command(self, value)`: Called when the value is changed in Home Assistant.
## Select
A dropdown list of options.
- **Platform**: `select`
- **Parameters**: `options` (list of strings)
- **Overridable Methods**:
- `state(self, value)`: Should return the currently selected option.
- `command(self, value)`: Called when a new option is selected in Home Assistant.
# Customizing Controls
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:
```python
btn = Button(name="Panic Button", icon="alert")
```
# Advanced: Custom Capabilities
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`.

7
docs/index.md Normal file
View file

@ -0,0 +1,7 @@
!!! tip "How Do I Get Started?"
See the [Quick Start](quick-start.md) section.
--8<--
README.md
--8<--

48
docs/quick-start.md Normal file
View file

@ -0,0 +1,48 @@
The easiest way to get started with `haco` is to define a simple device and run the client.
# Installation
`haco` can be installed via pip:
```bash
pip install haco
```
!!! tip "MQTT Broker Required"
`haco` communicates with Home Assistant via MQTT. Ensure you have an MQTT broker (like Mosquitto) running and accessible.
# Basic Usage
Here is a minimal example that creates a device with a single button:
```python
import asyncio
from haco import Button, Device, ClientHaco
async def main():
# 1. Define your controls
btn = Button(name="My Awesome Button")
# 2. Group them into a device
device = Device(name="My Cool Device", controls=[btn])
# 3. Create and start the client
# Replace 'mqtt.service' with your MQTT broker's address
client = ClientHaco(hostname='mqtt.service', device=device)
print("Starting haco client...")
await client.start()
if __name__ == "__main__":
asyncio.run(main())
```
# What Happens Next?
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](controls.md) for more details).