IKEA Starkvind Air Purifier

[ebaauw]

Update for IKEA Starkvind Air Purifier, see #5351 and #6118.

• Add fingerprint;
• Change type to ZHAAirPurifier so clients can distinguish between air quality sensors and air purifiers;
• Expose attribute 0x0004, which reports PM2.5 in µg/m³, as state.pm2_5 (instead of state.airqualityppb);
• Change thresholds for state.airquality as they're very different for PM2.5 vs TVOC;
• Base state.airquality directly on 0x0004 as I cannot get the numtostr on state.pm2_5 to work.
• Expose attribute 0x0000 as state.filterruntime;
• Expose attribute 0x0001 as state.replacefilter;
• Expose attribute 0x0002 as config.filterlifetime;
• Expose attribute 0x0003 as config.ledindication;
• Expose attribute 0x0005 as config.locked;
• Expose attribute 0x0008 as state.deviceruntime;
• Setup reporting for all attributes, change reporting to 1/300/1 for all attributes. Mains-powered device, so no battery considerations.

Resource now looks like:

{
  "config": {
    "filterlifetime": 256728,
    "ledindication": true,
    "locked": false,
    "mode": "auto",
    "on": true,
    "reachable": true
  },
  "ep": 1,
  "etag": "c4b3b77e0fc9b62f7f6b85031de61d98",
  "lastannounced": null,
  "lastseen": "2022-06-11T15:40Z",
  "manufacturername": "IKEA of Sweden",
  "modelid": "STARKVIND Air purifier",
  "name": "Starkvind",
  "state": {
    "airquality": "excellent",
    "deviceruntime": 185310,
    "filterruntime": 182857,
    "lastupdated": "2022-06-11T15:39:46.328",
    "pm2_5": 6,
    "replacefilter": false,
    "speed": 20
  },
  "swversion": "1.0.033",
  "type": "ZHAAirPurifier",
  "uniqueid": "cc:86:ec:ff:fe:6d:30:11-01-fc7d"
}

Note that deviceruntime, filterruntime, and filterlifetime are in minutes. To indicate that you've replaced the filter, update filterlifetime. The default life time (as set by the IKEA app is 259200 (6 months, or: 6 * 30 * 24 * 60).

[SwoopX]

The default value could be removed, as it comes already with the resource item. I'd recommend to add the read function as well, otherwise the state changes has probably no chance to succeed. If you've configured reporting for this attribute, it's also advisable to add "refresh.interval" with a duration time of max reporting interval + 60 (to allow some polling fallback)

[ebaauw]

The item defaults to false, where the Starkvind defaults to true.

[SwoopX]

Just a couple of minors from my end. Still strange that the previously used function to set airquality doesn't work for you. Maybe Manup has any idea around it.

[manup]

Base state.airquality directly on 0x0004 as I cannot get the numtostr on state.pm2_5 to work.

Just a couple of minors from my end. Still strange that the previously used function to set airquality doesn't work for you. Maybe Manup has any idea around it.

If I remember correctly currently there might be a certain order required for the items, so the source item like state/airqualityppb or state/pm2_5 needs to be in the JSON array before state/airquality. (This should be fixed in future so the order shouldn't matter).

Anyhow otherwise the PR looks solid to me, I haven't followed the full discussion are the REST-API visible changes ok for everyone? If yes we I'd like to merge it for v2.17.1 :)

[Thomas-Vos]

Is there any reason air quality state is not named e.g. airqualitypm2_5 to keep it consistent with airqualityppb naming?

[Thomas-Vos]

Another question: can we expect pm2_5 to appear on ZHAAirQuality sensors and airqualityppb on ZHAAirPurifier sensors in the future? For example if support for new devices is added that use different measurements than the current devices.

[ebaauw]

I don’t like airqualityppb, as it doesn’t indicate of what pollutant the level is being measured (in case of the Xioami: TVOC). Ideally, we would name the attributes tvoc_level and pm2_5_density, leaving room for tvoc_density and pm2_5_level. I haven’t seen them, but I can imagine CO sensors reporting the raw CO level or density, in addition to the binary CO detected. Same for natural gas sensors or other pollutants.

Air quality is derived from a pollutant level or density (with different thresholds for different pollutants). I don’t see any value in prefixing the pollutant attributes with airquality.

Ideally, I would have exposed the sensor function of the Starkvind as ZHAAirQuality resource, separately from the ZHAAirPurifier resource for the purifier function. However, this would lead to a uniqueid conflict, as the Starkvind combines both functions in the same manufacturer-specific Zigbee cluster. I would only expect a tvoc_level or airqualityppb on a ZHAAirPurifier for a device that also uses one cluster for both functions. I would expect pm2_5_density or pm2_5 on ZHAAirQuality, possibly even combined with tvoc_level or airqualityppb depending on what the device measures and how (in how many clusters) it reports these quantities.

Note: We will have to solve the uniqueid issue once we’ll introduce ZHARelativeRotary for the new Hue dial tap, breaking the “resource per cluster” (assumed) principle. The Hue API simply adds the button number (mac-01-fc00-14).

[Kane610]

Is this the new way with deconz to expose one device with all data? As this is similar to the other fan device which is a light as well as a fan, this is an air purifier with fan, these types of functionality becomes similar but different rather than being kept aligned between device types and on a separate e.g. fan endpoint

[ebaauw]

No, it’s the old way to expose a resource per cluster, as reflected in the uniqueid.

I fear this might not be sustainable, and @manup even thinks this is not desireable, but that’s really an APIv2 discussion, beyond the scope of the PR.

[manup]

From my perspective it's clean to separate into two sub resources as @ebaauw mentioned, for the endpoint and cluster id parts in the uniqueid we can just pick some other value, as long as we stick to xxxxxxxxxxxxxxxx-aa-bbbb format I don't expect problems in clients. Internally the DDF processing for one sub resource items already supports processing arbitrary endpoints and clusters.

[ebaauw]

for the endpoint and cluster id parts in the uniqueid we can just pick some other value, as long as we stick to xxxxxxxxxxxxxxxx-aa-bbbb format

Happy to change the DDF to expose two /sensors resources (ZHAAirPurifier and ZHAAirQuality) - this would actually make it easier on Homebridge deCONZ. Any takers for the "cluster" value in the uniqueid? I don't suppose Zigbee has an Air Quality Measurement cluster? Maybe abuse IAS Zone (cf some of the CO sensors), or maybe it's less confusing to just fake another endpoint?

As this is similar to the other fan device which is a light as well as a fan

I think that was the Hampton Bay fan module (#932), or are you referring to another device? I do think a fan is a different device than an air purifier, although both might carry (something resembling) fan speed.
The Hampton Bay does have a separate cluster 0x0202 for fan control, but /lights resources don't include the cluster in uniqueid, see #932 (comment). Back then, we preferred to use /lights resources for actuators; today we would prefer /sensors resources. Not sure if the Fan Level is included in the Scenes state, but if it is, that's also an argument to combine the functions in one /lights resource. I don't think we have a good solution yet in APIv2 for dealing with groups and scenes over multiple sub resources.

[Kane610]

Would you mind sharing an updated json output of the different endpoints?

[ebaauw]

Damn, I had, but appeantly forgot to press Comment. Anyways, new attempt:

{
  "config": {
    "filterlifetime": 256728,
    "ledindication": true,
    "locked": false,
    "mode": "auto",
    "on": true,
    "reachable": true
  },
  "ep": 1,
  "etag": "fea6623ea3909029409fed7a6224e60b",
  "lastannounced": null,
  "lastseen": "2022-06-30T18:19Z",
  "manufacturername": "IKEA of Sweden",
  "modelid": "STARKVIND Air purifier",
  "name": "Starkvind",
  "state": {
    "deviceruntime": 212939,
    "filterruntime": 210486,
    "lastupdated": "2022-06-30T18:19:46.177",
    "replacefilter": false,
    "speed": 20
  },
  "swversion": "1.0.033",
  "type": "ZHAAirPurifier",
  "uniqueid": "cc:86:ec:ff:fe:6d:30:11-01-fc7d"
}

{
  "config": {
    "on": true,
    "reachable": true
  },
  "ep": 1,
  "etag": "74eb5d8558a3895a39a3884189701c99",
  "lastannounced": null,
  "lastseen": "2022-06-30T18:20Z",
  "manufacturername": "IKEA of Sweden",
  "modelid": "STARKVIND Air purifier",
  "name": "Starkvind",
  "state": {
    "airquality": "excellent",
    "lastupdated": "2022-06-30T18:18:26.205",
    "pm2_5": 8
  },
  "swversion": "1.0.033",
  "type": "ZHAAirQuality",
  "uniqueid": "cc:86:ec:ff:fe:6d:30:11-02-fc7d"
}

[Kane610]

Thank you very much!

Can all values in config be reconfigured?

  "config": {
    "filterlifetime": 256728,
    "ledindication": true,
    "locked": false,
    "mode": "auto",
    "on": true,
    "reachable": true
  },

[ebaauw]

Yes. They're pretty much mapped 1:1 to the Zigbee attributes, see #5351 (comment).

[kimosak]

Running on v2.18.1-beta and still not able to control Starkvind Air Purifier. Only sensor (airquality) is reporting the state.
No option to change mode or speed? Can I do something?

[hph304]

I have the exact same problem as @kimosak

[fsedarkalex]

Same here.

[Mimiix]

Not sure what you mean..is this about phoscon? If so, report on the forums as we don't maintain phoscon in this GitHub.

Rest api should be able to control the values you ask for.

[oywino]

Rest api should be able to control the values you ask for.
As far as I could determine, the IKEA STARKVIND Air Purifier only accepts PUT commands to change values. But according to the HA DOC's, the REST-API only supports GET and POST
https://www.home-assistant.io/integrations/sensor.rest/