abb-rws-client 0.2.0 → 0.7.1

package/README.md

@@ -1,30 +1,35 @@
 # abb-rws-client
 
-A typed TypeScript/Node.js HTTP and WebSocket client for **ABB IRC5 robot controllers** using [Robot Web Services (RWS) 1.0](https://developercenter.robotstudio.com/api/rwsApi/).
+A typed TypeScript/Node.js client for **ABB Robot Web Services** — both protocols ABB ships:
 
-> **Compatibility:** RWS 1.0 / RobotWare 6.x only.  
-> **Not compatible** with OmniCore controllers, RobotWare 7.x, or RWS 2.0.
+- **RWS 1.0** — IRC5 / RobotWare 6.x → `RwsClient`
+- **RWS 2.0** — OmniCore / RobotWare 7.x → `RwsClient2`
+
+> **Compatibility:** dual-protocol since v0.7.0. Single-line auto-detection via `createClient()` if you don't know which one your controller speaks.
 
 ---
 
 ## VS Code Extension
 
-Prefer a GUI? The companion VS Code extension gives you live status, joint positions, RAPID control, and module management directly from the sidebar — no code required.
+Prefer a GUI? The companion VS Code extension gives you live status, motion data, RAPID control, I/O signals, event log, file management, and CFG database editing directly from the sidebar — no code required. Works against both IRC5 and OmniCore.
 
-**[ABB Robot (RWS) — VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=merajsafari.abb-rws-vscode)**
+**[ABB Robot (RWS) — VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=merajsafari.abb-rws)**
 
 ---
 
 ## Features
 
-- HTTP Digest Authentication (RFC 2617) — no external auth libraries
-- Session cookie management (`ABBCX`, `-http-session-`)
-- Request rate limiting (< 20 req/sec, configurable)
-- Automatic session re-authentication after 5-minute inactivity
-- WebSocket subscriptions for real-time events (execution state, I/O signals, etc.)
-- Auto-reconnect on WebSocket disconnect (3 retries, exponential backoff)
+- **Dual-protocol** — RWS 1.0 (Digest, JSON) and RWS 2.0 (Basic, XHTML;v=2.0)
+- **Auto-detection** — `createClient(host)` probes the auth challenge and returns the right client
+- **Multi-robot** — `MultiRobotManager` for orchestrating several controllers in one process
+- **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)
+- 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`
-- Zero runtime dependencies — Node 18+ built-ins only
+- Single dependency: `ws` (only one we don't reimplement)
 
 ---
 
@@ -34,213 +39,419 @@ Prefer a GUI? The companion VS Code extension gives you live status, joint posit
 npm install abb-rws-client
 ```
 
-**Requirements:** Node.js 21+ (or Node 18 with `--experimental-websocket` for WebSocket subscription support).
+**Requirements:** Node.js 18+.
+
+---
+
+## Quick Start (auto-detect)
+
+The simplest path: `createClient` probes the controller and returns the right protocol's client.
+
+```ts
+import { createClient, RwsClient2 } from 'abb-rws-client';
+
+const client = await createClient({
+  host: '192.168.125.1',
+  // username/password default to 'Admin' / 'robotics' (built-in admin account, full UAS grants)
+});
+
+console.log(`Connected via ${client instanceof RwsClient2 ? 'RWS 2.0' : 'RWS 1.0'}`);
+
+const state = await client.getControllerState();   // 'motoron' | 'motoroff' | …
+const mode  = await client.getOperationMode();     // 'AUTO' | 'MANR' | 'MANF'
+const joints = await client.getJointPositions();   // { rax_1, …, rax_6 }
+
+await client.disconnect();
+```
+
+If you only target one protocol, skip the helper and instantiate the client directly. See [`examples/`](./examples/) for runnable scripts.
+
+---
+
+## Choosing a client
+
+| Controller | Protocol | Class | Auth | Default port |
+|---|---|---|---|---|
+| **IRC5** (RobotWare 6.x) | RWS 1.0 | `RwsClient` | HTTP Digest | 80 (real), 80 / 11811 (VC) |
+| **OmniCore** (RobotWare 7.x) | RWS 2.0 | `RwsClient2` | HTTP Basic | 443 (real), 5466 (VC HTTPS) |
+
+Both classes expose **the same method names** for ~140 endpoints (controller state, RAPID execution, modules, variables, motion, I/O, file service, CFG database, mastership, event log, etc.). The protocol differences (URL shapes, response format, mastership-domain naming, `$HOME` vs `HOME`) are handled internally — your code looks the same.
+
+If you need a single typed reference that holds either:
+
+```ts
+import { createAdapter, type IRWSAdapter } from 'abb-rws-client';
+
+const adapter: IRWSAdapter = await createAdapter({ host: '192.168.125.1' });
+// adapter is RWS1Adapter or RWS2Adapter — both implement IRWSAdapter
+```
 
 ---
 
-## Quick Start — RobotStudio virtual controller
+## RWS 1.0 explicit usage
 
 ```ts
 import { RwsClient, RwsError } from 'abb-rws-client';
 
 const client = new RwsClient({
-  host: '127.0.0.1',   // RobotStudio default
-  port: 80,
-  username: 'Default User',
+  host: '192.168.125.1',
+  username: 'Admin',
   password: 'robotics',
 });
 
-try {
-  await client.connect();
+await client.connect();
 
-  // Read state
-  const state = await client.getControllerState();
-  console.log('Controller state:', state); // e.g. 'motoron'
+// Controller state
+const state = await client.getControllerState(); // 'motoron' | 'motoroff' | ...
+const mode  = await client.getOperationMode();   // 'AUTO' | 'MANR' | 'MANF'
 
-  const mode = await client.getOperationMode();
-  console.log('Operation mode:', mode); // e.g. 'AUTO'
+// Motion
+const joints    = await client.getJointPositions();    // rax_1..rax_6 in degrees
+const tcp       = await client.getCartesianPosition(); // x/y/z mm + quaternion
+const tcpConfig = await client.getCartesianFull();     // + j1/j4/j6/jx config flags
 
-  // Read positions
-  const joints = await client.getJointPositions();
-  console.log('J1:', joints.rax_1, 'degrees');
+// RAPID
+await client.startRapid();
+await client.stopRapid();
+await client.resetRapid(); // PP to Main
 
-  const tcp = await client.getCartesianPosition();
-  console.log('TCP:', tcp.x, tcp.y, tcp.z, 'mm');
+// Variables
+const val = await client.getRapidVariable('T_ROB1', 'user', 'reg1');
+await client.setRapidVariable('T_ROB1', 'user', 'reg1', '42');
 
-  // RAPID execution
-  await client.startRapid();
-  await client.stopRapid();
-
-  // I/O signals
-  const di = await client.readSignal('Local', 'DRV_1', 'DI_1');
-  console.log('DI_1 =', di.value);
-  await client.writeSignal('Local', 'DRV_1', 'DO_1', '1');
-
-  // Upload and load a RAPID module
-  const modSource = `MODULE MyMod\n  PROC main()\n    TPWrite "Hello";\n  ENDPROC\nENDMODULE`;
-  await client.uploadModule('$HOME/MyMod.mod', modSource);
-  await client.loadModule('T_ROB1', '$HOME/MyMod.mod');
-
-  // Subscribe to real-time events
-  const unsubscribe = await client.subscribe(
-    ['execution', 'controllerstate'],
-    (event) => {
-      console.log(`[${event.timestamp.toISOString()}] ${event.resource} = ${event.value}`);
-    }
-  );
-
-  // ... later, unsubscribe and disconnect
-  await unsubscribe();
-  await client.disconnect();
+// I/O signals
+const signals = await client.listAllSignals();
+await client.writeSignal('Local', 'DRV_1', 'DO_1', '1');
 
-} catch (e) {
-  if (e instanceof RwsError) {
-    console.error(`[${e.code}] ${e.message} (HTTP ${e.httpStatus ?? 'N/A'})`);
-  } else {
-    throw e;
-  }
+// Real-time subscriptions
+const unsubscribe = await client.subscribe(
+  ['execution', 'controllerstate', { type: 'signal', name: 'Local/DRV_1/DI_1' }],
+  (event) => console.log(event.resource, '=', event.value),
+);
+await unsubscribe();
+
+await client.disconnect();
+```
+
+---
+
+## RWS 2.0 explicit usage
+
+```ts
+import { RwsClient2 } from 'abb-rws-client';
+
+// RWS 2.0 takes a base URL (scheme + host + port).
+//   Real OmniCore:  https://<host>:443
+//   OmniCore VC:    https://127.0.0.1:5466
+const client = new RwsClient2(
+  'https://127.0.0.1:5466',
+  'Admin',
+  'robotics',
+);
+
+await client.connect();
+
+// Same method names as RWS 1.0 — only the underlying protocol differs.
+console.log('state:', await client.getControllerState());
+console.log('joints:', await client.getJointPositions());
+
+// RAPID variable read — RWS 2.0 symbol API uses suffix-style URLs internally
+// (`/rw/rapid/symbol/{symburl}/data`); the method shape is the same.
+const tool0 = await client.getRapidVariable('T_ROB1', 'BASE', 'tool0');
+
+// WebSocket subscriptions over `robapi2_subscription` subprotocol.
+const unsubscribe = await client.subscribe(
+  ['controllerstate', 'execution'],
+  (event) => console.log(event.resource, '=', event.value),
+);
+
+await unsubscribe();
+await client.disconnect();
+```
+
+### Notable RWS 2.0 quirks (handled automatically)
+
+These are documented because they bite anyone who tries to write an RWS 2.0 client from scratch:
+
+- **HTTP Basic auth**, not Digest (RWS 1.0).
+- **XHTML responses only** — `Accept: application/json` returns 406. Library uses `Accept: application/xhtml+xml;v=2.0`.
+- **Path-based actions** — `/rw/rapid/execution/stop`, not `?action=stop`.
+- **Mastership domains collapsed** — both `'rapid'` and `'cfg'` map to `'edit'`. The adapter maps internally so either name works.
+- **File service home** is `'HOME'`, not `'$HOME'`.
+- **Symbol API path is suffix-style** — `/rw/rapid/symbol/{symburl}/data` (RWS 1.0 puts `/data` at the front).
+- **Module unload** is `POST /rw/rapid/tasks/{task}/unloadmod` with body, NOT `DELETE` on the module URL (returns 405).
+- **Self-signed TLS** on virtual controllers — library uses `rejectUnauthorized: false` for HTTPS.
+- **WebSocket subscription URL** comes from the `Location` header (real hardware) or the XHTML body (VC). Subprotocol: `robapi2_subscription`.
+
+---
+
+## Multi-robot orchestration
+
+For applications that talk to several controllers, use `MultiRobotManager`:
+
+```ts
+import { MultiRobotManager } from 'abb-rws-client';
+
+const multi = MultiRobotManager.fromConfigs([
+  { id: 'cell-A', name: 'Cell A IRB120',  host: '192.168.125.1', port: 80,   useHttps: false, username: 'Admin', password: 'robotics' },
+  { id: 'cell-B', name: 'Cell B IRB1200', host: '192.168.125.2', port: 443,  useHttps: true,  username: 'Admin', password: 'robotics' },
+]);
+
+multi.onError((msg, actions) => {
+  console.error(`Robot error: ${msg}`);
+  return Promise.resolve(undefined); // headless: just log
+});
+
+multi.onDidChange(() => {
+  console.log(`active=${multi.activeId} state=${multi.state.ctrlstate}`);
+});
+
+for (const { id } of multi.entries) {
+  await multi.connectRobot(id);
 }
+// One robot is "active" at a time (handy for UIs); state for all is polled.
+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)
+
+You can also create a `RobotManager` directly if you only have one robot.
+
+---
+
+## Logging
+
+The lib ships a no-op logger by default. Hosts (CLIs, services, the VS Code extension) install their own:
+
+```ts
+import { setLogger } from 'abb-rws-client';
+
+setLogger({
+  info:  (msg) => console.log(`[info]  ${msg}`),
+  warn:  (msg) => console.warn(`[warn]  ${msg}`),
+  error: (msg, err) => console.error(`[error] ${msg}`, err),
+  show:  () => { /* bring log surface to front; no-op for CLIs */ },
+});
 ```
 
+Internal lifecycle events (connect/disconnect, polling cycles, subscription state, error recovery) flow through this.
+
 ---
 
 ## API Reference
 
-### `new RwsClient(options)`
+### Constructor
+
+```ts
+new RwsClient(options: RwsClientOptions)
+```
 
 | Option | Type | Default | Description |
-|---|---|---|---|
+|--------|------|---------|-------------|
 | `host` | `string` | — | Controller IP or hostname |
 | `port` | `number` | `80` | HTTP port |
-| `username` | `string` | `'Default User'` | RWS username |
+| `username` | `string` | `'Admin'` | RWS username |
 | `password` | `string` | `'robotics'` | RWS password |
-| `requestIntervalMs` | `number` | `55` | Minimum ms between requests (enforces < 20 req/sec) |
+| `requestIntervalMs` | `number` | `55` | Min ms between requests (enforces < 20 req/sec) |
 | `timeout` | `number` | `5000` | Request timeout in ms |
-| `sessionCookie` | `string` | — | Saved cookie string to reuse an existing session slot (avoids the 70-session controller limit) |
+| `sessionCookie` | `string` | — | Saved cookie to reuse an existing session slot |
 
 ---
 
 ### Connection
 
 | Method | Returns | Description |
-|---|---|---|
-| `connect()` | `Promise<void>` | Establish session and authenticate |
-| `disconnect()` | `Promise<void>` | Close subscriptions and clear session |
-| `getSessionCookie()` | `string \| null` | Current session cookie — save and pass as `sessionCookie` on next start to reuse the slot |
+|--------|---------|-------------|
+| `connect()` | `void` | Establish session and authenticate |
+| `disconnect()` | `void` | Close WebSocket subscriptions and clear session |
+| `getSessionCookie()` | `string \| null` | Current session cookie — persist to avoid 70-session limit |
 
 ---
 
-### Controller State
+### Controller State & Panel
 
 | Method | Returns | Description |
-|---|---|---|
-| `getControllerState()` | `Promise<ControllerState>` | `'init'` \| `'motoroff'` \| `'motoron'` \| `'guardstop'` \| `'emergencystop'` \| `'emergencystopreset'` \| `'sysfail'` |
-| `getOperationMode()` | `Promise<OperationMode>` | `'AUTO'` \| `'MANR'` \| `'MANF'` |
+|--------|---------|-------------|
+| `getControllerState()` | `ControllerState` | Motor state: motoron / motoroff / guardstop / emergencystop / … |
+| `setControllerState(state)` | `void` | Set motor state — requires mastership |
+| `getOperationMode()` | `OperationMode` | AUTO / MANR / MANF |
+| `lockOperationMode(pin, permanent?)` | `void` | Lock FlexPendant key switch with PIN |
+| `unlockOperationMode()` | `void` | Unlock FlexPendant key switch |
+| `getSpeedRatio()` | `number` | Speed override 0–100 |
+| `setSpeedRatio(ratio)` | `void` | Set speed override — AUTO mode only |
+| `getCollisionDetectionState()` | `CollisionDetectionState` | INIT / TRIGGERED / CONFIRMED / TRIGGERED_ACK |
+| `restartController(mode?)` | `void` | restart / istart / pstart / bstart |
+| `getControllerIdentity()` | `ControllerIdentity` | Name, ID, type, MAC address |
+| `getSystemInfo()` | `SystemInfo` | RobotWare version, options, system ID |
+| `getControllerClock()` | `ControllerClock` | Current date/time (UTC) |
+| `setControllerClock(y,mo,d,h,mi,s)` | `void` | Set controller date/time (UTC) |
 
 ---
 
 ### RAPID Execution
 
 | Method | Returns | Description |
-|---|---|---|
-| `getRapidExecutionState()` | `Promise<ExecutionState>` | `'running'` \| `'stopped'` |
-| `getRapidTasks()` | `Promise<RapidTask[]>` | All RAPID tasks and their states |
-| `startRapid()` | `Promise<void>` | Start RAPID execution (requires AUTO + motors on) |
-| `stopRapid()` | `Promise<void>` | Stop RAPID execution |
-| `resetRapid()` | `Promise<void>` | Reset program pointer to main |
+|--------|---------|-------------|
+| `getRapidExecutionState()` | `ExecutionState` | `'running'` \| `'stopped'` |
+| `getRapidExecutionInfo()` | `ExecutionInfo` | State + current cycle mode |
+| `getRapidTasks()` | `RapidTask[]` | All tasks with name, type, state, active flag |
+| `startRapid()` | `void` | Start execution (AUTO + motors on required) |
+| `stopRapid()` | `void` | Stop execution |
+| `resetRapid()` | `void` | Reset program pointer to Main |
+| `setExecutionCycle(cycle)` | `void` | `'once'` \| `'forever'` \| `'asis'` |
+| `activateRapidTask(task)` | `void` | Activate a task (multitasking) |
+| `deactivateRapidTask(task)` | `void` | Deactivate a task |
+| `activateAllRapidTasks()` | `void` | Activate all tasks |
+| `deactivateAllRapidTasks()` | `void` | Deactivate all tasks |
+
+---
+
+### RAPID Variables & Symbols
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getRapidVariable(task, module, symbol)` | `string` | Read variable as RAPID-syntax string |
+| `setRapidVariable(task, module, symbol, value)` | `void` | Write variable (RAPID syntax: `'42'`, `'"hello"'`, `'[1,0,0,0]'`) |
+| `validateRapidValue(task, value, datatype)` | `boolean` | Validate value against datatype before writing |
+| `getRapidSymbolProperties(task, module, symbol)` | `RapidSymbolProperties` | Type, dims, storage class, flags |
+| `searchRapidSymbols(params)` | `RapidSymbolInfo[]` | Search by task, type, datatype, or regex |
+| `getActiveUiInstruction()` | `UiInstruction \| null` | Detect if RAPID is waiting for operator input |
+| `setUiInstructionParam(stackurl, param, value)` | `void` | Respond to a UI instruction (TPReadNum, TPReadFK…) |
+
+---
+
+### RAPID Modules
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `listModules(taskName)` | `string[]` | Names of all loaded modules in a task |
+| `loadModule(task, modulePath, replace?)` | `void` | Load module from controller filesystem into task |
+| `unloadModule(task, moduleName)` | `void` | Unload module from task (RAPID must be stopped) |
 
 ---
 
 ### Motion
 
 | Method | Returns | Description |
-|---|---|---|
-| `getJointPositions(mechunit?)` | `Promise<JointTarget>` | Joint angles in degrees for all 6 axes |
-| `getCartesianPosition(mechunit?, tool?, wobj?)` | `Promise<RobTarget>` | TCP position (mm) and orientation (quaternion) |
+|--------|---------|-------------|
+| `getJointPositions(mechunit?)` | `JointTarget` | rax_1–rax_6 in degrees (default mechunit: ROB_1) |
+| `getCartesianPosition(mechunit?, tool?, wobj?)` | `RobTarget` | TCP x/y/z (mm) + q1–q4 quaternion |
+| `getCartesianFull(mechunit?)` | `CartesianFull` | TCP pose + j1/j4/j6/jx configuration flags |
 
 ---
 
-### Modules
+### File System
 
 | Method | Returns | Description |
-|---|---|---|
-| `uploadModule(remotePath, content)` | `Promise<void>` | Upload RAPID `.mod` source to controller filesystem |
-| `loadModule(taskName, modulePath)` | `Promise<void>` | Load an uploaded module into a RAPID task |
-| `unloadModule(taskName, moduleName)` | `Promise<void>` | Unload a module from a task (RAPID must be stopped) |
-| `listModules(taskName)` | `Promise<string[]>` | Names of all loaded modules in a task |
-| `readFile(remotePath)` | `Promise<string>` | Download a file from the controller filesystem as a string |
+|--------|---------|-------------|
+| `listDirectory(remotePath)` | `FileEntry[]` | Browse a directory (`$HOME`, `$TEMP`, …) |
+| `readFile(remotePath)` | `string` | Download file as UTF-8 string |
+| `uploadModule(remotePath, content)` | `void` | Upload file content (max 800 MB) |
+| `deleteFile(remotePath)` | `void` | Delete file |
+| `createDirectory(parentPath, dirName)` | `void` | Create directory |
+| `copyFile(sourcePath, destPath)` | `void` | Copy file on controller |
 
 ---
 
 ### I/O Signals
 
 | Method | Returns | Description |
-|---|---|---|
-| `readSignal(network, device, name)` | `Promise<Signal>` | Read current signal value |
-| `writeSignal(network, device, name, value)` | `Promise<void>` | Write a value to an output signal |
+|--------|---------|-------------|
+| `listAllSignals(start?, limit?)` | `Signal[]` | Paginated flat list of all signals |
+| `readSignal(network, device, name)` | `Signal` | Read a specific signal by address |
+| `writeSignal(network, device, name, value)` | `void` | Write DO/AO/GO — value as string: `'1'`, `'0'`, `'3.14'` |
+| `listNetworks()` | `IoNetwork[]` | All I/O networks |
+| `listDevices(network)` | `IoDevice[]` | Devices on a network |
+
+> Pass `''` for `network` and `device` to use the flat signal path (works by signal name alone).
+
+---
+
+### Event Log
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getEventLog(domain?, lang?)` | `ElogMessage[]` | Read log messages (domain 0 = main, newest first) |
+| `clearEventLog(domain?)` | `void` | Clear messages in one domain |
+| `clearAllEventLogs()` | `void` | Clear all domains |
 
 ---
 
-### Subscriptions
+### Mastership
+
+Required before modifying motor state, speed ratio, or certain RAPID operations.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `requestMastership(domain)` | `void` | Take control — `'cfg'` \| `'motion'` \| `'rapid'` |
+| `releaseMastership(domain)` | `void` | Release control — always call in `finally` |
 
 ```ts
-subscribe(
-  resources: SubscriptionResource[],
-  handler: (event: SubscriptionEvent) => void
-): Promise<() => Promise<void>>
+await client.requestMastership('rapid');
+try {
+  await client.setControllerState('motoron');
+} finally {
+  await client.releaseMastership('rapid');
+}
 ```
 
-Subscribe to real-time RWS events. Returns an async unsubscribe function.
+---
 
-**`SubscriptionResource`** can be:
-- `'execution'` — RAPID execution state changes
-- `'controllerstate'` — controller state changes
-- `'operationmode'` — operation mode changes
-- `{ type: 'signal'; name: 'network/device/signalname' }` — I/O signal changes
-- `{ type: 'persvar'; name: 'task/varname' }` — RAPID persistent variable changes
+### WebSocket Subscriptions
 
-**`SubscriptionEvent`**:
 ```ts
-{
-  resource: string;   // RWS path of the changed resource
-  value: string;      // New value as string
-  timestamp: Date;    // When the event was received
-}
+const unsubscribe = await client.subscribe(resources, handler);
+// ...
+await unsubscribe();
 ```
 
+| Resource | Type | Description |
+|----------|------|-------------|
+| `'execution'` | string | RAPID execution state changes |
+| `'controllerstate'` | string | Motor state changes |
+| `'operationmode'` | string | Operation mode changes |
+| `'speedratio'` | string | Speed ratio changes |
+| `'coldetstate'` | string | Collision detection state |
+| `'uiinstr'` | string | Active UI instruction changes |
+| `{ type: 'execycle' }` | object | Execution cycle mode changes |
+| `{ type: 'taskchange', task }` | object | Task state changes |
+| `{ type: 'signal', name }` | object | I/O signal value changes |
+| `{ type: 'persvar', name }` | object | RAPID persistent variable changes |
+| `{ type: 'elog', domain }` | object | New event log entries |
+
+`SubscriptionEvent`: `{ resource: string, value: string, timestamp: Date }`
+
 ---
 
 ### Error Handling
 
-All public methods throw `RwsError` (never plain `Error`) with a typed `code`:
+All public methods throw `RwsError` — never a plain `Error`.
 
 | Code | Meaning |
-|---|---|
+|------|---------|
 | `'AUTH_FAILED'` | Wrong credentials or session rejected |
-| `'SESSION_EXPIRED'` | Session timed out and re-auth was not possible |
-| `'MOTORS_OFF'` | Action requires motors to be on |
-| `'MODULE_NOT_FOUND'` | Module file not found on controller filesystem |
-| `'CONTROLLER_BUSY'` | Controller returned 503; retry later |
+| `'SESSION_EXPIRED'` | Session timed out |
+| `'MOTORS_OFF'` | Action requires motors on |
+| `'MODULE_NOT_FOUND'` | Module file not found on controller |
+| `'CONTROLLER_BUSY'` | Controller returned 503 — retry later |
 | `'RATE_LIMITED'` | Too many requests (429) |
-| `'NETWORK_ERROR'` | TCP/timeout/WebSocket error |
+| `'NETWORK_ERROR'` | TCP / timeout / WebSocket error |
 | `'PARSE_ERROR'` | Unexpected XML response format |
-| `'UNKNOWN'` | Unmapped error; check `httpStatus` and `rwsDetail` |
+| `'UNKNOWN'` | Unmapped error — check `httpStatus` and `rwsDetail` |
 
 ```ts
 try {
   await client.startRapid();
 } catch (e) {
   if (e instanceof RwsError) {
-    switch (e.code) {
-      case 'MOTORS_OFF':
-        console.error('Enable motors on the FlexPendant first');
-        break;
-      case 'AUTH_FAILED':
-        console.error('Check username/password');
-        break;
-      default:
-        console.error(`Unexpected error [${e.code}]: ${e.message}`);
-    }
+    if (e.code === 'MOTORS_OFF') console.error('Enable motors first');
+    else throw e;
   }
 }
 ```
@@ -249,43 +460,53 @@ try {
 
 ## Session Persistence
 
-The IRC5 controller allows a maximum of **70 concurrent RWS sessions**. To avoid exhausting this limit across process restarts, persist the session cookie:
+The IRC5 controller allows a maximum of **70 concurrent RWS sessions**. Persist the session cookie across restarts to always reuse the same slot:
 
 ```ts
 import fs from 'fs';
 
-// After connecting — save the cookie
+// Save after connecting
 const cookie = client.getSessionCookie();
 if (cookie) fs.writeFileSync('.rws-session', cookie, 'utf8');
 
-// On next start — reuse it
+// Restore on next start
 let sessionCookie: string | undefined;
 try { sessionCookie = fs.readFileSync('.rws-session', 'utf8'); } catch {}
 
 const client = new RwsClient({ host, username, password, sessionCookie });
-await client.connect(); // reuses the existing slot, no new session created
+await client.connect(); // reuses the existing session slot
 ```
 
 ---
 
-## Compatibility
+## 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 |
 
-| Feature | RobotWare 6.x (RWS 1.0) | RobotWare 7.x (RWS 2.0) |
-|---|---|---|
-| This package | ✓ Supported | ✗ Not compatible |
-| Controller: IRC5 | ✓ | n/a |
-| Controller: OmniCore | n/a | ✗ |
-| RobotStudio (virtual) | ✓ (127.0.0.1) | ✗ |
+---
+
+## Compatibility
 
-RWS 2.0 uses a completely different API structure. This package implements RWS 1.0 only and will not function with RobotWare 7.x or OmniCore controllers.
+| | 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) | ❌ |
 
 ---
 
 ## Resources
 
-- [ABB RWS 1.0 API Reference](https://developercenter.robotstudio.com/api/rwsApi/)
-- [ABB Developer Center](https://developercenter.robotstudio.com/api/RWS)
-- [VALIDATION.md](./VALIDATION.md) — Manual test procedures against a real IRC5 / RobotStudio controller
+- [ABB Developer Center — RWS API](https://developercenter.robotstudio.com/api/rwsApi/)
+- [Companion VS Code Extension](https://marketplace.visualstudio.com/items?itemName=merajsafari.abb-rws)
 
 ---