Govee Homebridge Plugin
Govee HomeBridge - Govee Making Your Life Smarter
Govee Making Your Life Smarter

Thanks Ben, I’ll Take It From Here

Move over Phillips’s Hue, Govee coming through! Govee integrates with Alexa, Google Home, and HomeKit thanks to Ben’s Homebridge Plugin. Unfortunately, Ben’s Govee HomeKitplugin leaves much to be desired when it comes to the depth of features and support for Govee devices’ more complex capabilities such as light scenes, DIY effects, and Apple Home UI controls. Introducing the Ultimate Govee Homebridge Plugin aimed to accomplish all of the features of the Govee Home app within the Apple Home platform.

Forget Govee’s Developer Program

Govee offers a fairly limited developer program. Through the Govee Home app, you can request an API key that gives you access to a truncated list of devices, their states, and a subset of control over the device. Full control over Govee devices is obtained via reverse engineering their AWS IoT and Bluetooth LE operation codes.

Govee offers a wide selection of devices that include Bulbs, Light Strips, Lamps, Car Lights, Sensors, and Home Appliances; all devices support Bluetooth LE, many support AWS IoT via WiFi connections. Device states and commands are represented by sets of 20 hexadecimal operation codes that start with a packet identifier and end with an XOR checksum.

Packet Identifiers

There are 5 distinct packet identifiers:

  • Command: 0x33
  • Report: 0xaa
  • Query: 0x81
  • DIY: 0xa1
  • Sequence/effect:
    • Write: 0xa3
    • Report: 0xa5

Command and Report

The second operation code in the set is the attribute which can vary depending on the device in question, but with some universal attributes:

  • Power/Active: 0x01
    • Value
      • True: 0x01
      • False: 0x00
  • Physical Controls: 0x0a
    • Value
      • Locked: 0x01
      • Unlocked: 0x00
  • Timer: 0x0b
    • Enabled
      • True: 0x01
      • False: 0x00
    • Duration (minutes)
      • Minimum: 0x0000
      • Maximum: 0xffff
  • Primary State: 0x05

Query

The command to query the device is:

  • 0x81
  • 0x8a
  • 0x8b

The resulting query response has the following structure:

  • Unknown
  • Unknown
  • Powered On: 0x23
  • Mode (See Below)
  • Unknown
  • Speed: 0x00 – 0x64
  • Red: 0x00 – 0xff
  • Green: 0x00 – 0xff
  • Green: 0x00 – 0xff
  • Warm White: 0x00 – 0xff
  • Firmware Version: 0x00 – 0xff
  • Cool White: 0x00 – 0xff
Query – Mode
  • 0x25: 7 Color Cross Fade
  • 0x26: Red Change
  • 0x27: Green Change
  • 0x28: Blue Change
  • 0x29: Yellow Change
  • 0x2a: Cyan Change
  • 0x2b: Purple Change
  • 0x2c: White Change
  • 0x2d: Red/Green Cross Fade
  • 0x2f: Green/Blue Cross Fade
  • 0x30: 7 Color Strobe
  • 0x31: Red Strobe
  • 0x32: Green Strobe
  • 0x33: Blue Strobe
  • 0x34: Yellow Strobe
  • 0x35: Cyan Strobe
  • 0x36: Purple Strobe
  • 0x37: White Strobe
  • 0x38: 7 Color Jumping
  • 0x60: Custom Mode
  • 0x61: Color Mode
  • 0x62: Special Mode

DIY RGBIC Effects

Many Govee devices support creating your own effects. Each DIY effect is an array of 20 operation codes, the first two:

  • Identifier: 0xa1
  • Write: 0x02
DIY – Start
  • Start Packet: 0x00
  • Number of Packets: 0x01 – 0xfe
DIY – Packet

Each DIY effect can support up to 8 color codes in 2 packets:

  • DIY Identifier:
    • Packer #1: 0x01 – 0xfe
    • Packet N: 0x00
  • Style and Mode:
    • Fade: 0x00
      • Whole: 0x00
      • Circulate: 0x02
    • Jumping: 0x01
      • Whole: 0x00
      • Segment: 0x01
      • Circulate: 0x02
    • Flicker: 0x02
      • Whole: 0x00
      • Segment: 0x01
      • Circulate: 0x02
    • Marquee: 0x03
      • Straight: 0x03
      • Gathered: 0x01
      • Dispersive: 0x02
    • Music: 0x04
      • Spectrum: 0x06
      • Rolling: 0x07
      • Rhythm: 0x08
    • Combo: 0xff
      • Empty: 0x00
  • Speed: 0x00 – 0x64 (0% – 100%)
  • Colors: Repeated up to 8 times, codes are continued on the following packet as needed
    • Red: 0x00 – 0xff
    • Green: 0x00 – 0xff
    • Blue: 0x00 – 0xff
  • Number of Colors: 0x01 – 0x08

Additional effects start a new packet and follow the same pattern above, omitting the DIY identifier.

Sequence Effects

Sequence effects come in sets of 20 operation codes with the following structure:

  • Packet Indicator: 0xa3
  • Report/Write:
    • Read: 0x00
    • Write: 0x01
  • Packet Number: 0x01 – 0xfe
  • State: 0x05
  • Mode: 0x03
  • Effect:
    • Cycle: 0x02
    • Clockwise: 0x09
    • Counterclockwise: 0x0a
    • Twinkle: 0x0f
    • Gradient: 0x13
    • Breathe: 0x14
  • Speed: 0x00 – 0x64 (0% – 100%)
  • Brightness: 0x00 -0x64 (0% – 100%)
  • Segments (Repeat 23 times)
    • Segment Length: 0x00 – 0x3c (0 – 50)
    • Red: 0x00 – 0xff
    • Green: 0x00 -0xff
    • Blue: 0x00 – 0xff
    • 0x00

Primary States

Humidifiers

  • State: 0x05
  • Humidifier Mode:
    • Current Mode:
      • 0x00
      • Simple: 0x01
      • Program: 0x02
      • Error: 0x04
        • Water Empty: 0x02
    • Simple Mode:
      • 0x01
      • Mist Level: 0x01 – 0x08
    • Programs:
      • Active Program:
        • Program 1: 0x00
        • Program 2: 0x11
        • Program 3: 0x22
      • Program 1:
        • Mist Level: 0x01 – 0x08
        • Program Duration (minutes): 0x00 0x00 – 0xff 0xff (0 – 65535)
        • Remaining Duration (minutes): 0x00 0x00 – 0xff 0xff (0 – 65535)
      • Program 2:
        • Mist Level: 0x01 – 0x08
        • Program Duration (minutes): 0x00 0x00 – 0xff 0xff (0 – 65535)
        • Remaining Duration (minutes): 0x00 0x00 – 0xff 0xff (0 – 65535)
      • Program 3 (Continuous):
        • Mist Level: 0x01 – 0x08
        • Program Duration: 0xff 0xff
        • Remaining Duration: 0xff 0xff

Air Purifier

  • State: 0x05
  • Speed:
    • Night: 0x10
    • Low: 0x01
    • Medium: 0x02
    • High: 0x03

RGB Lights (Including Car Lights and Lamps)

  • State: 0x05
    • Mode:
      • Music: 0x01
        • Mode:
          • Energetic: 0x00
          • Spectrum: 0x01
          • Rolling: 0x02
          • Rhythm: 0x03
        • Red: 0x00 – 0xff
        • Green: 0x00 – 0xff
        • Blue: 0x00 – 0xff
      • Manual: 0x02
        • Red: 0x00 – 0xff (0xff for Color Temperature)
        • Green: 0x00 – 0xff (0xff for Color Temperature)
        • Blue: 0x00 – 0xff (0xff for Color Temperature
        • Color Temperature:
          • On: 0x01
          • Off: 0x00
            • Red: 0x00 – 0xff
            • Green: 0x00 – 0xff
            • Blue: 0x00 – 0xff
      • Scene: 0x04
        • Scene Identifier: 0x01 – 0xff

RGBIC Lights (Including Car Lights, Lamps and Flow Lights)

  • State: 0x05
    • Mode:
      • Music: 0x0c
        • Mode:
          • Energetic: 0x00
          • Spectrum: 0x01
          • Rolling: 0x02
          • Rhythm: 0x03
        • Red: 0x00 – 0xff
        • Green: 0x00 – 0xff
        • Blue: 0x00 – 0xff
        • Sensitivity: 0x00 – 0x64 (0% – 100%)
        • Unknown
        • Color:
          • Automatic: 0x00
          • Specified: 0x01
            • Red: 0x00 – 0xff
            • Green: 0x00 – 0xff
            • Blue: 0x00 – 0xff
      • Scene: 0x04
        • Scene Identifier: 0x01 – 0x0ff
      • Write Segments: 0x0b
        • Brightness::
          • 0x02
          • Brightness: 0x00 – 0x64
        • Color:
          • 0x01
          • Red: 0x00 – 0xff
          • Green: 0x00 – 0xff
          • Blue: 0x00 – 0xff
          • Color Temperature – 0x0000 – 0xffff (Limited to specific set of values)
        • First 8 Segments: 0x00 – 0xff (binary representation of segments with this color)
        • Next 7 Segments: 0x00 – 0xff (binary representation of segments with this color)
      • Read Segments: 0x15 (Repeated 5 times)
        • Packet Number: 0x01 – 0x05
        • Segment: (Repeated 3 times per packet
          • Brightness: 0x00 – 0x64
          • Red: 0x00 – 0xff
          • Green: 0x00 – 0xff
          • Blue: 0x00 – 0xff
  • Gradient: 0xa3
    • Enable:
      • True: 0x01
      • False: 0x02

TV Lights

  • State: 0x05
  • Mode:
    • Video: 0x00
      • Segment:
        • Partial: 0x00
        • Whole: 0x01
      • Mode:
        • Movie: 0x00
        • Game: 0x01
      • Saturation: 0x00 – 0x64 (0% – 100%)
    • Music: 0x0c
      • Mode:
        • Energetic: 0x00
        • Spectrum: 0x01
        • Rolling: 0x02
        • Rhythm: 0x03
      • Sensitivity: 0x00 – 0x64 (0% – 100%)
      • Unknown
      • Color:
        • Automatic: 0x00
        • Specified: 0x01
          • Red: 0x00 – 0xff
          • Green: 0x00 – 0xff
          • Blue: 0x00 – 0xff
    • Segment: 0b (Multiple packets for multple color segements)
      • Red: 0x00 – 0xff
      • Green: 0x00 – 0xff
      • Blue: 0x00 – 0xff
      • Color Temperature – 0x0000 – 0xffff (Limited to specific set of values)
      • First 8 Segments: 0x00 – 0xff (binary representation of segments with this color)
      • Next 7 Segments: 0x00 – 0xff (binary representation of segments with this color)
  • Gradient: 0xa3
    • Enable:
      • True: 0x01
      • False: 0x02

Other Device Attributes

  • Display: 0x10
    • Enable:
      • True: 0x01
      • False: 0x00
    • Start Hour: 0x00 – 0x17 (0 – 23)
    • Start Minute: 0x00 – 0x3b (0 – 59)
    • End Hour: 0x00 – 0x17 (0 – 23)
    • End Minute: 0x00 – 0x3b (0 – 59)
  • Nightlight: 0x12
    • Enable:
      • True: 0x01
      • False: 0x00
    • Brightness: 0x00 – 0x64 (0% – 100%)

Designing the Govee Homebridge Plugin

The biggest hurdle is the massive number of devices Govee has on the market. Obtaining a full list of devices available involved unpacking the latest Govee Home Android application, which just so happens to contain such a list!

As with most APIs, your application needs to authenticate with their servers. You’ll need your Govee Home application credentials and a 32 character client identifier. Successful authentication responds with the following payload:

{
   "message":"Login successful",
   "status":200,
   "client":{
      "A":"testiot.cert",
      "B":"testIot",
      "topic":"{AWS IOT MQTT Account Topic}",
      "token":"{JWT Bearer Token}",
      "refreshToken":"{JWT Refresu Token}",
      "tokenExpireCycle":57600,
      "client":"{ClientId}",
      "clientName":"",
      "clientType":"0",
      "accountId":{AccountId},
      "pushToken":"",
      "versionCode":"",
      "versionName":"",
      "sysVersion":"",
      "isSavvyUser":false
   }
}

The JWT tokens have iat (Issued At Timestamp) and exp (Expires On Timestamp). These tokens expire approximately 2 months after their issue date; remember to store these tokens as the API limits the number of logins in a 24 hour period to 30 requests, after which you cannot authenticate with their servers for a full 24 hours.

The necessary information for connecting to Govee’s AWS IoT MQTT broker is also provided. Using the AWS IoT Device SDK library pass your clientId, CA Certificate, Client Certificate, Client Key, and aqm3wd1qlc3dy-ats.iot.us-east-1.amazonaws.com as the MQTT broker’s host address. You only need to subscribe to the topic provided in the authentication response, all device states are published here.

Valid bearer token in hand, it’s time to ask the Govee servers for a list of your devices. Each device in the response provides all the information to interact with said device:

{
    "devices": [
        {
            "device": "{DeviceId}",
            "sku": "{Device Model}",
            "deviceExt": {
                "deviceSettings": {
                    "topic": "{Device MQTT Topic}", # MQTT Topic to publish commands to (Device Supports AWS IoT)
                    "address": "{Device BLE Address}", # BLE peripheral address (Device Supports BLE)
                    ...
                }, # This field is actually a JSON string you will need to deserialize
                ...
            },
            ...
        },
        ...
    ],
}

AWS IoT MQTT Schemas

Request Device Status

Publishing this message to any device’s topic will trigger a response to the account topic:

{
    "msg": {
        "cmd": "status",
        "cmdVersion": 2,
        "type": 0,
        "transaction": "u_{now().timestamp()}"
    }
}
{
   "proType":2,
   "sku":"{Device Model}",
   "device":"{DeviceId}",
   "softVersion":"2.02.09",
   "cmd":"status",
   "type":0,
   "transaction":"y_1644625844857502",
   "pactType":2,
   "pactCode":1,
   "state":{
      "onOff":1,
      "brightness":100,
      "colorTemInKelvin":0,
      "color":{
         "r":0,
         "g":242,
         "b":242
      },
      "mode":21,
      "result":1,
      "connected":"true"
   },
   "op":{
      "command":[
         "qgUVAAAAAAAAAAAAAAAAAAAAALo=",
         "qqUBZADy8mQAf/9kAPLyAAAAAOo=",
         "qqUCZAB//2QA8vJkAH//AAAAAGk=",
         "qqUDZADy8mQAf/9kAPLyAAAAAOg=",
         "qqUEZAB//2QA8vJkAH//AAAAAG8=",
         "qqUFZADy8mQAf/9kAPLyAAAAAO4=",
         "qhEAHg8PAAAAAAAAAAAAAAAAAKU=",
         "qhL/ZAAAgAoAAAAAAAAAAAAAAKk=",
         "qiP/AAAAgAAAAIAAAACAAAAAgHY="
      ]
   }
}

Device attributes are present either under state or op.command – perform a base64 decode on each op.command and using the operation codes above to determine the attributes and values after parsing the result as an array of hexadecimal values.

Bluetooth LE

First, connect to the device using the address field from the device list response. Discover the service with UUID = 000102030405060708090a0b0c0d1910, and the characteristics:

  • 000102030405060708090a0b0c0d2b11 (Control Characteristic)
  • 000102030405060708090a0b0c0d2b10 (Report Characteristic)

Using either the query command above or any attribute with a packet identifier 0x33 to the Control Characteristic to trigger a data event with the reported state on the Report Characteristic.

Due to the BLE specification limitation, only one peripheral can be connected at a time so device states will have to polled individually on an interval.

Get the Govee Homebridge Plugin

I am continuing to add support for more devices, so make to update your plugin on the regular!

Related articles