npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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.

Readme

Homebridge BG Smart Local

npm npm Build

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

  1. Add and commission each device in the BG Smart app (Wi‑Fi pairing, naming, etc.) before expecting Homebridge to control it.
  2. Do not remove devices from the BG Smart app to use this plugin.
  3. 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.0 or ^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)

  1. Ensure your sockets are set up and working in the BG Smart app
  2. Open the Homebridge UI → Plugins
  3. Search for homebridge-bg-smart-local
  4. Install, then open Settings for BG Smart Local
  5. Leave Auto-Discover enabled (default) and restart Homebridge when prompted
  6. Discovered sockets should appear automatically (keep them in the BG Smart app)
  7. Optionally set Ignore Device IDs or Manual Devices / Overrides

npm / hb-service

sudo npm install -g homebridge-bg-smart-local

Then 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 discover

Devices 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 POP

Development

npm install
npm run build
npm test
npm run lint

See 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