homebridge-govee

Homebridge plugin to integrate Govee devices into HomeKit

Plugin Information

• This plugin allows you to view and control your Govee devices within HomeKit. The plugin:
  • requires your Govee credentials for most device models and Cloud/BLE connections
  • can control certain models locally via LAN control without any Govee credentials
  • does not make use of the Govee API key

Prerequisites

• To use this plugin, you will need to already have:
  • Node: version v20, v22 or v24 - any other major version is not supported.
  • Homebridge: v1.8 or above - refer to link for more information and installation instructions.
  • For bluetooth connectivity, it may be necessary to install extra packages on your system. Bluetooth works best when using a Raspberry Pi.

Installation

Search for "Govee" in the Homebridge UI plugins tab, or install via npm:

npm install -g @mp-consulting/homebridge-govee

Configuration

Configure the plugin using the Homebridge UI or by editing your config.json:

{
  "platforms": [
    {
      "platform": "Govee",
      "name": "Govee",
      "username": "[email protected]",
      "password": "your-govee-password"
    }
  ]
}

Configuration Options

| Option | Required | Description | |--------|----------|-------------| | platform | Yes | Must be "Govee" | | name | Yes | Display name for the platform | | username | Yes | Your Govee account email | | password | Yes | Your Govee account password | | refreshTime | No | Interval in seconds to refresh device states (default: 15) | | controlInterval | No | Minimum interval in milliseconds between commands (default: 500) | | disableAWS | No | Disable AWS IoT connection (default: false) | | disableLAN | No | Disable LAN control (default: false) | | disableBLE | No | Disable Bluetooth control (default: false) |

Features

Connection Methods

• AWS IoT: Real-time control via Govee cloud (requires credentials)
• LAN: Local network control (faster, no internet required for supported devices)
• BLE: Bluetooth control for nearby devices

Supported Device Types

• Lights: LED strips, bulbs, and other lighting devices
• Switches: Smart plugs and outlets
• Sensors: Temperature, humidity, leak detectors, presence sensors
• Appliances: Heaters, humidifiers, purifiers, fans, and more
• Other: Kettles, ice makers, and various smart home devices

Architecture

The plugin uses a modular architecture:

• Device Catalog (src/catalog/): Centralized device definitions, command codes, and capabilities
• Device Handlers (src/device/): Individual handlers for each device type extending a common base class
• Connections (src/connection/): AWS IoT, LAN, and BLE connection managers

Help/Support

• Support Request
• Changelog

Credits

• Based on the original homebridge-govee plugin
• To the creators/contributors of Homebridge who make this plugin possible

Disclaimer

• This plugin is a personal project maintained independently.
• Use this plugin entirely at your own risk - please see licence for more information.