Skip to content

Commit

Permalink
[hue] Add channels for time of last sensor update (API v2) (#15552)
Browse files Browse the repository at this point in the history
* Add channels for last motion/temperature sensor update (API v2)
* Add channel for last light level sensor update (API v2)
* Add channel for last rotary steps update (API v2)
* Add channel for last button update (API v2)

Resolves #15546

Signed-off-by: Jacob Laursen <jacob-github@vindvejr.dk>
  • Loading branch information
jlaur authored Oct 26, 2023
1 parent bdba338 commit 1702631
Show file tree
Hide file tree
Showing 31 changed files with 1,463 additions and 682 deletions.
53 changes: 29 additions & 24 deletions bundles/org.openhab.binding.hue/doc/readme_v2.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,30 +59,35 @@ The configuration of all things (as described above) is the same regardless of w

Device things support some of the following channels:

| Channel ID | Item Type | Description |
|-----------------------|--------------------|---------------------------------------------------------------------------------------------------------------------|
| color | Color | Supports full color control with hue, saturation and brightness values, or brightness only, or switching on or off. |
| brightness | Dimmer | Supports control of the brightness value, or switching on or off. |
| color-temperature | Dimmer | Supports control of the color temperature in percent from cold (0%) to warm (100%). |
| color-temperature-abs | Number:Temperature | Supports control of the color temperature via a QuantityType having a temperature unit e.g. Kelvin. (Advanced) |
| switch | Switch | Supports switching the device on and off. |
| dynamics | Number:Time | Sets the duration of dynamic transitions between light states. (Advanced) |
| alert | String | Allows setting an alert on a light e.g. flashing them. (Advanced) |
| effect | String | Allows setting an effect on a light e.g. 'candle' effect. (Advanced) |
| button-last-event | (String) | Informs which button was last pressed in the device. (Trigger Channel) |
| rotary-steps | (String) | Informs about the number of rotary steps of the last rotary dial movement. (Trigger Channel) |
| motion | Switch | Shows if motion has been detected by the sensor. (Read Only) |
| motion-enabled | Switch | Supports enabling / disabling the motion sensor. (Advanced) |
| light-level | Number:Illuminance | Shows the current light level measured by the sensor. (Read Only) |
| light-level-enabled | Switch | Supports enabling / disabling the light level sensor. (Advanced) |
| temperature | Number:Temperature | Shows the current temperature measured by the sensor. (Read Only) |
| temperature-enabled | Switch | Supports enabling / disabling the temperature sensor. (Advanced) |
| battery-level | Number | Shows the battery level. (Read Only) |
| battery-low | Switch | Indicates whether the battery is low or not. (Read Only) |
| last-updated | DateTime | The date and time when the thing state was last updated. (Read Only) (Advanced) |
| color-xy-only | Color | Allows access to the `color-xy` parameter of the light(s) only. Has no impact on `dimming` or `on-off` parameters. |
| dimming-only | Dimmer | Allows access to the `dimming` parameter of the light(s) only. Has no impact on `color-xy` or `on-off` parameters. |
| on-off-only | Switch | Allows access to the `on-off` parameter of the light(s) only. Has no impact on `color-xy` or `dimming` parameters. |
| Channel ID | Item Type | Description |
|---------------------------|--------------------|---------------------------------------------------------------------------------------------------------------------|
| color | Color | Supports full color control with hue, saturation and brightness values, or brightness only, or switching on or off. |
| brightness | Dimmer | Supports control of the brightness value, or switching on or off. |
| color-temperature | Dimmer | Supports control of the color temperature in percent from cold (0%) to warm (100%). |
| color-temperature-abs | Number:Temperature | Supports control of the color temperature via a QuantityType having a temperature unit e.g. Kelvin. (Advanced) |
| switch | Switch | Supports switching the device on and off. |
| dynamics | Number:Time | Sets the duration of dynamic transitions between light states. (Advanced) |
| alert | String | Allows setting an alert on a light e.g. flashing them. (Advanced) |
| effect | String | Allows setting an effect on a light e.g. 'candle' effect. (Advanced) |
| button-last-event | (String) | Informs which button was last pressed in the device. (Trigger Channel) |
| button-last-updated | DateTime | The date and time when a button was last pressed. (Read Only) (Advanced) |
| rotary-steps | (String) | Informs about the number of rotary steps of the last rotary dial movement. (Trigger Channel) |
| rotary-steps-last-updated | DateTime | The date and time when the rotary steps were last updated. (Read Only) (Advanced) |
| motion | Switch | Shows if motion has been detected by the sensor. (Read Only) |
| motion-enabled | Switch | Supports enabling / disabling the motion sensor. (Advanced) |
| motion-last-updated | DateTime | The date and time when the motion value was last updated. (Read Only) (Advanced) |
| light-level | Number:Illuminance | Shows the current light level measured by the sensor. (Read Only) |
| light-level-last-updated | DateTime | The date and time when the light level was last updated. (Read Only) (Advanced) |
| light-level-enabled | Switch | Supports enabling / disabling the light level sensor. (Advanced) |
| temperature | Number:Temperature | Shows the current temperature measured by the sensor. (Read Only) |
| temperature-last-updated | DateTime | The date and time when the temperature was last updated. (Read Only) (Advanced) |
| temperature-enabled | Switch | Supports enabling / disabling the temperature sensor. (Advanced) |
| battery-level | Number | Shows the battery level. (Read Only) |
| battery-low | Switch | Indicates whether the battery is low or not. (Read Only) |
| last-updated | DateTime | The date and time when the thing state was last updated. (Read Only) (Advanced) |
| color-xy-only | Color | Allows access to the `color-xy` parameter of the light(s) only. Has no impact on `dimming` or `on-off` parameters. |
| dimming-only | Dimmer | Allows access to the `dimming` parameter of the light(s) only. Has no impact on `color-xy` or `on-off` parameters. |
| on-off-only | Switch | Allows access to the `on-off` parameter of the light(s) only. Has no impact on `color-xy` or `dimming` parameters. |

The exact list of channels in a given device is determined at run time when the system is started.
Each device reports its own live list of capabilities, and the respective list of channels is created accordingly.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -151,12 +151,17 @@ public class HueBindingConstants {
public static final String CHANNEL_2_ALERT = CHANNEL_ALERT;
public static final String CHANNEL_2_EFFECT = CHANNEL_EFFECT;
public static final String CHANNEL_2_BUTTON_LAST_EVENT = "button-last-event";
public static final String CHANNEL_2_BUTTON_LAST_UPDATED = "button-last-updated";
public static final String CHANNEL_2_ROTARY_STEPS = "rotary-steps";
public static final String CHANNEL_2_ROTARY_STEPS_LAST_UPDATED = "rotary-steps-last-updated";
public static final String CHANNEL_2_MOTION = "motion";
public static final String CHANNEL_2_MOTION_LAST_UPDATED = "motion-last-updated";
public static final String CHANNEL_2_MOTION_ENABLED = "motion-enabled";
public static final String CHANNEL_2_LIGHT_LEVEL = "light-level";
public static final String CHANNEL_2_LIGHT_LEVEL_LAST_UPDATED = "light-level-last-updated";
public static final String CHANNEL_2_LIGHT_LEVEL_ENABLED = "light-level-enabled";
public static final String CHANNEL_2_TEMPERATURE = CHANNEL_TEMPERATURE;
public static final String CHANNEL_2_TEMPERATURE_LAST_UPDATED = "temperature-last-updated";
public static final String CHANNEL_2_TEMPERATURE_ENABLED = "temperature-enabled";
public static final String CHANNEL_2_BATTERY_LEVEL = "battery-level";
public static final String CHANNEL_2_BATTERY_LOW = "battery-low";
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -81,12 +81,14 @@
import org.openhab.binding.hue.internal.exceptions.ApiException;
import org.openhab.binding.hue.internal.exceptions.HttpUnauthorizedException;
import org.openhab.binding.hue.internal.handler.Clip2BridgeHandler;
import org.openhab.binding.hue.internal.serialization.InstantDeserializer;
import org.openhab.core.io.net.http.HttpClientFactory;
import org.openhab.core.io.net.http.HttpUtil;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonArray;
import com.google.gson.JsonElement;
import com.google.gson.JsonParseException;
Expand Down Expand Up @@ -556,7 +558,8 @@ public static boolean isClip2Supported(String hostName) throws IOException {
private final String registrationUrl;
private final String applicationKey;
private final Clip2BridgeHandler bridgeHandler;
private final Gson jsonParser = new Gson();
private final Gson jsonParser = new GsonBuilder().registerTypeAdapter(Instant.class, new InstantDeserializer())
.create();
private final Semaphore streamMutex = new Semaphore(MAX_CONCURRENT_STREAMS, true); // i.e. fair
private final ReadWriteLock sessionUseCreateLock = new ReentrantReadWriteLock(true); // i.e. fair
private final Map<Integer, Future<?>> fatalErrorTasks = new ConcurrentHashMap<>();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,6 @@
*/
package org.openhab.binding.hue.internal.dto.clip2;

import java.util.Objects;

import org.eclipse.jdt.annotation.NonNullByDefault;
import org.eclipse.jdt.annotation.Nullable;
import org.openhab.binding.hue.internal.dto.clip2.enums.ButtonEventType;
Expand All @@ -28,16 +26,29 @@
@NonNullByDefault
public class Button {
private @Nullable @SerializedName("last_event") String lastEvent;
private @Nullable @SerializedName("button_report") ButtonReport buttonReport;
private @SerializedName("repeat_interval") int repeatInterval;

/**
* @return the last button event as an enum.
* @throws IllegalArgumentException if lastEvent is null or bad.
* The underlying field is deprecated in the CLIP 2 API.
* Moved to button_report/event
*
* @return the last button event as an enum (null if none or invalid).
*/
public ButtonEventType getLastEvent() throws IllegalArgumentException {
public @Nullable ButtonEventType getLastEvent() {
String lastEvent = this.lastEvent;
if (Objects.nonNull(lastEvent)) {
if (lastEvent == null) {
return null;
}

try {
return ButtonEventType.valueOf(lastEvent.toUpperCase());
} catch (IllegalArgumentException e) {
return null;
}
throw new IllegalArgumentException("lastEvent field is null");
}

public @Nullable ButtonReport getButtonReport() {
return buttonReport;
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
/**
* Copyright (c) 2010-2023 Contributors to the openHAB project
*
* See the NOTICE file(s) distributed with this work for additional
* information.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0
*
* SPDX-License-Identifier: EPL-2.0
*/
package org.openhab.binding.hue.internal.dto.clip2;

import java.time.Instant;

import org.eclipse.jdt.annotation.NonNullByDefault;
import org.eclipse.jdt.annotation.Nullable;
import org.openhab.binding.hue.internal.dto.clip2.enums.ButtonEventType;

/**
* DTO for CLIP 2 button report.
*
* @author Jacob Laursen - Initial contribution
*/
@NonNullByDefault
public class ButtonReport {
private @NonNullByDefault({}) Instant updated;
private @Nullable String event;

/**
* @return last time the value of this property is updated.
*/
public Instant getLastChanged() {
return updated;
}

/**
* @return event which can be sent by a button control (null if none or invalid).
*/
public @Nullable ButtonEventType getLastEvent() {
String event = this.event;
if (event == null) {
return null;
}

try {
return ButtonEventType.valueOf(event.toUpperCase());
} catch (IllegalArgumentException e) {
return null;
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
package org.openhab.binding.hue.internal.dto.clip2;

import org.eclipse.jdt.annotation.NonNullByDefault;
import org.eclipse.jdt.annotation.Nullable;
import org.openhab.core.library.types.OnOffType;
import org.openhab.core.library.types.QuantityType;
import org.openhab.core.library.unit.Units;
Expand All @@ -30,11 +31,22 @@
public class LightLevel {
private @SerializedName("light_level") int lightLevel;
private @SerializedName("light_level_valid") boolean lightLevelValid;
private @Nullable @SerializedName("light_level_report") LightLevelReport lightLevelReport;

/**
* The underlying field is deprecated in the CLIP 2 API.
* Moved to light_level_report/light_level
* Should be used only as fallback for older firmwares.
*/
public int getLightLevel() {
return lightLevel;
}

/**
* The underlying field is deprecated in the CLIP 2 API.
* Indication whether the value presented in light_level is valid
* Should be used only as fallback for older firmwares.
*/
public boolean isLightLevelValid() {
return lightLevelValid;
}
Expand All @@ -56,4 +68,8 @@ public State getLightLevelState() {
public State isLightLevelValidState() {
return OnOffType.from(lightLevelValid);
}

public @Nullable LightLevelReport getLightLevelReport() {
return lightLevelReport;
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
/**
* Copyright (c) 2010-2023 Contributors to the openHAB project
*
* See the NOTICE file(s) distributed with this work for additional
* information.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0
*
* SPDX-License-Identifier: EPL-2.0
*/
package org.openhab.binding.hue.internal.dto.clip2;

import java.time.Instant;

import org.eclipse.jdt.annotation.NonNullByDefault;

import com.google.gson.annotations.SerializedName;

/**
* DTO for CLIP 2 light level sensor report.
*
* @author Jacob Laursen - Initial contribution
*/
@NonNullByDefault
public class LightLevelReport {
private @NonNullByDefault({}) Instant changed;
private @SerializedName("light_level") int lightLevel;

/**
* @return last time the value of this property is changed.
*/
public Instant getLastChanged() {
return changed;
}

/**
* 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.
*
* @return light level in 10000*log10(lux) +1 measured by sensor
*/
public int getLightLevel() {
return lightLevel;
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
package org.openhab.binding.hue.internal.dto.clip2;

import org.eclipse.jdt.annotation.NonNullByDefault;
import org.eclipse.jdt.annotation.Nullable;
import org.openhab.core.library.types.OnOffType;
import org.openhab.core.types.State;
import org.openhab.core.types.UnDefType;
Expand All @@ -28,11 +29,24 @@
public class Motion {
private boolean motion;
private @SerializedName("motion_valid") boolean motionValid;
private @Nullable @SerializedName("motion_report") MotionReport motionReport;

/**
* The underlying field is deprecated in the CLIP 2 API.
* Moved to motion_report/motion.
* Should be used only as fallback for older firmwares.
*
* @return true if motion is detected
*/
public boolean isMotion() {
return motion;
}

/**
* The underlying field is deprecated in the CLIP 2 API.
* Motion is valid when motion_report property is present, invalid when absent.
* Should be used only as fallback for older firmwares.
*/
public boolean isMotionValid() {
return motionValid;
}
Expand All @@ -44,4 +58,8 @@ public State getMotionState() {
public State getMotionValidState() {
return OnOffType.from(motionValid);
}

public @Nullable MotionReport getMotionReport() {
return motionReport;
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
/**
* Copyright (c) 2010-2023 Contributors to the openHAB project
*
* See the NOTICE file(s) distributed with this work for additional
* information.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0
*
* SPDX-License-Identifier: EPL-2.0
*/
package org.openhab.binding.hue.internal.dto.clip2;

import java.time.Instant;

import org.eclipse.jdt.annotation.NonNullByDefault;

/**
* DTO for CLIP 2 motion sensor report.
*
* @author Jacob Laursen - Initial contribution
*/
@NonNullByDefault
public class MotionReport {
private @NonNullByDefault({}) Instant changed;
private boolean motion;

/**
* @return last time the value of this property is changed.
*/
public Instant getLastChanged() {
return changed;
}

/**
* @return true if motion is detected
*/
public boolean isMotion() {
return motion;
}
}
Loading

0 comments on commit 1702631

Please sign in to comment.