python-airos

An asynchronous Python module to interact with Ubiquiti airOS devices, emulating a web browser client.

Overview

python-airos or airos from pypi is an asynchronous Python library designed to programmatically interact with Ubiquiti airOS devices. It mimics a web browser client to fetch device status, configuration, and perform actions like kicking connected stations.

This library is a key component for a potential future core integration with Home Assistant, with the initial pull request for core integration targeted for the 2025.8 release.

More details on the integration can be found on the Ubiquiti UISP airOS page. To add airOS directly feel free to use the button below:

Features

• Asynchronous Operations: Built with asyncio and aiohttp for non-blocking I/O, which is perfect for integrations and background tasks.
• Client Emulation: Authenticates and interacts with airOS devices by emulating a client browser, ensuring a high degree of compatibility.
• Data Retrieval: Fetches comprehensive device status information, including:
• Wireless mode and signal strength.
• Connected stations and their statistics.
• System information and uptime.
• Device Control: Provides methods to perform actions, such as reconnecting/kicking a connected wireless station and rebooting the device itself.
• Discovery of airOS devices on your local network (by listening to announcements these devices broadcast).

Installation

You can install python-airos from PyPI using pip:

pip install airos

Usage

Here is a more detailed example of how to use the library to connect, fetch status, and perform an action on an airOS device.

import aiohttp
import asyncio
from airos.airos6 import AirOS6, AirOS6Data
from airos.airos8 import AirOS8, AirOS8Data
from airos.helpers import DetectDeviceData, async_get_firmware_data


async def main():
    """Main function to demonstrate library usage."""
    # Create an aiohttp session with SSL verification disabled.
    # Be cautious with this setting; it's useful for self-signed certificates
    # but not recommended for production environments without proper validation.
    session = aiohttp.ClientSession(connector=aiohttp.TCPConnector(verify_ssl=False))

    # Connection data
    conn_data = {
        "host": "192.168.1.2",
        "username": "ubnt",
        "password": "password",
        "session": session,
    }

    device_data: DetectDeviceData = await async_get_firmware_data(**conn_data)
    airos_class: type[AirOS8 | AirOS6] = AirOS8
    AirOSDataDetect = AirOS8Data | AirOS6Data

    if device_data["fw_major"] == 6:
        airos_class = AirOS6

    # Initialize the AirOS device object.
    airos_device = airos_class(**conn_data)

    try:
        # Step 1: Login to the device.
        login_result = await airos_device.login()
        print(f"Login successful: {login_result}")

        # Step 2: Fetch the device status.
        status_data = await airos_device.status()
        print("\n--- Device Status ---")
        print(f"Device Name: {status_data.host.hostname}")
        print(f"Wireless Mode: {status_data.wireless.mode}")
        print(f"Firmware Version: {status_data.host.fwversion}")

        # Fetch and display connected stations if available
        if status_data.wireless.sta:
            print("\n--- Connected Stations ---")
            for station in status_data.wireless.sta:
                print(f"  - MAC: {station.mac}")
                print(f"    Signal: {station.signal} dBm")
                print(f"    Uptime: {station.uptime} seconds")

        # Step 3: Perform an action, e.g., kick a station.
        # Replace '01:23:45:67:89:AB' with the MAC address of a station to kick.
        # kick_result = await device.stakick("01:23:45:67:89:AB")
        # print(f"\nKick station result: {kick_result}")

    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        # Ensure the aiohttp session is closed properly.
        await session.close()


if __name__ == "__main__":
    asyncio.run(main())

Supported API classes and calls

Note: For firmware 6 we only support the login and status calls currently.

Classes

• airos.data (directly) as well as airos.airos8 (indirectly) provides AirOSData, a mashumaro based dataclass
• airos.discovery provides AirOSDiscoveryProtocol for the actual discovery, we recommend to use the async_discover_devices function for consumption as described below

Calls

• airos.airos8: initializes with host: str, username: str, password: str, session: aiohttp.ClientSession

  • login(): Authenticates with the device.

  • status(): Fetches a comprehensive dictionary of the device's status and statistics.

  • warnings(): Retrieves warning status dict.

  • stakick(mac_address: str): Disconnects a specific station by its MAC address.

  • reboot(): Reboots the device.

  • provmode(active: bool = False): Enables or disables the provisioning mode.

  • update_check(force: bool = False): Checks if new firmware has been discovered (or force to force check).

  • download(): Starts downloading (not installing) new firmware.

  • progress(): Fetches the firmware download (not install!) progress.

  • install(): Installs the new firmware.

• airos.discovery

  • async_discover_devices(timeout: int) mainly for consumption by HA's config_flow returning a dict mapping mac-addresses to discovered info.

Information

Update

Will return either {"update": False} or the full information regarding the available update:

{"checksum": "b1bea879a9f518f714ce638172e3a860", "version": "v8.7.19", "security": "", "date": "250811", "url": "https://dl.ubnt.com/firmwares/XC-fw/v8.7.19/WA.v8.7.19.48279.250811.0636.bin", "update": True, "changelog": "https://dl.ubnt.com/firmwares/XC-fw/v8.7.19/changelog.txt"}

Progress

If no progress to report {"progress": -1} otherwise a positive value between 0 and 100.

Install

Only a positive outcome is expected from the user experience; the call should return:

{
    "ok": true,
    "code": 0
}

Warnings

Will respond with something like:

{
    "isDefaultPasswd": false,
    "customScripts": false,
    "isWatchdogReset": 0,
    "label": 0,
    "chAvailable": false,
    "emergReasonCode": -1,
    "firmware": {
        "isThirdParty": false,
        "version": "",
        "uploaded": false
    }
}

Contributing

We welcome contributions as well as additional codeowners to python-airos.