homebridge-bg-smart-local
v0.2.0
Published
Homebridge plugin for BG Electrical / Luceco BG Smart devices (local LAN). Tested with HC-02 dual sockets. Not for BH Home.
Maintainers
Readme
Homebridge BG Smart Local
Local LAN control for BG Electrical / Luceco products that work with the official BG Smart app, for use with Homebridge.
This plugin talks to devices over your LAN using Espressif ESP Local Control (the protocol BG Smart products expose locally). It is not for BH Home products — those use a different protocol and are not supported.
So far the plugin has been tested with the HC-02 dual smart socket (BG 822/HC-02). Other BG Smart SKUs may work later but are untested.
Set up in BG Smart first
- Add and commission each device in the BG Smart app (Wi‑Fi pairing, naming, etc.) before expecting Homebridge to control it.
- Do not remove devices from the BG Smart app to use this plugin.
- Both work at the same time — HomeKit/Homebridge and the BG Smart app can control the same sockets together. Physical buttons and app toggles are reflected in HomeKit via polling.
Features
- Auto-discovery of compatible sockets on the LAN via mDNS (
_esp_local_ctrl._tcp) - Each HC-02 wall plate appears as one HomeKit accessory with two Outlets (Left / Right)
- Stable accessory identity from Device ID (PoP) — DHCP IP changes do not create duplicates
- Optional ignore list and manual overrides (name, fixed IP, outlet labels)
- Full coexistence with the official BG Smart app (no unlink / reset required)
- Config UI settings screen (
config.schema.json) - Optional CLI for discovery and protocol debugging (
bg-smart)
Supported devices
| Device | Status | |--------|--------| | BG Smart HC-02 dual socket (822/HC-02, ESP32-C2, port 8080) | Tested | | Other BG Smart / Luceco products for the BG Smart app | Untested | | BH Home products | Not supported (different protocol) |
Requirements
- Devices already added and online in the BG Smart app
- Homebridge
^1.8.0or^2.0.0 - Node.js 20, 22, or 24 (LTS 22 / 24 recommended)
- Homebridge and the sockets on the same LAN (check VLANs / firewalls)
Installation
Homebridge UI (recommended)
- Ensure your sockets are set up and working in the BG Smart app
- Open the Homebridge UI → Plugins
- Search for
homebridge-bg-smart-local - Install, then open Settings for BG Smart Local
- Leave Auto-Discover enabled (default) and restart Homebridge when prompted
- Discovered sockets should appear automatically (keep them in the BG Smart app)
- Optionally set Ignore Device IDs or Manual Devices / Overrides
npm / hb-service
sudo npm install -g homebridge-bg-smart-localThen add the platform via the Homebridge UI, or add a platform block to config.json (see below) and restart Homebridge.
Configuration
Most users only need the platform with auto-discovery enabled. Use the plugin Settings screen in the Homebridge UI whenever possible.
Minimal (auto-discover)
{
"platforms": [
{
"platform": "BGSmartLocal",
"name": "BG Smart Local"
}
]
}Full example
{
"platforms": [
{
"platform": "BGSmartLocal",
"name": "BG Smart Local",
"autoDiscover": true,
"ignore": ["DEVICE_ID_TO_SKIP"],
"pollInterval": 5,
"timeout": 10000,
"debug": false,
"devices": [
{
"name": "Garden Socket",
"host": "192.168.1.159",
"pop": "YOUR_DEVICE_ID",
"port": 8080,
"outlets": {
"left": { "name": "Left Socket" },
"right": { "name": "Right Socket" }
}
}
]
}
]
}| Field | Default | Description |
|-------|---------|-------------|
| autoDiscover | true | Browse the LAN and add ESP Local Control sockets automatically |
| ignore | [] | Device IDs (PoPs) to never add; removes them from HomeKit if already cached |
| devices | [] | Optional manual entries or overrides (same PoP merges — manual name / host / outlets win) |
| pollInterval | 5 | Seconds between state polls (2–60) for physical button / app changes |
| timeout | 10000 | HTTP timeout in milliseconds |
| debug | false | Verbose protocol logging (PoP and session keys are never logged in full) |
Device fields (devices[])
| Field | Required | Description |
|-------|----------|-------------|
| name | yes | Accessory name in Apple Home |
| host | yes | LAN IP or hostname (DHCP reservation recommended) |
| pop | yes | Proof of Possession / Device ID |
| port | no | ESP Local Control HTTP port (default 8080) |
| outlets.left.name / outlets.right.name | no | Outlet service names |
Finding a Device ID (PoP)
On tested HC-02 firmware the PoP is the same as:
- the Device ID in the BG Smart app (device → settings → Device information), and
- the mDNS
node_id/ hostname (<DeviceID>.local)
List what the LAN advertises:
npx bg-smart discoverDevices that use Sec1 with a PoP that is not the advertised node_id still need a manual devices[] entry.
Apple Home behaviour
- One accessory per dual socket; Left and Right outlets switch independently
- Accessory UUID is derived from Device ID / PoP, not IP address
- Physical button presses and BG app toggles are reflected via polling (default every 5s)
Networking & coexistence
- BG Smart app first — commission devices there; leave them in the app
- Simultaneous use — Homebridge and BG Smart control the same device without conflict; you do not need to remove the device from the app
- Control uses HTTP on port 8080 (not HTTPS on tested HC-02 firmware)
- Prefer a DHCP reservation if you also set a manual
host - Day-to-day Homebridge control is LAN-only; the plugin does not call BG cloud APIs
- BH Home gear will not work with this plugin
Troubleshooting
| Symptom | What to check |
|---------|----------------|
| Nothing discovered | Device added in BG Smart app and on Wi‑Fi; same LAN/VLAN; mDNS not blocked; try npx bg-smart discover |
| BH Home device missing / failing | Wrong product line — this plugin is BG Smart only |
| Connection refused / timeout | IP, port 8080, device powered, firewall |
| Wrong PoP | Device ID must match; use discover or BG Smart → device → Device information |
| Stale state | Lower pollInterval; check Wi‑Fi reliability |
| Duplicate accessory | One config entry per PoP; remove stale accessories in Homebridge |
| Unwanted device | Add its Device ID to ignore |
| IP changed | Auto-discovery refreshes host; or set DHCP reservation / manual host |
Enable debug in Settings for protocol diagnostics.
CLI (optional)
npx bg-smart discover
npx bg-smart inspect -- --host HOST --pop POP
npx bg-smart get -- --host HOST --pop POP --property params --path "Left Socket.Power"
npx bg-smart set -- --host HOST --pop POP --property params --path "Left Socket.Power" --value true
npx bg-smart probe -- --host HOST --pop POPDevelopment
npm install
npm run build
npm test
npm run lintSee docs/DEVELOPMENT.md for linking into a local Homebridge instance. Protocol references: docs/REFERENCES.md. Espressif .proto files are Apache-2.0 (proto/NOTICE).
Homebridge platform / accessories
↓
Hc02DoubleSocket (reconnect + poll)
↓
EspLocalCtrlClient (ESP Local Control)Contributing / support
- Issues: GitHub Issues
- Please include Homebridge / plugin versions, Node version, and relevant logs (with Device IDs masked if you prefer)
License
MIT © davetaz
