homebridge-schlecht-govee

A Homebridge plugin that reads all-day events from a CalDAV calendar (iCloud Family Calendar, Google Calendar, Nextcloud, etc.) and automatically applies a matching color/scene pattern to your Govee outdoor permanent lights (H7050, H7055, and other LAN-API-enabled models) via the local network at noon each day.

The lights are not turned on — the pattern is loaded so that a later HomeKit automation (e.g. "turn on at sunset") activates them with the correct color scheme already set.

Features

• 📅 Calendar-driven patterns — all-day events drive the color choice (e.g. a "Christmas" event applies your Christmas lights pattern).
• 🌐 LAN-only control — communicates directly with Govee devices over UDP; no cloud account required for light control.
• 🖥️ Interactive Config UI — the Homebridge Config UI X settings page includes two built-in tools: Discover Govee Shortcuts (look up all available shortcut codes for any device model) and Test Calendar Connection (verify CalDAV credentials without restarting Homebridge).
• 🔍 Built-in shortcut discovery — fetch every available built-in shortcut name and ready-to-copy sceneCode for your device model directly in the config UI, with no log-scraping required.
• 🔌 LAN auto-discovery — leave goveeDevices empty and the plugin will find devices on your network automatically.
• 🏡 HomeKit switches — each device is exposed as a switch accessory, usable in automations and scenes.
• 🕛 Timezone-aware noon scheduling — optionally specify an IANA timezone so patterns are applied at your local noon regardless of where Homebridge runs.

Requirements

| Requirement | Notes | |-------------|-------| | Node.js ≥ 20 | | | Homebridge ≥ 1.8 or ≥ 2.0-beta | | | Govee device with LAN Control enabled | Enable in the Govee app: Device → Settings → LAN Control | | Device and Homebridge on the same subnet | UDP multicast must be able to cross from your server to the lights | | CalDAV-accessible calendar | iCloud, Google Calendar, Nextcloud, Fastmail, … |

Installation

npm install -g homebridge-schlecht-govee

Or via the Homebridge UI — search for homebridge-schlecht-govee.

Configuration

Add a platform block to your Homebridge config.json:

{
  "platforms": [
    {
      "platform": "SchlechtGovee",
      "name": "Schlecht Govee",

      "calendar": {
        "url": "https://caldav.icloud.com",
        "username": "[email protected]",
        "password": "<app-specific-password>",
        "calendarName": "Family"
      },

      "goveeDevices": [
        {
          "name": "Front Yard Lights",
          "ip": "192.168.1.100",
          "deviceId": "AA:BB:CC:DD:EE:FF:00:01",
          "model": "H7050"
        }
      ],

      "colorPatterns": [
        {
          "name": "Christmas",
          "sceneCode": "MwUEzycAAAAAAAAAAAAAAAAAANo="
        },
        {
          "name": "Halloween",
          "sceneCode": "<base64-scene-packet>"
        }
      ],

      "timezone": "America/Chicago",
      "listScenesOnStartup": false
    }
  ]
}

Configuration options

| Option | Type | Required | Description | |--------|------|----------|-------------| | platform | string | ✅ | Must be "SchlechtGovee" | | name | string | ✅ | Display name | | calendar.url | string | ✅ | CalDAV server base URL (see table below) | | calendar.username | string | ✅ | CalDAV username (usually your email) | | calendar.password | string | ✅ | CalDAV password / app-specific password | | calendar.calendarName | string | ✅ | Display name of the calendar to read | | goveeDevices | array | — | Static device list. Leave empty to auto-discover | | goveeDevices[].name | string | ✅ | HomeKit display name | | goveeDevices[].ip | string | ✅ | Device local IP address | | goveeDevices[].deviceId | string | ✅ | Device ID (MAC-address format from the Govee app) | | goveeDevices[].model | string | ✅ | Model number, e.g. "H7050" | | colorPatterns | array | — | Named pattern → scene-code mappings | | colorPatterns[].name | string | ✅ | Matched (case-insensitively) against event titles | | colorPatterns[].sceneCode | string | ✅ | Base64-encoded 20-byte scene packet | | timezone | string | — | IANA timezone for noon scheduling (default: system tz) | | listScenesOnStartup | boolean | — | Log all available scene codes on startup (default: false) |

CalDAV server URLs

| Provider | URL | |----------|-----| | iCloud | https://caldav.icloud.com | | Google Calendar | https://apidata.googleusercontent.com/caldav/v2/ | | Nextcloud | https://yourserver/remote.php/dav | | Fastmail | https://caldav.fastmail.com/dav/ |

iCloud tip: Use an app-specific password generated at appleid.apple.com — do not use your regular Apple ID password.

Config UI (Homebridge Config UI X)

When you edit the plugin settings in Homebridge Config UI X, two interactive tools are displayed above the standard configuration form:

🔍 Discover Govee Shortcuts

Fetches every available built-in shortcut for a given device model directly from the Govee API and lists each one by name alongside a Copy button.

1. In Homebridge Config UI X, open the plugin settings for homebridge-schlecht-govee.
2. In the Discover Govee Shortcuts card, enter your device model (e.g. H7050). If you have already saved a device in the config, the model field is pre-filled.
3. Click Discover Shortcuts.
4. The tool displays every available shortcut name and its base64 scene code.
5. Click Copy next to the shortcut you want, then paste the value into a Color Patterns → Scene Code field in the configuration form.

This completely replaces the old listScenesOnStartup log-scraping workflow. You only need listScenesOnStartup: true if you prefer to see the codes in the Homebridge log.

🔗 Test Calendar Connection

Verifies your CalDAV credentials and lists all available calendars on the server, without restarting Homebridge.

1. Fill in the Calendar Settings fields (URL, Username, Password) in the form.
2. Click Test Connection.
3. The tool shows either ✅ with the list of calendar names found, or ❌ with the specific error message, so you can fix credentials before saving.

Running as a Child Bridge

Homebridge v1.3.0 and later lets any platform plugin run in its own isolated child process (a child bridge). Running this plugin as a child bridge gives you:

• Crash isolation — if the plugin throws a fatal error it won't bring down the main bridge or any other plugin.
• Performance isolation — the main bridge's response time is no longer slowed by this plugin's CalDAV or UDP requests.
• Independent restart — you can restart just this plugin without touching the rest of Homebridge.

Option A — via the Homebridge Config UI X (recommended)

1. Open Homebridge Config UI X.
2. Go to the Plugins tab and find homebridge-schlecht-govee.
3. Click the three-dot menu (⋮) → Bridge Settings (or Set Up Child Bridge).
4. Toggle child-bridge mode on and save.
5. Restart Homebridge.
6. Pair the new child bridge in the Home app:
   1. Open Home → tap + → Add Accessory.
   2. Select I Don't Have a Code or Cannot Scan.
   3. Choose the new plugin bridge from the list.
   4. Enter the PIN (default: same as your main bridge PIN).

Option B — manual config.json edit

Add a _bridge object to your platform block. The username and port must be unique — different from the main bridge and any other child bridge you have.

{
  "platforms": [
    {
      "platform": "SchlechtGovee",
      "name": "Schlecht Govee",

      "_bridge": {
        "username": "0E:83:FD:29:58:C9",
        "port": 55197
      },

      "calendar": {
        "url": "https://caldav.icloud.com",
        "username": "[email protected]",
        "password": "<app-specific-password>",
        "calendarName": "Family"
      },

      "goveeDevices": [
        {
          "name": "Front Yard Lights",
          "ip": "192.168.1.100",
          "deviceId": "AA:BB:CC:DD:EE:FF:00:01",
          "model": "H7050"
        }
      ],

      "colorPatterns": [
        { "name": "Christmas", "sceneCode": "MwUEzycAAAAAAAAAAAAAAAAAANo=" }
      ],

      "timezone": "America/Chicago"
    }
  ]
}

After restarting Homebridge, pair the child bridge in the Home app as described in Option A step 6.

Optional _bridge fields

| Field | Default | Notes | |-------|---------|-------| | username | — | Required. Unique MAC-style address | | port | dynamically assigned by Homebridge | Recommended to set explicitly to avoid surprises after restarts | | pin | same as main bridge | Override the HomeKit pairing PIN | | name | platform name | Label shown in the Home app |

How it works

Homebridge starts
  └─► Register Govee devices as HomeKit switches
  └─► (Optional) Log available scenes for each device model
  └─► Start noon scheduler

Every day at noon
  └─► Fetch today's all-day calendar events
  └─► Find first event whose title contains a configured pattern name
  └─► Send ptReal LAN command to each Govee device with the scene packet
  └─► (A later HomeKit automation turns the lights on at, e.g., sunset)

Pattern matching is case-insensitive substring: a calendar event titled "Christmas Lights 2024" will match a pattern named "Christmas".

Obtaining scene codes (sceneCode)

The sceneCode is a base64-encoded 20-byte scene packet sent to the device via the Govee LAN ptReal UDP command.

Option A — Discover Shortcuts tool in the Config UI (recommended)

1. Open the plugin settings in Homebridge Config UI X.
2. In the Discover Govee Shortcuts card, enter your device model and click Discover Shortcuts.
3. Find the shortcut you want in the list and click Copy next to it.
4. Paste the copied value into a Color Patterns → Scene Code field in the configuration form below.

Option B — Built-in scene listing at startup

1. Set "listScenesOnStartup": true in the config and restart Homebridge.
2. The plugin will fetch and log every built-in shortcut for each configured device model, including the ready-to-use sceneCode value:

   [SchlechtGovee] --- Available scenes for H7050 (42 total) ---
   [SchlechtGovee]   name: "Rainbow B"  code: 10191  scenePacket: "MwUEzycAAAAAAAAAAAAAAAAAANo="
   [SchlechtGovee]   name: "Sunrise"    code: 2099   scenePacket: "MwUEExMAAAAAAAAAAAAAAAAAHg=="
   ...

3. Copy the scenePacket value into colorPatterns[].sceneCode.
4. Set "listScenesOnStartup": false again.

Option C — Govee API directly

curl "https://app2.govee.com/appsku/v1/light-effect-libraries?sku=H7050" \
  -H "AppVersion: 5.6.01" | \
  jq '[.data.categories[] | {name:.sceneName, code:.lightEffects[0].sceneCode}]'

This returns [ { "name": "Rainbow B", "code": 10191 }, ... ].
The plugin's GoveeSceneService.buildScenePacket(code) can convert a numeric code to the base64 packet — see the development section below.

Option D — Govee One Touch Shortcuts

1. Open the Govee app → Home tab → + to add a Tap to Run shortcut.
2. Give it a name (e.g. "Christmas Scene"), add the target device → Mode.
3. Select the desired scene effect and save.
4. The homebridge-govee plugin (a separate plugin) will log the shortcut's [BLE] code on startup — that value is identical to the sceneCode here.

Option E — Wireshark capture

1. Enable LAN Control on the device (Govee app → device settings).
2. Open Wireshark, filter: udp.port == 4003.
3. Activate a scene in the Govee app while capturing.
4. Find the ptReal UDP packet; the command[0] field is the sceneCode.

Scene packet structure (for reference)

Byte  0 : 0x33  (fixed)
Byte  1 : 0x05  (fixed)
Byte  2 : 0x04  (scene type – 0x04 for pre-defined library scenes)
Bytes 3–4: scene code as little-endian uint16 (low byte first)
Bytes 5–18: zero padding
Byte 19 : XOR checksum of bytes 0–18

Example — Rainbow B (code 10191 = 0x27CF):

33 05 04 CF 27 00 00 00 00 00 00 00 00 00 00 00 00 00 00 DA
→ base64: MwUEzycAAAAAAAAAAAAAAAAAANo=

HomeKit automation example

After the noon scheduler has pre-loaded the scene you can trigger the lights with a standard HomeKit automation:

1. Condition: Today is Christmas (or leave this to the calendar approach).
2. Trigger: Sunset.
3. Action: Turn on Front Yard Lights (the switch registered by this plugin).

Because the color pattern was already applied at noon, the lights come on in the correct scene.

Enabling Govee LAN Control

1. Open the Govee Home app on your phone.
2. Tap the device you want to control.
3. Tap the ⚙️ settings icon (top right).
4. Toggle LAN Control on.
5. Assign a static IP (or a static DHCP lease) to avoid the IP changing.

LAN Control is not available on every Govee model. Supported models include H7050, H7055, and others — see the Govee LAN API guide for the full list.

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests (Jest)
npm test

# Run linter (ESLint)
npm run lint

# Watch mode (incremental TypeScript compilation)
npm run watch

Using GoveeSceneService directly

import { GoveeSceneService } from 'homebridge-schlecht-govee/dist/govee/goveeSceneService';

const svc = new GoveeSceneService(console as any);

// Build a packet from a numeric code
const base64 = svc.buildScenePacket(10191);
// → "MwUEzycAAAAAAAAAAAAAAAAAANo="

// Fetch and log all scenes for a model
await svc.logAvailableScenes('H7050');

Troubleshooting

| Symptom | Likely cause | Fix | |---------|-------------|-----| | Lights don't respond | LAN Control not enabled | Toggle it in the Govee app | | Calendar "X" not found in logs | Wrong calendar name | Set listScenesOnStartup and check logged names | | Discovery finds no devices | Multicast blocked by router/VLAN | Add device IPs statically in goveeDevices | | Pattern doesn't apply at noon | No matching calendar event | Check event title contains the pattern name | | Wrong timezone fires at wrong time | System tz differs from desired | Set timezone in config |

License

Apache-2.0