python

BetterDesk CDAP Python SDK

Build CDAP device bridges in Python for IoT sensors, industrial equipment, and automation systems.

Installation

pip install betterdesk-cdap
# or from source
pip install -e sdks/python/

Quick Start

importasynciofrombetterdesk_cdapimportCDAPBridge, gauge, toggle, button# Create bridgebridge=CDAPBridge(
server="ws://203.0.113.10:21122/cdap",
auth_method="api_key",
api_key="your-api-key",
device_name="Temperature Sensor",
device_type="iot",
tags=["factory-floor", "zone-a"],
)
# Define widgetstemp=bridge.add_widget(gauge("temp", "Temperature", unit="°C", max_val=50, warning_high=40))
humidity=bridge.add_widget(gauge("humidity", "Humidity", unit="%", max_val=100))
heater=bridge.add_widget(toggle("heater", "Heater", group="Controls"))
reboot=bridge.add_widget(button("reboot", "Reboot Device", confirm=True, icon="restart_alt"))
# Handle commands@bridge.on_command("heater")asyncdefhandle_heater(action, value, **kw):
ifaction=="set":
set_heater(value) # your hardware controlreturn {"new_state": value}
@bridge.on_command("reboot")asyncdefhandle_reboot(action, **kw):
ifaction=="trigger":
os.system("reboot")
return"rebooting"# Run (blocks forever with auto-reconnect)bridge.run()

Async Usage

asyncdefmain():
bridge=CDAPBridge(server="ws://host:21122/cdap", api_key="key")
bridge.add_widget(gauge("temp", "Temperature", unit="°C", max_val=100))
@bridge.on_command("temp")asyncdefhandle(action, value, **kw):
return {"ok": True}
# Start bridge in backgroundtask=asyncio.create_task(bridge._run_forever())
# Push state updates from your sensor loopwhileTrue:
temp_value=read_sensor()
awaitbridge.update_state("temp", temp_value)
awaitasyncio.sleep(5)
asyncio.run(main())

API Reference

CDAPBridge

Method	Description
add_widget(widget)	Register a widget for the manifest
on_command(widget_id)	Decorator to handle commands
update_state(widget_id, value)	Push widget state update
bulk_update(updates)	Push multiple state updates
fire_alert(alert_id, severity, message)	Fire an alert
resolve_alert(alert_id)	Resolve an alert
send_log(level, message)	Send a log entry
run()	Blocking main loop
stop()	Signal shutdown

Widget Helpers

Helper	Type	Key Options
gauge(id, label)	Gauge	unit, min_val, max_val, warning_high
toggle(id, label)	Toggle	value
button(id, label)	Button	icon, confirm, cooldown
text_widget(id, label)	Text	readonly, value
led(id, label)	LED	value
slider(id, label)	Slider	min_val, max_val, step
select(id, label)	Select	options
chart(id, label)	Chart	chart_type, points, series
table(id, label)	Table	columns, max_rows, sortable

Requirements

• Python 3.9+
• websockets >= 12.0