Skip to content

Commit d19a87c

Browse files
CoMPaTechCoMPaTech
authored
Update README.md
1 parent 93acae5 commit d19a87c

File tree

1 file changed

+112
-24
lines changed

1 file changed

+112
-24
lines changed

‎README.md‎

Lines changed: 112 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,124 @@
1-
# Ubiquity airOS Module
1+
<div align="center">
2+
<img src="https://github.com/home-assistant/brands/blob/master/core_brands/ubiquiti/icon.png?raw=true" alt="Ubiquiti airOS Logo" width="150" />
3+
<h1>python-airos</h1>
4+
<p>An asynchronous Python module to interact with Ubiquiti airOS devices, emulating a web browser client.</p>
5+
</div>
26

3-
## Main usage
7+
<div align="center">
48

5-
Via [Home-Assistant](https://www.home-assistant.io) - initial core integration [pending](https://github.com/home-assistant/core/pull/148989).
9+
</div>
610

7-
## Working
11+
[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/python-airos)
12+
[![CodeRabbit.ai is Awesome](https://img.shields.io/badge/AI-orange?label=CodeRabbit&color=orange&link=https%3A%2F%2Fcoderabbit.ai)](https://coderabbit.ai)
13+
[![renovate maintained](https://img.shields.io/badge/maintained%20with-renovate-blue?logo=renovatebot)](https://github.com/compatech/python-airos/issues/8)
814

9-
Emulating client browser
15+
[![PyPI version fury.io](https://badge.fury.io/py/airos.svg)](https://pypi.python.org/pypi/airos/)
16+
[![Latest release](https://github.com/compatech/python-airos/workflows/Latest%20release/badge.svg)](https://github.com/compatech/python-airos/actions)
17+
[![Newest commit](https://github.com/compatech/python-airos/workflows/Latest%20commit/badge.svg)](https://github.com/compatech/python-airos/actions)
1018

11-
```example.py
12-
from airos.airos8 import AirOS
19+
[![CodeFactor](https://www.codefactor.io/repository/github/compatech/python-airos/badge)](https://www.codefactor.io/repository/github/plugwise/python-airos)
20+
[![codecov](https://codecov.io/gh/compatech/python-airos/branch/main/graph/badge.svg?token=WI5K2IZWNS)](https://codecov.io/gh/compatech/python-airos)
21+
22+
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=CoMPaTech_python-airos&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=CoMPaTech_python-airos)
23+
[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=CoMPaTech_python-airos&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=CoMPaTech_python-airos)
24+
[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=CoMPaTech_python-airos&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=CoMPaTech_python-airos)
25+
26+
# Overview
27+
`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.
28+
29+
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.
30+
31+
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:
32+
33+
[![Open your Home Assistant instance and show your integrations.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/_change/?redirect=config_flow_start%2F%3Fdomain%3Dairos)
34+
35+
## Features
36+
37+
- Asynchronous Operations: Built with `asyncio` and `aiohttp` for non-blocking I/O, which is perfect for integrations and background tasks.
38+
- Client Emulation: Authenticates and interacts with airOS devices by emulating a client browser, ensuring a high degree of compatibility.
39+
- Data Retrieval: Fetches comprehensive device status information, including:
40+
- Wireless mode and signal strength.
41+
- Connected stations and their statistics.
42+
- System information and uptime.
43+
- Device Control: Provides methods to perform actions, such as reconnecting/kicking a connected wireless station.
44+
- Discovery of airOS devices on your local network (by listening to announcements these devices broadcast).
45+
46+
## Installation
47+
48+
You can install python-airos from PyPI using pip:
49+
50+
```Bash
51+
pip install airos
52+
```
53+
54+
## Usage
55+
56+
Here is a more detailed example of how to use the library to connect, fetch status, and perform an action on an airOS device.
57+
58+
```Python
1359
import aiohttp
1460
import asyncio
61+
from airos.airos8 import AirOS
1562

16-
async def test_airos():
63+
async def main():
64+
"""Main function to demonstrate library usage."""
65+
# Create an aiohttp session with SSL verification disabled.
66+
# Be cautious with this setting; it's useful for self-signed certificates
67+
# but not recommended for production environments without proper validation.
1768
session = aiohttp.ClientSession(connector=aiohttp.TCPConnector(verify_ssl=False))
18-
device = AirOS(host="192.168.1.2",username="ubnt",password="password",session=session)
19-
# Login
20-
result = await device.login()
21-
print(f"Result: {result}")
22-
# Fetch status (large dict, including connected stations)
23-
result = await device.status()
24-
print(f"Result: {result}")
25-
print(f"Result: {result.wireless.mode}")
26-
# Reconnect 'other side'
27-
result = await device.stakick("01:23:45:67:89:AB")
28-
print(f"Result: {result}")
29-
30-
def async_loop(loop: asyncio.AbstractEventLoop) -> int:
31-
return loop.run_until_complete(test_airos())
69+
70+
# Initialize the AirOS device object.
71+
device = AirOS(
72+
host="192.168.1.2",
73+
username="ubnt",
74+
password="password",
75+
session=session
76+
)
77+
78+
try:
79+
# Step 1: Login to the device.
80+
login_result = await device.login()
81+
print(f"Login successful: {login_result}")
82+
83+
# Step 2: Fetch the device status.
84+
status_data = await device.status()
85+
print("\n--- Device Status ---")
86+
print(f"Device Name: {status_data.host.hostname}")
87+
print(f"Wireless Mode: {status_data.wireless.mode}")
88+
print(f"Firmware Version: {status_data.host.fwversion}")
89+
90+
# Fetch and display connected stations if available
91+
if status_data.wireless.stations:
92+
print("\n--- Connected Stations ---")
93+
for station in status_data.wireless.stations:
94+
print(f" - MAC: {station.mac}")
95+
print(f" Signal: {station.signal} dBm")
96+
print(f" Uptime: {station.uptime} seconds")
97+
98+
# Step 3: Perform an action, e.g., kick a station.
99+
# Replace '01:23:45:67:89:AB' with the MAC address of a station to kick.
100+
# kick_result = await device.stakick("01:23:45:67:89:AB")
101+
# print(f"\nKick station result: {kick_result}")
102+
103+
except Exception as e:
104+
print(f"An error occurred: {e}")
105+
finally:
106+
# Ensure the aiohttp session is closed properly.
107+
await session.close()
32108

33109
if __name__ == "__main__":
34-
loop = asyncio.new_event_loop()
35-
result = async_loop(loop)
110+
asyncio.run(main())
36111
```
112+
113+
## Supported API Calls
114+
115+
The library currently supports the following methods:
116+
117+
- `login()`: Authenticates with the device.
118+
- `status()`: Fetches a comprehensive dictionary of the device's status and statistics.
119+
-` stakick(mac_address)`: Disconnects a specific station by its MAC address.
120+
121+
More features and API calls are planned for future releases.
122+
123+
## Contributing
124+
We welcome contributions as well as additional codeowners to python-airos.

0 commit comments

Comments
 (0)