[wiz] Initial contribution (#17681)

Also-by: Joshua Freeman <[email protected]>
Also-by: Stefan Fussenegger <[email protected]>
Also-by: Sara Damiano <[email protected]>
Signed-off-by: Cody Cutrer <[email protected]>

CODEOWNERS

@@ -421,6 +421,7 @@
 /bundles/org.openhab.binding.wemo/ @hmerk @jlaur
 /bundles/org.openhab.binding.wifiled/ @openhab/add-ons-maintainers
 /bundles/org.openhab.binding.windcentrale/ @marcelrv @wborn
+/bundles/org.openhab.binding.wiz/ @ccutrer @frejos
 /bundles/org.openhab.binding.wlanthermo/ @CSchlipp
 /bundles/org.openhab.binding.wled/ @Skinah
 /bundles/org.openhab.binding.wolfsmartset/ @BoBiene

bom/openhab-addons/pom.xml

@@ -2081,6 +2081,11 @@
       <artifactId>org.openhab.binding.windcentrale</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.wiz</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.wlanthermo</artifactId>

bundles/org.openhab.binding.wiz/NOTICE

@@ -0,0 +1,13 @@
+This content is produced and maintained by the openHAB project.
+
+* Project home: https://www.openhab.org
+
+== Declared Project Licenses
+
+This program and the accompanying materials are made available under the terms
+of the Eclipse Public License 2.0 which is available at
+https://www.eclipse.org/legal/epl-2.0/.
+
+== Source Code
+
+https://github.com/openhab/openhab-addons

bundles/org.openhab.binding.wiz/README.md

@@ -0,0 +1,150 @@
+# WiZ Binding
+
+This binding integrates [WiZ Connected](https://www.wizconnected.com/en-US/) smart devices.
+These inexpensive devices, typically smart bulbs, are available online and in most Home Depot stores.
+They come in a variety of bulb shapes and sizes with options of full color with tunable white, tunable white, and dimmable white.
+This binding has been tested with various bulbs and switchable plugs.
+They are sold under the Philips brand name.
+(Wiz is owned by Signify (formerly Philips Lighting).)
+*Note* that while both are sold by Philips, WiZ bulbs are *not* part of the Hue ecosystem.
+
+This binding operates completely within the local network - the discovery, control, and status monitoring is entirely over UDP in the local network.
+The binding never attempts to contact the WiZ servers in any way but does not stop them from doing so independently.
+It should not interfere in any way with control of the bulbs via the WiZ app or any other service integrated with the WiZ app (e.g. Alexa, IFTTT, SmartThings).
+Any changes made to the bulb state outside of openHAB should be detected by the binding and vice-versa.
+Before using the binding, the bulbs must be set up using the WiZ iOS or Android app.
+Local control must also be enabled with-in the WiZ app in the app settings.
+(This is the default.)
+
+## Supported Things
+
+- WiZ Full Color with Tunable White Bulbs
+- WiZ Tunable White Bulbs
+- WiZ Dimmable single-color bulbs
+- WiZ Smart Plugs
+- Smart fans (with or without a dimmable light)
+
+**NOTE:** This binding was created for and tested on the full color with tunable white bulbs, however, users have reported success with other bulb types and plugs.
+
+## Discovery
+
+New devices can be discovered by scanning and may also be discovered by background discovery.
+All discovered devices will default to 'Full Color' bulbs if unable to automatically detect the specific device type.
+You may need to create devices manually if desired.
+
+Devices must first have been set up using the WiZ iOS or Android app.
+If the binding cannot discover your device, try unplugging it, wait several seconds, and plug it back in.
+
+## Binding Configuration
+
+The binding does not require any special configuration.
+You can optionally manually set the IP and MAC address of the openHAB instance; if you do not set them, the binding will use the system defaults.
+
+## Thing Configuration
+
+To create or configure a device manually you need its IP address and MAC address.
+These can be quickly found in the iOS or Android app by entering the settings for device in question and clicking on the model name.
+The refresh interval may also be set; if unset it defaults to 30 seconds.
+If you desire instant updates, you may also enable "heart-beat" synchronization with the bulbs.
+Heart-beats are not used by default.
+When heart-beats are enabled, the binding will continuously re-register with the bulbs to receive sync packets on every state change and on every 5 seconds.
+Enabling heart-beats causes the refresh-interval to be ignored.
+If heart-beats are not enabled, the channels are only updated when polled at the set interval and thus will be slightly delayed with regard to changes made to the bulb state outside of the binding (e.g. via the WiZ app).
+
+**NOTE:** While the bulb's IP address is needed for initial manual configuration, this binding _does not_ require you to use a static IP for each bulb.
+After initial discovery or setup, the binding will automatically search for and re-match bulbs with changed IP addresses by MAC address once every hour.
+
+Thing parameters:
+
+| Parameter ID      | Parameter Type | Mandatory | Description                                                                                                                                                                                                                                                                                   | Default |
+|-------------------|----------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
+| macAddress        | text           | true      | The MAC address of the bulb                                                                                                                                                                                                                                                                   |         |
+| ipAddress         | text           | true      | The IP of the bulb                                                                                                                                                                                                                                                                            |         |
+| updateInterval    | integer        | false     | Update time interval in seconds to request the status of the bulb.                                                                                                                                                                                                                            | 60      |
+| useHeartBeats     | boolean        | false     | Whether to register for continuous 5s heart-beats                                                                                                                                                                                                                                             | false   |
+| reconnectInterval | integer        | false     | Interval in minutes between attempts to reconnect with a bulb that is no longer responding to status queries.  When the bulb first connects to the network, it should send out a firstBeat message allowing openHAB to immediately detect it.  This is only as a back-up to re-find the bulb. | 15      |
+
+Example Thing:
+
+```java
+Thing wiz:bulb:lamp "My Lamp" @ "Living Room" [ macAddress="accf23343cxx", ipAddress="192.168.0.xx" ]
+```
+
+## Channels
+
+The binding supports the following channels. If a device is only a light or only a fan, the channels will
+not be in a group.
+
+| Channel ID             | Item Type            | Description                                           | Access |
+|------------------------|----------------------|-------------------------------------------------------|--------|
+| light#color            | Color                | State, intensity, and color of the LEDs               | R/W    |
+| light#temperature      | Dimmer               | Color temperature of the bulb                         | R/W    |
+| light#temperature-abs  | Number:Temperature   | Color temperature of the bulb in Kelvin               | R/W    |
+| light#brightness       | Dimmer               | The brightness of the bulb                            | R/W    |
+| light#state            | Switch               | Whether the bulb is on or off                         | R/W    |
+| light#light-mode       | Number               | Preset light mode name to run                         | R/W    |
+| light#speed            | Dimmer               | Speed of the color changes in dynamic light modes     | R/W    |
+| fan#state              | Switch               | Whether the fan is on or off                          | R/W    |
+| fan#speed              | Number               | Speed of the fan, in arbitrary steps                  | R/W    |
+| fan#reverse            | Switch               | Whether the fan direction is reversed                 | R/W    |
+| fan#mode               | Number               | Special fan modes (Breeze)                            | R/W    |
+| device#last-update     | Time                 | The last time an an update was received from the bulb | R      |
+| device#signal-strength | Number               | Quality of the bulb's WiFi connection                 | R      |
+| device#rssi            | Number:Dimensionless | WiFi Received Signal Strength Indicator (in dB)       | R      |
+
+## Light Modes
+
+The binding supports the following Light Modes
+
+| ID | Scene Name    |
+|----|---------------|
+|  1 | Ocean         |
+|  2 | Romance       |
+|  3 | Sunset        |
+|  4 | Party         |
+|  5 | Fireplace     |
+|  6 | Cozy White    |
+|  7 | Forest        |
+|  8 | Pastel Colors |
+|  9 | Wakeup        |
+| 10 | Bed Time      |
+| 11 | Warm White    |
+| 12 | Daylight      |
+| 13 | Cool White    |
+| 14 | Night Light   |
+| 15 | Focus         |
+| 16 | Relax         |
+| 17 | True Colors   |
+| 18 | TV Time       |
+| 19 | Plant Growth  |
+| 20 | Spring        |
+| 21 | Summer        |
+| 22 | Fall          |
+| 23 | Deep Dive     |
+| 24 | Jungle        |
+| 25 | Mojito        |
+| 26 | Club          |
+| 27 | Christmas     |
+| 28 | Halloween     |
+| 29 | Candlelight   |
+| 30 | Golden White  |
+| 31 | Pulse         |
+| 32 | Steampunk     |
+
+## Bulb Limitations
+
+- Full-color bulbs operate in either color mode OR tunable white/color temperature mode.
+The RGB LED's are NOT used to control temperature - separate warm and cool white LED's are used.
+Sending a command on the color channel or the temperature channel will cause the bulb to switch the relevant mode.
+- Dimmable bulbs do not dim below 10%. 
+- The binding attempts to immediately retrieve the actual state from the device after each command is acknowledged, sometimes this means your settings don't 'stick' this is because the device itself did not accept the command or setting.
+- Parameters can not be changed while the bulbs are off, sending any commands to change any settings will cause the bulbs to turn on.
+- Power on behavior is configured in the app.
+- Fade in/out times are configured in the app.
+- Sending too many commands to the bulbs too quickly can cause them to stop responding for a period of time.
+
+## Example Item Linked To a Channel
+
+```java
+Color LivingRoom_Light_Color "Living Room Lamp" (gLivingroom) {channel="wiz:color-bulb:accf23343cxx:color"}
+```

bundles/org.openhab.binding.wiz/pom.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.openhab.addons.bundles</groupId>
+    <artifactId>org.openhab.addons.reactor.bundles</artifactId>
+    <version>4.3.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.wiz</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: WiZ Binding</name>
+
+</project>

bundles/org.openhab.binding.wiz/src/main/feature/feature.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.wiz-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.4.0">
+	<repository>mvn:org.openhab.core.features.karaf/org.openhab.core.features.karaf.openhab-core/${ohc.version}/xml/features</repository>
+
+	<feature name="openhab-binding-wiz" description="WiZ  Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.wiz/${project.version}</bundle>
+	</feature>
+</features>

bundles/org.openhab.binding.wiz/src/main/java/org/openhab/binding/wiz/internal/WizBindingConstants.java

@@ -0,0 +1,140 @@
+/**
+ * Copyright (c) 2010-2024 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.wiz.internal;
+
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link WizBindingConstants} class defines common constants, which
+ * are used across the whole binding.
+ *
+ * @author Sriram Balakrishnan - Initial contribution
+ * @author Joshua Freeman - update version
+ */
+@NonNullByDefault
+public class WizBindingConstants {
+
+    /**
+     * The binding id.
+     */
+    public static final String BINDING_ID = "wiz";
+
+    /**
+     * List of all Thing Type UIDs.
+     */
+    public static final ThingTypeUID THING_TYPE_COLOR_BULB = new ThingTypeUID(BINDING_ID, "color-bulb");
+    public static final ThingTypeUID THING_TYPE_TUNABLE_BULB = new ThingTypeUID(BINDING_ID, "tunable-bulb");
+    public static final ThingTypeUID THING_TYPE_DIMMABLE_BULB = new ThingTypeUID(BINDING_ID, "dimmable-bulb");
+    public static final ThingTypeUID THING_TYPE_SMART_PLUG = new ThingTypeUID(BINDING_ID, "plug");
+    public static final ThingTypeUID THING_TYPE_FAN = new ThingTypeUID(BINDING_ID, "fan");
+    public static final ThingTypeUID THING_TYPE_FAN_WITH_DIMMABLE_BULB = new ThingTypeUID(BINDING_ID,
+            "fan-with-dimmable-bulb");
+
+    /**
+     * The supported thing types.
+     */
+    public static final Set<ThingTypeUID> SUPPORTED_THING_TYPES = Set.of(THING_TYPE_COLOR_BULB, THING_TYPE_TUNABLE_BULB,
+            THING_TYPE_DIMMABLE_BULB, THING_TYPE_SMART_PLUG, THING_TYPE_FAN, THING_TYPE_FAN_WITH_DIMMABLE_BULB);
+
+    /**
+     * List of all Channel ids
+     */
+    public static final String CHANNEL_BRIGHTNESS = "brightness";
+    public static final String CHANNEL_COLOR = "color";
+    public static final String CHANNEL_LAST_UPDATE = "last-update";
+    public static final String CHANNEL_MODE = "mode";
+    public static final String CHANNEL_REVERSE = "reverse";
+    public static final String CHANNEL_RSSI = "rssi";
+    public static final String CHANNEL_SIGNAL_STRENGTH = "signal-strength";
+    public static final String CHANNEL_SPEED = "speed";
+    public static final String CHANNEL_STATE = "state";
+    public static final String CHANNEL_TEMPERATURE = "temperature";
+    public static final String CHANNEL_TEMPERATURE_ABS = "temperature-abs";
+
+    public static final String CHANNEL_GROUP_DEVICE = "device";
+    public static final String CHANNEL_GROUP_LIGHT = "light";
+    public static final String CHANNEL_GROUP_FAN = "fan";
+
+    // -------------- Configuration arguments ----------------
+    /**
+     * Mac address configuration argument key.
+     */
+    public static final String CONFIG_MAC_ADDRESS = "macAddress";
+
+    /**
+     * Host address configuration argument key.
+     */
+    public static final String CONFIG_IP_ADDRESS = "ipAddress";
+
+    /**
+     * Wifi socket update interval configuration argument key.
+     */
+    public static final String CONFIG_UPDATE_INTERVAL = "updateInterval";
+    public static final long DEFAULT_REFRESH_INTERVAL_SEC = 60;
+
+    /**
+     * Wifi socket update interval configuration argument key.
+     */
+    public static final String CONFIG_RECONNECT_INTERVAL = "reconnectInterval";
+    public static final long DEFAULT_RECONNECT_INTERVAL_MIN = 15;
+
+    // -------------- Default values ----------------
+
+    /**
+     * The number of refresh intervals without a response before a bulb is marked
+     * offline
+     */
+    public static final int MARK_OFFLINE_AFTER_SEC = 5 * 60;
+
+    /**
+     * Default Wifi socket default UDP port.
+     */
+    public static final int DEFAULT_UDP_PORT = 38899;
+
+    /**
+     * Default listener socket default UDP port.
+     */
+    public static final int DEFAULT_LISTENER_UDP_PORT = 38900;
+
+    /**
+     * How long before active discovery times out.
+     */
+    public static final int DISCOVERY_TIMEOUT_SECONDS = 2;
+
+    // -------------- Constants Used ----------------
+
+    /**
+     * The color temperature range of the WiZ bulbs
+     */
+    public static final int MIN_COLOR_TEMPERATURE = 2200;
+    public static final int MAX_COLOR_TEMPERATURE = 6500;
+
+    // -------------- Bulb Properties ----------------
+
+    public static final String PROPERTY_IP_ADDRESS = "ipAddress";
+
+    public static final String PROPERTY_HOME_ID = "homeId";
+    public static final String PROPERTY_ROOM_ID = "roomId";
+    public static final String PROPERTY_HOME_LOCK = "homeLock";
+    public static final String PROPERTY_PAIRING_LOCK = "pairingLock";
+    public static final String PROPERTY_TYPE_ID = "typeId";
+    public static final String PROPERTY_MODULE_NAME = "moduleName";
+    public static final String PROPERTY_GROUP_ID = "groupId";
+
+    public static final String EXPECTED_MODULE_NAME = "ESP01_SHRGB1C_31";
+    public static final String LAST_KNOWN_FIRMWARE_VERSION = "1.18.0";
+    public static final String MODEL_CONFIG_MINIMUM_FIRMWARE_VERSION = "1.22";
+}