[Device] Aqara TVOC air quality monitor (VOCKQJK11LM)

[kwolniak]

Device description
Zigbee Model: lumi.airmonitor.acn01
Zigbee Manufacturer: LUMI
Description: Aqara TVOC air quality monitor
Manufacturer: Xiaomi
Model: VOCKQJK11LM

Supported in Zigbee2MQTT?
Yes it is already in master branch, by this PR: Koenkk/zigbee-herdsman-converters#2815

Device model / Exposes information

    "definition": {
      "description": "Aqara TVOC air quality monitor",
      "exposes": [
        {
          "access": 1,
          "description": "Remaining battery in %",
          "name": "battery",
          "property": "battery",
          "type": "numeric",
          "unit": "%",
          "value_max": 100,
          "value_min": 0
        },
        {
          "access": 1,
          "description": "Measured temperature value",
          "name": "temperature",
          "property": "temperature",
          "type": "numeric",
          "unit": "°C"
        },
        {
          "access": 1,
          "description": "Measured relative humidity",
          "name": "humidity",
          "property": "humidity",
          "type": "numeric",
          "unit": "%"
        },
        {
          "access": 1,
          "description": "Measured VOC value",
          "name": "voc",
          "property": "voc",
          "type": "numeric",
          "unit": "ppb"
        },
        {
          "access": 1,
          "description": "Link quality (signal strength)",
          "name": "linkquality",
          "property": "linkquality",
          "type": "numeric",
          "unit": "lqi",
          "value_max": 255,
          "value_min": 0
        }
      ],
      "model": "VOCKQJK11LM",
      "supports_ota": false,
      "vendor": "Xiaomi"
    },

Missing features/functionality
Only one thing is missing in Homekit, the VOC.

Suggested services and characteristics
I'm not sure here, but when conected this device via aquara hub it is exposed to HomeKIt like TVOC Sensor in climate section:

[itavero]

HomeKit does seem to define a VOC Density characteristic as part of the Air Quality Sensor service.
Unfortunately this services also has a required Air Quality characteristic, for which the value does not seem to be provided by the device.
The question would be what the logic should be to determine the Air Quality.

I'm assuming they are using these characteristics (and service), but you might be able to verify that with an adjusted version of the HMCatalog app.

[kwolniak]

I found this scale for VOC Density (ppb), see TVOC bar.

So i think we can assume:
333 and less = Characteristic.AirQuality.EXCELLENT (1)
334 to 1000 = Characteristic.AirQuality.GOOD (2)
1001 to 3333 = Characteristic.AirQuality.FAIR (3)
3334 to 8332 = Characteristic.AirQuality.INFERIOR (4)
8333 and more = Characteristic.AirQuality.POOR (5)

(source: https://support.getawair.com/hc/en-us/articles/360039242373-Air-Quality-Factors-Measured-By-Awair-Element)

For example now I have in my room 109 ppb and it is shown on device screen as 5 star = excellent.
Unfortunately I do not have aquara hub, the previous screenshot it's just from the internet so I can not use HMCatalog app to to dump the communication.

Is this scale enough to expose this Air Quality and VOC Density to HomeKit?

[itavero]

Ideally we'd also have to combine other measurements from the sensor (in this case the relative humidity).
I'll see if I can come up with some logic for it.

[itavero]

I started working on the implementation and decided to keep the sensors separate.
Unfortunately I'm running into an issue that I have yet to pinpoint. I'll let you know when I've made some more progress.

[itavero]

FYI: Initially I added this to the Basic Sensor handler, but ran into several issues. To make it a bit more comprehensive, I decided to make a separate file that handles the Air Quality sensors. I've just finished that implementation (I hope), but I have yet to write the automated tests for it (which is where I got stuck previously 😅).

I'll let you know once it is released or available for testing somewhere.

[itavero]

Just released v1.5.0 which should add support for this sensor (and a few others).

Let me know if it works for you! 😉

[kwolniak]

It Works! Thanks a lot.

[satter]

I've noticed following warnings in logs and started to dig into VOC support in z2m/homebridge/homekit

[1/21/2023, 8:04:57 PM] [homebridge-z2m] This plugin generated a warning from the characteristic 'VOC Density': characteristic was supplied illegal value: number 1126 exceeded maximum of 1000. See https://homebridge.io/w/JtMGR for more info.
[1/21/2023, 8:05:27 PM] [homebridge-z2m] This plugin generated a warning from the characteristic 'VOC Density': characteristic was supplied illegal value: number 1095 exceeded maximum of 1000. See https://homebridge.io/w/JtMGR for more info.

What I've found:

• z2m reports VOC value as ppb
• homebridge-z2m seems to be using this value for calculating air quality string (and is reporting this value to homekit, apple home app displays same number as z2m web interface)
• homekit is expecting voc value as micrograms per cubic meter
• here are an examples 1,2 of converting ppb to mg/m3

@itavero

1. Is it possible to change homebridge default upper limit of VOC characteristic?
2. Is it possible to add VOC units conversion before reporting raw value to homekit?

Here is a discussion of the same issue and commit with changes for similar homebridge plugin