@xiboplayer/xmr 0.6.2 → 0.6.4

package/README.md

@@ -1,21 +1,29 @@
 # @xiboplayer/xmr
 
-**XMR WebSocket client for real-time Xibo CMS commands.**
+**XMR WebSocket client for real-time Xibo CMS push commands.**
 
 ## Overview
 
 Listens for push commands from the CMS over WebSocket with automatic reconnection:
 
-- **collectNow** — trigger an immediate collection cycle
-- **screenshot** — request a display screenshot
-- **changeLayout** — switch to a specific layout
-- **overlayLayout** — show an overlay layout
-- **revertToSchedule** — return to the scheduled playlist
-- **purgeAll** — clear all cached content
-- **dataUpdate** — notify of updated widget data
-- **triggerWebhook** — fire a webhook action
-- **commandAction** — execute a shell command
-- **criteriaUpdate** — update geo/criteria filters
+- **13 command handlers** -- collectNow, screenshot, changeLayout, overlayLayout, revertToSchedule, purgeAll, commandAction, triggerWebhook, dataUpdate, rekeyAction, criteriaUpdate, currentGeoLocation, licenceCheck
+- **Auto-reconnect** -- exponential backoff (5s base, up to 10 attempts), resumes on next collection cycle
+- **Intentional shutdown** -- clean disconnect without triggering reconnection
+- **Dual-path geo-location** -- CMS can push coordinates or request the player to report its position
+
+## Architecture
+
+```
+CMS (Push)                     XmrWrapper                    PlayerCore
+    |                              |                              |
+    +--- WebSocket message ------> xmr.on('collectNow') -------> player.collect()
+    +--- WebSocket message ------> xmr.on('changeLayout') -----> player.changeLayout()
+    +--- WebSocket message ------> xmr.on('screenshot') -------> player.captureScreenshot()
+    +--- WebSocket message ------> xmr.on('purgeAll') ---------> player.purgeAll()
+    |                              |                              |
+    +--- disconnect -------------> scheduleReconnect() ---------> [5s, 10s, 15s, ...]
+    +--- reconnect --------------> xmr.on('connected') --------> updateStatus('XMR connected')
+```
 
 ## Installation
 
@@ -26,22 +34,77 @@ npm install @xiboplayer/xmr
 ## Usage
 
 ```javascript
-import { XmrClient } from '@xiboplayer/xmr';
+import { XmrWrapper } from '@xiboplayer/xmr';
+
+const xmr = new XmrWrapper(config, player);
 
-const xmr = new XmrClient({
-  wsUrl: 'wss://your-cms.example.com/xmr',
-  channel: 'display-channel-key',
-  rsaKey: 'display-rsa-key',
-});
+// Start connection (from RegisterDisplay result)
+const success = await xmr.start(xmrWebSocketAddress, xmrCmsKey);
 
-xmr.on('collectNow', () => player.collect());
-xmr.on('screenshot', () => captureScreenshot());
-xmr.connect();
+if (success) {
+  console.log('XMR connected - real-time commands active');
+} else {
+  console.log('XMR failed - falling back to polling mode');
+}
+
+// Check status
+xmr.isConnected(); // true/false
+
+// Stop cleanly
+await xmr.stop();
 ```
 
+## Commands
+
+| Command | Payload | Action |
+|---------|---------|--------|
+| `collectNow` | -- | Trigger immediate XMDS collection cycle |
+| `screenShot` / `screenshot` | -- | Capture and upload display screenshot |
+| `changeLayout` | `{ layoutId, duration?, downloadRequired?, changeMode? }` | Switch to specific layout |
+| `overlayLayout` | `{ layoutId, duration?, downloadRequired? }` | Push overlay on top |
+| `revertToSchedule` | -- | Return to normal scheduled content |
+| `purgeAll` | -- | Clear all cached files and re-download |
+| `commandAction` | `{ commandCode, commands? }` | Execute player command (HTTP only in browser) |
+| `triggerWebhook` | `{ triggerCode }` | Fire a webhook trigger action |
+| `dataUpdate` | -- | Force refresh data connectors |
+| `rekeyAction` | -- | Rotate RSA key pair and re-register |
+| `criteriaUpdate` | `data` | Update display criteria, trigger collection |
+| `currentGeoLocation` | `{ latitude?, longitude? }` | Push coordinates or request location report |
+| `licenceCheck` | -- | No-op for Linux clients |
+
+## Reconnection
+
+- **Base delay:** 5 seconds, linear increase (5s, 10s, 15s, ...)
+- **Max attempts:** 10 per disconnect event
+- **After max:** stops trying until next collection cycle calls `start()` again
+- **Intentional stop:** `stop()` sets a flag that prevents reconnection on disconnect
+
+## API Reference
+
+### Constructor
+
+```javascript
+new XmrWrapper(config, player)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `config` | Object | Player config with `hardwareKey`, `xmrChannel` |
+| `player` | Object | PlayerCore instance with command methods |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `start(xmrUrl, cmsKey)` | `Promise<boolean>` | Connect to XMR WebSocket |
+| `stop()` | `Promise<void>` | Disconnect cleanly (no reconnect) |
+| `isConnected()` | `boolean` | Check connection status |
+| `send(action, data)` | `Promise<boolean>` | Send message to CMS |
+
 ## Dependencies
 
-- `@xiboplayer/utils` — logger, events
+- `@xibosignage/xibo-communication-framework` -- XMR protocol implementation
+- `@xiboplayer/utils` -- logger
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/xmr",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "XMR WebSocket client for real-time Xibo CMS commands",
   "type": "module",
   "main": "./src/index.js",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@xibosignage/xibo-communication-framework": "^0.0.6",
-    "@xiboplayer/utils": "0.6.2"
+    "@xiboplayer/utils": "0.6.4"
   },
   "devDependencies": {
     "vitest": "^2.0.0"