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

pip install aeraforhome

Or install from source:

pip install -e .

Usage

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

API Methods

Device Properties

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.
• test_schedules.py - Dumps active schedules and their actions (intensity values) for all devices.

Development

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.