BetterDesk/sdks/nodejs

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

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

Widget Helpers

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