Skip to main content

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

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(key, data) Update a schedule
get_schedule_actions(key) Fetch actions (intensity) for a schedule
create_schedule_action(key, data) Create an action on a schedule
update_schedule_action(key, data) Update an existing schedule action
delete_schedule_action(key) Delete a schedule action
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
error_condition Error code (integer, 0 = no error)
firmware_version Device firmware version string
max_intensity Maximum intensity level for this device type
has_session_feature Whether the device supports timed sessions
device_key Ayla device key (used for schedule APIs)

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.

Metadata

Release files for aeraforhome 0.4.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aeraforhome 0.4.2
File Size Uploaded Provenance Actions
aeraforhome-0.4.2.tar.gz 16.4 kB With provenance Details for aeraforhome-0.4.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aeraforhome 0.4.2
File Interpreter ABI Platform Actions
aeraforhome-0.4.2-py3-none-any.whl Python 3 none any Details for aeraforhome-0.4.2-py3-none-any.whl

Total release size: 28.1 kB

Release files / aeraforhome-0.4.2.tar.gz

Download URL aeraforhome-0.4.2.tar.gz
Size 16.4 kB
Tags Source
SHA-256 checksum
How to use checksums
fce8d8f1f33a708d8c9e5c48bfffde1757e7f358036472ee9e74658a8c230011
BLAKE2b-256 checksum
How to use checksums
0bc4d3658b9f82cc01a6011bce65cfe0bfdeb6d11824903cca931b3f87ab5d20
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / aeraforhome-0.4.2-py3-none-any.whl

Download URL aeraforhome-0.4.2-py3-none-any.whl
Size 11.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b30d12876031b229d02bc7b9db2ffe26d4d4cc9aadc59cb850ca912f341f09de
BLAKE2b-256 checksum
How to use checksums
c747d79b1d171aef3a0bba8ff459b86dbbd761a33c054e18d7efa318df9c0d4e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for aeraforhome 0.4.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aeraforhome-0.4.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page