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.
npm install betterdesk-cdap
# or from local path
npm install ./sdks/nodejsconst { 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);Handlers can return promises:
bridge.onCommand('restart', async ({ params }) => {
await someAsyncOperation(params);
return true;
});| 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 |
| 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 |
| 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 |
const { gauge, toggle, button, textWidget, led, slider, select, chart, table } = require('betterdesk-cdap');All helpers accept (id, label, opts?) and return a Widget object.
- Node.js >= 18.0.0
- BetterDesk server with CDAP enabled (port 21122)
AGPL-3.0