ioBroker.govee-smart

Control Govee smart lights via three seamless channels: LAN (fastest, primary), AWS IoT MQTT (real-time status push), and Cloud API v2 (scenes, segments, capabilities).

Features

• LAN First — UDP multicast discovery and control for lowest latency
• Real-Time Status — AWS IoT MQTT push updates (no polling)
• Scene Control — Dropdown select with all available scenes from Cloud API
• Segment Control — Per-segment color and brightness for LED strips
• Seamless Channel Routing — Automatically uses the fastest available channel (LAN > MQTT > Cloud)
• Graceful Degradation — Works LAN-only without any credentials; each credential level unlocks more features
• Rate Limited — Respects Govee API limits (10/min, 10,000/day) with priority queue

Requirements

• Node.js >= 20
• ioBroker js-controller >= 7.0.0
• ioBroker Admin >= 7.6.20
• Govee lights with LAN API support — Supported devices list

Ports

| Port | Protocol | Direction | Purpose | Configurable | |------|----------|-----------|---------|--------------| | 4001 | UDP | Outbound (multicast 239.255.255.250) | LAN device discovery | No — fixed by Govee LAN protocol | | 4002 | UDP | Inbound | LAN device responses | No — fixed by Govee LAN protocol | | 4003 | UDP | Outbound | LAN device commands | No — fixed by Govee LAN protocol |

Configuration

Credential Levels

The adapter works with different levels of configuration. Each level unlocks additional features:

| Level | Credentials | Features | |-------|-------------|----------| | LAN Only | None | Power, brightness, color, color temperature via LAN | | + Cloud API | API Key | Device names, capabilities, scenes, segments, cloud fallback | | + MQTT | Email + Password | Real-time status push, MQTT control fallback |

Getting a Govee API Key

1. Open the Govee Home app
2. Go to Profile > Settings > About Us > Apply for API Key
3. Enter your reason and submit — the key arrives via email

Settings

| Option | Description | Default | |--------|-------------|---------| | Network Interface | IP address of the network interface for LAN discovery (leave empty for all interfaces) | All | | API Key | Govee Cloud API key (optional) | — | | Email | Govee account email (optional) | — | | Password | Govee account password (optional) | — | | Poll Interval | Cloud device list refresh interval | 60s |

State Tree

Device folders use a stable sku_shortId naming (e.g., h61be_1d6f). The human-readable Cloud device name is stored in common.name and info.name. Groups (BaseGroup) are separated into a groups/ folder.

govee-smart.0.
├── info/
│   ├── connection              — Overall connection status (boolean)
│   ├── mqttConnected           — MQTT connection status (boolean)
│   └── cloudConnected          — Cloud API connection status (boolean)
├── devices/
│   └── h61be_1d6f/             — Stable SKU + short device ID
│       ├── info/
│       │   ├── name            — Cloud device name (string)
│       │   ├── model           — Product SKU (string)
│       │   ├── serial          — Device ID (string)
│       │   ├── online          — Device reachable (boolean)
│       │   └── ip              — LAN IP address (string, auto-updated)
│       ├── control/
│       │   ├── power           — On/Off (boolean, writable)
│       │   ├── brightness      — Brightness 0-100% (number, writable)
│       │   ├── colorRgb        — Color as "#RRGGBB" (string, writable)
│       │   ├── colorTemperature — Color temperature in Kelvin (number, writable)
│       │   ├── light_scene     — Light scene (string, dropdown, writable)
│       │   └── snapshot        — Saved snapshot (string, dropdown, writable)
│       └── segments/
│           ├── count           — Number of segments (number)
│           ├── command         — Batch control "1-5:#ff0000:20" (string, writable)
│           └── {0..n}/
│               ├── color       — Segment color "#RRGGBB" (string, writable)
│               └── brightness  — Segment brightness 0-100% (number, writable)
└── groups/
    └── basegroup_1280/         — Govee device groups
        ├── info/ ...
        └── control/ ...

Batch Segment Control

LED strips with multiple segments can be controlled in bulk via the segments.command state. This sends a single string command instead of setting each segment individually.

Format

segments:color:brightness

| Part | Description | Required | |------|-------------|----------| | segments | Which segments to target | Yes | | color | Hex color (#RRGGBB or RRGGBB) | No (omit with ::) | | brightness | Brightness 0–100% | No |

At least color or brightness must be provided.

Segment Selection

| Syntax | Meaning | Example | |--------|---------|---------| | all | All segments | all:#ff0000:50 | | 3 | Single segment | 3:#00ff00 | | 1-5 | Range (inclusive) | 1-5:#0000ff:80 | | 0,3,7 | Specific segments | 0,3,7:#ffffff | | 0,3-5,10 | Mixed | 0,3-5,10:#ff00ff:60 |

Segment indices start at 0. Values beyond the device's segment count are automatically clamped.

Examples

| Command | Effect | |---------|--------| | all:#ff0000:50 | All segments red at 50% brightness | | 1-5:#00ff00 | Segments 1–5 green (brightness unchanged) | | 0,3,7:#0000ff:80 | Segments 0, 3 and 7 blue at 80% | | all::30 | All segments brightness to 30% (color unchanged) | | 2-4:ff8800 | Segments 2–4 orange (# prefix optional) |

Notes

• Requires a Cloud API key (segments are controlled via Cloud API)
• Each command sends at most 2 API calls (one for color, one for brightness) regardless of how many segments are selected
• Individual segment states (segments.0.color, segments.0.brightness, etc.) are automatically updated after a batch command

Troubleshooting

No devices discovered

• Ensure your Govee lights are connected to the same network as ioBroker
• Check that UDP multicast (239.255.255.250) is not blocked by your router/firewall
• Only devices with LAN API support are discovered — Supported devices list
• Verify your lights have the latest firmware via the Govee Home app

Scenes/segments not available

• An API Key is required for scene and segment control
• Scenes are loaded from the Cloud API — check the API key is valid

Status updates are delayed

• Without MQTT credentials, status is only updated via LAN responses and cloud polling
• Add your Govee email and password for real-time MQTT status push

MQTT connection fails

• MQTT uses the same credentials as the Govee Home app
• If you use social login (Google/Apple), create a password in the Govee app first
• Check adapter logs for authentication errors

Changelog

0.8.1 (2026-04-06)

• Fix ready message showing disconnected channels as active
• Fix network interface default selection in admin UI

0.8.0 (2026-04-06)

• Network interface selection for LAN discovery (multi-NIC/VLAN support)

0.7.0 (2026-04-06)

• Add IP address to device info (info.ip), auto-updated on LAN discovery
• Batch segment control documentation (format, examples, notes)

0.6.4 (2026-04-06)

• Fix misleading "check email/password" for non-credential Govee login errors
• MQTT login errors classified by actual Govee response (rate-limit, credential, account issue)

0.6.3 (2026-04-06)

• MQTT auth backoff (stop after 3 failures), error dedup, recovery logging
• Cloud connection recovery detection
• Improved error classification (OS-level error codes)

0.6.2 (2026-04-06)

• Comprehensive test suite: 78 → 175 tests (command routing, value conversions, segment parsing, capability matching)

0.6.1 (2026-04-06)

• Fix snapshots not appearing (integer values from capabilities were filtered out)
• DIY scene dropdown support prepared (API currently provides no data)
• Scene reset now also clears diy_scene and snapshot dropdowns

Older changelog: CHANGELOG.md

Support

• ioBroker Forum
• GitHub Issues

Support Development

This adapter is free and open source. If you find it useful, consider buying me a coffee:

License

MIT License

Copyright (c) 2026 krobi [email protected]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Developed with assistance from Claude.ai