teltasync 0.1.0__tar.gz

teltasync-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: teltasync
+Version: 0.1.0
+Summary: Async, typed API client for Teltonika routers, built for Home Assistant
+Author: Karl Beecken
+Author-email: karl@beecken.berlin
+Requires-Python: >=3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: aiohttp (>=3.12,<4.0)
+Requires-Dist: pydantic (>=2.7,<3.0)

teltasync-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[tool.poetry]
+name = "teltasync"
+version = "0.1.0"
+description = "Async, typed API client for Teltonika routers, built for Home Assistant"
+authors = ["Karl Beecken <karl@beecken.berlin>"]
+packages = [
+    { include = "teltasync", from = "src" }
+]
+
+[tool.poetry.dependencies]
+python = ">=3.13"
+aiohttp = "^3.12"
+pydantic = "^2.7"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.2"
+pytest-asyncio = "^0.23"
+aioresponses = "^0.7"
+watchdog = "^5.0"
+pytest-watch = "^4.2"
+mypy = "^1.18.2"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "-q"
+
+[build-system]
+requires = ["poetry-core>=1.8.0"]
+build-backend = "poetry.core.masonry.api"

teltasync-0.1.0/src/teltasync/__init__.py

@@ -0,0 +1,18 @@
+"""Teltonika API library."""
+
+from teltasync.exceptions import (
+    TeltonikaException,
+    TeltonikaConnectionError,
+    TeltonikaAuthenticationError,
+    TeltonikaInvalidCredentialsError,
+)
+from teltasync.teltasync import Teltasync
+
+__version__ = "0.1.0"
+__all__ = [
+    "Teltasync",
+    "TeltonikaException",
+    "TeltonikaConnectionError",
+    "TeltonikaAuthenticationError",
+    "TeltonikaInvalidCredentialsError",
+]

teltasync-0.1.0/src/teltasync/api_base.py

@@ -0,0 +1,42 @@
+from typing import Any, Generic, TypeVar
+
+from pydantic import model_validator
+
+from teltasync.base_model import TeltasyncBaseModel
+
+T = TypeVar("T")
+
+
+def _convert_na_to_none(value: Any) -> Any:
+    if value == "N/A":
+        return None
+    if isinstance(value, dict):
+        return {key: _convert_na_to_none(val) for key, val in value.items()}
+    if isinstance(value, list):
+        return [_convert_na_to_none(item) for item in value]
+    return value
+
+
+class ApiError(TeltasyncBaseModel):
+    code: int
+    error: str
+    source: str | None = None
+    section: str | None = None
+
+
+class ApiResponse(TeltasyncBaseModel, Generic[T]):
+    success: bool
+    data: T | None = None
+    errors: list[ApiError] | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _convert_na_strings(cls, values: Any) -> Any:
+        if isinstance(values, dict):
+            return _convert_na_to_none(values)
+        return values
+
+    def get_error_by_code(self, code: int) -> ApiError | None:
+        if not self.errors:
+            return None
+        return next((error for error in self.errors if error.code == code), None)

teltasync-0.1.0/src/teltasync/auth.py

@@ -0,0 +1,180 @@
+import asyncio
+import time
+
+from aiohttp import ClientConnectorError, ClientSession, ClientTimeout
+from pydantic import BaseModel
+
+from teltasync.api_base import ApiResponse
+from teltasync.exceptions import (
+    TeltonikaAuthenticationError,
+    TeltonikaConnectionError,
+    TeltonikaInvalidCredentialsError,
+)
+
+
+class TokenData(BaseModel):
+    username: str
+    token: str
+    expires: int
+
+
+class LogoutResponse(BaseModel):
+    response: str
+
+
+class SessionStatusData(BaseModel):
+    active: bool
+
+
+class Auth:
+    def __init__(
+            self,
+            session: ClientSession,
+            base_url: str,
+            username: str,
+            password: str,
+            check_certificate: bool = True,
+    ):
+        self.session = session
+        self.base_url = base_url
+        self.username = username
+        self.password = password
+        self.check_certificate = check_certificate
+
+        self._token: str | None = None
+        self._token_expires: int | None = None
+        self._token_username: str | None = None
+        self._token_time: float | None = None
+        self._authenticated = False
+
+    @property
+    def token(self) -> str | None:
+        return self._token
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._authenticated and self._token is not None
+
+    def is_token_expired(self) -> bool:
+        if not self._token or not self._token_expires or not self._token_time:
+            return True
+        return time.time() - self._token_time >= self._token_expires - 5
+
+    def clear_token(self) -> None:
+        self._token = None
+        self._token_expires = None
+        self._token_username = None
+        self._token_time = None
+        self._authenticated = False
+
+    async def authenticate(self) -> ApiResponse[TokenData]:
+        try:
+            async with self.session.post(
+                    f"{self.base_url}/login",
+                    json={"username": self.username, "password": self.password},
+                    ssl=self.check_certificate,
+                    timeout=ClientTimeout(total=10.0),
+            ) as resp:
+                status = resp.status
+                payload = await resp.json()
+        except ClientConnectorError as exc:
+            raise TeltonikaConnectionError(
+                f"Cannot connect to device at {self.base_url}: {exc}",
+                exc,
+            ) from exc
+        except asyncio.TimeoutError as exc:
+            raise TeltonikaConnectionError(
+                f"Connection timeout to device at {self.base_url}",
+                exc,
+            ) from exc
+        except Exception as exc:
+            message = str(exc)
+            timeout_hit = "timeout" in message.lower()
+            raise TeltonikaConnectionError(
+                f"Connection {'timeout' if timeout_hit else 'error'} to device at {self.base_url}: {message}",
+                exc,
+            ) from exc
+
+        response = ApiResponse[TokenData](**payload)
+
+        if response.success and response.data:
+            self._token = response.data.token
+            self._token_expires = response.data.expires
+            self._token_username = response.data.username
+            self._token_time = time.time()
+            self._authenticated = True
+            return response
+
+        if status == 401:
+            raise TeltonikaInvalidCredentialsError()
+
+        if response.errors:
+            err = response.errors[0]
+            raise TeltonikaAuthenticationError(
+                f"Authentication failed: {err.error}",
+                err.code,
+            )
+
+        raise TeltonikaAuthenticationError("Authentication failed")
+
+    async def logout(self) -> ApiResponse[LogoutResponse]:
+        if self._token is None:
+            return ApiResponse[LogoutResponse](
+                success=True,
+                data=LogoutResponse(response="No active session"),
+            )
+
+        try:
+            async with self.session.post(
+                    f"{self.base_url}/logout",
+                    headers={"Authorization": f"Bearer {self._token}"},
+                    ssl=self.check_certificate,
+                    timeout=ClientTimeout(total=10.0),
+            ) as resp:
+                payload = await resp.json()
+                return ApiResponse[LogoutResponse](**payload)
+        finally:
+            self.clear_token()
+
+    async def get_session_status(self) -> ApiResponse[SessionStatusData]:
+        if self._token is None:
+            return ApiResponse[SessionStatusData](
+                success=True,
+                data=SessionStatusData(active=False),
+            )
+
+        try:
+            async with self.session.get(
+                    f"{self.base_url}/session/status",
+                    headers={"Authorization": f"Bearer {self._token}"},
+                    ssl=self.check_certificate,
+                    timeout=ClientTimeout(total=10.0),
+            ) as resp:
+                payload = await resp.json()
+        except Exception:
+            self.clear_token()
+            return ApiResponse[SessionStatusData](
+                success=True,
+                data=SessionStatusData(active=False),
+            )
+
+        response = ApiResponse[SessionStatusData](**payload)
+        if response.success and response.data and not response.data.active:
+            self.clear_token()
+        return response
+
+    async def request(self, method: str, endpoint: str, **kwargs):
+        if self.is_token_expired():
+            await self.authenticate()
+
+        headers = kwargs.pop("headers", {})
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+
+        return self.session.request(
+            method,
+            f"{self.base_url}/{endpoint.lstrip('/')}",
+            headers=headers,
+            ssl=self.check_certificate,
+            **kwargs,
+        )

teltasync-0.1.0/src/teltasync/base_model.py

@@ -0,0 +1,7 @@
+from pydantic import ConfigDict, BaseModel
+
+from teltasync.utils import camel_to_snake
+
+
+class TeltasyncBaseModel(BaseModel):
+    model_config = ConfigDict(alias_generator=camel_to_snake, populate_by_name=True)

teltasync-0.1.0/src/teltasync/error_codes.py

@@ -0,0 +1,66 @@
+"""Teltonika API error codes and their descriptions."""
+
+from enum import IntEnum
+from typing import Dict
+
+
+class TeltonikaErrorCode(IntEnum):
+    """Teltonika API error codes as defined in the API documentation."""
+
+    # General API errors (100-119)
+    RESPONSE_NOT_IMPLEMENTED = 100
+    NO_ACTION_PROVIDED = 101
+    PROVIDED_ACTION_NOT_AVAILABLE = 102
+    INVALID_OPTIONS = 103
+    UCI_GET_ERROR = 104
+    UCI_DELETE_ERROR = 105
+    UCI_CREATE_ERROR = 106
+    INVALID_STRUCTURE = 107
+    SECTION_CREATION_NOT_ALLOWED = 108
+    NAME_ALREADY_USED = 109
+    NAME_NOT_PROVIDED = 110
+    DELETE_NOT_ALLOWED = 111
+    DELETION_OF_WHOLE_CONFIG_NOT_ALLOWED = 112
+    INVALID_SECTION_PROVIDED = 113
+    NO_BODY_PROVIDED = 114
+    UCI_SET_ERROR = 115
+    INVALID_QUERY_PARAMETER = 116
+    GENERAL_CONFIGURATION_ERROR = 117
+
+    # Authentication and authorization errors (120-123)
+    UNAUTHORIZED_ACCESS = 120
+    LOGIN_FAILED = 121
+    GENERAL_STRUCTURE_INCORRECT = 122
+    INVALID_JWT_TOKEN = 123
+
+    # File upload errors (150-151)
+    NOT_ENOUGH_FREE_SPACE = 150
+    FILE_SIZE_TOO_BIG = 151
+
+
+ERROR_DESCRIPTIONS: Dict[int, str] = {
+    100: "Response not implemented",
+    101: "No action provided",
+    102: "Provided action is not available",
+    103: "Invalid options",
+    104: "UCI GET error",
+    105: "UCI DELETE error",
+    106: "UCI CREATE error",
+    107: "Invalid structure",
+    108: "Section creation is not allowed",
+    109: "Name already used",
+    110: "Name not provided",
+    111: "DELETE not allowed",
+    112: "Deletion of whole configuration is not allowed",
+    113: "Invalid section provided",
+    114: "No body provided for the request",
+    115: "UCI SET error",
+    116: "Invalid query parameter",
+    117: "General configuration error",
+    120: "Unauthorized access",
+    121: "Login failed for any reason",
+    122: "General structure of request is incorrect",
+    123: "JWT token that is provided with authorization header is invalid - unparsable, incomplete, etc.",
+    150: "Not enough free space in the device (when uploading files)",
+    151: "File size is bigger than the maximum size allowed (when uploading files)",
+}

teltasync-0.1.0/src/teltasync/exceptions.py

@@ -0,0 +1,19 @@
+class TeltonikaException(Exception):
+    pass
+
+
+class TeltonikaConnectionError(TeltonikaException):
+    def __init__(self, message: str, original_error: Exception | None = None):
+        super().__init__(message)
+        self.original_error = original_error
+
+
+class TeltonikaAuthenticationError(TeltonikaException):
+    def __init__(self, message: str, error_code: int | None = None):
+        super().__init__(message)
+        self.error_code = error_code
+
+
+class TeltonikaInvalidCredentialsError(TeltonikaAuthenticationError):
+    def __init__(self, message: str = "Invalid username or password"):
+        super().__init__(message, 121)

teltasync-0.1.0/src/teltasync/modems.py

@@ -0,0 +1,322 @@
+"""Bindings for the modem endpoints on Teltonika hardware."""
+
+from typing import Literal
+
+from pydantic import Field, computed_field
+
+from teltasync.api_base import ApiResponse
+from teltasync.auth import Auth
+from teltasync.base_model import TeltasyncBaseModel
+
+# Enum types for the state fields
+PinState = Literal[
+    "Inserted",
+    "Not ready",
+    "Required PIN, X attempts left",
+    "Required PUK, X attempts left",
+    "Not inserted",
+    "SIM failure",
+    "Busy",
+    "PUK"
+]
+
+OperatorState = Literal[
+    "Not registered",
+    "Registered, home",
+    "Searching",
+    "Denied",
+    "Unknown",
+    "Roaming"
+]
+
+
+def decode_ue_state(ue_state: int | None) -> str | None:
+    """Decode User Equipment state code to human-readable description.
+
+    Based on 3GPP TS 24.008.
+
+    Args:
+        ue_state: The UE state code (integer)
+
+    Returns:
+        Human-readable description of the UE state, or None if invalid/unknown
+    """
+    if ue_state is None:
+        return None
+
+    ue_states = {
+        0: "Detached",
+        1: "Attached",
+        2: "Connecting",
+        3: "Connected",
+        4: "Idle",
+        5: "Disconnecting",
+        6: "Emergency Attached",
+        7: "Limited Service",
+        8: "No Service"
+    }
+
+    return ue_states.get(ue_state, f"Unknown UE state ({ue_state})")
+
+
+def decode_mobile_stage(mobile_stage: int | None) -> str | None:
+    """Decode mobile stage code to human-readable description.
+
+    Key from https://developers.teltonika-networks.com/reference/rutx50/7.13.3/v1.5/modems#get-modems-status-id
+
+    Args:
+        mobile_stage: The mobile stage code (integer)
+
+    Returns:
+        Human-readable description of the mobile stage, or None if invalid/unknown
+    """
+    if mobile_stage is None:
+        return None
+
+    mobile_stages = {
+        0: "Unknown state",
+        1: "Waiting for SIM to be inserted",
+        2: "SIM failure",
+        3: "Idling",
+        4: "Waiting for user action",
+        5: "Waiting for PIN to be entered",
+        6: "Waiting for PUK to be entered",
+        7: "SIM blocked, no PUK attempts left",
+        8: "Initializing mobile connection",
+        9: "Configuring Voice over LTE (VoLTE)",
+        10: "Setting up connection settings",
+        11: "Scanning for available operators",
+        12: "Currently handling SIM PIN event",
+        13: "Currently handling SIM switch event",
+        14: "Initializing modem",
+        15: "Changed default SIM card",
+        16: "Setting up data connection settings",
+        17: "Clearing PDP context",
+        18: "Currently handling config",
+        19: "Mobile connection setup is complete"
+    }
+
+    return mobile_stages.get(mobile_stage, f"Unknown mobile stage ({mobile_stage})")
+
+
+class CellInfo(TeltasyncBaseModel):
+    """Cell information for modem."""
+    mcc: str | None = Field(None, description="Mobile Country Code")
+    mnc: str | None = Field(None, description="Mobile Network Code")
+    cell_id: str | None = Field(None, alias="cellid", description="Cell ID")
+    ue_state: int | None = Field(None, description="UE state code")
+    lac: str | None = Field(None, description="Location Area Code")
+    tac: str | None = Field(None, description="Tracking Area Code")
+    pcid: int | None = Field(None, description="Physical Cell ID")
+    earfcn: str | int | None = Field(None, description="E-ARFCN")
+    arfcn: str | int | None = Field(None, description="ARFCN")
+    uarfcn: str | int | None = Field(None, description="UARFCN")
+    nr_arfcn: str | int | None = Field(None, alias="nr-arfcn", description="NR-ARFCN")
+    rsrp: str | int | None = Field(None, description="Reference Signal Received Power")
+    rsrq: str | int | None = Field(None, description="Reference Signal Received Quality")
+    sinr: str | int | None = Field(None, description="Signal to Interference plus Noise Ratio")
+    bandwidth: str | None = Field(None, description="Bandwidth")
+
+    @computed_field
+    def ue_state_description(self) -> str | None:
+        """Get human-readable description of the UE state."""
+        return decode_ue_state(self.ue_state)
+
+
+class ServiceModes(TeltasyncBaseModel):
+    """Service modes available for each network type."""
+    field_2g: list[str] | None = Field(None, alias="2G", description="2G service modes")
+    field_3g: list[str] | None = Field(None, alias="3G", description="3G service modes")
+    field_4g: list[str] | None = Field(None, alias="4G", description="4G service modes")
+    nb: list[str] | None = Field(None, alias="NB", description="NB-IoT service modes")
+    field_5g_nsa: list[str] | None = Field(None, alias="5G_NSA", description="5G NSA service modes")
+    field_5g_sa: list[str] | None = Field(None, alias="5G_SA", description="5G SA service modes")
+
+
+class CarrierAggregationSignal(TeltasyncBaseModel):
+    """Carrier aggregation signal information."""
+    band: str | None = Field(None, description="Band")
+    bandwidth: str | None = Field(None, description="Bandwidth")
+    sinr: int | None = Field(None, description="SINR")
+    rsrq: int | None = Field(None, description="RSRQ")
+    rsrp: int | None = Field(None, description="RSRP")
+    pcid: int | None = Field(None, description="Physical Cell ID")
+    frequency: str | int | None = Field(None, description="Frequency")
+    # Some CA signals might not have all fields
+    primary: bool | None = Field(None, description="Primary carrier")
+
+
+class ModemStatusFull(TeltasyncBaseModel):
+    """Full modem status when online."""
+    id: str = Field(description="Modem ID")
+    imei: str | None = Field(None, description="IMEI")
+    model: str | None = Field(None, description="Modem model")
+    cell_info: list[CellInfo] | None = Field(None, description="Cell information")
+    dynamic_mtu: bool | None = Field(None, description="Dynamic MTU support")
+    service_modes: ServiceModes | None = Field(None, description="Available service modes")
+    lac: str | None = Field(None, description="Location Area Code")
+    tac: str | None = Field(None, description="Tracking Area Code")
+    name: str | None = Field(None, description="Modem name")
+    index: int | None = Field(None, description="Modem index")
+    sim_count: int | None = Field(None, description="Number of SIM cards")
+    version: str | None = Field(None, description="Modem version")
+    manufacturer: str | None = Field(None, description="Manufacturer")
+    builtin: bool | None = Field(None, description="Built-in modem")
+    mode: int | None = Field(None, description="Modem mode")
+    primary: bool | None = Field(None, description="Primary modem")
+    multi_apn: bool | None = Field(None, description="Multi APN support")
+    ipv6: bool | None = Field(None, description="IPv6 support")
+    volte_supported: bool | None = Field(None, description="VoLTE support")
+    auto_3g_bands: bool | None = Field(None, description="Auto 3G bands")
+    operators_scan: bool | None = Field(None, description="Operators scan support")
+    mobile_dfota: bool | None = Field(None, description="Mobile DFOTA support")
+    no_ussd: bool | None = Field(None, description="No USSD")
+    framed_routing: bool | None = Field(None, description="Framed routing")
+    low_signal_reconnect: bool | None = Field(None, description="Low signal reconnect")
+    active_sim: int | None = Field(None, description="Currently active SIM card")
+    conntype: str | None = Field(None, description="Connection type")
+    simstate: str | None = Field(None, description="SIM state")
+    simstate_id: int | None = Field(None, description="SIM state ID")
+    data_conn_state: str | None = Field(None, description="Data connection state")
+    data_conn_state_id: int | None = Field(None, description="Data connection state ID")
+    txbytes: int | None = Field(None, description="Transmitted bytes")
+    rxbytes: int | None = Field(None, description="Received bytes")
+    baudrate: int | None = Field(None, description="Baudrate")
+    is_busy: int | None = Field(None, description="Is busy")
+    data_off: bool | None = Field(None, description="Data turned off with mobileoff SMS")
+    busy_state: str | None = Field(None, description="Busy state")
+    busy_state_id: int | None = Field(None, description="Busy state ID")
+    pinstate: PinState | None = Field(None, description="PIN state")
+    pinstate_id: int | None = Field(None, description="PIN state ID (deprecated)", deprecated=True)
+    operator_state: OperatorState | None = Field(None, description="Operator state")
+    operator_state_id: int | None = Field(None, description="Operator state ID (deprecated)", deprecated=True)
+    rssi: int | None = Field(None, description="Received Signal Strength Indicator")
+    operator: str | None = Field(None, description="Operator name")
+    provider: str | None = Field(None, description="Provider")
+    ntype: str | None = Field(None, description="Network type")
+    imsi: str | None = Field(None, description="International Mobile Subscriber Identity")
+    iccid: str | None = Field(None, description="Integrated Circuit Card Identifier")
+    cellid: str | None = Field(None, description="Cell ID")
+    rscp: str | None = Field(None, description="Received Signal Code Power")
+    ecio: str | None = Field(None, description="Energy per chip to Interference power ratio")
+    rsrp: int | None = Field(None, description="Reference Signal Received Power")
+    rsrq: int | None = Field(None, description="Reference Signal Received Quality")
+    sinr: int | None = Field(None, description="Signal to Interference plus Noise Ratio")
+    pinleft: int | None = Field(None, description="PIN attempts left")
+    volte: bool | None = Field(None, description="VoLTE active")
+    sc_band_av: str | None = Field(None, description="Carrier aggregation status")
+    ca_signal: list[CarrierAggregationSignal] | None = Field(None, description="Carrier aggregation signal values")
+    temperature: int | None = Field(None, description="Modem temperature")
+    esim_profile: str | None = Field(None, description="Active eSIM profile")
+    mobile_stage: int | None = Field(None, description="Current mobile connection stage")
+    gnss_state: int | None = Field(None, description="GNSS state for devices that switch between mobile and GNSS")
+
+    # Additional fields found in API response (not documented)
+    nr5g_sa_disabled: bool | None = Field(None, description="5G SA disabled status")
+    wwan_gnss_conflict: bool | None = Field(None, description="WWAN GNSS conflict status")
+    modem_state_id: int | None = Field(None, description="Modem state ID")
+    sim_switch_enabled: bool | None = Field(None, description="SIM switch enabled")
+    serial: str | None = Field(None, description="Modem serial number")
+    auto_2g_bands: bool | None = Field(None, description="Auto 2G bands")
+    cfg_version: str | None = Field(None, description="Configuration version")
+    csd: bool | None = Field(None, description="CSD support")
+    pukleft: int | None = Field(None, description="PUK attempts left")
+    band: str | None = Field(None, description="Current band")
+    auto_5g_mode: bool | None = Field(None, description="Auto 5G mode")
+
+    # Deprecated fields (keeping for compatibility)
+    state: str | None = Field(None, description="Data connection state (deprecated)", deprecated=True)
+    state_id: int | None = Field(None, description="Data connection state ID (deprecated)", deprecated=True)
+    signal: int | None = Field(None, description="Signal strength (deprecated)", deprecated=True)
+    oper: str | None = Field(None, description="Operator (deprecated)", deprecated=True)
+    netstate: str | None = Field(None, description="Network state (deprecated)", deprecated=True)
+    netstate_id: int | None = Field(None, description="Network state ID (deprecated)", deprecated=True)
+
+    @computed_field
+    def mobile_stage_description(self) -> str | None:
+        """Get human-readable description of the mobile stage."""
+        return decode_mobile_stage(self.mobile_stage)
+
+
+class ModemStatusOffline(TeltasyncBaseModel):
+    """Limited modem status when offline."""
+    id: str = Field(description="Offline modem id")
+    name: str | None = Field(None, description="Offline modem name")
+    offline: str | None = Field(None, description="Modem state")
+    blocked: str | None = Field(None, description="Modem block state")
+    disabled: str | None = Field(None, description="Modem disable state")
+    builtin: bool | None = Field(None, description="Modem type")
+    primary: bool | None = Field(None, description="Primary modem")
+    sim_count: int | None = Field(None, description="Modem SIM count")
+    mode: int | None = Field(None, description="Modem mode")
+    multi_apn: bool | None = Field(None, description="Multi APN support")
+    operators_scan: bool | None = Field(None, description="Operators scan support")
+    dynamic_mtu: bool | None = Field(None, description="Dynamic MTU support")
+    ipv6: bool | None = Field(None, description="IPv6 support")
+    volte: bool | None = Field(None, description="VoLTE support")
+    esim_profile: str | None = Field(None, description="Active eSIM profile")
+
+
+# Union type for modem status, can be either full (=online) or offline
+ModemStatus = ModemStatusFull | ModemStatusOffline
+
+
+class Modems:
+    """Modem management client for Teltonika devices."""
+
+    def __init__(self, auth: Auth):
+        """Initialize modems client."""
+        self.auth = auth
+
+    async def get_status(self) -> ApiResponse[list[ModemStatus]]:
+        """Get status of all modems.
+
+        Returns:
+            List of modem statuses. Each modem can be either online (full status)
+            or offline (limited status) depending on its current state.
+        """
+        async with await self.auth.request("GET", "modems/status") as resp:
+            json_response = await resp.json()
+            return ApiResponse[list[ModemStatus]](**json_response)
+
+    @staticmethod
+    def is_online(modem: ModemStatus) -> bool:
+        """Check if a modem is online based on its status type.
+
+        Args:
+            modem: Modem status object
+
+        Returns:
+            True if modem is online (has full status), False if offline.
+        """
+        return isinstance(modem, ModemStatusFull)
+
+    @staticmethod
+    def get_online_modems(modems_response: ApiResponse[list[ModemStatus]]) -> list[ModemStatusFull]:
+        """Get only the online modems from a modems status response.
+
+        Args:
+            modems_response: Response from get_status()
+
+        Returns:
+            List of only the online modems with full status.
+        """
+        if not modems_response.success or not modems_response.data:
+            return []
+
+        return [modem for modem in modems_response.data if isinstance(modem, ModemStatusFull)]
+
+    @staticmethod
+    def get_offline_modems(modems_response: ApiResponse[list[ModemStatus]]) -> list[ModemStatusOffline]:
+        """Get only the offline modems from a modems status response.
+
+        Args:
+            modems_response: Response from get_status()
+
+        Returns:
+            List of only the offline modems with limited status.
+        """
+        if not modems_response.success or not modems_response.data:
+            return []
+
+        return [modem for modem in modems_response.data if isinstance(modem, ModemStatusOffline)]

teltasync-0.1.0/src/teltasync/system.py

@@ -0,0 +1,213 @@
+"""System endpoint bindings for the Teltonika API."""
+
+from pydantic import Field
+
+from teltasync.api_base import ApiResponse
+from teltasync.auth import Auth
+from teltasync.base_model import TeltasyncBaseModel
+
+
+class ManufacturingInfo(TeltasyncBaseModel):
+    """Manufacturing metadata returned by /system/device/status."""
+    mac_eth: str = Field(alias="macEth", description="Ethernet WAN MAC address")
+    name: str = Field(description="Product code")
+    hw_ver: str = Field(alias="hwver", description="Hardware revision")
+    batch: str = Field(description="Batch number")
+    serial: str = Field(description="Serial number")
+    mac: str = Field(description="Ethernet LAN MAC address")
+    bl_ver: str = Field(alias="blver", description="Bootloader version")
+
+
+class ReleaseInfo(TeltasyncBaseModel):
+    """Firmware release summary."""
+    distribution: str = Field(description="Distribution name")
+    revision: str = Field(description="Revision")
+    version: str = Field(description="Version of release")
+    target: str = Field(description="Target of device")
+    description: str = Field(description="Description of release")
+
+
+class StaticInfo(TeltasyncBaseModel):
+    """Firmware and hardware identifiers for the device."""
+    fw_version: str = Field(description="Firmware version")
+    kernel: str = Field(description="Kernel version")
+    system: str = Field(description="Processor name")
+    device_name: str = Field(description="Device name")
+    hostname: str = Field(description="Hostname of router")
+    cpu_count: int = Field(description="Number of CPU cores")
+    release: ReleaseInfo
+    fw_build_date: str = Field(description="Firmware build date")
+    model: str = Field(description="Model name")
+    board_name: str = Field(description="Board name")
+
+
+class Features(TeltasyncBaseModel):
+    """Feature flags advertised by the device."""
+    ipv6: bool = Field(description="IPv6 support")
+
+
+class Modem(TeltasyncBaseModel):
+    """Single modem entry in the system response."""
+    id: str = Field(description="Modem ID")
+    num: str = Field(description="Modem number")
+    builtin: bool = Field(description="Modem built-in")
+    sim_count: int = Field(alias="simcount", description="Modem SIM count")
+    gps_out: bool = Field(description="GPS support")
+    primary: bool = Field(description="Modem primary")
+    revision: str = Field(description="Modem revision")
+    modem_func_id: int = Field(description="Modem func id")
+    multi_apn: bool = Field(description="Modem multiple APN support")
+    operator_scan: bool = Field(description="Modem operator scan support")
+    dhcp_filter: bool = Field(description="Modem DHCP filter support")
+    dynamic_mtu: bool = Field(description="Modem dynamic MTU support")
+    ipv6: bool = Field(description="Modem IPv6 support")
+    volte: bool = Field(description="Modem VoLTE support")
+    csd: bool = Field(description="Modem CSD support")
+    band_list: list[str] = Field(description="Modem supported bands")
+    product: str = Field(description="Modem product code")
+    vendor: str = Field(description="Modem vendor")
+    gps: str = Field(description="GPS support")
+    stop_bits: str = Field(description="Modem stop bits")
+    baudrate: str = Field(alias="boudrate", description="Modem baudrate")
+    type: str = Field(description="Modem type")
+    desc: str = Field(description="Modem description")
+    control: str = Field(description="Modem control")
+
+
+class NetworkInterface(TeltasyncBaseModel):
+    """Configuration values for a network interface."""
+    proto: str = Field(description="Protocol")
+    device: str = Field(description="Device name")
+    default_ip: str | None = Field(None, description="Default IP address")
+
+
+class NetworkConfig(TeltasyncBaseModel):
+    """WAN and LAN interface configuration."""
+    wan: NetworkInterface
+    lan: NetworkInterface
+
+
+class ModelInfo(TeltasyncBaseModel):
+    """Identifier and marketing name for the device."""
+    id: str = Field(description="Model ID")
+    platform: str = Field(description="Model platform")
+    name: str = Field(description="Model name")
+
+
+class NetworkOptions(TeltasyncBaseModel):
+    """Limits and defaults used by the switch configuration."""
+    readonly_vlans: int
+    max_mtu: int
+    vlans: int
+
+
+class SwitchRole(TeltasyncBaseModel):
+    """Mapping of switch ports to their assigned role."""
+    ports: str = Field(description="Switch ports")
+    role: str = Field(description="Switch role")
+    device: str = Field(description="Switch device")
+
+
+class SwitchPort(TeltasyncBaseModel):
+    """Switch port definition with tagging hints."""
+    device: str | None = Field(None, description="Switch port device")
+    num: int = Field(description="Switch port number")
+    want_untag: bool | None = Field(None, description="Switch port want untag")
+    need_tag: bool | None = Field(None, description="Switch port need tag")
+    role: str | None = Field(None, description="Switch port role")
+    index: int | None = Field(None, description="Switch port index")
+
+
+class SwitchConfig(TeltasyncBaseModel):
+    """Complete switch profile for switch0."""
+    enable: bool
+    roles: list[SwitchRole]
+    ports: list[SwitchPort]
+    reset: bool = Field(description="Switch reset")
+
+
+class Switch(TeltasyncBaseModel):
+    """Wrapper for switch configuration blocks."""
+    switch0: SwitchConfig
+
+
+class HardwareInfo(TeltasyncBaseModel):
+    """Hardware capabilities advertised by the platform."""
+    wps: bool | None = Field(None, description="WPS support")
+    rs232: bool | None = Field(None, description="RS232 support")
+    nat_offloading: bool | None = Field(None, description="NAT Offloading support")
+    dual_sim: bool | None = Field(None, description="Dual SIM support")
+    bluetooth: bool | None = Field(None, description="Bluetooth support")
+    soft_port_mirror: bool | None = Field(None, description="Software Port Mirroring support")
+    vcert: bool | None = Field(None, description="VCert support")
+    micro_usb: bool | None = Field(None, description="Micro USB support")
+    wifi: bool | None = Field(None, description="WiFi support")
+    sd_card: bool | None = Field(None, description="SD Card support")
+    multi_tag: bool | None = Field(None, description="Multi Tag support")
+    dual_modem: bool | None = Field(None, description="Dual Modem support")
+    sfp_switch: bool | None = Field(None, description="SFP switch support")
+    dsa: bool | None = Field(None, description="DSA support")
+    hw_nat: bool | None = Field(None, description="HW NAT support")
+    sw_rst_on_init: bool | None = Field(None, description="SW RST on init support")
+    at_sim: bool | None = Field(None, description="AT SIM support")
+    port_link: bool | None = Field(None, description="Port link support")
+    ios: bool | None = Field(None, description="iOS support")
+    usb: bool | None = Field(None, description="USB support")
+    console: bool | None = Field(None, description="Console support")
+    dual_band_ssid: bool | None = Field(None, description="Dual band SSID support")
+    gps: bool | None = Field(None, description="GPS support")
+    ethernet: bool | None = Field(None, description="Ethernet support")
+    sfp_port: bool | None = Field(None, description="SFP port support")
+    rs485: bool | None = Field(None, description="RS485 support")
+    mobile: bool | None = Field(None, description="Mobile support")
+    poe: bool | None = Field(None, description="POE support")
+    gigabit_port: bool | None = Field(None, description="Gigabit port support")
+    field_2_5_gigabit_port: bool | None = Field(None, alias="2_5_gigabit_port",
+                                                description="2.5 Gigabit port support")
+
+    # Additional undocumented fields found in the response
+    esim: bool | None = Field(None, description="eSIM support")
+    modem_reset: bool | None = Field(None, description="Modem reset support")
+
+
+class BoardInfo(TeltasyncBaseModel):
+    """High-level board configuration including modems and switch."""
+    modems: list[Modem]
+    network: NetworkConfig
+    model: ModelInfo
+    usb_jack: str = Field(description="USB ports")
+    network_options: NetworkOptions
+    switch: Switch
+    hw_info: HardwareInfo = Field(alias="hwinfo")
+
+
+class DeviceStatusData(TeltasyncBaseModel):
+    """Aggregated payload returned by the status endpoint."""
+    mnf_info: ManufacturingInfo = Field(alias="mnfinfo")
+    static: StaticInfo
+    features: Features
+    board: BoardInfo
+
+
+class RebootResponse(TeltasyncBaseModel):
+    """Minimal response body for reboot requests."""
+    pass
+
+
+class System:
+    """API wrapper for /system endpoints."""
+
+    def __init__(self, auth: Auth):
+        self.auth = auth
+
+    async def get_device_status(self) -> ApiResponse[DeviceStatusData]:
+        """Return manufacturing, firmware and hardware details."""
+        async with await self.auth.request("GET", "system/device/status") as resp:
+            json_response = await resp.json()
+            return ApiResponse[DeviceStatusData](**json_response)
+
+    async def reboot(self) -> ApiResponse[RebootResponse]:
+        """Trigger a reboot and return the raw API response."""
+        async with await self.auth.request("POST", "system/actions/reboot") as resp:
+            json_response = await resp.json()
+            return ApiResponse[RebootResponse](**json_response)

teltasync-0.1.0/src/teltasync/teltasync.py

@@ -0,0 +1,143 @@
+from aiohttp import ClientSession
+
+from teltasync.auth import Auth
+from teltasync.exceptions import TeltonikaAuthenticationError, TeltonikaConnectionError
+from teltasync.modems import ModemStatusFull, ModemStatusOffline, Modems
+from teltasync.system import DeviceStatusData, System
+from teltasync.unauthorized import UnauthorizedClient, UnauthorizedStatusData
+
+
+class Teltasync:
+    def __init__(
+            self,
+            base_url: str,
+            username: str,
+            password: str,
+            *,
+            session: ClientSession | None = None,
+            verify_ssl: bool = True,
+    ):
+        self._session = session
+        self._own_session = session is None
+        self._base_url = base_url
+        self._username = username
+        self._password = password
+        self._verify_ssl = verify_ssl
+
+        self._auth: Auth | None = None
+        self._system: System | None = None
+        self._modems: Modems | None = None
+        self._unauthorized: UnauthorizedClient | None = None
+
+    @classmethod
+    async def create(
+            cls,
+            base_url: str,
+            username: str,
+            password: str,
+            *,
+            verify_ssl: bool = True,
+    ) -> "Teltasync":
+        session = ClientSession()
+        return cls(
+            base_url=base_url,
+            username=username,
+            password=password,
+            session=session,
+            verify_ssl=verify_ssl,
+        )
+
+    @property
+    def session(self) -> ClientSession:
+        if self._session is None:
+            self._session = ClientSession()
+        return self._session
+
+    async def close(self) -> None:
+        if self._own_session and self._session:
+            await self._session.close()
+            self._session = None
+
+    async def __aenter__(self) -> "Teltasync":
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.close()
+
+    async def get_device_info(self) -> UnauthorizedStatusData:
+        await self._ensure_session()
+        response = await self.unauthorized.get_status()
+        if response.success and response.data:
+            return response.data
+        raise TeltonikaConnectionError("Failed to get device info")
+
+    async def validate_credentials(self) -> bool:
+        try:
+            await self._ensure_session()
+            await self.auth.authenticate()
+        except TeltonikaAuthenticationError:
+            return False
+        finally:
+            await self.logout()
+        return True
+
+    async def get_system_info(self) -> DeviceStatusData:
+        await self._ensure_session()
+        response = await self.system.get_device_status()
+        if response.success and response.data:
+            return response.data
+        raise TeltonikaConnectionError("Failed to get system info")
+
+    async def get_modem_status(self) -> list[ModemStatusFull | ModemStatusOffline]:
+        await self._ensure_session()
+        response = await self.modems.get_status()
+        if response.success and response.data:
+            return response.data
+        raise TeltonikaConnectionError("Failed to get modem status")
+
+    async def reboot_device(self) -> bool:
+        await self._ensure_session()
+        response = await self.system.reboot()
+        return bool(response and response.success)
+
+    async def logout(self) -> bool:
+        await self._ensure_session()
+        response = await self.auth.logout()
+        return bool(response and response.success)
+
+    @property
+    def auth(self) -> Auth:
+        if self._auth is None:
+            self._auth = Auth(
+                self.session,
+                self._base_url,
+                self._username,
+                self._password,
+                check_certificate=self._verify_ssl,
+            )
+        return self._auth
+
+    @property
+    def system(self) -> System:
+        if self._system is None:
+            self._system = System(self.auth)
+        return self._system
+
+    @property
+    def modems(self) -> Modems:
+        if self._modems is None:
+            self._modems = Modems(self.auth)
+        return self._modems
+
+    @property
+    def unauthorized(self) -> UnauthorizedClient:
+        if self._unauthorized is None:
+            self._unauthorized = UnauthorizedClient(
+                self.session,
+                self._base_url,
+                check_certificate=self._verify_ssl,
+            )
+        return self._unauthorized
+
+    async def _ensure_session(self) -> ClientSession:
+        return self.session

teltasync-0.1.0/src/teltasync/unauthorized.py

@@ -0,0 +1,54 @@
+import asyncio
+from typing import Optional
+
+from aiohttp import ClientConnectorError, ClientSession, ClientTimeout
+from pydantic import ConfigDict
+
+from teltasync.api_base import ApiResponse
+from teltasync.base_model import TeltasyncBaseModel
+from teltasync.exceptions import TeltonikaConnectionError
+from teltasync.utils import camel_to_snake
+
+
+class SecurityBanner(TeltasyncBaseModel):
+    title: str
+    message: str
+
+
+class UnauthorizedStatusData(TeltasyncBaseModel):
+    lang: str
+    filename: Optional[str] = None
+    device_name: str
+    device_model: str
+    api_version: str
+    device_identifier: str
+    security_banner: Optional[SecurityBanner] = None
+
+    model_config = ConfigDict(alias_generator=camel_to_snake, populate_by_name=True)
+
+
+class UnauthorizedClient:
+    def __init__(self, session: ClientSession, base_url: str, check_certificate: bool = True):
+        self.session = session
+        self.base_url = base_url
+        self.check_certificate = check_certificate
+
+    async def get_status(self) -> ApiResponse[UnauthorizedStatusData]:
+        try:
+            async with self.session.get(
+                    f"{self.base_url}/unauthorized/status",
+                    ssl=self.check_certificate,
+                    timeout=ClientTimeout(total=10.0),
+            ) as resp:
+                payload = await resp.json()
+                return ApiResponse[UnauthorizedStatusData](**payload)
+        except ClientConnectorError as exc:
+            raise TeltonikaConnectionError(
+                f"Cannot connect to device at {self.base_url}: {exc}",
+                exc,
+            ) from exc
+        except asyncio.TimeoutError as exc:
+            raise TeltonikaConnectionError(
+                f"Connection timeout to {self.base_url}",
+                exc,
+            ) from exc

teltasync-0.1.0/src/teltasync/utils.py

@@ -0,0 +1,6 @@
+import re
+
+
+def camel_to_snake(name: str) -> str:
+    """Convert camelCase to snake_case."""
+    return re.sub(r'(?<!^)(?=[A-Z])', '_', name).lower()