rtls-sdk 0.3.0__tar.gz → 0.4.0__tar.gz

{rtls_sdk-0.3.0 → rtls_sdk-0.4.0}/CHANGELOG.md

@@ -7,6 +7,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-05-19
+
+### Added
+
+#### Schedules, LSB, Network resources (ported from desktop site-plan)
+
+- `client.schedules` — CRUD on `/api/v2/tdoa/schedules/`: `list`,
+  `get`, `create`, `update`, `delete`. The per-slot table is carried
+  as an opaque `content` blob so callers can round-trip both v1 and
+  v2 schedule wire formats without an SDK release. New
+  `rtls_sdk.Schedule` model.
+- `client.lsb` — read/write the Location Synchronization Bus
+  settings on `/api/v2/tdoa/settings/`: `get`, `update`. Settings
+  include the active-schedule pointer, autostart flag, and per-anchor
+  sync roles (master / distributor / client). The server upserts on
+  POST keyed by `project_uid` in the body. The `values` payload is
+  exposed as `dict[str, Any]` to support both `lsb_version=1` (`sfd`,
+  `autostart_devices`) and `lsb_version=2` (`masters`,
+  `distributors`) shapes side-by-side. The SDK also merges the
+  top-level `tdoa_version` / `lsb_version` fields from the response
+  into the model. New `rtls_sdk.LsbSettings` model.
+- `client.network` — `/api/v2/network_settings/` read/update for the
+  per-project service-mode toggle (`enabled`, `duration`,
+  `devices_in_service_mode`). New `rtls_sdk.NetworkSettings` and
+  `rtls_sdk.ServiceMode` models; null device lists coerce to `[]`.
+- Live tests under `tests/live/test_schedules.py`,
+  `tests/live/test_lsb.py`, `tests/live/test_network.py`. The
+  service-mode toggle test is guarded by
+  `RTLS_LIVE_ALLOW_SERVICE_MODE_TOGGLE=1` because it affects real
+  hardware.
+- Docs: `docs/entities/schedules.md`, `lsb.md`, `network.md`.
+
+#### LSB start/stop orchestration
+
+- `client.lsb.start(masters, *, bcs=1, tdoas=0, timeout=9.0,
+  resend_interval=3.0, check_interval=0.7)` — push `sync_slot` + `sf`
+  to each master and poll `hw_params` until every node echoes back
+  the configured values. Raises `LsbConvergenceError` (with the
+  unresolved MAC list) on timeout. Faithful port of the desktop
+  site-plan's start flow.
+- `client.lsb.stop(macs, *, timeout=15.0, …)` — send the all-zero
+  `sf` "stop trick" to each master and poll until every node reports
+  `sf.value.sfd == 0` (or `addr` empty / `"0000"`).
+- New `LsbMasterSpec` dataclass (`mac`, `addr`, `slot`, `sfd`) for
+  the `start()` argument.
+- New `LsbConvergenceError` exception carrying `unresolved: list[str]`.
+
+#### LSB settings accessors and configured-start convenience
+
+- `LsbSettings.masters()` and `LsbSettings.distributors()` — typed
+  views over the opaque `values` dict that smooth the v1/v2 fork.
+  Return frozen `LsbMasterEntry` / `LsbDistributorEntry` dataclasses
+  (also exported at the top level). The wire shape of `values` stays
+  an opaque dict for forward-compatibility.
+- `client.lsb.start_configured(*, tdoas, bcs=None, …)` — convenience
+  start: reads LSB settings, joins anchors + nodes, derives each
+  master's MAC and 4-char hex addr (from `node.node_id`), then
+  delegates to `client.lsb.start([...])`. Raises `RuntimeError` with
+  a clear message when resolution fails (no masters configured, no
+  registered node for an anchor's MAC, etc.). `bcs` defaults to
+  `max(slot) + 1` matching site-plan.
+
+#### Node parameter primitives
+
+- `client.nodes.send_param(mac, **plist)` — POSTs to
+  `/api/v2/win_message_que/create.json/`. Accepts any plist keys
+  (`sf`, `sync_slot`, `nwk_cfg`, `srv_mode`, `tdoa_schedule`,
+  `tdoa_schd`, `p`). Multiple keys per call supported. MAC is
+  normalised.
+- `client.nodes.read_params(macs, fields, *, force_update=False)` —
+  GETs `/api/v2/hw_params.json` with repeated `mac=` and `fields=`
+  query parameters (matching the desktop client's wire format).
+  Returns `list[NodeParams]`. Server-side `"pending"` strings on
+  each field coerce to `None` so callers always see `dict | None`.
+- New `rtls_sdk.NodeParams` model.
+
 ## [0.3.0] — 2026-05-13
 
 ### Documentation

{rtls_sdk-0.3.0 → rtls_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rtls-sdk
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python SDK for the RTLS REST API
 Project-URL: Homepage, https://github.com/rpplabs/rtls-sdk
 Project-URL: Documentation, https://github.com/rpplabs/rtls-sdk/tree/master/docs

{rtls_sdk-0.3.0 → rtls_sdk-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rtls-sdk"
-version = "0.3.0"
+version = "0.4.0"
 description = "Python SDK for the RTLS REST API"
 readme = "README.md"
 requires-python = ">=3.10"

{rtls_sdk-0.3.0 → rtls_sdk-0.4.0}/src/rtls_sdk/__init__.py

@@ -18,6 +18,7 @@ from .errors import (
     AuthenticationError,
     Conflict,
     ConnectionError,
+    LsbConvergenceError,
     NotFound,
     PartialFailureError,
     PermissionDenied,
@@ -46,7 +47,12 @@ from .models import (
     Group,
     Host,
     ImportResult,
+    LsbDistributorEntry,
+    LsbMasterEntry,
+    LsbSettings,
+    NetworkSettings,
     Node,
+    NodeParams,
     NotificationProfile,
     NotificationType,
     Position,
@@ -54,6 +60,8 @@ from .models import (
     Report,
     ReportType,
     Role,
+    Schedule,
+    ServiceMode,
     Site,
     Subscriber,
     SubscriberAddresses,
@@ -81,13 +89,18 @@ from .models.ws import (
     WsChannelMessage,
     ZoneEventMessage,
 )
-from .resources import UserMessagesAPI, WsAPI
+from .resources import LsbAPI, NetworkAPI, SchedulesAPI, UserMessagesAPI, WsAPI
+from .resources.lsb import LsbMasterSpec
 from .resources.ws import WsSession
 
 __all__ = [  # noqa: RUF022 — grouped logically, not alphabetically
     # Client
     "RtlsClient",
     # Resource sub-clients
+    "LsbAPI",
+    "LsbMasterSpec",
+    "NetworkAPI",
+    "SchedulesAPI",
     "UserMessagesAPI",
     "WsAPI",
     # WebSocket types
@@ -106,6 +119,7 @@ __all__ = [  # noqa: RUF022 — grouped logically, not alphabetically
     "AuthenticationError",
     "Conflict",
     "ConnectionError",
+    "LsbConvergenceError",
     "NotFound",
     "PartialFailureError",
     "PermissionDenied",
@@ -133,7 +147,12 @@ __all__ = [  # noqa: RUF022 — grouped logically, not alphabetically
     "Group",
     "Host",
     "ImportResult",
+    "LsbDistributorEntry",
+    "LsbMasterEntry",
+    "LsbSettings",
+    "NetworkSettings",
     "Node",
+    "NodeParams",
     "NotificationProfile",
     "NotificationType",
     "Position",
@@ -141,6 +160,8 @@ __all__ = [  # noqa: RUF022 — grouped logically, not alphabetically
     "Report",
     "ReportType",
     "Role",
+    "Schedule",
+    "ServiceMode",
     "Site",
     "Subscriber",
     "SubscriberAddresses",

{rtls_sdk-0.3.0 → rtls_sdk-0.4.0}/src/rtls_sdk/_client.py

@@ -30,11 +30,14 @@ from .resources import (
     FloorplansAPI,
     GroupsAPI,
     LoggerAPI,
+    LsbAPI,
     MessagingAPI,
+    NetworkAPI,
     NodesAPI,
     NotificationsAPI,
     ProjectsAPI,
     ReportsAPI,
+    SchedulesAPI,
     SitesAPI,
     SubscribersAPI,
     SystemAPI,
@@ -184,6 +187,9 @@ class RtlsClient:
         self.ws = WsAPI(self)
         self.logger = LoggerAPI(self)
         self.context = ContextAPI(self)
+        self.schedules = SchedulesAPI(self)
+        self.lsb = LsbAPI(self)
+        self.network = NetworkAPI(self)
 
     # -- public scope helpers --------------------------------------------
 

{rtls_sdk-0.3.0 → rtls_sdk-0.4.0}/src/rtls_sdk/errors.py

@@ -155,6 +155,25 @@ class PartialFailureError(RtlsError):
         self.partial_result: dict[str, Any] = partial_result or {}
 
 
+class LsbConvergenceError(RtlsError):
+    """``client.lsb.start()`` / ``stop()`` didn't converge within the timeout.
+
+    ``unresolved`` lists the MACs that did not reach the target state
+    before the timeout elapsed. Inspect to decide whether to retry,
+    take individual nodes offline, or accept the partial state.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        unresolved: list[str],
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.unresolved = unresolved
+
+
 class WsError(RtlsError):
     """Base class for WebSocket surface errors.
 
@@ -253,6 +272,7 @@ __all__ = [
     "AuthenticationError",
     "Conflict",
     "ConnectionError",
+    "LsbConvergenceError",
     "NotFound",
     "PartialFailureError",
     "PermissionDenied",

{rtls_sdk-0.3.0 → rtls_sdk-0.4.0}/src/rtls_sdk/models/__init__.py

@@ -11,12 +11,16 @@ from .floorplan import Floorplan
 from .group import Group
 from .heatmap import Heatmap, HeatmapInput
 from .import_result import ImportResult
+from .lsb import LsbDistributorEntry, LsbMasterEntry, LsbSettings
+from .network import NetworkSettings, ServiceMode
 from .node import Node
+from .node_params import NodeParams
 from .notification import NotificationProfile, NotificationType
 from .position import Position
 from .project import Project
 from .pws import PwsEvent, PwsReport
 from .report import Report, ReportType
+from .schedule import Schedule
 from .session_context import SessionContext
 from .site import Site
 from .subscriber import Subscriber, SubscriberAddresses, SystemSubscriber
@@ -45,7 +49,12 @@ __all__ = [
     "HeatmapInput",
     "Host",
     "ImportResult",
+    "LsbDistributorEntry",
+    "LsbMasterEntry",
+    "LsbSettings",
+    "NetworkSettings",
     "Node",
+    "NodeParams",
     "NotificationProfile",
     "NotificationType",
     "Position",
@@ -55,6 +64,8 @@ __all__ = [
     "Report",
     "ReportType",
     "Role",
+    "Schedule",
+    "ServiceMode",
     "SessionContext",
     "Site",
     "Subscriber",

rtls_sdk-0.4.0/src/rtls_sdk/models/lsb.py

@@ -0,0 +1,129 @@
+"""LSB (Location Synchronization Bus) settings model.
+
+LSB settings hold the TDOA sync configuration for a project: which
+anchor is the master, which are distributors, slot assignments,
+superframe frequency, and the uid of the currently active schedule.
+
+The shape of ``values`` differs between LSB v1 (``sfd`` /
+``autostart_devices``) and v2 (``masters`` / ``distributors``). The SDK
+keeps the wire payload as an opaque dict so both versions round-trip
+without forcing typed sub-models on callers, and provides typed
+read-side accessors (:meth:`LsbSettings.masters`,
+:meth:`LsbSettings.distributors`) that smooth the v1/v2 fork.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import Field
+
+from ._base import _BaseModel
+
+
+@dataclass(frozen=True)
+class LsbMasterEntry:
+    """A typed view over one master row in LSB settings.
+
+    Cross-version: on v1, masters come from ``values.autostart_devices``
+    (carrying only a MAC and inheriting the global ``values.sfd``); on
+    v2, from ``values.masters[]`` (per-master ``sfd`` and ``slot``). The
+    fields that don't apply to a given version are ``None``.
+    """
+
+    sfd: int
+    slot: int
+    anchor_uid: str | None = None
+    mac: str | None = None
+
+
+@dataclass(frozen=True)
+class LsbDistributorEntry:
+    """A typed view over one distributor row (v2 only).
+
+    On v1 there is no distributor concept and
+    :meth:`LsbSettings.distributors` returns an empty list.
+    """
+
+    anchor_uid: str
+    slot: int
+    master_uid: str | None = None
+
+
+class LsbSettings(_BaseModel):
+    """LSB sync configuration for a project.
+
+    ``values`` is intentionally untyped — see module docstring. Use
+    :meth:`masters` / :meth:`distributors` for typed read access.
+    """
+
+    project_uid: str | None = None
+    tdoa_version: int | None = None
+    lsb_version: int | None = None
+    values: dict[str, Any] = Field(default_factory=dict)
+
+    def masters(self) -> list[LsbMasterEntry]:
+        """Typed view of the configured masters, cross-version.
+
+        v2 reads ``values.masters[]`` directly. v1 reads
+        ``values.autostart_devices[].mac`` and pairs each MAC with the
+        global ``values.sfd`` (default 1000 if missing) and a
+        positional ``slot``.
+        """
+        if self.lsb_version == 2:
+            raw = self.values.get("masters")
+            if not isinstance(raw, list):
+                return []
+            out: list[LsbMasterEntry] = []
+            for row in raw:
+                if not isinstance(row, dict):
+                    continue
+                out.append(
+                    LsbMasterEntry(
+                        sfd=int(row.get("sfd", 0)),
+                        slot=int(row.get("slot", 0)),
+                        anchor_uid=row.get("anchor_uid"),
+                    )
+                )
+            return out
+        # v1 (or unknown): treat autostart_devices as the master list
+        raw_v1 = self.values.get("autostart_devices")
+        if not isinstance(raw_v1, list):
+            return []
+        global_sfd = int(self.values.get("sfd") or 1000)
+        out_v1: list[LsbMasterEntry] = []
+        for idx, row in enumerate(raw_v1):
+            if not isinstance(row, dict):
+                continue
+            mac = row.get("mac")
+            if not isinstance(mac, str):
+                continue
+            out_v1.append(LsbMasterEntry(sfd=global_sfd, slot=idx, mac=mac))
+        return out_v1
+
+    def distributors(self) -> list[LsbDistributorEntry]:
+        """Typed view of the configured distributors. Empty on v1."""
+        if self.lsb_version != 2:
+            return []
+        raw = self.values.get("distributors")
+        if not isinstance(raw, list):
+            return []
+        out: list[LsbDistributorEntry] = []
+        for row in raw:
+            if not isinstance(row, dict):
+                continue
+            anchor_uid = row.get("anchor_uid")
+            if not isinstance(anchor_uid, str):
+                continue
+            out.append(
+                LsbDistributorEntry(
+                    anchor_uid=anchor_uid,
+                    slot=int(row.get("slot", 0)),
+                    master_uid=row.get("master_uid"),
+                )
+            )
+        return out
+
+
+__all__ = ["LsbDistributorEntry", "LsbMasterEntry", "LsbSettings"]

rtls_sdk-0.4.0/src/rtls_sdk/models/network.py

@@ -0,0 +1,43 @@
+"""Network settings model (project-scoped service-mode config)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field, model_validator
+
+from ._base import _BaseModel
+
+
+class ServiceMode(_BaseModel):
+    """Service-mode toggle for a project's devices.
+
+    ``devices_in_service_mode`` is sometimes returned as ``null`` on
+    deployments that haven't activated service mode yet; coerce to an
+    empty list so the typed surface stays clean.
+    """
+
+    enabled: bool = False
+    enabled_at: str | None = None
+    duration: int | None = None
+    expired: bool = False
+    devices_in_service_mode: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_null_devices(cls, data: Any) -> Any:
+        if isinstance(data, dict) and data.get("devices_in_service_mode") is None:
+            data = {**data, "devices_in_service_mode": []}
+        return data
+
+
+class NetworkSettings(_BaseModel):
+    """Per-project network configuration."""
+
+    project_uid: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+    service_mode: ServiceMode | None = None
+
+
+__all__ = ["NetworkSettings", "ServiceMode"]

rtls_sdk-0.4.0/src/rtls_sdk/models/node_params.py

@@ -0,0 +1,51 @@
+"""Node parameter snapshot model (server-side parameter cache).
+
+Returned by ``client.nodes.read_params(...)``. Each parameter field
+holds either ``None`` (server-side "pending" — node hasn't reported
+the value back yet) or a dict ``{"value": {...}, "elapsed": int}`` with
+the last known value and a timestamp.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import model_validator
+
+from ._base import _BaseModel
+
+
+class NodeParams(_BaseModel):
+    """One row of a ``hw_params.json`` response.
+
+    Field shapes per parameter type (when not ``None``):
+
+    - ``sf``: ``{"value": {"addr", "sfd", "bcs", "tdoas", "bsd", "tsd"}, "elapsed": int}``
+    - ``sync_slot``: ``{"value": {"addr": str, "slot": int}, "elapsed": int}``
+    - ``nwk_cfg``: ``{"value": {"router": bool}, "elapsed": int}``
+
+    Other parameter types (``tdoa_schedule``, ``tdoa_schd``,
+    ``srv_mode``, ``p``, …) ride on ``extra="allow"`` and are
+    accessible via :attr:`raw`.
+    """
+
+    mac_address: str
+    sf: dict[str, Any] | None = None
+    sync_slot: dict[str, Any] | None = None
+    nwk_cfg: dict[str, Any] | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_pending(cls, data: Any) -> Any:
+        """Convert ``"pending"`` strings (server-side cache miss) to ``None``.
+
+        The server returns ``"sf": "pending"`` for a node it has queued
+        but not yet heard back from. Coerce so callers always see
+        ``dict | None`` and can branch on truthiness.
+        """
+        if isinstance(data, dict):
+            return {k: (None if v == "pending" else v) for k, v in data.items()}
+        return data
+
+
+__all__ = ["NodeParams"]

rtls_sdk-0.4.0/src/rtls_sdk/models/schedule.py

@@ -0,0 +1,30 @@
+"""TDOA schedule model.
+
+A ``Schedule`` is a named TDOA timing plan stored on the server. The
+desktop site-plan tool serializes the per-slot schedule items (source /
+destination anchor, slot number, dimension, margin, …) into the
+``content`` blob; the SDK keeps it opaque so callers can read or replace
+it without the SDK taking a position on the v1 vs v2 wire format.
+"""
+
+from __future__ import annotations
+
+from ._base import _BaseModel
+
+
+class Schedule(_BaseModel):
+    """A TDOA schedule definition.
+
+    ``content`` is the serialized per-slot table (format depends on
+    ``tdoa_version``). Use :attr:`raw` for any fields the SDK doesn't
+    surface yet.
+    """
+
+    uid: str
+    name: str | None = None
+    content: str | None = None
+    default: bool = False
+    tdoa_version: int | None = None
+
+
+__all__ = ["Schedule"]

{rtls_sdk-0.3.0 → rtls_sdk-0.4.0}/src/rtls_sdk/resources/__init__.py

@@ -11,11 +11,14 @@ from .events import EventsAPI
 from .floorplans import FloorplansAPI
 from .groups import GroupsAPI
 from .logger import LoggerAPI
+from .lsb import LsbAPI
 from .messaging import MessagingAPI
+from .network import NetworkAPI
 from .nodes import NodesAPI
 from .notifications import NotificationsAPI
 from .projects import ProjectsAPI
 from .reports import ReportsAPI
+from .schedules import SchedulesAPI
 from .sites import SitesAPI
 from .subscribers import SubscribersAPI
 from .system import SystemAPI
@@ -37,11 +40,14 @@ __all__ = [
     "FloorplansAPI",
     "GroupsAPI",
     "LoggerAPI",
+    "LsbAPI",
     "MessagingAPI",
+    "NetworkAPI",
     "NodesAPI",
     "NotificationsAPI",
     "ProjectsAPI",
     "ReportsAPI",
+    "SchedulesAPI",
     "SitesAPI",
     "SubscribersAPI",
     "SystemAPI",