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

npm install betterdesk-cdap
# or from local path
npm install ./sdks/nodejs

Quick Start

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:

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

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

MIT

README.md

BetterDesk CDAP — Node.js SDK