Metadata-Version: 2.4
Name: aiogrilla
Version: 0.2.0
Summary: Async client for Grilla Grills Alpha Connect smokers (unofficial)
Project-URL: Homepage, https://github.com/zwrose/aiogrilla
Project-URL: Source, https://github.com/zwrose/aiogrilla
Project-URL: Issues, https://github.com/zwrose/aiogrilla/issues
Project-URL: Changelog, https://github.com/zwrose/aiogrilla/blob/main/CHANGELOG.md
Author: zwrose
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: asyncio,aws-iot,bbq,grill,grilla,home-assistant,mqtt,smoker
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.9
Requires-Dist: awsiotsdk<2,>=1.21
Requires-Dist: boto3<2,>=1.34
Requires-Dist: pycognito>=2024.5.1
Provides-Extra: dev
Requires-Dist: pyright>=1.1; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# aiogrilla

[![PyPI version](https://img.shields.io/pypi/v/aiogrilla.svg)](https://pypi.org/project/aiogrilla/)
[![Python versions](https://img.shields.io/pypi/pyversions/aiogrilla.svg)](https://pypi.org/project/aiogrilla/)
[![CI](https://img.shields.io/github/actions/workflow/status/zwrose/aiogrilla/ci.yml?branch=main&label=CI&logo=github)](https://github.com/zwrose/aiogrilla/actions/workflows/ci.yml)
[![License](https://img.shields.io/pypi/l/aiogrilla.svg)](https://github.com/zwrose/aiogrilla/blob/main/LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

Unofficial async Python client for Grilla Grills Alpha Connect smokers.
It provides read-only access to live grill and probe temperatures, cook status,
cook mode, and the cook timer via the vendor's cloud service.

## Disclaimer

**aiogrilla is an unofficial, third-party library. It is not affiliated with,
endorsed by, or supported by Grilla Grills or Fahrenheit Technologies, Inc.
"Grilla" is used here as a nominative reference to identify the product this
library works with. This library is provided as-is and may stop working at any
time if the vendor changes their cloud service. Use is entirely at your own risk,
with no warranty of any kind.**

## Install

```bash
pip install aiogrilla
```

### From source

```bash
git clone https://github.com/zwrose/aiogrilla.git
cd aiogrilla
pip install -e .
```

## Usage

Run the bundled example — it prompts for your password and never stores it:

```bash
export GRILLA_EMAIL="your@email.com"   # optional; the example prompts if unset
python examples/dump_state.py
```

Or use the library directly. Log in **once** with your password to obtain a refresh
token, then persist and reuse that token — the password is never needed again and never
has to be stored:

```python
import asyncio
import getpass
from aiogrilla import GrillaClient


async def main(email: str, password: str) -> None:
    client = GrillaClient()
    refresh = await client.async_login_with_password(email, password)
    # Persist `refresh` securely (e.g. a secrets manager) and reconnect later with
    # GrillaClient(refresh_token=refresh) — no password storage required.
    grills = await client.async_get_grills()
    print("grills:", grills)
    if not grills:
        return
    grill = grills[0]
    client.on_state(grill.id, lambda s: print("state:", s.mode, s.grill_temp, s.probe_temp))
    client.on_availability(grill.id, lambda a: print("available:", a))
    await client.async_connect()
    await asyncio.sleep(30)
    await client.async_disconnect()


asyncio.run(main(input("Grilla email: "), getpass.getpass("Grilla password: ")))
```

## What it does / v1 scope

aiogrilla is intentionally read-only in its first release:

- Live grill temperature and target temperature
- Probe temperature(s) and target probe temperature(s)
- Cook status / operating mode (off, igniting, running, hold, shutdown, etc.)
- Cook timer (total and remaining seconds)
- Grill availability (connected / disconnected)

Write operations (set temperature, start/stop cook, etc.) are out of scope for
v1.

## Caveats

The field mapping is best-effort and validated against a limited set of devices
and firmware. Some fields (probe 2, turntable, alarm range) may not apply to all
grill models or firmware versions. If you observe unexpected parsing behavior,
please open an issue with a **redacted** (no credentials or tokens) sample.

## Contributing

Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). This project
uses [Conventional Commits](https://www.conventionalcommits.org/) and
release-please, so commit messages drive versioning and the changelog.

## License

Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
