abb-rws-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meraj Safari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# 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/).
+
+> **Compatibility:** RWS 1.0 / RobotWare 6.x only.  
+> **Not compatible** with OmniCore controllers, RobotWare 7.x, or RWS 2.0.
+
+---
+
+## 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)
+- Fully typed public API — every method throws `RwsError` with a typed `code`
+- Zero runtime dependencies — Node 18+ built-ins only
+
+---
+
+## Installation
+
+```bash
+npm install abb-rws-client
+```
+
+**Requirements:** Node.js 21+ (or Node 18 with `--experimental-websocket` for WebSocket subscription support).
+
+---
+
+## Quick Start — RobotStudio virtual controller
+
+```ts
+import { RwsClient, RwsError } from 'abb-rws-client';
+
+const client = new RwsClient({
+  host: '127.0.0.1',   // RobotStudio default
+  port: 80,
+  username: 'Default User',
+  password: 'robotics',
+});
+
+try {
+  await client.connect();
+
+  // Read state
+  const state = await client.getControllerState();
+  console.log('Controller state:', state); // e.g. 'motoron'
+
+  const mode = await client.getOperationMode();
+  console.log('Operation mode:', mode); // e.g. 'AUTO'
+
+  // Read positions
+  const joints = await client.getJointPositions();
+  console.log('J1:', joints.rax_1, 'degrees');
+
+  const tcp = await client.getCartesianPosition();
+  console.log('TCP:', tcp.x, tcp.y, tcp.z, 'mm');
+
+  // 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();
+
+} catch (e) {
+  if (e instanceof RwsError) {
+    console.error(`[${e.code}] ${e.message} (HTTP ${e.httpStatus ?? 'N/A'})`);
+  } else {
+    throw e;
+  }
+}
+```
+
+---
+
+## API Reference
+
+### `new RwsClient(options)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `host` | `string` | — | Controller IP or hostname |
+| `port` | `number` | `80` | HTTP port |
+| `username` | `string` | `'Default User'` | RWS username |
+| `password` | `string` | `'robotics'` | RWS password |
+| `requestIntervalMs` | `number` | `55` | Minimum ms between requests (enforces < 20 req/sec) |
+| `timeout` | `number` | `5000` | Request timeout in ms |
+
+---
+
+### Connection
+
+| Method | Returns | Description |
+|---|---|---|
+| `connect()` | `Promise<void>` | Establish session and authenticate |
+| `disconnect()` | `Promise<void>` | Close subscriptions and clear session |
+
+---
+
+### Controller State
+
+| Method | Returns | Description |
+|---|---|---|
+| `getControllerState()` | `Promise<ControllerState>` | `'init'` \| `'motoroff'` \| `'motoron'` \| `'guardstop'` \| `'emergencystop'` \| `'emergencystopreset'` \| `'sysfail'` |
+| `getOperationMode()` | `Promise<OperationMode>` | `'AUTO'` \| `'MANR'` \| `'MANF'` |
+
+---
+
+### 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 |
+
+---
+
+### 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) |
+
+---
+
+### Modules
+
+| 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 |
+| `listModules(taskName)` | `Promise<string[]>` | Names of all loaded modules in a task |
+
+---
+
+### 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 |
+
+---
+
+### Subscriptions
+
+```ts
+subscribe(
+  resources: SubscriptionResource[],
+  handler: (event: SubscriptionEvent) => void
+): Promise<() => Promise<void>>
+```
+
+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
+
+**`SubscriptionEvent`**:
+```ts
+{
+  resource: string;   // RWS path of the changed resource
+  value: string;      // New value as string
+  timestamp: Date;    // When the event was received
+}
+```
+
+---
+
+### Error Handling
+
+All public methods throw `RwsError` (never plain `Error`) with a typed `code`:
+
+| 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 |
+| `'RATE_LIMITED'` | Too many requests (429) |
+| `'NETWORK_ERROR'` | TCP/timeout/WebSocket error |
+| `'PARSE_ERROR'` | Unexpected XML response format |
+| `'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}`);
+    }
+  }
+}
+```
+
+---
+
+## Compatibility
+
+| 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) | ✗ |
+
+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.
+
+---
+
+## 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
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE)

package/dist/HttpSession.d.ts

@@ -0,0 +1,92 @@
+/**
+ * HttpSession — HTTP communication layer for ABB IRC5 controllers.
+ *
+ * Features:
+ * - HTTP Digest Authentication (RFC 2617) implemented from scratch using node:crypto
+ * - ABBCX + -http-session- cookie management
+ * - Request queue enforcing minimum interval between requests (<20 req/sec RWS limit)
+ * - Automatic re-authentication on session expiry (5-minute inactivity)
+ * - 401 retry with fresh digest handshake; 503 retry with 200ms backoff
+ * - AbortController-based timeout
+ *
+ * Uses Node 18+ built-in fetch and node:crypto. Zero external dependencies.
+ */
+import type { HttpResponse } from './types.js';
+export interface HttpSessionOptions {
+    baseUrl: string;
+    username: string;
+    password: string;
+    requestIntervalMs: number;
+    timeoutMs: number;
+}
+export declare class HttpSession {
+    private readonly baseUrl;
+    private readonly username;
+    private readonly password;
+    private readonly requestIntervalMs;
+    private readonly timeoutMs;
+    /** Stored session cookies: '-http-session-' and 'ABBCX' */
+    private cookies;
+    /** Last parsed digest challenge from WWW-Authenticate */
+    private digestChallenge;
+    /** Nonce use counter — reset to 0 whenever a new nonce is received */
+    private nonceCount;
+    /** Timestamp of the most recent request sent */
+    private lastRequestTime;
+    /** Timestamp of the most recent successful response — used for session expiry */
+    private lastActivityTime;
+    /** Promise chain that serialises all outbound requests */
+    private requestQueue;
+    /** 5-minute session inactivity timeout (milliseconds) */
+    private static readonly SESSION_TIMEOUT_MS;
+    constructor(options: HttpSessionOptions);
+    get(path: string): Promise<HttpResponse>;
+    post(path: string, body?: string): Promise<HttpResponse>;
+    put(path: string, body: string | Uint8Array): Promise<HttpResponse>;
+    delete(path: string): Promise<HttpResponse>;
+    /** Returns the current cookie string for use in WebSocket connections */
+    getCookieHeader(): string;
+    /** Clear all session state (called on disconnect) */
+    clearSession(): void;
+    /**
+     * Append a function to the serial request queue, enforcing the minimum interval
+     * between requests. Error suppression on `this.requestQueue` (not on `result`)
+     * ensures queue continues processing even when individual requests fail.
+     */
+    private enqueue;
+    private execute;
+    /** Issue a single HTTP request with digest auth header if we have a challenge */
+    private rawFetch;
+    /**
+     * Parse the WWW-Authenticate: Digest ... header into a DigestChallenge.
+     * Handles both quoted and unquoted parameter values per RFC 2617.
+     */
+    private parseDigestChallenge;
+    /**
+     * Build the Authorization: Digest ... header value for the given request.
+     * Increments the nonce use counter (nc).
+     *
+     * RFC 2617 §3.2.2:
+     *   HA1 = MD5(username:realm:password)
+     *   HA2 = MD5(method:digestURI)
+     *   response = MD5(HA1:nonce:nc:cnonce:qop:HA2)  — when qop=auth
+     *   response = MD5(HA1:nonce:HA2)                — RFC 2069 compat (no qop)
+     *
+     * Important: the space in 'Default User' is NOT percent-encoded for HA1.
+     * The nc value is NOT quoted in the Authorization header.
+     * The URI is path+query only, not scheme://host:port/path.
+     */
+    private buildAuthHeader;
+    /**
+     * Extract Set-Cookie headers from a response and store name=value pairs.
+     * Uses Headers.getSetCookie() (Node 18.14.1+) to correctly handle multiple
+     * Set-Cookie headers. Falls back to headers.get('set-cookie') on older Node 18,
+     * though this may misparse cookie values containing commas.
+     */
+    private storeCookies;
+    private buildCookieHeader;
+    private isSessionExpired;
+    private isOk;
+    private mapHttpStatus;
+}
+//# sourceMappingURL=HttpSession.d.ts.map

package/dist/HttpSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpSession.d.ts","sourceRoot":"","sources":["../src/HttpSession.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAmB,YAAY,EAAE,MAAM,YAAY,CAAC;AAchE,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,2DAA2D;IAC3D,OAAO,CAAC,OAAO,CAAkC;IAEjD,yDAAyD;IACzD,OAAO,CAAC,eAAe,CAAgC;IAEvD,sEAAsE;IACtE,OAAO,CAAC,UAAU,CAAK;IAEvB,gDAAgD;IAChD,OAAO,CAAC,eAAe,CAAK;IAE5B,iFAAiF;IACjF,OAAO,CAAC,gBAAgB,CAAK;IAE7B,0DAA0D;IAC1D,OAAO,CAAC,YAAY,CAAoC;IAExD,yDAAyD;IACzD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAiB;gBAE/C,OAAO,EAAE,kBAAkB;IAUvC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIxC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIxD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC;IAInE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI3C,yEAAyE;IACzE,eAAe,IAAI,MAAM;IAIzB,qDAAqD;IACrD,YAAY,IAAI,IAAI;IASpB;;;;OAIG;IACH,OAAO,CAAC,OAAO;YAsBD,OAAO;IA0DrB,iFAAiF;YACnE,QAAQ;IAoDtB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IA8B5B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,eAAe;IAwCvB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAyBpB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,aAAa;CAetB"}