# Virtual device on 2.8.1
**URL:** https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844
**Category:** Free talk
**Created:** [December 8, 2025, 3:59pm UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844 "2025-12-08T15:59:15Z")
**Posts on this page:** 20
**Page:** 1
### Author:  [@john.e.dixon](https://forum.ewelink.cc/u/john.e.dixon)
#### Post date: [December 8, 2025, 3:59pm UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/1 "2025-12-08T15:59:15Z")
Now that iHost 2.8.1. is stable its good to see the new Matter bridged devices like Light Sensor, Smoke Alarm and Air Quality.
I’ve created an Air Quality virtual sensor to show pm2.5 with no problem but as there’s no API documentation on this I’m struggling to configure how to indicate Air Quality level on a device tile (here Smartthings) i.e. here shown as Unknown, but should be “Good”, “Fair” etc
I’ve tried the permission and Settings as variations on
> `{`
> `“capability”: “air-quality”,`
> `“permission”: “1100”,`
> `“settings”: {`
> `“supportedValues”: {`
> `“type”: “enum”,`
> `“permission”: “01”,`
> `“values”: [`
> `“0”,“1”,“2”,“3”,“4”,“5”,“6”`
> `]`
> `}`
> `}`
> `}`
but not working. Also tried values as Unknown", “Good”, “Fair”, “Moderate”, “Poor”, “VeryPoor”,
and “ExtremelyPoor” although that doesn’t seem logical
Perhaps @SuiKa could help here.
---
### Author:  [@jam3](https://forum.ewelink.cc/u/jam3)
#### Post date: [December 8, 2025, 4:05pm UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/2 "2025-12-08T16:05:12Z")
> [@john.e.dixon](#):
>
> I’m struggling to configure how to indicate
In iHost, go to Developer Tools → Device Logs. You will see the exact JSON events sent by your sensor. If you only see pm2.5: 12, that means the air-quality attribute is missing.
You need to add logic in the driver: for example, if pm2.5 ≤ 12, then publish “air-quality”: “2” (Good).
Try it, as it might help to get things back on track 😉
---
### Author:  [@john.e.dixon](https://forum.ewelink.cc/u/john.e.dixon)
#### Post date: [December 8, 2025, 4:57pm UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/3 "2025-12-08T16:57:13Z")
> [@jam3](#):
>
> for example, if pm2.5 ≤ 12, then publish “air-quality”: “2” (Good).
Agreed, that’s basically what I do via Node-red on this Homekit virtual device and it runs Ok,
but in the case of the Cube virtual devices they need configuration of permissions (attribute) with an enum range when creating the virtual device. Would seem logical as eg. in this case the tile might show “Good” rather than “Excellent” for that level.
---
### Author:  [@jam3](https://forum.ewelink.cc/u/jam3)
#### Post date: [December 8, 2025, 5:34pm UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/4 "2025-12-08T17:34:15Z")
> [@john.e.dixon](#):
>
> Perhaps @SuiKa could help here.
Indeed 🙂
---
### Author:  [@SuiKa](https://forum.ewelink.cc/u/SuiKa)
#### Post date: [December 9, 2025, 6:24am UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/5 "2025-12-09T06:24:50Z")
The appropriate capability for your requirement is **air-quality@enum**.
Here is its configuration:
```auto
{
"capability": "air-quality@enum",
"permission": "0100",
"settings": {
"range": {
"permission": "01",
"type": "enum",
"values": ["excellent", "moderate", "poor"]
}
}
}
```
And its **state** should be expressed as:
```auto
{
"air-quality@enum": {
"air-quality": "excellent" // String value indicating air quality; must be one of settings.range.values
}
}
```
---
### Author:  [@john.e.dixon](https://forum.ewelink.cc/u/john.e.dixon)
#### Post date: [December 9, 2025, 7:19am UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/6 "2025-12-09T07:19:44Z")
> [@SuiKa](#):
>
> `["excellent", "moderate", "poor"]`
Trying with this, and even small variation on these settings, choosing the first of the 2 capabilities Air Quality on the list , but getting debug error
```auto
payload error, check capability air-quality@enum info fail, msg:settings contains keys not allowed, support keys:[range]
```
---
### Author:  [@SuiKa](https://forum.ewelink.cc/u/SuiKa)
#### Post date: [December 9, 2025, 7:48am UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/7 "2025-12-09T07:48:33Z")
Could you paste your complete data payload?
The error message suggests there’s an issue with the data structure.
---
### Author:  [@john.e.dixon](https://forum.ewelink.cc/u/john.e.dixon)
#### Post date: [December 9, 2025, 11:16am UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/8 "2025-12-09T11:16:42Z")
Hi @SuiKa
This is the register node for the Air Quality sensor - the pm2.5 functions correctly.
> **Node**
>
> [
> {
> “id”: “1324f0f17032a0f5”,
> “type”: “register-device”,
> “z”: “819e12b16623dc86”,
> “name”: “AQI”,
> “server”: “7645b9a88fbe034c”,
> “device\_id”: “88692c0a-d0dd-11f0-8de9-0242ac120002”,
> “device\_name”: “AQI”,
> “category”: “sensor”,
> “capabilities”: “null”,
> “manufacturer”: “John”,
> “model”: “NRAQ”,
> “firmware\_version”: “v1”,
> “service\_address”: “192.168.0.85”,
> “tags”: “{}”,
> “state”: “{“pm25”:{“pm25”:25},“air-quality@enum”:{“air-quality”:“excellent”}}”,
> “capabilities\_v2”: “[{“capability”:“pm25”,“permission”:“0100”},{“capability”:“air-quality@enum”,“permission”:“0100”,“settings”:“{\“capability\”:\“air-quality@enum\”,\“permission\”:\“0100\”,\“settings\”:{\“range\”:{\“permission\”:\“01\”,\“type\”:\“enum\”,\“values\”:[\“excellent\”,\“moderate\”,\“poor\”]}}}”}]”,
> “x”: 450,
> “y”: 4360,
> “wires”: [
> [
> “0d08faedbeb09fcd”
> ]
> ]
> },
> {
> “id”: “7645b9a88fbe034c”,
> “type”: “api-server”,
> “name”: “Token”,
> “ip”: “192.168.0.85:80”,
> “ipaddr”: “”,
> “token”: “70320e15-887e-4d48-ad3e-3d12061c6925”
> },
> {
> “id”: “07808d991a052221”,
> “type”: “global-config”,
> “env”: ,
> “modules”: {
> “node-red-contrib-ewelink-cube”: “1.3.7”
> }
> }
> ]
And this is the debug payload
> **Debug**
>
> {“header”:{“name”:“ErrorResponse”,“message\_id”:“7757dccd-647f-43d7-a1e3-288501d81023”,“version”:“2”},“payload”:{“type”:“INVALID\_PARAMETERS”,“description”:“payload error, check capability air-quality@enum info fail, msg:settings contains keys not allowed, support keys:[range]”}}
Hope you can see something
---
### Author:  [@SuiKa](https://forum.ewelink.cc/u/SuiKa)
#### Post date: [December 11, 2025, 6:14am UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/9 "2025-12-11T06:14:49Z")
Your capability and state structure contains an incorrect nested configuration, which is why the API is returning an error. In your payload, the `air-quality@enum` capability is nested inside itself, causing an invalid format.
You provided this (incorrect):
```auto
[
{
"capability": "pm25",
"permission": "0100"
},
{
"capability": "air-quality@enum",
"permission": "0100",
"settings": {
"capability": "air-quality@enum",
"permission": "0100",
"settings": {
"range": {
"permission": "01",
"type": "enum",
"values": [
"excellent",
"moderate",
"poor"
]
}
}
}
}
]
{
"pm25":{
"pm25":25
},
"air-quality@enum":{
"air-quality":"excellent"
}
}
```
* * *
### Correct Format
The correct structure should **not** contain nested `capability` or `settings`. It should look like this:
```auto
[
{
"capability": "pm25",
"permission": "0100"
},
{
"capability": "air-quality@enum",
"permission": "0100",
"settings": {
"range": {
"permission": "01",
"type": "enum",
"values": [
"excellent",
"moderate",
"poor"
]
}
}
}
]
```
And the correct **state** format is:
```auto
{
"pm25": {
"pm25": 25
},
"air-quality@enum": {
"air-quality": "excellent"
}
}
```
* * *
If you update your payload to this structure, the API should accept it normally.
---
### Author:  [@ociepa.ekotox](https://forum.ewelink.cc/u/ociepa.ekotox)
#### Post date: [December 11, 2025, 10:15am UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/10 "2025-12-11T10:15:52Z")
> [@SuiKa](#):
>
> If you update your payload to this structure, the API should accept it normally.
This flow is not working
================
[flows.json](https://forum.ewelink.cc/uploads/short-url/sku6dv3zGGo1xddRbKsawwwIKo4.json) (2.5 KB)
There are two AIR QUALITY values in the Capabilities menu. But neither one works properly.
---
### Author:  [@john.e.dixon](https://forum.ewelink.cc/u/john.e.dixon)
#### Post date: [December 11, 2025, 12:31pm UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/11 "2025-12-11T12:31:25Z")
> [@ociepa.ekotox](#):
>
> This flow is not working
Yes, the upper one works, although it’s rather limited.
Permission is 0100 on the selection box, while the Settings box needs only
```auto
{
"range": {
"permission": "01",
"type": "enum",
"values": [
"excellent",
"moderate",
"poor"
]
}
}
```
It seems that there are 3 levels, like the IKEA color codes (Green, Amber, Red) as against the 5 or 6 levels of the EU or US levels, which means to pass this on to the control node I used these
```auto
let R25 = msg.payload.VINDRIKTNING["PM2.5"];
let Aqi = " ";
if (R25 > 0 && R25 < 10) { Aqi = "excellent"; }//Good
if (R25 >= 10 && R25 < 35) { Aqi = "excellent"; }//Moderate
if (R25 >= 35 && R25 < 85) { Aqi = "moderate"; }//Slightly Unhealthy
if (R25 >= 85 && R25 < 100) { Aqi = "poor"; }//Unhealthy
if (R25 >= 200 && R25 < 300) { Aqi = "poor"; }//Very Unhealthy
if (R25 >= 300) { Aqi = "poor"; }//Hazardous
let obj = { "air-quality@enum": {
"air-quality": Aqi
}
}
msg.payload = obj;
return msg;
```
levels, showing “Moderate” on the iHost device tile, as seen here when bridged on Matter :-
Unfortunately there is a bug which is not mapping “poor” to either Homekit or Smarthings
---
### Author:  [@SuiKa](https://forum.ewelink.cc/u/SuiKa)
#### Post date: [December 11, 2025, 1:15pm UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/12 "2025-12-11T13:15:14Z")
You don’t need to limit the reported value strictly to `["excellent", "moderate", "poor"]`.
As long as the value you report in **state** matches one of the values defined in `settings.range.values`, it will work correctly.
For example, you can define a richer set of air-quality categories:
```json
[
{
"capability": "air-quality@enum",
"permission": "1100",
"settings": {
"range": {
"permission": "01",
"type": "enum",
"values": [
"Good",
"Moderate",
"Slightly Unhealthy",
"Unhealthy",
"Very Unhealthy",
"Hazardous"
]
}
}
}
]
```
Then report any one of these values in the **state** :
```json
{
"air-quality@enum": {
"air-quality": "Good"
}
}
```
As long as the state value appears in `settings.range.values`, the capability will be treated as valid.
---
### Author:  [@john.e.dixon](https://forum.ewelink.cc/u/john.e.dixon)
#### Post date: [December 11, 2025, 6:22pm UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/13 "2025-12-11T18:22:34Z")
> [@SuiKa](#):
>
> As long as the state value appears in `settings.range.values`, the capability will be treated as valid.
Hi @SuiKa , thanks for your prompt feedback but unable to get this functioning. I´ve taken for an example your suggestion as you can see from this node JSON.
> **Register Node**
>
> [
> {
> “id”: “2bbac63f8b4087cf”,
> “type”: “register-device”,
> “z”: “819e12b16623dc86”,
> “name”: “AQI Test”,
> “server”: “7645b9a88fbe034c”,
> “device\_id”: “5f5d6e80-d6ae-11f0-8de9-0242ac120002”,
> “device\_name”: “AQI Test”,
> “category”: “sensor”,
> “capabilities”: “null”,
> “manufacturer”: “John”,
> “model”: “NRAQ2”,
> “firmware\_version”: “v1”,
> “service\_address”: “192.168.0.85”,
> “tags”: “{}”,
> “state”: “{“air-quality@enum”:{“air-quality”:“Good”}}”,
> “capabilities\_v2”: “[{“capability”:“air-quality@enum”,“permission”:“0100”,“settings”:“{\“range\”:{\“permission\”:\“01\”,\“type\”:\“enum\”,\“values\”:[\“Good\”,\“Moderate\”,\“Slightly Unhealthy\”,\“Unhealthy\”,\“Very Unhealthy\”,\“Hazardous\”]}}”}]”,
> “x”: 460,
> “y”: 4580,
> “wires”: [
> [
> “97c4aadb18a18935”
> ]
> ]
> },
> {
> “id”: “7645b9a88fbe034c”,
> “type”: “api-server”,
> “name”: “Token”,
> “ip”: “192.168.0.85:80”,
> “ipaddr”: “”,
> “token”: “70320e15-887e-4d48-ad3e-3d12061c6925”
> },
> {
> “id”: “fb10fcb97878e2d2”,
> “type”: “global-config”,
> “env”: ,
> “modules”: {
> “node-red-contrib-ewelink-cube”: “1.3.7”
> }
> }
> ]
It does not give an Error Response, and _will create the virtual device_ but _no values are shown_, neither on the iHost device tile, nor of course on the bridged device. Can you give this a try?
---
### Author:  [@SuiKa](https://forum.ewelink.cc/u/SuiKa)
#### Post date: [December 12, 2025, 3:04am UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/14 "2025-12-12T03:04:47Z")
When I import this data directly into Node-RED, it throws an error.
Could you export it in JSON format and send it to me? I’d like to try reproducing the issue on my side.
---
### Author:  [@john.e.dixon](https://forum.ewelink.cc/u/john.e.dixon)
#### Post date: [December 12, 2025, 6:48am UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/15 "2025-12-12T06:48:46Z")
OK, just deleted and tested again and it creates the virtual device, but without values. The debug positive response is
> **Summary**
>
> {“header”:{“name”:“Response”,“message\_id”:“8de5ba30-80ab-46c5-8678-e1c13faede1d”,“version”:“2”},“payload”:{“endpoints”:[{“serial\_number”:“4217463e-0abf-4544-8e88-e57fa077cfb1”,“third\_serial\_number”:“5f5d6e80-d6ae-11f0-8de9-0242ac120002”}]}}
This is the register node in JSON format - I have tested and it imports OK into Node Red, only needs changing the server
[NodeAQI.json](https://forum.ewelink.cc/uploads/short-url/A1vtqpi3PUyAghIfEYuaXsPA1Yv.json) (1.4 KB)
---
### Author:  [@SuiKa](https://forum.ewelink.cc/u/SuiKa)
#### Post date: [December 15, 2025, 1:40am UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/16 "2025-12-15T01:40:07Z")
I tried reproducing the issue and found that it’s caused by a problem on the iHost front-end page, which prevents it from displaying properly. We’ve already logged this bug and will fix it in the next release.
Also, the fact that the Matter Bridge can’t synchronize this device does seem abnormal. A few days ago, we pushed a new patch firmware to your iHost—have you updated yet? If so, did it resolve the synchronization issue?
---
### Author:  [@john.e.dixon](https://forum.ewelink.cc/u/john.e.dixon)
#### Post date: [December 15, 2025, 7:16am UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/17 "2025-12-15T07:16:11Z")
> [@SuiKa](#):
>
> Matter Bridge can’t synchronize this device does seem abnormal
Yes i´m on the latest version of firmware (shows 2.8.23 as I had several updates pushed out by the team) and all Matter devices and virtual devices are syncing correctly to both my Smartthings and Homekit hubs.
This device simply shows “Unknown”, but I have another version of the Air Quality sensor using the original values you gave me ( `["excellent", "moderate", "poor"]`. which using the same sensor source syncs correctly, except for the condition “poor” which shows “Poor” on the ihost UI tile, but will not map to either of the bridged hubs.
Thanks for the follow up to find this issue - waiting for the next release.
---
### Author:  [@SuiKa](https://forum.ewelink.cc/u/SuiKa)
#### Post date: [December 15, 2025, 7:52am UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/18 "2025-12-15T07:52:23Z")
What does it mean when this device simply shows “Unknown”? Can you describe the issue in more detail?
Regarding the air-quality status not being synchronized, how should we interpret that?
It would be helpful if you could provide more information, such as screenshots or videos, to assist us in reproducing and identifying the issue.
---
### Author:  [@john.e.dixon](https://forum.ewelink.cc/u/john.e.dixon)
#### Post date: [December 15, 2025, 10:54am UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/19 "2025-12-15T10:54:33Z")
> [@SuiKa](#):
>
> What does it mean when this device simply shows “Unknown”? Can you describe the issue in more detail?
Simply I´m saying this device when bridged shows -
and if I try injecting a value with an inject node, or use a function node as described on another post nothing changes. _If we add the pm2.5 capability to this same device it will not sync the pm2.5 value._
On the other hand another virtual device created using the range `[“excellent”, “moderate”, “poor”]`, with the pm2.5 capability also, syncs and shows e.g. Smartthings -
The only bug here is, as commented before, the “poor” level does not map, neither here nor in Homekit.
---
### Author:  [@ociepa.ekotox](https://forum.ewelink.cc/u/ociepa.ekotox)
#### Post date: [December 17, 2025, 8:09am UTC](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844/20 "2025-12-17T08:09:54Z")
> [@SuiKa](#):
>
> will fix it in the next release.
When is the next update planned?
[Next page](https://forum.ewelink.cc/t/virtual-device-on-2-8-1/206844.md?page=2)