Usage

govee-ble is a stateless parser for Govee Bluetooth Low Energy advertisement payloads. It does not scan for devices or open connections — feed it raw advertisement data and it returns a SensorUpdate describing what was decoded.

Scope

This library has a deliberately narrow scope: decode passive BLE advertisements from Govee sensor devices. That boundary defines what belongs here and what does not.

In scope

  • Parsing raw advertisement payloads (manufacturer data, service data, local name) into SensorUpdate readings.

  • Sensor and event devices: thermometers, hygrometers, BBQ/meat probes, motion/occupancy, door/window, vibration, presence, pressure pads, buttons, and CO₂/air-quality monitors. See Supported devices.

  • Stateless, pure per-packet decoding (beyond the small accumulator needed for multi-packet protocols such as the H5178 primary/remote pair). The parser never opens a connection.

Out of scope

  • Active GATT control — connecting to a device, writing characteristics, polling, or sending commands. This library only reads advertisements; it does not import bleak or hold connections.

  • Light / LED control — Govee BLE lights that require a GATT connection to switch on/off, set brightness, or change colour belong in led-ble, the org’s active-control library for Telink-style LED devices. For example, the iHoment/Govee H6196 light controller raised in issue #259 is out of scope here — it advertises a writable Telink service and needs an active connection, which is led-ble’s domain.

  • Smoothing, de-glitching, or filtering readings — these are stateful concerns that belong in the consumer (e.g. Home Assistant), not in a pure parser.

The split is intentional: govee-ble stays a connection-free parser so it can be used anywhere advertisement bytes are available, while anything that needs to talk back to a device lives in a connection-based package.

Quick start

from bluetooth_sensor_state_data import BluetoothServiceInfo
from govee_ble import GoveeBluetoothDeviceData

service_info = BluetoothServiceInfo(
    name="GVH5075_2762",
    address="A4:C1:38:00:00:00",
    rssi=-63,
    manufacturer_data={
        60552: b"\x00\x03A\xc2d\x00L\x00\x02\x15INTELLI_ROCKS_HW"
        b"Pu\xf2\xff\x0c"
    },
    service_uuids=["0000ec88-0000-1000-8000-00805f9b34fb"],
    service_data={},
    source="local",
)

device = GoveeBluetoothDeviceData()
update = device.update(service_info)

for description in update.entity_descriptions.values():
    value = update.entity_values[description.device_key]
    print(description.device_key.key, value.native_value)

device.update() accepts a BluetoothServiceInfo for every advertisement seen for a given MAC. Reuse the same GoveeBluetoothDeviceData instance per device — readings from multi-packet protocols (e.g. the H5178 primary/remote pair) are accumulated on the instance.

Inspecting a device

After at least one successful update(), the instance exposes:

Attribute

Description

device.device_type

Govee model id, e.g. "H5075". None until the first packet is decoded.

device.sensor_type

A SensorType enum: THERMOMETER, BUTTON, MOTION, WINDOW, VIBRATION, PRESENCE, or PRESSURE.

device.button_count

Number of buttons, for button-bearing models.

device.sleepy

True for battery-powered sleep-and-wake devices that only advertise on events.

get_model_info(model_id) returns the same metadata without needing an instance:

from govee_ble import get_model_info, SensorType

info = get_model_info("H5121")
assert info.sensor_type is SensorType.MOTION
assert info.sleepy is True

Supported devices

The parser decodes ~30 Govee BLE models across several categories:

  • Thermometers / hygrometers — H5051, H5052, H5055, H5071, H5072, H5074, H5075, H5100, H5101, H5102, H5103, H5104, H5105, H5106, H5108, H5174, H5177, H5179, GV5179

  • Multi-probe thermometers — H5110, H5112 (dual probe)

  • BBQ probes — H5181, H5182, H5183, H5184, H5185, H5191, H5198 (up to four probes per device with high/low alarm temperatures)

  • Thermometer + hygrometer with remote sensor — H5178 (primary + remote)

  • Temperature / humidity / CO₂ — H5140

  • Motion / occupancy — H5121, H5127

  • Door / window — H5123

  • Vibration — H5124

  • Buttons — H5122 (1 button), H5125 (6 buttons), H5126 (2 buttons)

  • Pressure pad — H5130

The encrypted H512x family (H5121–H5126, H5130) advertises a CRC-checked 24-byte payload; the parser drops packets that fail the CRC check.

Integration with Home Assistant

govee-ble is the parser library behind Home Assistant’s govee_ble integration. In Home Assistant, advertisement bytes arrive via the Bluetooth integration; you generally do not need to call govee-ble directly. For external scripts and other consumers, the API shown above is the full surface.