[hue] Add channels for time of last sensor update (API v2)

[jlaur]

This introduces new channels:

• motion-last-updated for API v2 which is equivalent to channel last_updated for API v1 thing type 0107 (motion sensor).
• temperature-last-updated for API v2 which is equivalent to channel last_updated for API v1 thing type 0302 (temperature sensor).
• light-level-last-updated for API v2 which is equivalent to channel last_updated for API v1 thing type 0106 (light sensor).
• button-last-updated for API v2.
• rotary-steps-last-updated for API v2.

Additionally, the motion / temperature / light-level / button-last-event / rotary-steps channels have been refactored to use new DTO fields with fallback to the now deprecated fields.

Resolves #15546
Resolves #15599

Relevant DTO documentation

GET /resource/motion/{id} response

motion: required(object)

• motion: required(boolean)
  Deprecated. Moved to motion_report/motion.
• motion_valid: required(boolean)
  Deprecated. Motion is valid when motion_report property is present, invalid when absent.
• motion_report: (object)
  • changed: required(datetime)
    last time the value of this property is changed.
  • motion: required(boolean)
    true if motion is detected

See https://developers.meethue.com/develop/hue-api-v2/api-reference/#resource_motion__id__get for full response.

GET /resource/temperature/{id} response

temperature: required(object)

• temperature: required(number)
  Deprecated. Moved to Temperature_report/temperature
• temperature_valid: required(boolean)
  Deprecated. Indication whether the value presented in temperature is valid
• temperature_report: (object)
  • changed: required(datetime)
    last time the value of this property is changed.
  • temperature: required(number)
    Temperature in 1.00 degrees Celsius

See https://developers.meethue.com/develop/hue-api-v2/api-reference/#resource_temperature__id__get for full response.

GET /resource/light_level/{id} response

light: required(object)

• light_level: required(integer)
  Deprecated. Moved to light_level_report/light_level
• light_level_valid: required(boolean)
  Deprecated. Indication whether the value presented in light_level is valid
• light_level_report: (object)
  • changed: required(datetime)
    last time the value of this property is changed.
  • light_level: required(integer)
    Light level in 10000*log10(lux) +1 measured by sensor. Logarithmic scale used because the human eye adjusts to light levels and small changes at low lux levels are more noticeable than at high lux levels. This allows use of linear scale configuration sliders.

See https://developers.meethue.com/develop/hue-api-v2/api-reference/#resource_light_level__id__get for full response.

GET /resource/button/{id} response

button: required(object)

• last_event: (one of initial_press, repeat, short_release, long_release, double_short_release, long_press)
  Deprecated. Move to button_report/event
• button_report: (object)
  • updated: required(datetime)
    last time the value of this property is updated.
  • event: required(one of initial_press, repeat, short_release, long_release, double_short_release, long_press)
    event which can be send by a button control
• repeat_interval: (integer)
  Duration of a light transition or timed effects in ms.
• event_values: (array of ButtonEvent)
  list of all button events that this device supports

See https://developers.meethue.com/develop/hue-api-v2/api-reference/#resource_button__id__get for full response.

GET /resource/relative_rotary/{id} response

relative_rotary: required(object)

• last_event: (object)
  Deprecated. Renamed to RelativeRotaryReport. Indicate which type of rotary event is received
• action: required(one of start, repeat)
  Indicate which type of rotary event is received
• rotation: required(object)
  • direction: required(one of clock_wise, counter_clock_wise)
    A rotation opposite to the previous rotation, will always start with new start command.
  • steps: required(integer – minimum: 0 – maximum: 32767)
    amount of rotation since previous event in case of repeat, amount of rotation since start in case of a start_event. Resolution = 1000 steps / 360 degree rotation.
  • duration: required(integer – minimum: 0 – maximum: 65534)
    duration of rotation since previous event in case of repeat, amount of rotation since start in case of a start_event. duration is specified in miliseconds.
• rotary_report: (object)
  • updated: required(datetime)
    last time the value of this property is updated.
  • action: required(one of start, repeat)
    Indicate which type of rotary event is received
  • rotation: required(object)
    • direction: required(one of clock_wise, counter_clock_wise)
      A rotation opposite to the previous rotation, will always start with new start command.
    • steps: required(integer – minimum: 0 – maximum: 32767)
      amount of rotation since previous event in case of repeat, amount of rotation since start in case of a start_event. Resolution = 1000 steps / 360 degree rotation.
    • duration: required(integer – minimum: 0 – maximum: 65534)
      duration of rotation since previous event in case of repeat, amount of rotation since start in case of a start_event. duration is specified in miliseconds.

See https://developers.meethue.com/develop/hue-api-v2/api-reference/#resource_relative_rotary__id__get for full response.

[jlaur]

Small note (to self / @andrewfg): Consider trying to figure out when motion_report/temperature_report were introduced. If the old fields were already deprecated before first non-beta CLIP 2 firmware, there is probably no need to maintain backwards compatibility.

[andrewfg]

@jlaur I will study this in more detail over the weekend, but I already have some quick suggestions..

• It is inconsistent to implement this xxx-report model only for motion and temperature sensors. You should implement it for light-level, button, and relative-rotary sensor channels as well.
• Last week Philips Signify introduced their range of home security products, and consequently they added new resource types for camera-motion, contact and tamper security sensors. These also use the xxx-report model. The full support for those new resource / things should not be added in this PR, but please consider if there is anything necessary in this PR in order prepare the foundations for that subsequent PR to come.
• So I suggest the DTOs for motion-report, temperature-report, button-report, light-level-report, relative-rotary-report, tamper-report, contact-report, camera-motion-report etc. should all descend from a common base-sensor-report class that implements the updated resp. changed JSON field. Note: I don't know why some sensor DTO's use updated and others use changed field names, but apparently they are synonyms, so the base class could deserialize both these alternate field names as one actual class field.

---

EDIT: @jlaur as this PR has increased in scope from your original concept, I am happy to take over the coding, if you prefer. Please let me know.

---

EDIT 2: probably the 'camera-motion' sensor could be coded in OH as the same channel as current 'motion' sensor; the advantage of doing that would be that we could reduce the total number of channels in OH things. WDYT?

[andrewfg]

• It is inconsistent to implement this xxx-report model only for motion and temperature sensors. You should implement it for light-level, button, and relative-rotary sensor channels as well.
• Last week Philips Signify introduced their range of home security products, and consequently they added new resource types for camera-motion, contact and tamper security sensors. These also use the xxx-report model. The full support for those new resource / things should not be added in this PR, but please consider if there is anything necessary in this PR in order prepare the foundations for that subsequent PR to come.
• So I suggest the DTOs for motion-report, temperature-report, button-report, light-level-report, relative-rotary-report, tamper-report, contact-report, camera-motion-report etc. should all descend from a common base-sensor-report class that implements the updated resp. changed JSON field. Note: I don't know why some sensor DTO's use updated and others use changed field names, but apparently they are synonyms, so the base class could deserialize both these alternate field names as one actual class field.

[andrewfg]

Consider trying to figure out when motion_report/temperature_report were introduced.

@jlaur see the following post from March this year..

https://hueblog.com/2023/03/14/hue-bridge-update-brings-back-popular-feature/

[andrewfg]

I have just created #15601 to add support for security devices. And #15602 to fix the deprecated DTOs for button and relative_rotary sensors. They both depend on some underlying infrastructure that I am expecting to be introduced in this PR (e.g. the BaseReport class).

@jlaur can you please look at #15601 and #15602 to give you an idea what I am counting on?

[jlaur]

It is inconsistent to implement this xxx-report model only for motion and temperature sensors. You should implement it for light-level, button, and relative-rotary sensor channels as well.

Thanks, I was unaware of these. I managed to refactor light-level as well before leaving on a short holiday this week. I will add button and relative-rotary as well for consistency. I don't have any relative-rotary devices to test with, but since it will be similar to the others, I guess chances are good that it will work too.

Completion of this PR for Motion, Temperature, LightLevel sensors => @jlaur => keep scope as is, or include 2. as well?

See above.

Make the same analogous changes for existing Button and RelativeRotary sensors => @jlaur include in this PR, or @andrewfg create a new PR?

See above. I see you already created a draft PR. I will have a look at that also to make sure I get it right. I already noticed that button is a bit different since there is one report per individual button.

Implement the new home security sensors, (including the same analogous code) as above => @andrewfg

Agreed.

[andrewfg]

will add button and relative-rotary as well for consistency. I don't have any relative-rotary devices to test with, but since it will be similar to the others, I guess chances are good that it will work too.

I have added the button and relative rotary in #15602 and the home security with #15601

[andrewfg]

@jlaur I will only be able to look at this finally next week

[andrewfg]

@jlaur a few points..

• in the interests of having an easy life, I accept your argument not to inherit the xxxReport classes from a common base class. Even though it means that I have to modify my own PR for home security to match you.
• apart from the comment about button last updated above, I reviewed you other code again, and I did not find any new points
• nevertheless I think there are still some open points from my prior review still to be resolved

[jlaur]

• nevertheless I think there are still some open points from my prior review still to be resolved

I believe I responded to all comments, can you check?

[jlaur]

@openhab/add-ons-maintainers - a review would be much appreciated, since there's currently a moderate activity level for this binding, and additional issues waiting in line to be tackled as well. Thanks in advance. 😉

[andrewfg]

a review would be much appreciated, since there's currently a moderate activity level for this binding, and additional issues waiting in line to be tackled as well

@openhab/add-ons-maintainers there is also a new PR #15601 to support new Hue security products that depends on this PR being merged :)

[kaikreuzer]

lgtm, many thanks @jlaur for the enhancement and @andrewfg for the review!