mirror of
https://github.com/UNITRONIX/BetterDesk.git
synced 2026-09-10 09:35:39 +00:00
UNITRONIX
0874d4f3d9
Updated the entire project to AGPL-3.0, including all components and documentation. The stable releases up to v3.3.x will remain under Apache 2.0 until the next major feature release. Withdrawn and recreated French and Traditional Chinese translations under the new license. Updated relevant documentation and changelog to reflect these changes.
126 lines
3.7 KiB
Markdown
126 lines
3.7 KiB
Markdown
# BetterDesk CDAP — Node.js SDK
|
|
|
|
Node.js SDK for the **Connected Device Automation Protocol (CDAP)** used by
|
|
BetterDesk server. Build custom bridges, IoT gateways, or automation agents
|
|
that expose widgets and handle commands through the BetterDesk web panel.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install betterdesk-cdap
|
|
# or from local path
|
|
npm install ./sdks/nodejs
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```js
|
|
const { CDAPBridge, gauge, toggle } = require('betterdesk-cdap');
|
|
|
|
const bridge = new CDAPBridge({
|
|
server: 'ws://your-betterdesk-server:21122/cdap',
|
|
apiKey: 'YOUR_API_KEY',
|
|
deviceName: 'Room Sensor',
|
|
deviceType: 'sensor',
|
|
bridgeName: 'room-sensor',
|
|
});
|
|
|
|
// Define widgets
|
|
bridge
|
|
.addWidget(gauge('temperature', 'Temperature', { unit: '°C', min: -10, max: 50 }))
|
|
.addWidget(toggle('heater', 'Heater'));
|
|
|
|
// Handle commands
|
|
bridge.onCommand('heater', ({ value }) => {
|
|
console.log('Heater toggled to', value);
|
|
return value; // returned value becomes new widget state
|
|
});
|
|
|
|
// Events
|
|
bridge.on('connected', () => console.log('Connected'));
|
|
bridge.on('registered', () => console.log('Registered'));
|
|
bridge.on('error', (err) => console.error(err));
|
|
|
|
// Start (blocks — reconnects automatically)
|
|
bridge.run();
|
|
|
|
// Push state changes at any time
|
|
setInterval(() => {
|
|
bridge.updateState('temperature', 20 + Math.random() * 5);
|
|
}, 5000);
|
|
```
|
|
|
|
## Async Command Handlers
|
|
|
|
Handlers can return promises:
|
|
|
|
```js
|
|
bridge.onCommand('restart', async ({ params }) => {
|
|
await someAsyncOperation(params);
|
|
return true;
|
|
});
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### `new CDAPBridge(options)`
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `server` | `string` | — | WebSocket URL (`ws://host:21122/cdap`) |
|
|
| `authMethod` | `string` | `'api_key'` | `api_key` / `device_token` / `user_password` |
|
|
| `apiKey` | `string` | `''` | API key (when `authMethod='api_key'`) |
|
|
| `deviceToken` | `string` | `''` | Device token |
|
|
| `username` | `string` | `''` | Username |
|
|
| `password` | `string` | `''` | Password |
|
|
| `deviceId` | `string` | `''` | Device ID (auto-assigned if empty) |
|
|
| `deviceName` | `string` | hostname | Display name |
|
|
| `deviceType` | `string` | `'bridge'` | Device type |
|
|
| `bridgeName` | `string` | `''` | Bridge identifier |
|
|
| `bridgeVersion` | `string` | `'1.0.0'` | Bridge version |
|
|
| `heartbeatSec` | `number` | `15` | Heartbeat interval (seconds) |
|
|
| `reconnectSec` | `number` | `5` | Initial reconnect delay |
|
|
| `maxReconnect` | `number` | `120` | Maximum reconnect delay |
|
|
|
|
### Methods
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `addWidget(widget)` | Add a widget to the manifest |
|
|
| `onCommand(widgetId, handler)` | Register command handler for a widget |
|
|
| `updateState(widgetId, value)` | Push a single state update to server |
|
|
| `bulkUpdate({ id: value })` | Push multiple state updates |
|
|
| `fireAlert(id, severity, msg, details?)` | Fire an alert |
|
|
| `resolveAlert(id)` | Resolve a fired alert |
|
|
| `sendLog(level, msg, data?)` | Send a log entry |
|
|
| `run()` | Start (async, reconnects automatically) |
|
|
| `stop()` | Stop the bridge |
|
|
|
|
### Events
|
|
|
|
| Event | Payload | Description |
|
|
|-------|---------|-------------|
|
|
| `connected` | — | WebSocket connected |
|
|
| `disconnected` | `{ code, reason }` | WebSocket closed |
|
|
| `registered` | payload | Registration confirmed |
|
|
| `command` | payload | Command received |
|
|
| `error` | `Error` | Error occurred |
|
|
| `message` | `{ type, payload }` | Any raw message |
|
|
|
|
### Widget Helpers
|
|
|
|
```js
|
|
const { gauge, toggle, button, textWidget, led, slider, select, chart, table } = require('betterdesk-cdap');
|
|
```
|
|
|
|
All helpers accept `(id, label, opts?)` and return a `Widget` object.
|
|
|
|
## Requirements
|
|
|
|
- Node.js >= 18.0.0
|
|
- BetterDesk server with CDAP enabled (port 21122)
|
|
|
|
## License
|
|
|
|
AGPL-3.0
|