abb-rws-client 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to `abb-rws-client` are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.2] — 2026-05-08
+
+### Documentation
+
+- **Fixed the embarrassing compatibility table** that incorrectly claimed
+  RobotWare 7.x / OmniCore was "Not compatible". The package has supported
+  both protocols since v0.7.0 — the table was a stale leftover from when
+  only RWS 1.0 shipped. Now correctly shows both ✅, with live-tested
+  versions called out (RW7.21 + RW6.16).
+- **Documented `RobotManager` higher-level surface** — the README's
+  API-reference tables only covered the protocol-level `RwsClient`, so
+  callers couldn't see what `RobotManager` adds on top: RMMP, mastership
+  status, opmode auto-routing, backup, FK, service-routine call,
+  tool/wobj activation, CFG write surface, DIPC messaging, file volumes,
+  module source, compress, value validation. New section lists all of
+  these with descriptions.
+- **Clarified RWS 2.0 subscription quirks** — the polling-fallback
+  paragraph now names the specific RWS 2.0 VC `robapi2_subscription`
+  rejection that triggers the fallback, rather than implying it's
+  always 5s polling.
+- **Session-pool clarifications** — IRC5's 70-session number was being
+  presented as universal; called out OmniCore's also-finite-but-different
+  pool with the empirical 503-once-full behaviour we observed during
+  protocol probes.
+- **`RobotManager` polling cadence** correctly described as hybrid:
+  5 s when WS subscriptions handle state changes, 1 s when polling
+  covers everything.
+
+No code changes — pure README updates. `RwsClient`, `RwsClient2`,
+`RobotManager`, `MultiRobotManager`, `createClient`, all examples and
+unit tests are bit-for-bit identical to v0.7.1.
+
 ## [0.7.1] — 2026-05-07
 
 ### Added

package/README.md

@@ -25,7 +25,7 @@ Prefer a GUI? The companion VS Code extension gives you live status, motion data
 - **Connection lifecycle** — `RobotManager` handles port discovery, polling, WebSocket subscriptions with polling fallback, reconnect-on-failure
 - **Typed adapter pattern** — `IRWSAdapter` lets you write code that works across both protocols
 - **WebSocket subscriptions** for real-time events (panel state, RAPID exec, signals, persvar, elog, jointtarget, …)
-- Session cookie management (avoids the controller's 70-session pool fill)
+- Session cookie management (IRC5: avoids the controller's 70-session pool fill; OmniCore: avoids 503 lockout from session-pool exhaustion)
 - Automatic `/logout` on disconnect to release server-side mastership and free the session slot
 - Request rate limiting (< 20 req/sec)
 - Fully typed public API — every method throws `RwsError` with a typed `code`
@@ -214,17 +214,40 @@ multi.setActive('cell-B');
 ```
 
 `MultiRobotManager` wraps individual `RobotManager` instances. Each `RobotManager` handles its own:
-- Auto port discovery (probes 5466/9403/443/80/11811, plus a wide-scan fallback)
-- Protocol auto-detection (Digest vs Basic challenge)
-- 5-second polling for non-subscription state
-- WebSocket subscriptions with automatic polling fallback
-- Reconnect-on-failure (3-strike)
-- Clean `/logout` on disconnect (avoids orphan mastership locks)
+- Auto port discovery (probes 5466 / 9403 / 443 / 80 / 11811 in that order, plus a wide-scan fallback when none of those answer — RobotStudio assigns random VC ports above 30000)
+- Protocol auto-detection (`WWW-Authenticate: Digest` → RWS 1.0; `Basic` → RWS 2.0)
+- Hybrid polling cadence: **5 s when WebSocket subscriptions are active** (positions only — state-change resources stream over WS); **1 s when subscriptions failed** (full state coverage via polling)
+- WebSocket subscriptions with automatic polling fallback (RWS 2.0 VC notably rejects the `robapi2_subscription` subprotocol — fallback kicks in)
+- Reconnect-on-failure (3-strike, surfaces via `onError` listener)
+- Clean `GET /logout` on disconnect — releases server-side mastership and frees the session slot
 
 You can also create a `RobotManager` directly if you only have one robot.
 
 ---
 
+## `RobotManager` — higher-level surface
+
+`RobotManager` wraps either client with operational helpers that handle mastership, polling, and protocol differences for you. In addition to delegating every protocol method to the underlying client, it exposes:
+
+- **`getRmmpPrivilege()`**, **`requestRmmp(level)`** — Remote Mastership Privilege management. Required on OmniCore in AUTO mode for any modify op.
+- **`getMastershipStatus(domain?)`** — read who currently holds rapid/cfg/motion mastership (uid + application name).
+- **`setOperationMode('AUTO' | 'MANR' | 'MANF')`** — VC-only switch with auto-routing through MANR for AUTO ↔ MANF (the controller rejects direct transitions). Acquires `edit` mastership for the higher-privilege direction.
+- **`setSpeedRatio(0..100)`** — wraps `edit` mastership; uses the live-verified `?action=setspeedratio&speed-ratio=N` form on RWS 2.0 (the bare endpoint returns 400).
+- **`createBackup(name)`**, **`restoreBackup(name)`**, **`getBackupStatus()`**, **`listBackups()`** — `/ctrl/backup/...`
+- **`callServiceRoutine(task, name, args?)`** — invoke a service routine remotely (calibration, brake check, etc.).
+- **`calcJointsFromCartesian(...)`** — inverse kinematics. **`calcCartesianFromJoints(...)`** — forward kinematics.
+- **`setActiveTool(mechunit, name)`**, **`setActiveWobj(mechunit, name)`** — switch active persistent tooldata / wobjdata.
+- **CFG write** — `setCfgInstance` / `createCfgInstance` / `removeCfgInstance` / `loadCfgFile` / `saveCfgFile`. Each acquires `edit` mastership for the duration.
+- **DIPC** — `listDipcQueues` / `createDipcQueue` / `sendDipcMessage` / `readDipcMessage` / `removeDipcQueue`. Bidirectional messaging between RAPID and external clients.
+- **`listFileVolumes()`** — every controller volume (HOME, BACKUP, DATA, ADDINDATA, PRODUCTS, RAMDISK, TEMP).
+- **`getModuleSource(task, name)`** — pull a module's RAPID text in one call.
+- **`compressPath(source, dest)`** — controller-side compression.
+- **`validateRapidValue(task, value, datatype)`** — pre-flight a literal before writing.
+
+Every method returns `Promise<...>` and throws `RwsError` on failure.
+
+---
+
 ## Logging
 
 The lib ships a no-op logger by default. Hosts (CLIs, services, the VS Code extension) install their own:
@@ -460,7 +483,7 @@ try {
 
 ## Session Persistence
 
-The IRC5 controller allows a maximum of **70 concurrent RWS sessions**. Persist the session cookie across restarts to always reuse the same slot:
+IRC5 controllers allow a maximum of **70 concurrent RWS sessions**; OmniCore controllers also have a finite session pool (the exact number isn't published, but heavy probing without `/logout` returns HTTP 503 once it fills). Persist the session cookie across restarts to always reuse the same slot — the lib calls `/logout` on `disconnect()` to free the slot cleanly, but a saved cookie is the most robust path:
 
 ```ts
 import fs from 'fs';
@@ -481,14 +504,16 @@ await client.connect(); // reuses the existing session slot
 
 ## Rate Limits
 
-| Constraint | Value |
-|------------|-------|
-| Max request rate | 20 req/sec |
-| Client enforced interval | 55 ms between requests |
-| Max concurrent sessions | 70 |
-| Session inactivity timeout | 5 minutes |
-| Max session lifetime | 25 minutes |
-| Max file upload | 800 MB |
+| Constraint | Value | Source |
+|------------|-------|--------|
+| Max request rate | 20 req/sec | Both protocols (controller-enforced) |
+| Client-enforced interval | 55 ms between requests | This package, default |
+| Max concurrent sessions | 70 (IRC5) / finite (OmniCore) | Controller-enforced |
+| Session inactivity timeout | 5 minutes (IRC5) | Controller-enforced |
+| Max session lifetime | 25 minutes (IRC5) | Controller-enforced |
+| Max file upload | 800 MB (IRC5) | Controller-enforced; OmniCore is similar |
+
+OmniCore-specific limits aren't fully documented by ABB; what the lib observes empirically matches the IRC5 numbers within an order of magnitude.
 
 ---
 
@@ -496,10 +521,13 @@ await client.connect(); // reuses the existing session slot
 
 | | RobotWare 6.x (RWS 1.0) | RobotWare 7.x (RWS 2.0) |
 |--|--|--|
-| This package | ✅ Supported | ❌ Not compatible |
-| IRC5 controller | ✅ | n/a |
-| OmniCore controller | n/a | ❌ |
-| RobotStudio virtual | ✅ (127.0.0.1) | ❌ |
+| This package | ✅ `RwsClient` | ✅ `RwsClient2` |
+| IRC5 controller (real) | ✅ | n/a |
+| OmniCore controller (real) | n/a | ✅ |
+| RobotStudio virtual controller | ✅ (RW6.x VC) | ✅ (RW7.x VC) |
+| Auto-detect from one entry point | ✅ via `createClient()` | ✅ via `createClient()` |
+
+**Live-tested matrix** as of v0.7.1: RobotWare 7.21 (OmniCore VC, RWS 2.0), RobotWare 6.16 (IRC5 VC, RWS 1.0). 116 unit tests + 339 live protocol-coverage tests pass against both.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abb-rws-client",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Typed TypeScript/Node.js client for ABB Robot Web Services — supports both RWS 1.0 (IRC5/RobotWare 6) and RWS 2.0 (OmniCore/RobotWare 7).",
   "keywords": [
     "abb",