diff --git a/CODEOWNERS b/CODEOWNERS index a2d901c962635..59b492dac404c 100755 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -29,6 +29,7 @@ /bundles/org.openhab.binding.androidtv/ @morph166955 /bundles/org.openhab.binding.anel/ @paphko /bundles/org.openhab.binding.anthem/ @mhilbush +/bundles/org.openhab.binding.argoclima/ @mbronk /bundles/org.openhab.binding.asuswrt/ @wildcs /bundles/org.openhab.binding.astro/ @gerrieg /bundles/org.openhab.binding.atlona/ @mlobstein diff --git a/bom/openhab-addons/pom.xml b/bom/openhab-addons/pom.xml index bc27b7d2f8f5e..b2983e2cc2df8 100644 --- a/bom/openhab-addons/pom.xml +++ b/bom/openhab-addons/pom.xml @@ -136,6 +136,11 @@ org.openhab.binding.anthem ${project.version} + + org.openhab.addons.bundles + org.openhab.binding.argoclima + ${project.version} + org.openhab.addons.bundles org.openhab.binding.astro diff --git a/bundles/org.openhab.binding.argoclima/NOTICE b/bundles/org.openhab.binding.argoclima/NOTICE new file mode 100644 index 0000000000000..38d625e349232 --- /dev/null +++ b/bundles/org.openhab.binding.argoclima/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 diff --git a/bundles/org.openhab.binding.argoclima/README.md b/bundles/org.openhab.binding.argoclima/README.md new file mode 100644 index 0000000000000..4c4e1be0cf9f7 --- /dev/null +++ b/bundles/org.openhab.binding.argoclima/README.md @@ -0,0 +1,429 @@ +# ArgoClima Binding + +The binding provides support for [ArgoClima](https://argoclima.com/en/) Wi-Fi-enabled air conditioning devices which use ***Argo Web APP*** for control. +Refer to [Argo Web APP details](#argo-web-app-details) section for an example. + +> ***IMPORTANT:*** The same vendor also manufactures HVAC devices supported by a [phone application](http://smart.argoclima.com/EN/). +> +> These devices are using a different protocol and are ***not*** supported by this binding. +> There are good chances these will be supported by the [Gree](https://www.openhab.org/addons/bindings/gree/) binding, though! + +The binding supports all HVAC remote functions (including built-in schedule and settings) except for ***iFeel*** (room) temperature which is not supported by the Argo remote protocol and has to be sent via infrared. +The binding can operate in local, remote and hybrid modes. +Refer to [Connection Modes](#connection-modes) for more details. + +See also [Argo protocol details](#argo-protocol-details) to find out more about how the device operates. + +## Supported Things + +- `remote`: Represents a HVAC device which is controlled remotely - through vendor's web application +- `local`: Represents a locally available device, which openHAB interacts with directly *(or indirectly, through a stub server)*. Refer to [Connection Modes](#connection-modes) for more details. + +The binding has been primarily developed and tested using [Ulisse 13 DCI ECO Wi-Fi](https://argoclima.com/en/prodotti/argo-ulisse-eco/) device. + +## Discovery + +The binding does not support device auto-discovery (as the devices don't announce themselves locally). + +- Note it is *technically* possible for the advanced mode with API stub to discover devices, but as it requires manual firewall reconfiguration, it won't be an "auto" anyway so was not implemented. + +## Thing Configuration + +### `remote` Thing Configuration + +| Name | Type | Description | Default | Required | Advanced | +|------------------|---------|---------------------------------------------------------------|---------------|----------|----------| +| **username** | text | Remote site login (can be retrieved from device during setup) | N/A | yes | no | +| **password** | text | Password to access the device | N/A | yes | no | +| refreshInterval | integer | Interval the remote API is polled with (in sec.) | 30 | no | yes | +| oemServerAddress | text | The Argo server's IP or hostname, used for communications. | 31.14.128.210 | no | yes | +| oemServerPort | integer | The Argo server's port. | 80 | no | yes | + +### `local` Thing Configuration + +| Name | Type | Description | Default | Required | Advanced | +|-------------------------------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------|----------| +| **hostname** | text | Hostname or IP address of the HVAC device. If ```useLocalConnection``` setting is enabled, **this** address will be used for direct communication with the device. | N/A | yes | no | +| connectionMode | text | Type of connection to use. One of: ```LOCAL_CONNECTION```, ```REMOTE_API_STUB```, ```REMOTE_API_PROXY```. Refer to [Connection Modes](#connection-modes) | LOCAL_CONNECTION | yes | no | +| hvacListenPort | integer | Port at which the HVAC listens on (used if ```useLocalConnection== true```) | 1001 | no | yes | +| localDeviceIP | text | Local IP address of the device for matching intercepted requests (may be different from **hostname**, if behind NAT). Used in ```REMOTE_API_*``` modes. | N/A | no | yes | +| deviceCpuId | text | CPU ID of the device. Optional, value is used for detecting device update in proxy mode. Used in ```REMOTE_API_*``` modes. | N/A | no | yes | +| useLocalConnection | boolean | Whether the binding is permitted to talk to the device directly. | yes | no | yes | +| refreshInterval | integer | Interval the device is polled in (in sec.). Used if ```useLocalConnection== true``` | 30 | no | yes | +| stubServerPort | integer | Stub server listen port Used in ```REMOTE_API_*``` modes. | 8239 | no | yes | +| stubServerListenAddresses | text(multiple) | List of interfaces the stub server will listen on Used in ```REMOTE_API_*``` modes. | 0.0.0.0 | no | yes | +| oemServerAddress | text | The Argo server's IP or hostname, used for pass-through. Used in ```REMOTE_API_PROXY``` mode | 31.14.128.210 | no | yes | +| oemServerPort | integer | The Argo server's port. Used in ```REMOTE_API_PROXY``` mode | 80 | no | yes | +| includeDeviceSidePasswordsInProperties | text | Whether to show the intercepted passwords (in ```REMOTE_API_*``` modes) as Thing Properties. One of: ```NEVER```, ```MASKED```, ```CLEARTEXT``` | NEVER | no | yes | +| matchAnyIncomingDeviceIp | boolean | If enabled, will accept any Argo message as matching this Thing (instead of requiring an exact-match by ```hostname``` or ```localDeviceIP```). Used in ```REMOTE_API_*``` modes. | no | no | yes | + +### General Device Configuration (dynamic) + +These parameters are modeled as thing configuration, but are actually configuring behavior of the HVAC device itself (when in certain modes). +The same values apply to **both** `remote` and `local`. + +| Name | Type | Description | Default | Required | Advanced | +|------------------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------|----------|----------| +| schedule1DayOfWeek | text(multiple) | Days (set comprising of values ```MON```, ```TUE```, ```WED```, ```THU```, ```FRI```, ```SAT```, ``SUN``), when Schedule Timer 1 actions should be performed. This is used only if ```active-timer``` [channel](#channels) is in ```SCHEDULE_TIMER_1``` mode. | [MON, TUE, WED, THU, FRI, SAT, SUN] | no | yes | +| schedule1OnTime | text | The time of day (HH:MM) the device should turn **ON** *(in the last used mode)* on the ```schedule1DayOfWeek```-specified days. In effect only if ```active-timer``` [channel](#channels) is in ```SCHEDULE_TIMER_1``` mode | 8:00 | no | yes | +| schedule1OffTime | text | The time of day (HH:MM) the device should turn **OFF** on the ```schedule1DayOfWeek```-specified days. In effect only if ```active-timer``` [channel](#channels) is in ```SCHEDULE_TIMER_1``` mode | 18:00 | no | yes | +| schedule2DayOfWeek | text(multiple) | Days (set comprising of values ```MON```, ```TUE```, ```WED```, ```THU```, ```FRI```, ```SAT```, ``SUN``), when Schedule Timer 1 actions should be performed. This is used only if ```active-timer``` [channel](#channels) is in ```SCHEDULE_TIMER_1``` mode. | [MON, TUE, WED, THU, FRI] | no | yes | +| schedule2OnTime | text | The time of day (HH:MM) the device should turn **ON** *(in the last used mode)* on the ```schedule2DayOfWeek```-specified days. In effect only if ```active-timer``` [channel](#channels) is in ```SCHEDULE_TIMER_2``` mode | 15:00 | no | yes | +| schedule2OffTime | text | The time of day (HH:MM) the device should turn **OFF** on the ```schedule2DayOfWeek```-specified days. In effect only if ```active-timer``` [channel](#channels) is in ```SCHEDULE_TIMER_2``` mode | 20:00 | no | yes | +| schedule3DayOfWeek | text(multiple) | Days (set comprising of values ```MON```, ```TUE```, ```WED```, ```THU```, ```FRI```, ```SAT```, ``SUN``), when Schedule Timer 1 actions should be performed. This is used only if ```active-timer``` [channel](#channels) is in ```SCHEDULE_TIMER_1``` mode. | [SAT, SUN] | no | yes | +| schedule3OnTime | text | The time of day (HH:MM) the device should turn **ON** *(in the last used mode)* on the ```schedule3DayOfWeek```-specified days. In effect only if ```active-timer``` [channel](#channels) is in ```SCHEDULE_TIMER_3``` mode | 11:00 | no | yes | +| schedule3OffTime | text | The time of day (HH:MM) the device should turn **OFF** on the ```schedule3DayOfWeek```-specified days. In effect only if ```active-timer``` [channel](#channels) is in ```SCHEDULE_TIMER_3``` mode | 22:00 | no | yes | +| resetToFactoryDefaults | boolean(action) | When set, upon successful Thing initialization, the binding will issue a one-time factory reset request to the device (and flip this value back do OFF) | false | no | yes | + +## Channels + +Both thing types are functionally equivalent and support the same channels. + +| Channel | Type | Read/Write | Description | +|--------------------------|----------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| - **A/C Controls** |||| +| power | Switch | RW | This is the control channel | +| mode | String | RW | Operation mode. One of: ```COOL```, ```DRY```, ```FAN```, ```AUTO``` | +| set-temperature | Number:Temperature | RW | The device's target temperature | +| current-temperature | Number:Temperature | R | Actual (ambient) temperature. Either from device's built-in sensor or iFeel. Read-only, see also: [Room Temperature Support](#room-temperature-support) | +| fan-speed | String | RW | Fan mode. One of: ```AUTO```, ```LEVEL_1```, ```LEVEL_2```, ```LEVEL_3```, ```LEVEL_4```, ```LEVEL_5```, ```LEVEL_6``` | +| - **Operation Modes** |||| +| eco-mode | Switch | RW | Economy (Energy Saving) Mode (cap device max power to the ```eco-power-limit```) | +| turbo-mode | Switch | RW | Turbo mode (max power). *While the device API (similarly to original remote) allows enabling ```turbo``` **while** ```night``` and/or ```economy``` modes are **active**, actual effect of such a combo is unknown :)* | +| night-mode | Switch | RW | Night mode *(lowers device noise by lowering the fan speed and automatically raising the set temperature by 1°C after 60 minutes of enabling this option)* | +| - **Timers (advanced)** |||| +| active-timer | String | RW | Active timer. One of ```NO_TIMER```, ```DELAY_TIMER```, ```SCHEDULE_TIMER_1```, ```SCHEDULE_TIMER_2```, ```SCHEDULE_TIMER_3```. See also [schedule configuration](#general-device-configuration-dynamic) | +| delay-timer | Number:Time | W | Delay timer value. In effect only if ```active-timer``` is in ```DELAY_TIMER``` mode. The delay timer toggles the current ```power``` (ex. OFF->ON) after the configured period elapses | +| - **Settings** |||| +| ifeel-enabled | Switch | RW | Use iFeel Temperature updates for ```current-temperature``` | +| device-lights | Switch | RW | Device Lights | +| temperature-display-unit | String | W | **(advanced)** Unit's display temperature display unit. One of ```SCALE_CELSIUS```, ```SCALE_FARHENHEIT``` | +| eco-power-limit | Number:Dimensionless | W | **(advanced)** Power limit in eco mode (in %, factory default is 75%), | +| - **Advanced (not supported by all devices)** |||| +| mode-ex | String | RW | Extended Operation mode. Same as ```mode```, but also supports ```WARM``` | +| swing-mode | String | RW | Airflow Direction (flap setting). One of ```AUTO```, ```LEVEL_1```, ```LEVEL_2```, ```LEVEL_3```, ```LEVEL_4```, ```LEVEL_5```, ```LEVEL_6```, ```LEVEL_7``` | +| filter-mode | Switch | RW | Filter Mode | + +## Full Example + +### argoclima.things + + ```java + //BASIC MODES examples + Thing argoclima:remote:argoHvacRemote "Argo HVAC (via Argo remote API)" @ "Living Room" [ + username="", + password="" + ] + + + Thing argoclima:local:argoHvacLocalDirect "Argo HVAC (connected locally)" @ "Living Room" [ + hostname="192.168.0.3" + ] + + Thing argoclima:local:argoHvacLocalDirectEx "Argo HVAC (connected locally) - extended example (with explicit options)" [ + hostname="192.168.0.3", + connectionMode="LOCAL_CONNECTION", + refreshInterval=30, + hvacListenPort=1001, + + // Schedule options (these are valid for all thing types) + schedule1DayOfWeek="[FRI, SAT, SUN, MON]", + schedule1OnTime="7:35", + schedule1OffTime="18:00", + schedule2DayOfWeek="[MON, TUE, WED, THU, FRI]", + schedule2OnTime="15:00", + schedule2OffTime="22:00", + schedule3DayOfWeek="SUN","SAT", //Alternative syntax for the weekdays list + schedule3OnTime="11:00", + schedule3OffTime="22:00" + //,resetToFactoryDefaults=true //This triggers a one-shot command each time the thing + // definition is (re)loaded from file. + // Use only intermittently - it is not designed with prolonged + // usage via Things text file in mind (mostly a MainUI feature!) + ] + + //ADVANCED MODES examples + Thing argoclima:local:argoHvacLocalWithPassthroughIndirect "Argo HVAC (accessible only indirectly, via pass-through mode)" [ + hostname="192.168.4.2", // Doesn't have to be reachable! + connectionMode="REMOTE_API_PROXY", + useLocalConnection=false + ] + + + Thing argoclima:local:argoHvacLocalWithPassthroughPlusDirectEx "Argo HVAC (accessible both indirectly and directly, via pass-through mode, with explicit options)" [ + hostname="192.168.0.3", // Direct address of the device (reachable from openHAB) + connectionMode="REMOTE_API_PROXY", + + hvacListenPort=1001, + refreshInterval=30, + useLocalConnection=true, + + // Stub server-specific + stubServerPort=8240, + stubServerListenAddresses="7d47:86bd:0bfe:0413:4688:4523:4284:5936","192.168.0.195", + includeDeviceSidePasswordsInProperties="MASKED", + matchAnyIncomingDeviceIp=false, + deviceCpuId="deadbeefdeadbeef", // For direct match to a concrete device (optional) + localDeviceIP="192.168.4.2", // Address in local subnet (used for indirect request matching) + + // Pass-through-specific + oemServerAddress="uisetup.ddns.net", + oemServerPort=80 + ] + + + Thing argoclima:local:argoHvacLocalWithStub "Argo HVAC (accessible both indirectly and directly with a stub) - **RECOMMENDED MODE**" [ + hostname="192.168.0.3", // Has to be reachable, since useLocalConnection is true (default) + connectionMode="REMOTE_API_STUB", + localDeviceIP="192.168.4.2" // Or use matchAnyIncomingDeviceIp=true + ] + ``` + +### argoclima.items + + ```java + Group GArgoClimaHVACRemote "Ulisse 13 DCI ECO - remote mode" ["HVAC"] + + Switch ArgoClimaHVACRemote_Power "Power" (GArgoClimaHVACRemote) { + channel="argoclima:remote:argoHvacRemote:ac-controls#power" + } + + String ArgoClimaHVACRemote_Mode "Mode" (GArgoClimaHVACRemote) ["Control"] { + channel="argoclima:remote:argoHvacRemote:ac-controls#mode" + } + + Number:Temperature ArgoClimaHVACRemote_SetTemperature "Set Temperature" (GArgoClimaHVACRemote) ["Temperature", "Setpoint"] { + channel="argoclima:remote:argoHvacRemote:ac-controls#set-temperature", + unit="°C", + stateDescription="" [ pattern="%.1f °C", readOnly=false, min=10.0, max=36.0, step=0.5], + widget="oh-stepper-card" [ min=10, max=36, step=0.5, autorepeat=true], + listWidget="oh-stepper-item" [min=10, max=36, step=0.5, autorepeat=true] + } + + Number:Temperature ArgoClimaHVACRemote_CurrentTemperature "Current Temperature" (GArgoClimaHVACRemote) ["Temperature", "Measurement"] { + channel="argoclima:remote:argoHvacRemote:ac-controls#current-temperature" + } + + String ArgoClimaHVACRemote_FanSpeed "Fan Speed" (GArgoClimaHVACRemote) { + channel="argoclima:remote:argoHvacRemote:ac-controls#fan-speed" + } + + Switch ArgoClimaHVACRemote_EcoMode "Eco Mode" (GArgoClimaHVACRemote) { + channel="argoclima:remote:argoHvacRemote:modes#eco-mode" + } + + Switch ArgoClimaHVACRemote_TurboMode "Turbo Mode" (GArgoClimaHVACRemote) { + channel="argoclima:remote:argoHvacRemote:modes#turbo-mode" + } + + Switch ArgoClimaHVACRemote_NightMode "Night Mode" (GArgoClimaHVACRemote) { + channel="argoclima:remote:argoHvacRemote:modes#night-mode" + } + + String ArgoClimaHVACRemote_ActiveTimer "Active timer" (GArgoClimaHVACRemote) { + channel="argoclima:remote:argoHvacRemote:timers#active-timer" + } + + Number:Time ArgoClimaHVACRemote_DelayTimer "Delay timer value"