https://github.com/thingspanel/device-connector-sdk-go
Go SDK for ThingsPanel DeviceConnector plugins
https://github.com/thingspanel/device-connector-sdk-go
Last synced: 20 days ago
JSON representation
Go SDK for ThingsPanel DeviceConnector plugins
- Host: GitHub
- URL: https://github.com/thingspanel/device-connector-sdk-go
- Owner: ThingsPanel
- Created: 2026-05-26T22:03:51.000Z (27 days ago)
- Default Branch: main
- Last Pushed: 2026-05-26T22:07:37.000Z (27 days ago)
- Last Synced: 2026-05-27T00:08:16.117Z (27 days ago)
- Language: Go
- Size: 11.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ThingsPanel Device Connector SDK (Go)
Minimal Go SDK for building ThingsPanel device connectors. It handles HTTP
routing, heartbeat, and graceful shutdown so connector authors focus only on
device capability mapping.
## What the SDK does for you
- Registers all ThingsPanel HTTP callback routes (`/api/v1/form/config`,
`/api/v1/device/add`, `/api/v1/device/disconnect`, etc.)
- Exposes `/health` for K8S readiness and liveness probes
- Sends `POST /api/v1/plugin/heartbeat` on a configurable interval
- Reads runtime identity from environment variables (injected by K8S runner)
- Handles graceful shutdown on SIGTERM
## What you write
1. **`device-connector.yaml`** — identity and runtime spec (image, port, MQTT prefix)
2. **`handler.go`** — implement `sdk.Handler` with your device's capability mapping
See connector repositories such as `thingspanel-device-connector-snmp`, `thingspanel-device-connector-homeassistant`, and `thingspanel-device-connector-xiaomi` for end-to-end examples.
## Handler interface
```go
type Handler interface {
FormConfig(ctx context.Context) (FormConfig, error)
OnDeviceAdd(ctx context.Context, req DeviceAddRequest) error
OnDeviceDelete(ctx context.Context, req DeviceDeleteRequest) error
OnCommand(ctx context.Context, req CommandRequest) (CommandResponse, error)
OnConfigUpdate(ctx context.Context, req ConfigUpdateRequest) error
OnDisconnect(ctx context.Context, req DisconnectRequest) error
OnEvent(ctx context.Context, ev EventNotification) error
}
```
## Environment variables
| Variable | Required | Default | Description |
|---|---|---|---|
| `CONNECTOR_SERVICE_IDENTIFIER` | yes | — | Must match `device_connectors.connector_key` |
| `CONNECTOR_INSTANCE_ID` | yes | — | `ConnectorInstance.ID` from control plane |
| `CONNECTOR_LISTEN_ADDR` | no | `:9001` | HTTP bind address |
| `THINGSPANEL_BACKEND_URL` | yes* | — | Backend base URL for heartbeat |
| `CONNECTOR_HEARTBEAT_INTERVAL` | no | `30s` | How often to POST heartbeat |
*Heartbeat is disabled (with a warning) if `THINGSPANEL_BACKEND_URL` is empty.
## Local development
```bash
CONNECTOR_SERVICE_IDENTIFIER=my-connector \
CONNECTOR_INSTANCE_ID=local-dev \
THINGSPANEL_BACKEND_URL=http://localhost:9999 \
go run .
```
Then verify:
```bash
curl http://localhost:9001/health
curl http://localhost:9001/api/v1/form/config
```