aioairq 0.6.0

Asynchronous library to retrieve data from air-Q devices.

PyPI package aioairq

Python library for asynchronous data access to local air-Q devices.

Retrieve data from air-Q

At its present state, AirQ requires an aiohttp session to be provided by the user:

import asyncio
import aiohttp
from aioairq import AirQ

# The address can be an IP, an mDNS hostname, or the short device ID
# (the 5-char hex string printed on the device, e.g. "123ab").
# Use AirQ.connect() to auto-resolve a device ID to its mDNS name.
ADDRESS = "123ab"
PASSWORD = "airqsetup"

async def main():
    async with aiohttp.ClientSession() as session:
        airq = await AirQ.connect(ADDRESS, PASSWORD, session)

        config = await airq.config
        print(f"Available sensors: {config['sensors']}")

        data = await airq.data
        print(f"Momentary data: {data}")

asyncio.run(main())

Note on mDNS: AirQ.connect() resolves a device ID to <id>_air-q.local via mDNS. This requires multicast DNS support on your network (Avahi on Linux, Bonjour on macOS). Some routers block mDNS traffic — if connecting by device ID fails, use the device's IP address directly. You can also look up the hostname your router assigns to the device (often <id>_air-q without .local) via your router's admin UI or nslookup <id>_air-q <router-ip>.

Download historical data

The air-Q stores measurement data on its SD card. You can browse and download this data:

import asyncio
import aiohttp
from aioairq import AirQ

ADDRESS = "123ab_air-q.local"
PASSWORD = "airqsetup"

async def main():
    async with aiohttp.ClientSession() as session:
        airq = AirQ(ADDRESS, PASSWORD, session)

        # Browse the directory structure (year/month/day/timestamp)
        years = await airq.get_historical_files_list()
        days = await airq.get_historical_files_list("2024/5")
        files = await airq.get_historical_files_list("2024/5/12")

        # Download a file (compressed by default, ~1/5 the size)
        data = await airq.get_historical_file("2024/5/12/1715000000")

        # Or download uncompressed
        data = await airq.get_historical_file("2024/5/12/1715000000", compressed=False)

asyncio.run(main())

Logging

Since version 0.4.4, aioairq supports a very verbose logging at the DEBUG level, especially in AirQ.get_latest_data method, which can cache the previous data and log the difference between the latest and the previous sensor readings. Note that this caching and difference calculation does not happen when the logging is set up to a higher level than DEBUG, incurring no additional overhead when not requested.

Development

Example script for Linux how to run everything.

# Checkout the repository
git clone https://github.com/CorantGmbH/aioairq
cd aioairq

# Create a virtual environment
#
# We assume that your system has Python in version 3.9 or higher installed
# and accessible via `python3`. 
# - If this command is not found or references an older version, consult your distribution.
# - Depending on the distribution, you may need to install an additional package, e.g. `python3-venv`.
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .
# Optionally, you may install developmental dependencies
# which include testing, linting/formatting, and pre-commit
pip install -e ".[dev]" # if errors, see below

# You can now create a script (see example above) and run it
vim hello-air-q.py
python hello-air-q.py

Testing

# If you get an error message about incompatible version, when attempting
# pip install -e ".[dev]", you may try to install the packages separately:
#
# pip install pytest
# pip install pytest-asyncio

# Prepare an environment file
# (You don't want to type your passwords into the shell)
cat <<EOF >.env
export AIRQ_IP=192.168.168.42
export AIRQ_PASS=12345678
export AIRQ_MDNS=abcde_air-q.local
export AIRQ_HOSTNAME=air-q-livingroom
EOF

# Run the tests
source .env
pytest

Contributing

This repository uses pre-commit primarily to ensure linting and formatting using Ruff (besides codespell and yamlling). If you want to commit changes to this repository, make sure you have pre-commit installed (included among the dev extras). Then initialise the git hooks by running

pre-commit install

Once successfully installed, ruff git hook will be triggered upon git commit and it will lint and try to fix the code you are about to commit. Should any changes be made, the commit will be aborted and you will need to address the lints and stage the modified files to your commit before trying again.

Linting

Ruff's rule list is far less exhaustive than that of pylint, so if you want, you can gain additional insight by running pylint (not installed as a part of the dev extras).

pip install pylint
pylint aioairq/*.py

Once done, you may leave the virtual environment

deactivate