<div align="center">
<img src="https://github.com/home-assistant/brands/blob/master/core_brands/ubiquiti/icon.png?raw=true" alt="Ubiquiti airOS Logo" width="150" />
<h1>python-airos</h1>
<p>An asynchronous Python module to interact with Ubiquiti airOS devices, emulating a web browser client.</p>
</div>
<div align="center">
</div>
[](https://github.com/python-airos)
[](https://coderabbit.ai)
[](https://github.com/compatech/python-airos/issues/8)
[](https://pypi.python.org/pypi/airos/)
[](https://github.com/compatech/python-airos/actions)
[](https://github.com/compatech/python-airos/actions)
[](https://www.codefactor.io/repository/github/plugwise/python-airos)
[](https://codecov.io/gh/compatech/python-airos)
[](https://sonarcloud.io/summary/new_code?id=CoMPaTech_python-airos)
[](https://sonarcloud.io/summary/new_code?id=CoMPaTech_python-airos)
[](https://sonarcloud.io/summary/new_code?id=CoMPaTech_python-airos)
# Overview
`python-airos` or [`airos`](https://pypi.org/projects/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](https://www.home-assistant.io), 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](https://www.home-assistant.io/integrations/airos/) page. To add airOS directly feel free to use the button below:
[](https://my.home-assistant.io/redirect/_change/?redirect=config_flow_start%2F%3Fdomain%3Dairos)
## 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.
- 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:
```Bash
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.
```Python
import aiohttp
import asyncio
from airos.airos8 import AirOS
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))
# Initialize the AirOS device object.
device = AirOS(
host="192.168.1.2",
username="ubnt",
password="password",
session=session
)
try:
# Step 1: Login to the device.
login_result = await device.login()
print(f"Login successful: {login_result}")
# Step 2: Fetch the device status.
status_data = await 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.stations:
print("\n--- Connected Stations ---")
for station in status_data.wireless.stations:
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
### Classes
- `airos.data` (directly) as well as `airos.airos8` (indirectly) provides `AirOSData`, a [mashumaro](https://pypi.org/project/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.
- `stakick(mac_address: str)`: Disconnects a specific station by its MAC address.
- `airos.discovery`
- `async_discover_devices(timeout: int)` mainly for consumption by HA's `config_flow` returning a dict mapping mac-addresses to discovered info.
More features and API calls are planned for future releases.
## Contributing
We welcome contributions as well as additional codeowners to python-airos.
Raw data
{
"_id": null,
"home_page": null,
"name": "airos",
"maintainer": "CoMPaTech",
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "home, automation, ubiquity, uisp, airos, module",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/4b/d3/f1a2ff01d3c75f59f02a320ddbac91f8675428813dec1ad57cb6638e347a/airos-0.2.6.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n<img src=\"https://github.com/home-assistant/brands/blob/master/core_brands/ubiquiti/icon.png?raw=true\" alt=\"Ubiquiti airOS Logo\" width=\"150\" />\n<h1>python-airos</h1>\n<p>An asynchronous Python module to interact with Ubiquiti airOS devices, emulating a web browser client.</p>\n</div>\n\n<div align=\"center\">\n\n</div>\n\n[](https://github.com/python-airos)\n[](https://coderabbit.ai)\n[](https://github.com/compatech/python-airos/issues/8)\n\n[](https://pypi.python.org/pypi/airos/)\n[](https://github.com/compatech/python-airos/actions)\n[](https://github.com/compatech/python-airos/actions)\n\n[](https://www.codefactor.io/repository/github/plugwise/python-airos)\n[](https://codecov.io/gh/compatech/python-airos)\n\n[](https://sonarcloud.io/summary/new_code?id=CoMPaTech_python-airos)\n[](https://sonarcloud.io/summary/new_code?id=CoMPaTech_python-airos)\n[](https://sonarcloud.io/summary/new_code?id=CoMPaTech_python-airos)\n\n# Overview\n\n`python-airos` or [`airos`](https://pypi.org/projects/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.\n\nThis library is a key component for a potential future core integration with [Home Assistant](https://www.home-assistant.io), with the initial pull request for core integration targeted for the 2025.8 release.\n\nMore details on the integration can be found on the [Ubiquiti UISP airOS](https://www.home-assistant.io/integrations/airos/) page. To add airOS directly feel free to use the button below:\n\n[](https://my.home-assistant.io/redirect/_change/?redirect=config_flow_start%2F%3Fdomain%3Dairos)\n\n## Features\n\n- Asynchronous Operations: Built with `asyncio` and `aiohttp` for non-blocking I/O, which is perfect for integrations and background tasks.\n- Client Emulation: Authenticates and interacts with airOS devices by emulating a client browser, ensuring a high degree of compatibility.\n- Data Retrieval: Fetches comprehensive device status information, including:\n- Wireless mode and signal strength.\n- Connected stations and their statistics.\n- System information and uptime.\n- Device Control: Provides methods to perform actions, such as reconnecting/kicking a connected wireless station.\n- Discovery of airOS devices on your local network (by listening to announcements these devices broadcast).\n\n## Installation\n\nYou can install python-airos from PyPI using pip:\n\n```Bash\npip install airos\n```\n\n## Usage\n\nHere is a more detailed example of how to use the library to connect, fetch status, and perform an action on an airOS device.\n\n```Python\nimport aiohttp\nimport asyncio\nfrom airos.airos8 import AirOS\n\nasync def main():\n \"\"\"Main function to demonstrate library usage.\"\"\"\n # Create an aiohttp session with SSL verification disabled.\n # Be cautious with this setting; it's useful for self-signed certificates\n # but not recommended for production environments without proper validation.\n session = aiohttp.ClientSession(connector=aiohttp.TCPConnector(verify_ssl=False))\n\n # Initialize the AirOS device object.\n device = AirOS(\n host=\"192.168.1.2\",\n username=\"ubnt\",\n password=\"password\",\n session=session\n )\n\n try:\n # Step 1: Login to the device.\n login_result = await device.login()\n print(f\"Login successful: {login_result}\")\n\n # Step 2: Fetch the device status.\n status_data = await device.status()\n print(\"\\n--- Device Status ---\")\n print(f\"Device Name: {status_data.host.hostname}\")\n print(f\"Wireless Mode: {status_data.wireless.mode}\")\n print(f\"Firmware Version: {status_data.host.fwversion}\")\n\n # Fetch and display connected stations if available\n if status_data.wireless.stations:\n print(\"\\n--- Connected Stations ---\")\n for station in status_data.wireless.stations:\n print(f\" - MAC: {station.mac}\")\n print(f\" Signal: {station.signal} dBm\")\n print(f\" Uptime: {station.uptime} seconds\")\n\n # Step 3: Perform an action, e.g., kick a station.\n # Replace '01:23:45:67:89:AB' with the MAC address of a station to kick.\n # kick_result = await device.stakick(\"01:23:45:67:89:AB\")\n # print(f\"\\nKick station result: {kick_result}\")\n\n except Exception as e:\n print(f\"An error occurred: {e}\")\n finally:\n # Ensure the aiohttp session is closed properly.\n await session.close()\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## Supported API classes and calls\n\n### Classes\n\n- `airos.data` (directly) as well as `airos.airos8` (indirectly) provides `AirOSData`, a [mashumaro](https://pypi.org/project/mashumaro/) based dataclass\n- `airos.discovery` provides `AirOSDiscoveryProtocol` for the actual discovery, we recommend to use the `async_discover_devices` function for consumption as described below\n\n### Calls\n\n- `airos.airos8`: initializes with `host: str, username: str, password: str, session: aiohttp.ClientSession`\n - `login()`: Authenticates with the device.\n - `status()`: Fetches a comprehensive dictionary of the device's status and statistics.\n - `stakick(mac_address: str)`: Disconnects a specific station by its MAC address.\n- `airos.discovery`\n - `async_discover_devices(timeout: int)` mainly for consumption by HA's `config_flow` returning a dict mapping mac-addresses to discovered info.\n\nMore features and API calls are planned for future releases.\n\n## Contributing\n\nWe welcome contributions as well as additional codeowners to python-airos.\n",
"bugtrack_url": null,
"license": null,
"summary": "Ubiquity airOS module(s) for Python 3.",
"version": "0.2.6",
"project_urls": {
"Bug Reports": "https://github.com/compatech/python-airos/issues",
"Source Code": "https://github.com/compatech/python-airos"
},
"split_keywords": [
"home",
" automation",
" ubiquity",
" uisp",
" airos",
" module"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "db86777688f00f8775238bd7ce380f060e04a21fca21813008bd86c60b69cd1e",
"md5": "04c0810e435e073370cf2acab20b9158",
"sha256": "eef68ff8124e8cf0c3d2357c704c01979b5e1a2c6e840191cb6e896efc5bd1d9"
},
"downloads": -1,
"filename": "airos-0.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "04c0810e435e073370cf2acab20b9158",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 16637,
"upload_time": "2025-08-06T17:56:02",
"upload_time_iso_8601": "2025-08-06T17:56:02.180826Z",
"url": "https://files.pythonhosted.org/packages/db/86/777688f00f8775238bd7ce380f060e04a21fca21813008bd86c60b69cd1e/airos-0.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4bd3f1a2ff01d3c75f59f02a320ddbac91f8675428813dec1ad57cb6638e347a",
"md5": "3cba079281d40c6f078cf6ee6c733929",
"sha256": "8dcea2ad4349bc528d71442ca447bc99084abc221b8bab2d89a30ae260c24be2"
},
"downloads": -1,
"filename": "airos-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "3cba079281d40c6f078cf6ee6c733929",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 30881,
"upload_time": "2025-08-06T17:56:03",
"upload_time_iso_8601": "2025-08-06T17:56:03.016387Z",
"url": "https://files.pythonhosted.org/packages/4b/d3/f1a2ff01d3c75f59f02a320ddbac91f8675428813dec1ad57cb6638e347a/airos-0.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-06 17:56:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "compatech",
"github_project": "python-airos",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
"==",
"3.12.15"
]
]
},
{
"name": "mashumaro",
"specs": [
[
"==",
"3.16"
]
]
}
],
"lcname": "airos"
}
JSON
