Add warning and update-check endpoints, improve quality

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.0] - 2025-08-15
+
+### Added
+
+- Implementation of `[AP|Sta]-[MODE]` to Enums.
+- Added update check (non-forced) endpoint
+- Added warnings fetch endpoint
+
 ## [0.2.11] - 2025-08-14
 
 ### Changed

airos/airos8.py

@@ -11,7 +11,12 @@
 import aiohttp
 from mashumaro.exceptions import InvalidFieldValue, MissingField
 
-from .data import AirOS8Data as AirOSData, redact_data_smart
+from .data import (
+    AirOS8Data as AirOSData,
+    DerivedWirelessMode,
+    DerivedWirelessRole,
+    redact_data_smart,
+)
 from .exceptions import (
     AirOSConnectionAuthenticationError,
     AirOSConnectionSetupError,
@@ -54,6 +59,8 @@ def __init__(
         self._status_cgi_url = f"{self.base_url}/status.cgi"  # AirOS 8
         self._stakick_cgi_url = f"{self.base_url}/stakick.cgi"  # AirOS 8
         self._provmode_url = f"{self.base_url}/api/provmode"  # AirOS 8
+        self._warnings_url = f"{self.base_url}/api/warnings"  # AirOS 8
+        self._update_check_url = f"{self.base_url}/api/fw/update-check"  # AirOS 8
         self.current_csrf_token: str | None = None
 
         self._use_json_for_login_post = False
@@ -201,6 +208,8 @@ def derived_data(response: dict[str, Any]) -> dict[str, Any]:
             "access_point": False,
             "ptp": False,
             "ptmp": False,
+            "role": DerivedWirelessRole.STATION,
+            "mode": DerivedWirelessMode.PTP,
         }
 
         # Access Point / Station vs PTP/PtMP
@@ -209,12 +218,16 @@ def derived_data(response: dict[str, Any]) -> dict[str, Any]:
             case "ap-ptmp":
                 derived["access_point"] = True
                 derived["ptmp"] = True
+                derived["role"] = DerivedWirelessRole.ACCESS_POINT
+                derived["mode"] = DerivedWirelessMode.PTMP
             case "sta-ptmp":
                 derived["station"] = True
                 derived["ptmp"] = True
+                derived["mode"] = DerivedWirelessMode.PTMP
             case "ap-ptp":
                 derived["access_point"] = True
                 derived["ptp"] = True
+                derived["role"] = DerivedWirelessRole.ACCESS_POINT
             case "sta-ptp":
                 derived["station"] = True
                 derived["ptp"] = True
@@ -384,3 +397,69 @@ async def provmode(self, active: bool = False) -> bool:
         except asyncio.CancelledError:
             _LOGGER.info("Provisioning mode change task was cancelled")
             raise
+
+    async def warnings(self) -> dict[str, Any] | Any:
+        """Get warnings."""
+        if not self.connected:
+            _LOGGER.error("Not connected, login first")
+            raise AirOSDeviceConnectionError from None
+
+        request_headers = {**self._common_headers}
+        if self.current_csrf_token:
+            request_headers["X-CSRF-ID"] = self.current_csrf_token
+
+        # Formal call is '/api/warnings?_=1755249683586'
+        try:
+            async with self.session.get(
+                self._warnings_url,
+                headers=request_headers,
+            ) as response:
+                response_text = await response.text()
+                if response.status == 200:
+                    return json.loads(response_text)
+                log = f"Unable to fech warning status {response.status} with {response_text}"
+                _LOGGER.error(log)
+                raise AirOSDataMissingError from None
+        except json.JSONDecodeError:
+            _LOGGER.exception("JSON Decode Error in warning response")
+            raise AirOSDataMissingError from None
+        except (TimeoutError, aiohttp.ClientError) as err:
+            _LOGGER.exception("Error during call to retrieve warnings: %s", err)
+            raise AirOSDeviceConnectionError from err
+        except asyncio.CancelledError:
+            _LOGGER.info("Warning check task was cancelled")
+            raise
+
+    async def update_check(self) -> dict[str, Any] | Any:
+        """Get warnings."""
+        if not self.connected:
+            _LOGGER.error("Not connected, login first")
+            raise AirOSDeviceConnectionError from None
+
+        request_headers = {**self._common_headers}
+        if self.current_csrf_token:
+            request_headers["X-CSRF-ID"] = self.current_csrf_token
+        request_headers["Content-type"] = "application/json"
+
+        # Post without data
+        try:
+            async with self.session.post(
+                self._update_check_url,
+                headers=request_headers,
+                json={},
+            ) as response:
+                response_text = await response.text()
+                if response.status == 200:
+                    return json.loads(response_text)
+                log = f"Unable to fech update status {response.status} with {response_text}"
+                _LOGGER.error(log)
+                raise AirOSDataMissingError from None
+        except json.JSONDecodeError:
+            _LOGGER.exception("JSON Decode Error in warning response")
+            raise AirOSDataMissingError from None
+        except (TimeoutError, aiohttp.ClientError) as err:
+            _LOGGER.exception("Error during call to retrieve update status: %s", err)
+            raise AirOSDeviceConnectionError from err
+        except asyncio.CancelledError:
+            _LOGGER.info("Warning update status task was cancelled")
+            raise

airos/data.py

@@ -141,6 +141,20 @@ class IeeeMode(Enum):
     # More to be added when known
 
 
+class DerivedWirelessRole(Enum):
+    """Enum definition."""
+
+    STATION = "station"
+    ACCESS_POINT = "access_point"
+
+
+class DerivedWirelessMode(Enum):
+    """Enum definition."""
+
+    PTP = "point_to_point"
+    PTMP = "point_to_multipoint"
+
+
 class WirelessMode(Enum):
     """Enum definition."""
 
@@ -350,7 +364,7 @@ class Remote(AirOSDataClass):
     rssi: int
     noisefloor: int
     tx_power: int
-    distance: int
+    distance: int  # In meters
     rx_chainmask: int
     chainrssi: list[int]
     tx_ratedata: list[int]
@@ -408,7 +422,7 @@ class Station(AirOSDataClass):
     tx_nss: int
     rx_nss: int
     tx_latency: int
-    distance: int
+    distance: int  # In meters
     tx_packets: int
     tx_lretries: int
     tx_sretries: int
@@ -446,7 +460,7 @@ class Wireless(AirOSDataClass):
     frequency: int
     center1_freq: int
     dfs: int
-    distance: int
+    distance: int  # In meters
     security: Security
     noisef: int
     txpower: int
@@ -554,6 +568,9 @@ class Derived(AirOSDataClass):
     ptp: bool
     ptmp: bool
 
+    role: DerivedWirelessRole
+    mode: DerivedWirelessMode
+
 
 @dataclass
 class AirOS8Data(AirOSDataClass):

fixtures/airos_LiteBeam5AC_ap-ptp_30mhz.json

@@ -13,8 +13,10 @@
     "access_point": true,
     "mac": "68:D7:9A:9A:08:BB",
     "mac_interface": "br0",
+    "mode": "point_to_point",
     "ptmp": false,
     "ptp": true,
+    "role": "access_point",
     "station": false
   },
   "firewall": {

fixtures/airos_LiteBeam5AC_sta-ptp_30mhz.json

@@ -13,8 +13,10 @@
     "access_point": false,
     "mac": "68:D7:9A:98:FB:FF",
     "mac_interface": "br0",
+    "mode": "point_to_point",
     "ptmp": false,
     "ptp": true,
+    "role": "station",
     "station": true
   },
   "firewall": {

fixtures/airos_liteapgps_ap_ptmp_40mhz.json

@@ -13,8 +13,10 @@
     "access_point": true,
     "mac": "04:11:22:33:19:7E",
     "mac_interface": "br0",
+    "mode": "point_to_multipoint",
     "ptmp": true,
     "ptp": false,
+    "role": "access_point",
     "station": false
   },
   "firewall": {

fixtures/airos_loco5ac_ap-ptp.json

@@ -13,8 +13,10 @@
     "access_point": true,
     "mac": "01:23:45:67:89:AB",
     "mac_interface": "br0",
+    "mode": "point_to_point",
     "ptmp": false,
     "ptp": true,
+    "role": "access_point",
     "station": false
   },
   "firewall": {

fixtures/airos_loco5ac_sta-ptp.json

@@ -13,8 +13,10 @@
     "access_point": false,
     "mac": "01:23:45:67:89:CD",
     "mac_interface": "br0",
+    "mode": "point_to_point",
     "ptmp": false,
     "ptp": true,
+    "role": "station",
     "station": true
   },
   "firewall": {

fixtures/airos_nanobeam5ac_sta_ptmp_40mhz.json

@@ -13,8 +13,10 @@
     "access_point": false,
     "mac": "22:22:33:44:31:38",
     "mac_interface": "br0",
+    "mode": "point_to_multipoint",
     "ptmp": true,
     "ptp": false,
+    "role": "station",
     "station": true
   },
   "firewall": {

fixtures/airos_nanostation_ap-ptp_8718_missing_gps.json

@@ -13,8 +13,10 @@
     "access_point": true,
     "mac": "00:11:22:33:34:66",
     "mac_interface": "br0",
+    "mode": "point_to_point",
     "ptmp": false,
     "ptp": true,
+    "role": "access_point",
     "station": false
   },
   "firewall": {

fixtures/update_check_available.json

@@ -0,0 +1 @@
+{"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"}

fixtures/warnings.json

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

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name            = "airos"
-version         = "0.2.11"
+version         = "0.3.0"
 license         = "MIT"
 description     = "Ubiquity airOS module(s) for Python 3."
 readme          = "README.md"

requirements-test.txt

@@ -10,3 +10,4 @@ radon==6.0.1
 types-aiofiles==24.1.0.20250809
 mypy==1.17.1
 pylint==3.3.7
+aiofiles==24.1.0

script/generate_ha_fixture.py

@@ -55,8 +55,10 @@ def generate_airos_fixtures() -> None:
 
             except json.JSONDecodeError:
                 _LOGGER.error("Skipping '%s': Not a valid JSON file.", filename)
+                raise
             except Exception as e:
                 _LOGGER.error("Error processing '%s': %s", filename, e)
+                raise
 
 
 if __name__ == "__main__":