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

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

@@ -7,7 +7,161 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
-## [0.2.0] — 2026-05-12
+## [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
+
+- New `entities/streaming.md` documenting `client.ws`, the eight
+  typed channel models, reconnects, heartbeats, backpressure, and a
+  REST → WS round-trip recipe. Reference pages (`resources.md`,
+  `models.md`, `errors.md`) now list the WS surface. Catalog and
+  quickstart link to the new page.
+
+### Added
+
+#### Typed WS channel models (M18)
+
+- `rtls_sdk.models.ws` — new sub-package with one pydantic model per
+  decoded channel: `PositionMessage` (pos), `NotifyMessage` (notify),
+  `AlarmMessage` (alarm), `ZoneEventMessage` (zone_event),
+  `SensorMessage` (sensor), `OtaMessage` (ota), `ParamPMessage`
+  (param_p), `UserMsgMessage` (user_msg). All eight inherit from
+  `WsChannelEnvelope` and carry the full wire dict on `.raw` for
+  forward-compat field access.
+- `client.ws.subscribe(...)` now yields typed messages instead of the
+  M17 untyped envelope; iteration patterns like
+  `match msg: case PositionMessage(x=x, y=y): ...` work directly. The
+  yield type narrowed from `WsChannelMessage` to `WsChannelEnvelope`.
+- Unknown channels and decode failures fall back to
+  `WsChannelMessage` (now a pydantic model, was a frozen dataclass) so
+  the iterator never dies on a single bad frame. Validation errors
+  log at WARNING with the channel name.
+- New `include_heartbeats: bool = False` kwarg on
+  `client.ws.subscribe(...)`. By default, `notify` frames with
+  `action == "HB"` are dropped at the reader; opt-in callers receive
+  them as `NotifyMessage(action="HB")`. Heartbeat drops do not count
+  toward `session.messages_dropped` — that counter remains
+  backpressure-only.
+
+### Changed
+
+- `WsChannelMessage` moved from `rtls_sdk._ws` to
+  `rtls_sdk.models.ws`; the import path under the top-level package
+  (`from rtls_sdk import WsChannelMessage`) is unchanged.
+
+#### WebSocket subscription scaffold (M17)
+
+- `client.ws` — new `WsAPI` sub-client wrapping the JSON-RPC 2.0
+  subscriptions-manager. `ws.list_channels()` returns the server's
+  advertised channel inventory in a one-shot dial (no auth required).
+  `ws.subscribe(channels, *, project_uid=None, reconnect=True,
+  queue_max=1024)` opens a long-lived session that is both a context
+  manager and a blocking iterator of `WsChannelMessage` envelopes.
+  Naming is transport-specific on purpose — future streaming
+  protocols (MQTT, Kafka) would land as siblings (`client.mqtt`,
+  `client.kafka`) rather than crowd a generic `client.stream`
+  namespace.
+- `WsChannelMessage(channel, raw)` — untyped pass-through for any
+  channel; typed channel models land in M18.
+- Reader runs on a daemon thread behind a bounded queue. Backpressure
+  drops the oldest message and bumps `session.messages_dropped`.
+  Auto-reconnect with capped exponential backoff
+  `(1, 2, 4, 8, 15, 30, 30, 30)` seconds on unclean disconnects;
+  re-subscribes the current channel set. Auth failure during reconnect
+  surfaces as `WsAuthError` from the iterator and stops further
+  attempts.
+- New error classes `WsError`, `WsAuthError`, and `WsProtocolError`
+  (all subclasses of `RtlsError`).
+- New dependency: `websockets >= 12.0`.
+
+#### User messages REST (M16)
+
+- `client.user_messages.send(tag_uid, hex)` — new `UserMessagesAPI`
+  sub-client; sends a hex payload to a tag's badge over the WIN
+  gateway. Wire endpoint: `POST /api/v2/user_msg/`. Independent of
+  `client.messaging` (which targets the inbox endpoint at
+  `/api/v2/messaging`); the two surfaces stay separate because the
+  endpoints serve different features on the wire (UDP frame vs. inbox
+  row) and share no storage. Client-side validation rejects malformed
+  hex before any network I/O.
+
+## [0.2.0] — 2026-05-13
 
 ### Added
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rtls-sdk
-Version: 0.2.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
@@ -21,6 +21,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.5
+Requires-Dist: websockets>=12.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.8; extra == 'dev'
 Requires-Dist: pytest-cov>=4.1; extra == 'dev'

{rtls_sdk-0.2.0 → rtls_sdk-0.4.0}/prompts/README.md

@@ -17,6 +17,12 @@ These prompts implement the design in `/Users/yzhbankov/rtls/rtls-sdk/DESIGN.md`
 | 13 | `13-m11-entity-docs.md` | M11 | Docs-only: reorganize user documentation around **entities**. New `docs/entities/` tree (one page per entity + catalog index) replaces the workflow-oriented guides. Answers "what can I do with X?" on one page. |
 | 14 | `14-m12-schema-audit-mac-fix.md` | M12 | Schema-correctness audit. Fix three real bugs caught by reading the server's Joi schemas directly: MAC format is bare 12-hex (not colon-separated); `tags.create` does not accept `mac_address` (server silently strips); add live MAC round-trip test as a regression gate. |
 | 15 | `15-m13-final-audit.md` | M13 | **Check-only.** Full ship-readiness audit across code quality, documentation site, internal consistency, wire-shape correctness, deep doc-quality analysis (with persona-driven proposals), and release artifacts. Produces `AUDIT.md` at the repo root with a verdict (ready / not ready), itemised blockers, repo-wide markdown link validation, and a prioritised list of documentation improvement proposals. Does not modify code or docs — a separate milestone applies any accepted fixes. |
+| 16 | `16-m14-e2e-live-test.md` | M14 | Full-stack live E2E test (`tests/live/test_m14_full_stack.py`). Builds the entity tree top-down, lists, updates each kind, deletes bottom-up. Fix-test-retry discipline — surfaces SDK bugs and fixes them in-flight. |
+| 17 | `17-m15-user-msg-websocket-research.md` | M15 | **Research-only.** Investigates the server-side `user_msg` REST endpoint and the JSON-RPC WebSocket protocol (subscriptions-manager). Produces `prompts/17-m15-research.md` with wire shapes, channel inventory, discrepancies, and concrete SDK extension signatures. |
+| 18 | `18-m16-user-msg-rest.md` | M16 | `messaging.send_to_tag(tag_uid, hex)` — POST `/api/v2/user_msg/` sends a hex payload to a tag's badge over the WIN gateway. Unit + integration + live test. |
+| 19 | `19-m17-ws-scaffold.md` | M17 | WebSocket sub-client `client.stream`: connect, list channels, subscribe / unsubscribe, blocking-iterator over `RawChannelMessage`, heartbeat passthrough, reconnect with backoff. Dependency: `websockets`. |
+| 20 | `20-m18-ws-typed-models.md` | M18 | Typed channel models (`PositionMessage`, `AlarmMessage`, `NotifyMessage`, `ZoneEventMessage`, `SensorMessage`, `OtaMessage`, `ParamPMessage`, `UserMsgMessage`) + discriminated-union decode dispatch + `include_heartbeats` flag (default off). |
+| 21 | `21-m19-ws-live-gate.md` | M19 | End-to-end live gate: REST `send_to_tag` → WS `user_msg` notify round-trip. Five-consecutive-pass stability requirement. |
 
 ## Inputs each prompt reads
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rtls-sdk"
-version = "0.2.0"
+version = "0.4.0"
 description = "Python SDK for the RTLS REST API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,6 +24,7 @@ classifiers = [
 dependencies = [
     "httpx>=0.27",
     "pydantic>=2.5",
+    "websockets>=12.0",
 ]
 
 [project.optional-dependencies]

{rtls_sdk-0.2.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,
@@ -28,6 +29,9 @@ from .errors import (
     RtlsError,
     ServerError,
     ValidationError,
+    WsAuthError,
+    WsError,
+    WsProtocolError,
 )
 from .models import (
     Alarm,
@@ -43,7 +47,12 @@ from .models import (
     Group,
     Host,
     ImportResult,
+    LsbDistributorEntry,
+    LsbMasterEntry,
+    LsbSettings,
+    NetworkSettings,
     Node,
+    NodeParams,
     NotificationProfile,
     NotificationType,
     Position,
@@ -51,6 +60,8 @@ from .models import (
     Report,
     ReportType,
     Role,
+    Schedule,
+    ServiceMode,
     Site,
     Subscriber,
     SubscriberAddresses,
@@ -66,14 +77,49 @@ from .models import (
     Zone,
     ZoneEvent,
 )
+from .models.ws import (
+    AlarmMessage,
+    NotifyMessage,
+    OtaMessage,
+    ParamPMessage,
+    PositionMessage,
+    SensorMessage,
+    UserMsgMessage,
+    WsChannelEnvelope,
+    WsChannelMessage,
+    ZoneEventMessage,
+)
+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
+    "AlarmMessage",
+    "NotifyMessage",
+    "OtaMessage",
+    "ParamPMessage",
+    "PositionMessage",
+    "SensorMessage",
+    "UserMsgMessage",
+    "WsChannelEnvelope",
+    "WsChannelMessage",
+    "WsSession",
+    "ZoneEventMessage",
     # Errors
     "AuthenticationError",
     "Conflict",
     "ConnectionError",
+    "LsbConvergenceError",
     "NotFound",
     "PartialFailureError",
     "PermissionDenied",
@@ -84,6 +130,9 @@ __all__ = [  # noqa: RUF022 — grouped logically, not alphabetically
     "RtlsError",
     "ServerError",
     "ValidationError",
+    "WsAuthError",
+    "WsError",
+    "WsProtocolError",
     # Models
     "Alarm",
     "Anchor",
@@ -98,7 +147,12 @@ __all__ = [  # noqa: RUF022 — grouped logically, not alphabetically
     "Group",
     "Host",
     "ImportResult",
+    "LsbDistributorEntry",
+    "LsbMasterEntry",
+    "LsbSettings",
+    "NetworkSettings",
     "Node",
+    "NodeParams",
     "NotificationProfile",
     "NotificationType",
     "Position",
@@ -106,6 +160,8 @@ __all__ = [  # noqa: RUF022 — grouped logically, not alphabetically
     "Report",
     "ReportType",
     "Role",
+    "Schedule",
+    "ServiceMode",
     "Site",
     "Subscriber",
     "SubscriberAddresses",

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

@@ -30,16 +30,21 @@ from .resources import (
     FloorplansAPI,
     GroupsAPI,
     LoggerAPI,
+    LsbAPI,
     MessagingAPI,
+    NetworkAPI,
     NodesAPI,
     NotificationsAPI,
     ProjectsAPI,
     ReportsAPI,
+    SchedulesAPI,
     SitesAPI,
     SubscribersAPI,
     SystemAPI,
     TagsAPI,
+    UserMessagesAPI,
     UsersAPI,
+    WsAPI,
     ZonesAPI,
 )
 
@@ -178,8 +183,13 @@ class RtlsClient:
         self.system = SystemAPI(self)
         self.auth = AuthAPI(self)
         self.messaging = MessagingAPI(self)
+        self.user_messages = UserMessagesAPI(self)
+        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 --------------------------------------------