Metadata-Version: 2.4
Name: aio-powerrise-api
Version: 0.1.0.dev1
Summary: Async Python API for Hunter Douglas PowerRise shade systems using the Platinum Hub
Author: James Wilkinson
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE.md
License-File: NOTICE.md
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# aio-powerrise-api

Async Python API for Hunter Douglas PowerRise® shade systems.

This library communicates with a PowerRise® Platinum bridge (PlatLink-PDBU) over a
plain-text TCP protocol on port 522 and exposes an API that is intentionally
similar to [aio-powerview-api](https://github.com/sander76/aio-powerview-api) so
that it can be integrated into Home Assistant with minimal effort.

## Quick Start

```python
import asyncio
from aiopowerrise import Hub

async def main():
    hub = Hub("192.168.1.100")
    await hub.connect()

    # Get all data
    house = await hub.get_data()

    # List shades
    for shade_id, shade in house.shades.items():
        print(f"Shade {shade_id}: {shade.name} position={shade.position}")

    # Move a shade (0-100%)
    await hub.shades.move(shade_id=1, position=50)

    # Activate a scene
    await hub.scenes.activate(scene_id=0)

    await hub.close()

asyncio.run(main())
```

## CLI

A command-line tool is included for testing and debugging:

```bash
# Discover hubs on the network
powerrise-cli discover

# Get all data from hub
powerrise-cli --host 192.168.1.100 get-data

# List shades
powerrise-cli --host 192.168.1.100 shades

# Move a shade
powerrise-cli --host 192.168.1.100 move-shade --id 1 --position 50

# Activate a scene
powerrise-cli --host 192.168.1.100 activate-scene --id 0

# List scenes
powerrise-cli --host 192.168.1.100 scenes

# List rooms
powerrise-cli --host 192.168.1.100 rooms
```

## Architecture

The library follows the same pattern as `aio-powerview-api`:

- **Hub** – Top-level entry point; manages connection to the bridge
- **Shades** – Collection manager for shade resources
- **Scenes** – Collection manager for scene resources
- **Rooms** – Collection manager for room resources
- **BaseShade** – Individual shade resource with move/open/close/stop
- **Scene** – Individual scene resource with activate
- **Room** – Individual room resource

### Protocol

The PowerRise® Platinum bridge speaks a simple line-based text protocol on TCP
port 522.  Commands start with `$` and fields are separated by `-`.

| Command | Description |
|---------|-------------|
| `$dat` | Retrieve all data (rooms, shades, scenes, positions, etc.) |
| `$dmy` | Keep-alive / dummy ping |
| `$pss{shade}-{feature}-{level}-` | Set shade position (level 0-255) |
| `$rls` | Release shade (after position command) |
| `$inm{scene}-` | Invoke / activate a scene |
| `$mrp{scene}-{room}-{cmd}-{level}-0-` | Position scene+room |
| `$sml{scene}-{shade}-{linked}-` | Set scene link |

### Data Parsing

After sending `$dat`, the hub streams lines prefixed with `$` identifiers:

| Prefix | Content |
|--------|---------|
| `$cr` | Room definition |
| `$cs` | Shade definition |
| `$cm` | Scene definition |
| `$cp` | Shade position |
| `$cq` | Scene-shade link |
| `$cx` | Scene-room position |
| `$ct` | House title |
| `$ca` | Timed event |
| `$firm` | Firmware version |
| `$LEDl` | LED brightness |
| `$upd01-` | End of data marker |

## Development

```bash
pip install -e ".[dev]"
pytest
```
