mirror of
https://github.com/UNITRONIX/BetterDesk.git
synced 2026-09-10 17:45:42 +00:00
UNITRONIX
1118fc2ba6
Remove internal LAN IP, SSH user, and developer paths from docs and examples; move deploy runbook to gitignored docs/private with a public template; drop Cursor debug logging leftovers; add CI checks to prevent regression. Co-authored-by: Cursor <cursoragent@cursor.com>
109 lines
2.7 KiB
Markdown
109 lines
2.7 KiB
Markdown
# BetterDesk CDAP — Reference Bridges
|
|
|
|
This directory contains ready-to-use bridge implementations that connect
|
|
external systems to BetterDesk via the CDAP protocol. Each bridge uses
|
|
the **Python SDK** (`sdks/python/`) and can be deployed as a standalone
|
|
service alongside BetterDesk server.
|
|
|
|
## Available Bridges
|
|
|
|
| Bridge | Directory | Protocol | Use Case |
|
|
|--------|-----------|----------|----------|
|
|
| **Modbus** | `modbus/` | Modbus TCP / RTU | PLCs, VFDs, power meters, industrial I/O |
|
|
| **SNMP** | `snmp/` | SNMP v2c / v3 | Network switches, routers, UPS, printers |
|
|
| **REST Webhook** | `rest-webhook/` | HTTP REST | Home automation (HA, OpenHAB), cloud APIs |
|
|
|
|
## Architecture
|
|
|
|
```
|
|
External Device/API
|
|
│
|
|
▼
|
|
┌──────────────┐
|
|
│ Bridge │ ← polls/subscribes to external system
|
|
│ (Python) │ ← pushes state updates to CDAP
|
|
│ │ ← receives commands from CDAP → writes to external system
|
|
└──────┬───────┘
|
|
│ WebSocket (CDAP)
|
|
▼
|
|
┌──────────────┐
|
|
│ BetterDesk │
|
|
│ CDAP Gateway │
|
|
│ (:21122) │
|
|
└──────────────┘
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 1. Install Python SDK
|
|
cd sdks/python
|
|
pip install -e .
|
|
|
|
# 2. Install bridge dependencies
|
|
cd bridges/modbus
|
|
pip install -r requirements.txt
|
|
|
|
# 3. Copy and edit config
|
|
cp config.example.json config.json
|
|
# edit config.json with your server URL, API key, and device addresses
|
|
|
|
# 4. Run
|
|
python bridge_modbus.py --config config.json
|
|
```
|
|
|
|
## Creating a Custom Bridge
|
|
|
|
Use the Python SDK directly:
|
|
|
|
```python
|
|
from betterdesk_cdap import CDAPBridge, gauge, toggle
|
|
|
|
bridge = CDAPBridge(
|
|
server="ws://your-server:21122/cdap",
|
|
api_key="YOUR_KEY",
|
|
device_name="My Custom Bridge",
|
|
device_type="bridge",
|
|
)
|
|
|
|
bridge.add_widget(gauge("sensor1", "Temperature", unit="°C", max_val=50))
|
|
|
|
@bridge.on_command("relay1")
|
|
async def handle_relay(action, value, **kw):
|
|
# Write to your external system here
|
|
return value
|
|
|
|
bridge.run()
|
|
```
|
|
|
|
See the [Python SDK README](../sdks/python/README.md) and
|
|
[Node.js SDK README](../sdks/nodejs/README.md) for full API reference.
|
|
|
|
## Configuration
|
|
|
|
All bridges use a shared configuration pattern:
|
|
|
|
```json
|
|
{
|
|
"cdap": {
|
|
"server": "ws://203.0.113.10:21122/cdap",
|
|
"api_key": "YOUR_API_KEY",
|
|
"device_name": "Bridge Name",
|
|
"device_type": "bridge",
|
|
"heartbeat_sec": 15
|
|
},
|
|
"bridge_specific_options": { }
|
|
}
|
|
```
|
|
|
|
## Deployment
|
|
|
|
Each bridge can run as:
|
|
- **systemd service** (Linux) — see `install/` in each bridge directory
|
|
- **Docker container** — `docker run` with mounted `config.json`
|
|
- **Screen/tmux session** — for testing
|
|
|
|
## License
|
|
|
|
AGPL-3.0
|