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.1

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.1
File Size Uploaded Provenance Actions
aeraforhome-0.4.1.tar.gz 16.4 kB With provenance Details for aeraforhome-0.4.1.tar.gz

Built distribution (wheel)

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

Total release size: 28.1 kB

Release files / aeraforhome-0.4.1.tar.gz

Download URL aeraforhome-0.4.1.tar.gz
Size 16.4 kB
Tags Source
SHA-256 checksum
How to use checksums
e4ee0c34f7cae21c308d3237446ede4205ad9286d1243aa3d5c6863e2395422f
BLAKE2b-256 checksum
How to use checksums
4b940d80f2bb0781b8f89c01bc63796a0471f28e5d5d676d83b89ddda80e36f8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 10, 2026.

Transparency log

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

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

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 Oct 10, 2026.

Transparency log

Security for aeraforhome 0.4.1

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.1.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 Oct 10, 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