Add Govee H5140 Smart CO2 Monitor

[bafulton]

Description:

Adds decoder support for the Govee H5140 Smart CO2 Monitor, which broadcasts temperature, humidity, and CO2 readings via BLE manufacturer data advertisements.

Device Information

Property	Value
Brand	Govee
Model	Smart CO2 Monitor
Model ID	H5140
Advertisement Name	GV5140XXXX
Sensors	Temperature, Humidity, CO2

Data Format

The H5140 broadcasts 10 bytes (20 hex characters) of manufacturer data:

Hex Position	Bytes	Description
0-7	0-3	Header (01000101)
8-13	4-6	24-bit combined temp/humidity
14-17	7-8	16-bit CO2 in ppm (big-endian)
18-19	9	Padding/unknown

Decoding Formulas

• Temperature (°C): 24bit_value / 10000
• Humidity (%): (24bit_value % 1000) / 10
• CO2 (ppm): 16bit_value (direct reading)

Example

Raw data: 0100010103fcbf044c00

• Header: 01000101
• Temp/Hum: 03fcbf = 261311 decimal
  • Temperature: 261311 / 10000 = 26.13°C
  • Humidity: (261311 % 1000) / 10 = 31.1%
• CO2: 044c = 1100 ppm

Testing

Tested with an H5140 device using OpenMQTTGateway on ESP32. Decoded values match the device's LCD display readings.

This device uses the same encoding scheme as other Govee temperature/humidity sensors (H5072, H5075, etc.) for the temp/humidity portion, with an additional CO2 field.

Checklist:

• The pull request is done against the latest development branch
• Only one feature/fix was added per PR and the code change compiles without warnings
• I accept the DCO.

[bafulton]

Live BLE Advertisement Samples

Here are some raw manufacturer data samples captured from a real H5140 device, along with the corresponding display readings for validation:

Manufacturer Data	Display Reading	Decoded Values
0100010103fcbf044c00	78.4°F, 31%, 1100 ppm	temp=26.13°C, hum=31.1%, co2=1100
0100010103fc56045600	78.8°F, 31%, 1110 ppm	temp=26.13°C, hum=31.0%, co2=1110
0100010103fc4e045400	78.8°F, 31%, 1108 ppm	temp=26.13°C, hum=31.0%, co2=1108
0100010103fc46045200	78.8°F, 31%, 1106 ppm	temp=26.13°C, hum=31.0%, co2=1106
0100010103fc3e045000	78.8°F, 31%, 1104 ppm	temp=26.13°C, hum=31.0%, co2=1104
0100010103fc36044f00	78.8°F, 31%, 1103 ppm	temp=26.12°C, hum=31.0%, co2=1103
0100010103fc2e044d00	78.8°F, 31%, 1101 ppm	temp=26.12°C, hum=31.0%, co2=1101

Decoding verification

Taking 0100010103fcbf044c00 as an example:

• Header: 01000101 ✓
• Temp/Hum bytes: 03fcbf = 261311 decimal
  • Temperature: 261311 / 10000 = 26.13°C (79.03°F) ✓
  • Humidity: (261311 % 1000) / 10 = 31.1% ✓
• CO2 bytes: 044c = 1100 decimal = 1100 ppm ✓

Data captured using OpenMQTTGateway on ESP32 with raw advertisement publishing enabled.

[bafulton]

Related Issues

This decoder addresses requests from the community for H5140 support:

• Home Assistant Feature Request: https://github.com/orgs/home-assistant/discussions/1410
• BLE Monitor Issue: [New Sensor]: Govee H5140 Smart CO₂ Monitor custom-components/ble_monitor#1509

The BLE Monitor issue contains additional reverse engineering notes and device information that informed this implementation.

[DigiH]

Many thanks @bafulton

Ould you change and add the following to this PR
• Change the "tag":"0301" to "tag":0f02" so that the type becomes "AIR" as all other air quality sensors, and also to indicate that the device needs active scanning due to its name being in the model condition.
• Change the property definition

      "co2":{
         "unit":"ppm",
         "name":"co2"
      }

to

      "co2":{
         "unit":"ppm",
         "name":"carbon_dioxide"
      }

to allow for correct Home Assistant MQTT discovery of the CO2 value.
• Add a documentation page for the H5140 Smart CO2 Monitor - along the lines of all the other Govee devices
• Add two or three test cases for automatic regression testing

If you are unsure about the last point I can add the test cases once you have addressed the first three points and this has been merged.

[bafulton]

@DigiH thanks for the quick and thorough review feedback! All good callouts. I've made the following changes:

1. Tag updated: Changed from 0301 to 0f02 for AIR sensor classification.
2. Property renamed: Changed "name":"co2" to "name":"carbon_dioxide" for HA MQTT discovery.
3. Documentation added: Created docs/devices/H5140.md.
4. Test cases: Added 3 regression test cases covering different temperature/humidity/CO2 values. I took a stab at these, but I'm not as confident I set everything up correctly. Double check me?

Ready for another review when you have time!

[bafulton]

Shoot, the test is failing. Hang on a sec. Good to go now. 👍

[bafulton]

Also, any idea when the next release will go out? I'm pretty excited to see some CO2 data in HA! 😁

[DigiH]

@bafulton

• Change the "tag":"0301" to "tag":0f02"

My bad, this should actually be "tag":0f03"`, as "cidc":false, should actually still remain ;) in the regression tests as well.

Also, any idea when the next release will go out? I'm pretty excited to see some CO2 data in HA! 😁

What are you actually using the decoder with, OpenMQTTGateway on an ESP32 or Theengs Gateway?

[DigiH]

@bafulton

I took the liberty to make that last correction so I can merge your PR. It will then also be included in the latest OpenMQTTGateway nightly development build, which you can install at

https://docs.openmqttgateway.com/dev/upload/web-install.html

[bafulton]

@DigiH awesome! I wondered re the cidc piece--I thought they should've been in there, but I couldn't get the tests to work with them in. Thanks for sorting it out for me!

What are you actually using the decoder with

I'm using OpenMQTTGateway on an ESP32. I bumped to develop and it all just worked. I've got sensor data now. 🥳