aeraforhome 0.1.0__tar.gz

aeraforhome-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: aeraforhome
+Version: 0.1.0
+Summary: Python API for Aera for Home smart fragrance diffusers
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: aioresponses>=0.7; extra == "dev"
+
+# aeraforhome-api
+
+Unofficial Python client for the Aera for Home smart fragrance diffuser cloud API, reverse-engineered from the Android app (v2.3.6). Covers:
+
+- **Authentication**: email/password login via the Ayla Networks IoT platform, automatic token refresh on 401.
+- **Device control**: power on/off, intensity adjustment, timed fragrance sessions, schedule management.
+- **Device state**: fragrance name, remaining percentage, cartridge presence, error conditions.
+- **Fragrance catalog**: Mini fragrance lookup with names, codes, and QR URLs via Contentful CMS.
+
+This library is designed to power a Home Assistant integration, but has no dependency on Home Assistant and can be used standalone.
+
+## Installation
+
+```bash
+pip install aeraforhome
+```
+
+Or install from source:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+import asyncio
+from aera import AeraApi
+
+async def main():
+    api = AeraApi("your-email@example.com", "your-password")
+
+    try:
+        await api.login()
+
+        devices = await api.get_devices()
+        for device in devices:
+            props = await api.get_device_properties(device)
+            print(f"{device.device_name}: {device.fragrance_name} ({device.fragrance_remaining}%)")
+
+        # Control a device
+        await api.set_power(devices[0], True)
+        await api.set_intensity(devices[0], 5)
+
+        # Start a 60-minute session
+        await api.start_session(devices[0], 60)
+
+        # Get all Mini-compatible fragrances (for QR scanning)
+        fragrances = await api.get_mini_fragrances()
+        for f in fragrances:
+            print(f"{f['name']} ({f['code']}): {f['qr_url']}")
+
+    finally:
+        await api.close()
+
+asyncio.run(main())
+```
+
+## Supported Devices
+
+| Model | Type | Max Intensity |
+|-------|------|---------------|
+| Aera 1 | `aera1` | 10 |
+| Aera 2 | `aera2` | 10 |
+| Aera 3 | `aera3` | 10 |
+| Aera 3.1 | `aera31` | 10 |
+| Aera Mini | `aeraMini` | 5 |
+
+## API Methods
+
+| Method | Description |
+|--------|-------------|
+| `login()` | Authenticate with email/password |
+| `refresh_auth()` | Refresh the access token |
+| `get_devices()` | Fetch all devices (includes room names) |
+| `get_device_properties(device)` | Fetch current state for a device |
+| `set_power(device, on)` | Turn device on/off |
+| `set_intensity(device, level)` | Set fragrance intensity |
+| `start_session(device, minutes)` | Start a timed session |
+| `stop_session(device)` | Stop a running session |
+| `get_schedules(device)` | Fetch device schedules |
+| `update_schedule(device, key, data)` | Update a schedule |
+| `get_mini_fragrances()` | Get all Mini fragrance names, codes, and QR URLs |
+| `get_device_metadata()` | Fetch user-assigned room names and positions |
+| `sign_out()` | Sign out from the service |
+| `close()` | Close the HTTP session |
+
+## Device Properties
+
+| Property | Description |
+|----------|-------------|
+| `device_name` | User-assigned room name (falls back to product name) |
+| `device_type` | `DeviceType` enum |
+| `is_online` | Connection status |
+| `is_power_on` | Power state |
+| `intensity` | Current intensity level |
+| `fragrance_name` | Resolved fragrance name (via Contentful for Mini) |
+| `fragrance_color` | Hex color from fragrance catalog |
+| `fragrance_remaining` | Percentage remaining (0-100) |
+| `is_cartridge_present` | Whether a cartridge is inserted (full-size only) |
+| `session_active` | Whether a timed session is running |
+| `session_time_remaining` | Minutes left in session |
+| `has_error` | Whether the device has an error condition |
+
+## Scripts
+
+- **`example.py`** - Minimal usage example showing device listing and control.
+- **`test_local.py`** - Interactive test script that dumps all device properties including raw values, useful for debugging.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Disclaimer
+
+This is an unofficial, reverse-engineered client with no affiliation to Aera, Prolitec, or Ayla Networks. It may break if the upstream API changes.

aeraforhome-0.1.0/README.md

@@ -0,0 +1,119 @@
+# aeraforhome-api
+
+Unofficial Python client for the Aera for Home smart fragrance diffuser cloud API, reverse-engineered from the Android app (v2.3.6). Covers:
+
+- **Authentication**: email/password login via the Ayla Networks IoT platform, automatic token refresh on 401.
+- **Device control**: power on/off, intensity adjustment, timed fragrance sessions, schedule management.
+- **Device state**: fragrance name, remaining percentage, cartridge presence, error conditions.
+- **Fragrance catalog**: Mini fragrance lookup with names, codes, and QR URLs via Contentful CMS.
+
+This library is designed to power a Home Assistant integration, but has no dependency on Home Assistant and can be used standalone.
+
+## Installation
+
+```bash
+pip install aeraforhome
+```
+
+Or install from source:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+import asyncio
+from aera import AeraApi
+
+async def main():
+    api = AeraApi("your-email@example.com", "your-password")
+
+    try:
+        await api.login()
+
+        devices = await api.get_devices()
+        for device in devices:
+            props = await api.get_device_properties(device)
+            print(f"{device.device_name}: {device.fragrance_name} ({device.fragrance_remaining}%)")
+
+        # Control a device
+        await api.set_power(devices[0], True)
+        await api.set_intensity(devices[0], 5)
+
+        # Start a 60-minute session
+        await api.start_session(devices[0], 60)
+
+        # Get all Mini-compatible fragrances (for QR scanning)
+        fragrances = await api.get_mini_fragrances()
+        for f in fragrances:
+            print(f"{f['name']} ({f['code']}): {f['qr_url']}")
+
+    finally:
+        await api.close()
+
+asyncio.run(main())
+```
+
+## Supported Devices
+
+| Model | Type | Max Intensity |
+|-------|------|---------------|
+| Aera 1 | `aera1` | 10 |
+| Aera 2 | `aera2` | 10 |
+| Aera 3 | `aera3` | 10 |
+| Aera 3.1 | `aera31` | 10 |
+| Aera Mini | `aeraMini` | 5 |
+
+## API Methods
+
+| Method | Description |
+|--------|-------------|
+| `login()` | Authenticate with email/password |
+| `refresh_auth()` | Refresh the access token |
+| `get_devices()` | Fetch all devices (includes room names) |
+| `get_device_properties(device)` | Fetch current state for a device |
+| `set_power(device, on)` | Turn device on/off |
+| `set_intensity(device, level)` | Set fragrance intensity |
+| `start_session(device, minutes)` | Start a timed session |
+| `stop_session(device)` | Stop a running session |
+| `get_schedules(device)` | Fetch device schedules |
+| `update_schedule(device, key, data)` | Update a schedule |
+| `get_mini_fragrances()` | Get all Mini fragrance names, codes, and QR URLs |
+| `get_device_metadata()` | Fetch user-assigned room names and positions |
+| `sign_out()` | Sign out from the service |
+| `close()` | Close the HTTP session |
+
+## Device Properties
+
+| Property | Description |
+|----------|-------------|
+| `device_name` | User-assigned room name (falls back to product name) |
+| `device_type` | `DeviceType` enum |
+| `is_online` | Connection status |
+| `is_power_on` | Power state |
+| `intensity` | Current intensity level |
+| `fragrance_name` | Resolved fragrance name (via Contentful for Mini) |
+| `fragrance_color` | Hex color from fragrance catalog |
+| `fragrance_remaining` | Percentage remaining (0-100) |
+| `is_cartridge_present` | Whether a cartridge is inserted (full-size only) |
+| `session_active` | Whether a timed session is running |
+| `session_time_remaining` | Minutes left in session |
+| `has_error` | Whether the device has an error condition |
+
+## Scripts
+
+- **`example.py`** - Minimal usage example showing device listing and control.
+- **`test_local.py`** - Interactive test script that dumps all device properties including raw values, useful for debugging.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Disclaimer
+
+This is an unofficial, reverse-engineered client with no affiliation to Aera, Prolitec, or Ayla Networks. It may break if the upstream API changes.

aeraforhome-0.1.0/aera/__init__.py

@@ -0,0 +1,16 @@
+"""Aera for Home API - Python wrapper for the Aera smart fragrance diffuser."""
+
+from aera.api import AeraApi
+from aera.device import AeraDevice, DeviceType
+from aera.const import (
+    AERA_APP_ID,
+    AERA_APP_SECRET,
+)
+
+__all__ = [
+    "AeraApi",
+    "AeraDevice",
+    "DeviceType",
+    "AERA_APP_ID",
+    "AERA_APP_SECRET",
+]

aeraforhome-0.1.0/aera/api.py

@@ -0,0 +1,327 @@
+"""Aera for Home API client using the Ayla IoT platform."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import aiohttp
+
+from aera.const import (
+    AERA_APP_ID,
+    AERA_APP_SECRET,
+    ALL_READABLE_PROPERTIES,
+    DEVICE_METADATA_KEY,
+    DEVICE_SERVICE_URL,
+    PROP_SET_INTENSITY_MANUAL,
+    PROP_SET_POWER_STATE,
+    PROP_SET_SESSION_LENGTH,
+    USER_SERVICE_URL,
+)
+from aera.contentful import ContentfulClient
+from aera.device import AeraDevice
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class AeraAuthError(Exception):
+    """Raised when authentication fails."""
+
+
+class AeraApiError(Exception):
+    """Raised when an API call fails."""
+
+
+class AeraApi:
+    """Async client for the Aera for Home cloud API (Ayla Networks)."""
+
+    def __init__(
+        self,
+        email: str,
+        password: str,
+        session: aiohttp.ClientSession | None = None,
+        app_id: str = AERA_APP_ID,
+        app_secret: str = AERA_APP_SECRET,
+    ):
+        self._email = email
+        self._password = password
+        self._app_id = app_id
+        self._app_secret = app_secret
+        self._session = session
+        self._owns_session = session is None
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+        self._devices: dict[str, AeraDevice] = {}
+        self._contentful: ContentfulClient | None = None
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+            self._owns_session = True
+        return self._session
+
+    def _auth_header(self) -> dict[str, str]:
+        if not self._access_token:
+            raise AeraAuthError("Not authenticated. Call login() first.")
+        return {"Authorization": f"auth_token {self._access_token}"}
+
+    async def login(self) -> bool:
+        """Authenticate with the Ayla user service."""
+        session = await self._get_session()
+        payload = {
+            "user": {
+                "email": self._email,
+                "password": self._password,
+                "application": {
+                    "app_id": self._app_id,
+                    "app_secret": self._app_secret,
+                },
+            }
+        }
+        async with session.post(
+            f"{USER_SERVICE_URL}/users/sign_in.json",
+            json=payload,
+        ) as resp:
+            if resp.status == 401:
+                raise AeraAuthError("Invalid email or password.")
+            if resp.status != 200:
+                text = await resp.text()
+                raise AeraAuthError(f"Login failed ({resp.status}): {text}")
+            data = await resp.json()
+            self._access_token = data.get("access_token")
+            self._refresh_token = data.get("refresh_token")
+            _LOGGER.debug("Login successful")
+            return True
+
+    async def refresh_auth(self) -> bool:
+        """Refresh the access token."""
+        if not self._refresh_token:
+            raise AeraAuthError("No refresh token available. Call login() first.")
+        session = await self._get_session()
+        payload = {"user": {"refresh_token": self._refresh_token}}
+        async with session.post(
+            f"{USER_SERVICE_URL}/users/refresh_token.json",
+            json=payload,
+        ) as resp:
+            if resp.status != 200:
+                self._access_token = None
+                self._refresh_token = None
+                raise AeraAuthError("Token refresh failed. Re-authentication needed.")
+            data = await resp.json()
+            self._access_token = data.get("access_token")
+            self._refresh_token = data.get("refresh_token")
+            _LOGGER.debug("Token refresh successful")
+            return True
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        json: dict | None = None,
+        retry_on_401: bool = True,
+    ) -> Any:
+        """Make an authenticated API request with auto-refresh on 401."""
+        session = await self._get_session()
+        headers = self._auth_header()
+        async with session.request(method, url, headers=headers, json=json) as resp:
+            if resp.status == 401 and retry_on_401:
+                _LOGGER.debug("Got 401, attempting token refresh")
+                await self.refresh_auth()
+                return await self._request(method, url, json=json, retry_on_401=False)
+            if resp.status not in (200, 201):
+                text = await resp.text()
+                raise AeraApiError(f"API error ({resp.status}): {text}")
+            return await resp.json()
+
+    async def get_devices(self) -> list[AeraDevice]:
+        """Fetch all devices associated with the account."""
+        data = await self._request("GET", f"{DEVICE_SERVICE_URL}/apiv1/devices.json")
+        devices = []
+        for item in data:
+            device_data = item.get("device", item)
+            dsn = device_data.get("dsn", "")
+            if dsn in self._devices:
+                self._devices[dsn]._data = device_data
+            else:
+                self._devices[dsn] = AeraDevice(device_data)
+            devices.append(self._devices[dsn])
+        try:
+            await self.get_device_metadata()
+        except Exception as ex:
+            _LOGGER.debug("Failed to fetch device metadata: %s", ex)
+        return devices
+
+    async def get_device_metadata(self) -> dict[str, dict[str, Any]]:
+        """Fetch user-assigned device metadata (room names, positions).
+
+        Returns a dict of DSN -> metadata dict. Also applies room names
+        to any already-fetched devices.
+        """
+        import json as json_lib
+
+        data = await self._request(
+            "GET",
+            f"{USER_SERVICE_URL}/api/v1/users/data/{DEVICE_METADATA_KEY}.json",
+        )
+        datum = data.get("datum", data)
+        value_str = datum.get("value", "")
+        metadata: dict[str, dict[str, Any]] = {}
+        try:
+            entries = json_lib.loads(value_str) if value_str else []
+        except (json_lib.JSONDecodeError, TypeError):
+            entries = []
+        for entry in entries:
+            dsn = entry.get("dsn", "")
+            if dsn:
+                metadata[dsn] = entry
+                if dsn in self._devices:
+                    self._devices[dsn].room_name = entry.get("room_name", "")
+        return metadata
+
+    async def get_device_properties(self, device: AeraDevice | str) -> dict[str, Any]:
+        """Fetch all properties for a device. Returns a dict of name -> value."""
+        dsn = device.dsn if isinstance(device, AeraDevice) else device
+        data = await self._request(
+            "GET", f"{DEVICE_SERVICE_URL}/apiv1/dsns/{dsn}/properties.json"
+        )
+        properties: dict[str, Any] = {}
+        for item in data:
+            prop = item.get("property", item)
+            name = prop.get("name")
+            value = prop.get("value")
+            if name:
+                properties[name] = value
+        if dsn in self._devices:
+            dev = self._devices[dsn]
+            dev.update_properties(properties)
+            await self._resolve_fragrance(dev)
+        return properties
+
+    async def _ensure_contentful(self) -> ContentfulClient:
+        """Lazily load the Contentful fragrance data."""
+        if self._contentful is None:
+            session = await self._get_session()
+            self._contentful = ContentfulClient(session)
+        if not self._contentful.is_loaded:
+            await self._contentful.load_fragrances()
+        return self._contentful
+
+    async def _resolve_fragrance(self, device: AeraDevice) -> None:
+        """Resolve fragrance metadata from Contentful for a device."""
+        identifier = device.fragrance_identifier
+        if not identifier:
+            return
+        contentful = await self._ensure_contentful()
+        info = contentful.resolve_fragrance(identifier, device.device_type.is_mini)
+        device.fragrance_info = info
+
+    async def set_property(
+        self, device: AeraDevice | str, property_name: str, value: Any
+    ) -> bool:
+        """Set a property value on a device (creates a datapoint)."""
+        dsn = device.dsn if isinstance(device, AeraDevice) else device
+        payload = {"datapoint": {"value": value}}
+        await self._request(
+            "POST",
+            f"{DEVICE_SERVICE_URL}/apiv1/dsns/{dsn}/properties/{property_name}/datapoints.json",
+            json=payload,
+        )
+        if dsn in self._devices:
+            self._devices[dsn].update_properties({property_name: value})
+        return True
+
+    async def set_power(self, device: AeraDevice | str, on: bool) -> bool:
+        """Turn device on or off."""
+        return await self.set_property(device, PROP_SET_POWER_STATE, 1 if on else 0)
+
+    async def set_intensity(self, device: AeraDevice | str, level: int) -> bool:
+        """Set fragrance intensity level (1-10 for full-size, 1-5 for Mini)."""
+        dsn = device.dsn if isinstance(device, AeraDevice) else device
+        dev = self._devices.get(dsn)
+        if dev:
+            max_level = dev.max_intensity
+            level = max(1, min(level, max_level))
+        return await self.set_property(device, PROP_SET_INTENSITY_MANUAL, level)
+
+    async def start_session(
+        self, device: AeraDevice | str, duration_minutes: int
+    ) -> bool:
+        """Start a timed fragrance session."""
+        return await self.set_property(device, PROP_SET_SESSION_LENGTH, duration_minutes)
+
+    async def stop_session(self, device: AeraDevice | str) -> bool:
+        """Stop a running fragrance session (set session length to 0)."""
+        return await self.set_property(device, PROP_SET_SESSION_LENGTH, 0)
+
+    async def get_mini_fragrances(self) -> list[dict[str, str | None]]:
+        """Get all Mini-compatible fragrances with name, code, and QR URL."""
+        contentful = await self._ensure_contentful()
+        return [
+            {
+                "name": f.fragrance_name,
+                "code": f.fragrance_id,
+                "qr_url": f.fragrance_qr,
+            }
+            for f in contentful.get_mini_fragrances()
+        ]
+
+    async def get_schedules(self, device: AeraDevice | str) -> list[dict[str, Any]]:
+        """Fetch all schedules for a device."""
+        dsn = device.dsn if isinstance(device, AeraDevice) else device
+        data = await self._request(
+            "GET", f"{DEVICE_SERVICE_URL}/apiv1/dsns/{dsn}/schedules.json"
+        )
+        schedules = []
+        for item in data:
+            schedule = item.get("schedule", item)
+            schedules.append(schedule)
+        return schedules
+
+    async def update_schedule(
+        self, device: AeraDevice | str, schedule_key: str, schedule_data: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Update a schedule on a device."""
+        dsn = device.dsn if isinstance(device, AeraDevice) else device
+        payload = {"schedule": schedule_data}
+        data = await self._request(
+            "PUT",
+            f"{DEVICE_SERVICE_URL}/apiv1/dsns/{dsn}/schedules/{schedule_key}.json",
+            json=payload,
+        )
+        return data.get("schedule", data)
+
+    async def sign_out(self) -> bool:
+        """Sign out from the Ayla service."""
+        if not self._access_token:
+            return True
+        session = await self._get_session()
+        headers = self._auth_header()
+        payload = {"user": {"access_token": self._access_token}}
+        try:
+            async with session.post(
+                f"{USER_SERVICE_URL}/users/sign_out.json",
+                headers=headers,
+                json=payload,
+            ) as resp:
+                pass
+        except Exception:
+            pass
+        self._access_token = None
+        self._refresh_token = None
+        return True
+
+    async def close(self) -> None:
+        """Close the session."""
+        if self._contentful:
+            await self._contentful.close()
+            self._contentful = None
+        if self._owns_session and self._session and not self._session.closed:
+            await self._session.close()
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._access_token is not None
+
+    @property
+    def devices(self) -> dict[str, AeraDevice]:
+        return self._devices

aeraforhome-0.1.0/aera/const.py

@@ -0,0 +1,50 @@
+"""Constants extracted from the Aera for Home Android app."""
+
+AERA_APP_ID = "android-id-id"
+AERA_APP_SECRET = "android-id-oYOAkxPCU46_E04WxtwfOYatrUI"
+
+USER_SERVICE_URL = "https://user-field.aylanetworks.com"
+DEVICE_SERVICE_URL = "https://ads-field.aylanetworks.com"
+
+# Properties written TO device (inputs)
+PROP_SET_POWER_STATE = "set_power_state"
+PROP_SET_INTENSITY_MANUAL = "set_intensity_manual"
+PROP_SET_INTENSITY_SCHEDULE = "set_intensity_sched"
+PROP_SET_SESSION_LENGTH = "set_session_length"
+PROP_SET_FRAGRANCE_IDENTIFIER = "set_fragrance_identifier"
+PROP_EJECT_PRESSED = "eject_press_on_app"
+PROP_DEVICE_FW_VERSION = "device_fw_version"
+PROP_QR_SCANNED_TIME = "pump_life_time_qr_scanned"
+
+# Properties read FROM device (outputs)
+PROP_POWER_STATE = "power_state"
+PROP_INTENSITY_STATE = "intensity_state"
+PROP_CARTRIDGE_USAGE = "cartridge_usage"
+PROP_CARTRIDGE_PRESENT = "cartridge_present"
+PROP_FRAGRANCE_NAME = "fragrance_name"
+PROP_ERROR_CONDITION = "error_condition"
+PROP_INTERRUPT_SCHEDULE = "interrupt_schedule"
+PROP_SESSION_STATE = "session_state"
+PROP_SESSION_TIME_LEFT = "session_time_left"
+PROP_PUMP_LIFE_TIME = "pump_life_time"
+
+DEVICE_METADATA_KEY = "device_data_table"
+
+ALL_READABLE_PROPERTIES = [
+    PROP_POWER_STATE,
+    PROP_INTENSITY_STATE,
+    PROP_CARTRIDGE_USAGE,
+    PROP_CARTRIDGE_PRESENT,
+    PROP_FRAGRANCE_NAME,
+    PROP_ERROR_CONDITION,
+    PROP_INTERRUPT_SCHEDULE,
+    PROP_SESSION_STATE,
+    PROP_SESSION_TIME_LEFT,
+    PROP_PUMP_LIFE_TIME,
+    PROP_SET_INTENSITY_MANUAL,
+    PROP_SET_POWER_STATE,
+    PROP_SET_SESSION_LENGTH,
+    PROP_SET_FRAGRANCE_IDENTIFIER,
+    PROP_DEVICE_FW_VERSION,
+    PROP_QR_SCANNED_TIME,
+]

aeraforhome-0.1.0/aera/contentful.py

@@ -0,0 +1,139 @@
+"""Contentful CMS client for fetching Aera fragrance metadata."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+import aiohttp
+
+_LOGGER = logging.getLogger(__name__)
+
+CONTENTFUL_SPACE = "bsswjwaepi0w"
+CONTENTFUL_TOKEN = "UC4IVgBwitvaugwTZQLSvO28UcUdUumEvpOy4MejPUg"
+CONTENTFUL_BASE_URL = f"https://cdn.contentful.com/spaces/{CONTENTFUL_SPACE}"
+
+
+@dataclass
+class FragranceInfo:
+    """Fragrance metadata from Contentful."""
+
+    fragrance_id: str | None
+    fragrance_qr: str | None
+    fragrance_name: str | None
+    firmware_name: str | None
+    color: str | None
+    mini_fill: float | None
+    mini_output: float | None
+
+
+class ContentfulClient:
+    """Fetches fragrance data from the Aera Contentful CMS."""
+
+    def __init__(self, session: aiohttp.ClientSession | None = None):
+        self._session = session
+        self._owns_session = session is None
+        self._fragrances: list[FragranceInfo] = []
+        self._loaded = False
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+            self._owns_session = True
+        return self._session
+
+    async def load_fragrances(self) -> list[FragranceInfo]:
+        """Fetch all fragrances from Contentful."""
+        session = await self._get_session()
+        headers = {"Authorization": f"Bearer {CONTENTFUL_TOKEN}"}
+        fragrances: list[FragranceInfo] = []
+        skip = 0
+        limit = 100
+
+        while True:
+            url = (
+                f"{CONTENTFUL_BASE_URL}/entries"
+                f"?content_type=fragrance&limit={limit}&skip={skip}"
+            )
+            async with session.get(url, headers=headers) as resp:
+                if resp.status != 200:
+                    _LOGGER.error("Contentful API error: %s", resp.status)
+                    break
+                data = await resp.json()
+
+            items = data.get("items", [])
+            for item in items:
+                fields = item.get("fields", {})
+                fragrances.append(
+                    FragranceInfo(
+                        fragrance_id=fields.get("fragranceId"),
+                        fragrance_qr=fields.get("fragranceQr"),
+                        fragrance_name=fields.get("fragranceName"),
+                        firmware_name=fields.get("firmwareName"),
+                        color=fields.get("color"),
+                        mini_fill=fields.get("miniFill"),
+                        mini_output=fields.get("miniOutput"),
+                    )
+                )
+
+            total = data.get("total", 0)
+            skip += limit
+            if skip >= total:
+                break
+
+        self._fragrances = fragrances
+        self._loaded = True
+        _LOGGER.debug("Loaded %d fragrances from Contentful", len(fragrances))
+        return fragrances
+
+    @property
+    def is_loaded(self) -> bool:
+        return self._loaded
+
+    def get_fragrance_by_id(self, identifier: str) -> FragranceInfo | None:
+        """Look up fragrance by fragranceId (used by Mini devices)."""
+        identifier_lower = identifier.lower()
+        for f in self._fragrances:
+            if f.fragrance_id and f.fragrance_id.lower() == identifier_lower:
+                return f
+        return None
+
+    def get_fragrance_by_name(self, name: str) -> FragranceInfo | None:
+        """Look up fragrance by fragranceName, then firmwareName (used by full-size)."""
+        name_lower = name.lower()
+        for f in self._fragrances:
+            if f.fragrance_name and f.fragrance_name.lower() == name_lower:
+                return f
+        for f in self._fragrances:
+            if f.firmware_name and f.firmware_name.lower() == name_lower:
+                return f
+        return None
+
+    def get_fragrance_by_qr(self, qr_id: str) -> FragranceInfo | None:
+        """Look up fragrance by fragranceQr code."""
+        qr_lower = qr_id.lower()
+        for f in self._fragrances:
+            if f.fragrance_qr and f.fragrance_qr.lower() == qr_lower:
+                return f
+        return None
+
+    def get_mini_fragrances(self) -> list[FragranceInfo]:
+        """Return all fragrances compatible with Aera Mini (those with a fragrance_id)."""
+        return [f for f in self._fragrances if f.fragrance_id]
+
+    def resolve_fragrance(self, identifier: str, is_mini: bool) -> FragranceInfo | None:
+        """Resolve a fragrance identifier using the app's matching logic.
+
+        For Mini: try fragranceId first, then fragranceName/firmwareName.
+        For full-size: try fragranceName/firmwareName only.
+        """
+        if is_mini:
+            result = self.get_fragrance_by_id(identifier)
+            if result:
+                return result
+        return self.get_fragrance_by_name(identifier)
+
+    async def close(self) -> None:
+        if self._owns_session and self._session and not self._session.closed:
+            await self._session.close()

aeraforhome-0.1.0/aera/device.py

@@ -0,0 +1,243 @@
+"""Aera device model."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from aera.contentful import FragranceInfo
+
+
+class DeviceType(Enum):
+    """Aera device model types."""
+
+    AERA1 = "aera1"
+    AERA2 = "aera2"
+    AERA3 = "aera3"
+    AERA3_1 = "aera31"
+    AERA_MINI = "aeraMini"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def from_oem_model(cls, oem_model: str | None) -> DeviceType:
+        if not oem_model:
+            return cls.UNKNOWN
+        for member in cls:
+            if member.value == oem_model:
+                return member
+        return cls.UNKNOWN
+
+    @property
+    def is_full_size(self) -> bool:
+        return self in (
+            DeviceType.AERA1,
+            DeviceType.AERA2,
+            DeviceType.AERA3,
+            DeviceType.AERA3_1,
+        )
+
+    @property
+    def is_mini(self) -> bool:
+        return self == DeviceType.AERA_MINI
+
+    @property
+    def max_intensity(self) -> int:
+        return 10 if self.is_full_size else 5
+
+
+class AeraDevice:
+    """Represents a single Aera fragrance diffuser."""
+
+    def __init__(self, device_data: dict[str, Any], properties: dict[str, Any] | None = None):
+        self._data = device_data
+        self._properties: dict[str, Any] = properties or {}
+        self._fragrance_info: FragranceInfo | None = None
+        self._room_name: str | None = None
+
+    @property
+    def dsn(self) -> str:
+        return self._data.get("dsn", "")
+
+    @property
+    def product_name(self) -> str:
+        return self._data.get("product_name", "")
+
+    @property
+    def device_name(self) -> str:
+        if self._room_name:
+            return self._room_name
+        return self._data.get("device_name", self.product_name)
+
+    @property
+    def room_name(self) -> str | None:
+        return self._room_name
+
+    @room_name.setter
+    def room_name(self, value: str | None) -> None:
+        self._room_name = value or None
+
+    @property
+    def oem_model(self) -> str:
+        return self._data.get("oem_model", "")
+
+    @property
+    def device_type(self) -> DeviceType:
+        return DeviceType.from_oem_model(self.oem_model)
+
+    @property
+    def model(self) -> str:
+        return self._data.get("model", "")
+
+    @property
+    def sw_version(self) -> str | None:
+        return self._data.get("sw_version")
+
+    @property
+    def mac(self) -> str | None:
+        return self._data.get("mac")
+
+    @property
+    def lan_ip(self) -> str | None:
+        return self._data.get("lan_ip")
+
+    @property
+    def connected_at(self) -> str | None:
+        return self._data.get("connected_at")
+
+    @property
+    def is_online(self) -> bool:
+        status = self._data.get("connection_status")
+        return status == "Online"
+
+    @property
+    def is_power_on(self) -> bool | None:
+        val = self._properties.get("power_state")
+        if val is None:
+            return None
+        return int(val) == 1
+
+    @property
+    def intensity(self) -> int | None:
+        val = self._properties.get("intensity_state")
+        if val is None:
+            return None
+        return int(val)
+
+    @property
+    def max_intensity(self) -> int:
+        return self.device_type.max_intensity
+
+    @property
+    def cartridge_usage(self) -> int | None:
+        val = self._properties.get("cartridge_usage")
+        if val is None:
+            return None
+        return int(val)
+
+    @property
+    def fragrance_remaining(self) -> int | None:
+        if self.device_type.is_mini:
+            return self._mini_fragrance_remaining()
+        usage = self.cartridge_usage
+        if usage is None:
+            return None
+        return max(0, 100 - usage)
+
+    def _mini_fragrance_remaining(self) -> int | None:
+        pump_life = self._properties.get("pump_life_time")
+        pump_qr = self._properties.get("pump_life_time_qr_scanned")
+        if pump_life is None or pump_qr is None:
+            return None
+        if self._fragrance_info is None:
+            return None
+        mini_fill = self._fragrance_info.mini_fill
+        mini_output = self._fragrance_info.mini_output
+        if not mini_fill or not mini_output:
+            return None
+        usage = round(
+            ((int(pump_life) - int(pump_qr)) * mini_output / (mini_fill * 3600)) * 100
+        )
+        return max(0, min(100, 100 - usage))
+
+    @property
+    def is_cartridge_present(self) -> bool | None:
+        val = self._properties.get("cartridge_present")
+        if val is None:
+            return None
+        return int(val) == 1
+
+    @property
+    def fragrance_name(self) -> str | None:
+        if self._fragrance_info and self._fragrance_info.fragrance_name:
+            return self._fragrance_info.fragrance_name
+        return self._properties.get("fragrance_name") or None
+
+    @property
+    def fragrance_color(self) -> str | None:
+        if self._fragrance_info:
+            return self._fragrance_info.color
+        return None
+
+    @property
+    def fragrance_identifier(self) -> str | None:
+        """Raw fragrance identifier from device (short code for Mini, full name for full-size)."""
+        return (
+            self._properties.get("set_fragrance_identifier")
+            or self._properties.get("fragrance_name")
+            or None
+        )
+
+    @property
+    def fragrance_info(self) -> FragranceInfo | None:
+        return self._fragrance_info
+
+    @fragrance_info.setter
+    def fragrance_info(self, value: FragranceInfo | None) -> None:
+        self._fragrance_info = value
+
+    @property
+    def error_condition(self) -> int | None:
+        val = self._properties.get("error_condition")
+        if val is None:
+            return None
+        return int(val)
+
+    @property
+    def has_error(self) -> bool:
+        return self.error_condition is not None and self.error_condition != 0
+
+    @property
+    def session_active(self) -> bool | None:
+        val = self._properties.get("session_state")
+        if val is None:
+            return None
+        return int(val) == 1
+
+    @property
+    def session_time_remaining(self) -> int | None:
+        val = self._properties.get("session_time_left")
+        if val is None:
+            return None
+        return int(val)
+
+    @property
+    def firmware_version(self) -> str | None:
+        return self._properties.get("device_fw_version")
+
+    @property
+    def has_session_feature(self) -> bool:
+        return self.device_type in (
+            DeviceType.AERA3,
+            DeviceType.AERA3_1,
+            DeviceType.AERA_MINI,
+        )
+
+    def update_properties(self, properties: dict[str, Any]) -> None:
+        self._properties.update(properties)
+
+    def __repr__(self) -> str:
+        return (
+            f"AeraDevice(dsn={self.dsn!r}, name={self.device_name!r}, "
+            f"type={self.device_type.name}, online={self.is_online})"
+        )

aeraforhome-0.1.0/aeraforhome.egg-info/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: aeraforhome
+Version: 0.1.0
+Summary: Python API for Aera for Home smart fragrance diffusers
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: aioresponses>=0.7; extra == "dev"
+
+# aeraforhome-api
+
+Unofficial Python client for the Aera for Home smart fragrance diffuser cloud API, reverse-engineered from the Android app (v2.3.6). Covers:
+
+- **Authentication**: email/password login via the Ayla Networks IoT platform, automatic token refresh on 401.
+- **Device control**: power on/off, intensity adjustment, timed fragrance sessions, schedule management.
+- **Device state**: fragrance name, remaining percentage, cartridge presence, error conditions.
+- **Fragrance catalog**: Mini fragrance lookup with names, codes, and QR URLs via Contentful CMS.
+
+This library is designed to power a Home Assistant integration, but has no dependency on Home Assistant and can be used standalone.
+
+## Installation
+
+```bash
+pip install aeraforhome
+```
+
+Or install from source:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+import asyncio
+from aera import AeraApi
+
+async def main():
+    api = AeraApi("your-email@example.com", "your-password")
+
+    try:
+        await api.login()
+
+        devices = await api.get_devices()
+        for device in devices:
+            props = await api.get_device_properties(device)
+            print(f"{device.device_name}: {device.fragrance_name} ({device.fragrance_remaining}%)")
+
+        # Control a device
+        await api.set_power(devices[0], True)
+        await api.set_intensity(devices[0], 5)
+
+        # Start a 60-minute session
+        await api.start_session(devices[0], 60)
+
+        # Get all Mini-compatible fragrances (for QR scanning)
+        fragrances = await api.get_mini_fragrances()
+        for f in fragrances:
+            print(f"{f['name']} ({f['code']}): {f['qr_url']}")
+
+    finally:
+        await api.close()
+
+asyncio.run(main())
+```
+
+## Supported Devices
+
+| Model | Type | Max Intensity |
+|-------|------|---------------|
+| Aera 1 | `aera1` | 10 |
+| Aera 2 | `aera2` | 10 |
+| Aera 3 | `aera3` | 10 |
+| Aera 3.1 | `aera31` | 10 |
+| Aera Mini | `aeraMini` | 5 |
+
+## API Methods
+
+| Method | Description |
+|--------|-------------|
+| `login()` | Authenticate with email/password |
+| `refresh_auth()` | Refresh the access token |
+| `get_devices()` | Fetch all devices (includes room names) |
+| `get_device_properties(device)` | Fetch current state for a device |
+| `set_power(device, on)` | Turn device on/off |
+| `set_intensity(device, level)` | Set fragrance intensity |
+| `start_session(device, minutes)` | Start a timed session |
+| `stop_session(device)` | Stop a running session |
+| `get_schedules(device)` | Fetch device schedules |
+| `update_schedule(device, key, data)` | Update a schedule |
+| `get_mini_fragrances()` | Get all Mini fragrance names, codes, and QR URLs |
+| `get_device_metadata()` | Fetch user-assigned room names and positions |
+| `sign_out()` | Sign out from the service |
+| `close()` | Close the HTTP session |
+
+## Device Properties
+
+| Property | Description |
+|----------|-------------|
+| `device_name` | User-assigned room name (falls back to product name) |
+| `device_type` | `DeviceType` enum |
+| `is_online` | Connection status |
+| `is_power_on` | Power state |
+| `intensity` | Current intensity level |
+| `fragrance_name` | Resolved fragrance name (via Contentful for Mini) |
+| `fragrance_color` | Hex color from fragrance catalog |
+| `fragrance_remaining` | Percentage remaining (0-100) |
+| `is_cartridge_present` | Whether a cartridge is inserted (full-size only) |
+| `session_active` | Whether a timed session is running |
+| `session_time_remaining` | Minutes left in session |
+| `has_error` | Whether the device has an error condition |
+
+## Scripts
+
+- **`example.py`** - Minimal usage example showing device listing and control.
+- **`test_local.py`** - Interactive test script that dumps all device properties including raw values, useful for debugging.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Disclaimer
+
+This is an unofficial, reverse-engineered client with no affiliation to Aera, Prolitec, or Ayla Networks. It may break if the upstream API changes.

aeraforhome-0.1.0/aeraforhome.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+aera/__init__.py
+aera/api.py
+aera/const.py
+aera/contentful.py
+aera/device.py
+aeraforhome.egg-info/PKG-INFO
+aeraforhome.egg-info/SOURCES.txt
+aeraforhome.egg-info/dependency_links.txt
+aeraforhome.egg-info/requires.txt
+aeraforhome.egg-info/top_level.txt

aeraforhome-0.1.0/aeraforhome.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aeraforhome-0.1.0/aeraforhome.egg-info/requires.txt

@@ -0,0 +1,6 @@
+aiohttp>=3.9.0
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21
+aioresponses>=0.7

aeraforhome-0.1.0/aeraforhome.egg-info/top_level.txt

@@ -0,0 +1 @@
+aera

aeraforhome-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aeraforhome"
+version = "0.1.0"
+description = "Python API for Aera for Home smart fragrance diffusers"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+dependencies = [
+    "aiohttp>=3.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "aioresponses>=0.7",
+]
+
+[tool.setuptools.packages.find]
+include = ["aera*"]

aeraforhome-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+