mirror of
https://github.com/fmtr/haco.git
synced 2026-11-21 07:26:25 -05:00
Add prototype doc
This commit is contained in:
parent
8dc96d708d
commit
f42becceb0
24 changed files with 657 additions and 51 deletions
99
docs/controls.md
Normal file
99
docs/controls.md
Normal 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
7
docs/index.md
Normal 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
48
docs/quick-start.md
Normal 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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue