{"id":50500755,"url":"https://github.com/thingspanel/device-connector-sdk-go","last_synced_at":"2026-06-02T11:02:56.916Z","repository":{"id":360555268,"uuid":"1250691710","full_name":"ThingsPanel/device-connector-sdk-go","owner":"ThingsPanel","description":"Go SDK for ThingsPanel DeviceConnector plugins","archived":false,"fork":false,"pushed_at":"2026-05-26T22:07:37.000Z","size":12,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T00:08:16.117Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThingsPanel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T22:03:51.000Z","updated_at":"2026-05-26T22:07:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ThingsPanel/device-connector-sdk-go","commit_stats":null,"previous_names":["thingspanel/device-connector-sdk-go"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ThingsPanel/device-connector-sdk-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThingsPanel%2Fdevice-connector-sdk-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThingsPanel%2Fdevice-connector-sdk-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThingsPanel%2Fdevice-connector-sdk-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThingsPanel%2Fdevice-connector-sdk-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThingsPanel","download_url":"https://codeload.github.com/ThingsPanel/device-connector-sdk-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThingsPanel%2Fdevice-connector-sdk-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33818568,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-02T11:02:55.812Z","updated_at":"2026-06-02T11:02:56.910Z","avatar_url":"https://github.com/ThingsPanel.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ThingsPanel Device Connector SDK (Go)\n\nMinimal Go SDK for building ThingsPanel device connectors. It handles HTTP\nrouting, heartbeat, and graceful shutdown so connector authors focus only on\ndevice capability mapping.\n\n## What the SDK does for you\n\n- Registers all ThingsPanel HTTP callback routes (`/api/v1/form/config`,\n  `/api/v1/device/add`, `/api/v1/device/disconnect`, etc.)\n- Exposes `/health` for K8S readiness and liveness probes\n- Sends `POST /api/v1/plugin/heartbeat` on a configurable interval\n- Reads runtime identity from environment variables (injected by K8S runner)\n- Handles graceful shutdown on SIGTERM\n\n## What you write\n\n1. **`device-connector.yaml`** — identity and runtime spec (image, port, MQTT prefix)\n2. **`handler.go`** — implement `sdk.Handler` with your device's capability mapping\n\nSee connector repositories such as `thingspanel-device-connector-snmp`, `thingspanel-device-connector-homeassistant`, and `thingspanel-device-connector-xiaomi` for end-to-end examples.\n\n## Handler interface\n\n```go\ntype Handler interface {\n    FormConfig(ctx context.Context) (FormConfig, error)\n    OnDeviceAdd(ctx context.Context, req DeviceAddRequest) error\n    OnDeviceDelete(ctx context.Context, req DeviceDeleteRequest) error\n    OnCommand(ctx context.Context, req CommandRequest) (CommandResponse, error)\n    OnConfigUpdate(ctx context.Context, req ConfigUpdateRequest) error\n    OnDisconnect(ctx context.Context, req DisconnectRequest) error\n    OnEvent(ctx context.Context, ev EventNotification) error\n}\n```\n\n## Environment variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `CONNECTOR_SERVICE_IDENTIFIER` | yes | — | Must match `device_connectors.connector_key` |\n| `CONNECTOR_INSTANCE_ID` | yes | — | `ConnectorInstance.ID` from control plane |\n| `CONNECTOR_LISTEN_ADDR` | no | `:9001` | HTTP bind address |\n| `THINGSPANEL_BACKEND_URL` | yes* | — | Backend base URL for heartbeat |\n| `CONNECTOR_HEARTBEAT_INTERVAL` | no | `30s` | How often to POST heartbeat |\n\n*Heartbeat is disabled (with a warning) if `THINGSPANEL_BACKEND_URL` is empty.\n\n## Local development\n\n```bash\nCONNECTOR_SERVICE_IDENTIFIER=my-connector \\\nCONNECTOR_INSTANCE_ID=local-dev \\\nTHINGSPANEL_BACKEND_URL=http://localhost:9999 \\\ngo run .\n```\n\nThen verify:\n\n```bash\ncurl http://localhost:9001/health\ncurl http://localhost:9001/api/v1/form/config\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthingspanel%2Fdevice-connector-sdk-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthingspanel%2Fdevice-connector-sdk-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthingspanel%2Fdevice-connector-sdk-go/lists"}