Add support for individual LED themes

[theHacker]

• NOTE: Just like the manual predicated, there is a bug in the device and this does not work! The device responds with "unsupported option for key 'ledTheme' - can be [list of strings]" instead of accepting the data object.

---

Manual says

Known bug - this function does not work at the moment! As nobody has complained yet, fixing this bug is not on top of our list. If you want to use this function, please contact us.

Complaining right now 😉

You can the test case in this PR. As I understand from the manual, the device should just take the complex object as the theme.
Testing with pytest -k individual_led_theme.

With adding a print statement, you see the air-Q's error:

Error: unsupported option for key 'ledTheme' - can be ['standard', 'standard (contrast)', 'Virus', 'Virus (contrast)', 'co2_covid19', 'CO2', 'VOC', 'Humidity', 'CO', 'PM1', 'PM2.5', 'PM10', 'Noise', 'Noise (contrast)', 'Noise Average', 'Noise Average (contrast)']

just like an unsupported string was provided.

---

Since I am not sure what the current state with the "known bug" is, a few thoughts.
If "known bug" is "not implemented yet", you might want to use that chance and improve the options a little.

Current use-case

My current use-case is to bring air-Q's LED to show a fine-granular VOC scale. With low=0, high=360, datasource="voc" I would get one LED per 20 ppb VOC. That would be sufficient for now.
The default VOC theme will only light one LED per 100 ppb.

Thinking possibilities

If the endpoint is not yet fix, you might think the current proposal does not give all the options.

I like the Noise theme, having a green-yellow-red bar.
Doing this for example with CO2 value is not possible.

The same goes for the Noise (contrast) theme where LEDs are just unlit, when the value is not reached.

Last year when mailing to Mario, I had the idea you could split the LEDs into 4x4 scales (with one LED unlit as separator) showing 4 values at once.

Thinking towards HomeAssistant

Given the fact, a user cannot (or better: does not want to) click together a complex data object for such an individual theme, it would be nice (and maybe easier for you to implement) if a theme could be defined up front.

Like:

POST /config

{
  "customLedThemes": {
    "my-o2": { // API like in the manual
       "low": 20.8,
       "high": 20.9,
       "datasource": "o2",
       "colorLow": [255,0,0],
       "colorMedium": [0,255,0],
       "colorHigh": [0,0,255]
    },
    "colorized-co2-contrast": {
       "datasource": "co2",
       "leds": [ // allow for mixer-style like "Noise (contrast)", setting each LED individual, even with customized scale
           { value: 400, color: [0, 255, 0] },
           { value: 420, color: [0, 222, 0] },
           { value: 450, color: [0, 192, 0] }, // if CO>=450 LED is on with that color, else it's unlit
           { value: 500, color: [0, 128, 0] },
           { value: 600, color: [255, 255, 0] },
           { value: 700, color: [255, 192, 0] },
           { value: 800, color: [255, 128, 0] },
           { value: 1000, color: [255, 64, 0] },
           { value: 1250, color: [255, 0, 0] }
       ]
    },
    "colorized-co2": {
       "datasource": "co2",
       "leds": [ // allow for mixer-style like "Noise", setting each LED individual, even with customized scale
           { value: 400, color: [0, 255, 0], colorOff: [0, 64, 0] },
           { value: 420, color: [0, 222, 0], colorOff: [0, 64, 0] },
           { value: 450, color: [0, 192, 0], colorOff: [0, 64, 0] },  // if CO2>=450 LED is on with "0,192,0"; CO2<450 LED is on with "0,64,0"
           { value: 500, color: [0, 128, 0], colorOff: [0, 64, 0] },
           { value: 600, color: [255, 255, 0], colorOff: [32. 64, 0] },
           { value: 700, color: [255, 192, 0], colorOff: [64, 64, 0] },
           { value: 800, color: [255, 128, 0], colorOff: [64, 64, 0] },
           { value: 1000, color: [255, 64, 0], colorOff: [64, 0, 0] },
           { value: 1250, color: [255, 0, 0], colorOff: [64, 0, 0] },
       ]
    },
   "two-scales-at-a-time": {
       "leds": [ // putting "datasource" for each LED allows to display multiple values
           { datasource: "co2",  value: 400, color: [0, 255, 0] },
           { datasource: "co2",  value: 700, color: [255, 255, 0] },
           { datasource: "co2",  value: 1000, color: [255, 128, 0] },
           { datasource: "co2",  value: 1200, color: [255, 0, 0] },
           { color: null } // always off
           { datasource: "voc", value: 0, color: [0, 255, 0], colorOff: [0, 64, 0] },
           { datasource: "voc", value: 250, color: [0, 128, 0], colorOff: [0, 64, 0] },
           { datasource: "voc", value: 500, color: [255, 128, 0], colorOff: [64, 64, 0] },
           { datasource: "voc", value: 750, color: [128, 0, 0], colorOff: [64, 64, 0] },
       ]
   },
   "crazy-all-values-at-the-same-time": {
       "leds": [ // the same approach let's you build a warning for all sensors
           { datasource: "co2",  value: 1000, color: [255, 0, 0], colorOff: null },
           { datasource: "co",  value: 4.0, color: [255, 0, 255], colorOff: [16,0,16] },
           { datasource: "pm1",  value: 25.0, color: [192, 64, 32], colorOff: [16,16,16] },
           { datasource: "pm2.5",  value: 25.0, color: [192, 64, 32], colorOff: [16,16,16] },
           { datasource: "pm10",  value: 25.0, color: [192, 64, 32], colorOff: [16,16,16] },
           { color: null } // splitter and after 5 alarm LEDs still 3 LEDs left for a noise meter
           { datasource: "noise", value: 20, color: [0, 255, 0], colorOff: [0, 64, 0] },
           { datasource: "noise", value: 45, color: [0, 128, 0], colorOff: [0, 64, 0] },
           { datasource: "noise", value: 50, color: [255, 128, 0], colorOff: [64, 64, 0] },
       ]
   }
  }

A perfect move would be to provide all LED themes customizable and retrieveable by API, even your default ones you currently provide.

After defining themes, they can be selected like the default themes:

POST /config

{
  "ledTheme": {
     "left": "VOC" // default
     "right": "colorized-co2" // my own theme
  }
}

With such defined themes a user-interaction would be made more easily in HA UI.
A 5-minute GIMPing to visualize, how it could look:

---

Sorry, posting got longer than expected, but I had a lot of ideas.
What do you think?

Since the LEDs are air-Q's optical sugar ("Look, what things my air-Q can all do?"), I would love to see more options available.

[Sibgatulin]

Thanks for complaining @theHacker :) As well as for specifying the desired functionality in such details.
Now I only wanted to briefly mention that

1. The underlying known bug in the firmware is being tackled with an increased (albeit, unfortunately, only moderately) priority.
2. Prompted by the test in this PR I am looking into the way you implemented the LED theme handling in the previous PR and I may come up with some further questions and/or propositions