Merge branch 'v4.1.0-rc'

README.md

@@ -14,10 +14,10 @@ Home Climate Control
 
 ---
 
-## v4.0.0. is out
+## v4.1.0. is out
 
-* Get the code [here](https://github.com/home-climate-control/dz/tree/v4.0.0)
-* See the [v4.0.0 Release Notes](./docs/release-notes/v4.0.0.md) for the list of changes
+* Get the code [here](https://github.com/home-climate-control/dz/tree/v4.1.0)
+* See the [v4.1.0 Release Notes](./docs/release-notes/v4.1.0.md) for the list of changes
 * See the [list of release notes](./docs/release-notes.md)
 
 

build.gradle.kts

@@ -42,7 +42,7 @@ subprojects {
     }
 
     group = "net.sf.dz3"
-    version = "4.0.0"
+    version = "4.1.0"
 
     jacoco {
         toolVersion = "0.8.9"

docs/configuration/console.md

@@ -25,7 +25,7 @@ Set of references to [directors](./directors.md). If you skip it HCC will assume
 > Both "include all" and "missing" will be logged at `WARNING` level, verify if what you think you configured is what HCC thinks it is.
 
 ### sensors
-Set of references to [sensors](./sensors-and-switches.md).
+Set of references to [sensors](./sensors-switches-fans.md).
 
 > **NOTE**: Be careful with an empty set. Quarkus will not ignore it, but Spring will include all, and you likely have A LOT of sensors in the system, and it's unlikely that you want all of them on the console.
 > Be sure to examine the boot log to verify how exactly the configuration was interpreted.

docs/configuration/directors.md

@@ -33,7 +33,7 @@ Best explained by example:
   * [home-assistant](./home-assistant.md)
   * [http](./http.md)
   * [influx](./influx.md)
-* `sensor-feed-mapping`: List of relations from the [sensor](./sensors-and-switches.md) reference (on the left) to the [zone](./zones.md) it is serving (on the right).
+* `sensor-feed-mapping`: List of relations from the [sensor](./sensors-switches-fans.md) reference (on the left) to the [zone](./zones.md) it is serving (on the right).
 * `unit`: [Unit abstraction](./units.md) to use.
 * `hvac`: [HVAC device](./hvac.md) to use.
 * `mode`: Initial mode for this director. Note that the configuration above shows different units in different modes (yes, this is supported).

docs/configuration/hvac.md

@@ -34,6 +34,12 @@ Best explained by example:
     - heatpump-hat:
         - id: heatpump-hat
           mode-change-delay: 20S
+    - variable:
+        - id: hvac-infinity-ac-a6
+          mode: cooling
+          actuator: fan-infinity-ac-a6
+          band-count: 5
+          max-power: 0.5
 
 ```
 ### Common Properties
@@ -45,7 +51,7 @@ Best explained by example:
 
 An on/off HVAC device. Examples: heat fan, radiant heater, oil heater, motorized shade, economizer.
 
-* `mode`: Which mode this device is used in. There can be one. The system will refuse to use this device in the wrong mode.
+* `mode`: Which mode this device is used in. There can be one. The system will refuse to use this device in the wrong mode. This parameter is mandatory.
 * `switch-address`: Address of the switch that turns this device on or off.
 
 ### heatpump
@@ -66,6 +72,19 @@ This is a Raspberry Pi specific device utilizing a [Pimoroni Automation HAT](htt
 
 No additional configuration is required.
 
+### variable
+
+An on/off HVAC device. Examples: heat fan, radiant heater, oil heater, motorized shade, economizer.
+
+* `mode`: Which mode this device is used in. There can be one. The system will refuse to use this device in the wrong mode. This parameter is mandatory.
+* `actuator`: The variable output device used as a HVAC unit. Currently, only [MQTT fans](./mqtt.md#sensors-switches-fans) are supported.
+* `max-power`: scale the maximum power output of this device to this much from the total power. The purpose of this parameter is to reduce noise.
+* `band-count`: The control signal will be split into this many bands, and the output will not change while the control signal is within the same band. This is done to make the device noise less noticeable, infinitely variable devices annoy people.
+  * Default band count is 10, and the maximum possible value is 100. It would probably be a bad idea to raise it above the default.
+  * Value of 0 disables banding altogether.
+
+> NOTE: Device power output is first scaled to `max-power`, and then banded by `band-count`. Control quality does not deteriorate with reduced output.
+
 ### Property of
 * [home-climate-control](./home-climate-control.md)
 

docs/configuration/index.md

@@ -1,48 +1,24 @@
 Home Climate Control: Configuration Reference
 ==
-## Variants
-There are currently four ways to run the application (see [build](../build/index.md) for details):
-* Standalone ("minimal")
-* SpringBoot
-* Quarkus
-* Docker
-
-The "minimal" variant is the only one that requires things to be spelled out exactly, the rest follow the usual Spring and Quarkus conventions (splitting configuration into many files, specifying active profiles, using YAML anchors, etc.).
-
-> **NOTE:** YAML merging is not so smart. Verify the effective configuration, it is logged at debug level at the start of the application.
-
-### YAML Anchors
-
-Configuration file for HCC can be quite big (400+ lines is not unheard of), do take advantage of [YAML Anchors](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) to make it stable.
-
-## Infrastructure Specific
-This part contains what you would usually provide for your standard Spring or Quarkus applications. For your convenience, basic
-[localhost](../../dz3r-app-springboot/src/main/resources/application-localhost.yaml) and
-[docker](../../dz3r-app-springboot/src/main/resources/application-docker.yaml) profiles are included into default configuration - feel free to override them as you see fit.
-## Home Climate Control Specific
-
-> **NOTE:** There are two source trees, [Spring specific](../../dz3r-app-springboot/src/main/java/net/sf/dz3/runtime/config/HccRawRecordConfig.java) and
-> [Quarkus specific](../../dz3r-app-quarkus/src/main/java/net/sf/dz3/runtime/config/quarkus/HccRawInterfaceConfig.java) that directly map to configuration entries.
-> They are expected to behave the same way (the reason two of them exist is very different conventions followed by Spring and Quarkus), if there's ever any discrepancy (the application works invoked with Spring and doesn't work invoked with Quarkus, or the other way around), please [file an issue](https://github.com/home-climate-control/dz/issues).
-
-> **NOTE:** You can use your IDE to edit configuration files, this will give you code completion and extended documentation, thanks to [Spring Configuration Metadata](https://docs.spring.io/spring-boot/docs/current/reference/html/configuration-metadata.html), and "code walking" if you are using YAML anchors.
+## Variants & Infrastructure Specific
+Read more [here](./variants.md).
 
 ### General Structure
-Here's the configuration file skeleton:
+Here's the configuration file skeleton. Order of these entries is important.
 ```yaml
 home-climate-control:
-  instance: <your-instance-name>
+  instance: ...
   esphome: ...
   zigbee2mqtt: ...
   zwave2mqtt: ...
   onewire: ...
   xbee: ...
   mocks: ...
   filters: ...
+  hvac: ...
   zones: ...
   schedule: ...
   connectors: ...
-  hvac: ...
   units: ...
   directors: ...
   web-ui: ...
@@ -60,12 +36,12 @@ home-climate-control:
     * [xbee](./xbee.md)
     * [mocks](./mocks.md)
     * [filters](./filters.md)
+    * [hvac](./hvac.md)
     * [zones](./zones.md)
     * [schedule](./schedule.md)
     * [connectors](./connectors.md)
         * [influx](./influx.md)
         * [http](./http.md)
-    * [hvac](./hvac.md)
     * [units](./units.md)
     * [directors](./directors.md)
     * [web-ui](./web-ui.md)
@@ -97,6 +73,15 @@ home-climate-control:
           address: /esphome/board-MAC/switch-heatpump-running
         - id: switch-heatpump-fan
           address: /esphome/board-MAC/switch-heatpump-fan
+  hvac:
+    - heatpump:
+        - id: heatpump-main
+          switch-mode: switch-heatpump-mode
+          switch-mode-reverse: true
+          switch-running: switch-heatpump-running
+          switch-fan: switch-heatpump-fan
+          filter:
+            lifetime: 200H
   zones:
     - id: bedroom-master
       name: Master Bedroom
@@ -147,18 +132,6 @@ home-climate-control:
         uri: http://dx:8086
         sensor-feed-mapping:
           air-ambient: air-ambient-temperature
-          air-bedroom-master: air-bedroom-master-temperature
-          air-bedroom-kids: air-bedroom-kids-temperature
-          air-family-room: air-family-room-temperature
-  hvac:
-    - heatpump:
-        - id: heatpump-main
-          switch-mode: switch-heatpump-mode
-          switch-mode-reverse: true
-          switch-running: switch-heatpump-running
-          switch-fan: switch-heatpump-fan
-          filter:
-            lifetime: 200H
   units:
     - single-stage:
         - id: heatpump
@@ -186,3 +159,5 @@ home-climate-control:
       - air-ambient-north
       - air-ambient-south
 ```
+---
+[^^^ Index](../index.md)

docs/configuration/influx.md

@@ -3,7 +3,7 @@ influx
 
 Integration that allows to use [InfluxDB](https://www.influxdata.com/) as telemetry data sink.
 
-> **NOTE:** This integration will be inactive except for `sensor-field-mapping` unless included into [directors.connectors](./directors.md).
+> **NOTE:** This integration will be inactive except for `sensor-field-mapping` unless included into [directors.connectors](./directors.md).   
 
 > **NOTE:** This integration is different from default InfluxDB integration embedded into Spring and Quarkus, those must be configured in [infrastructure configuration](./index.md#infrastructure-specific).
 
@@ -13,7 +13,7 @@ Short list:
 
 * Zone state (setpoints, PID controller internal state, and more)
 * Economizer state (setpoints, PID controller internal state, and more)
-* Unit status (demand, uptime, and more)
+* Unit state (demand, uptime, filter life left, and more)
 
 ### Configuration
 
@@ -39,7 +39,7 @@ Best explained by example:
 * `uri`: InfluxDB server to connect to
 * `username`: InfluxDB username - optional, but recommended
 * `password`: InfluxDB password - optional, but recommended
-* `sensor-feed-mapping`: Optional list of pairs where on the left is the [sensor](./sensors-and-switches.md#sensors) ID, and on the right is the name it will translate to in InfluxDB.
+* `sensor-feed-mapping`: Optional list of pairs where on the left is the [sensor](./sensors-switches-fans.md#sensors) ID, and on the right is the name it will translate to in InfluxDB. Note that this mapping is on top of the standard telemetry emitted for all the entities included in the [directors](./directors.md) this connector is attached to.
 
 ### Property of
 * [connectors](./connectors.md)

docs/configuration/mocks.md

@@ -3,7 +3,7 @@ mocks
 
 The primary use for the mocks is to be able to debug the system configuration without jeopardizing expensive hardware.
 
-This section follows the same syntax as [sensors & switches](./sensors-and-switches.md). Only switches are supported at the moment.
+This section follows the same syntax as [sensors & switches](./sensors-switches-fans.md). Only switches are supported at the moment.
 
 Example:
 

docs/configuration/mqtt.md

@@ -13,14 +13,16 @@ They all share common properties:
       id: <Client ID> # optional, defaults to internally generated stable hash code
       host: <MQTT broker host>
       port: <MQTT broker port> # optional, defaults to 1883
-      root-topic: <root topic for all messages for this connector>
+      root-topic: <root MQTT topic for all messages for this connector>
       username: <MQTT broker username> # optional, but recommended
       password: <MQTT broker password> # optional, but recommended
       auto-reconnect: <boolean flag> #optional, see below
     sensors:
       ...
     switches:
       ...
+    fans:
+      ...
 ```
 
 ### broker
@@ -33,9 +35,9 @@ Used to identify this client to the MQTT server. Defaults to internally generate
 #### auto-reconnect
 Instructs the MQTT library to try to reconnect automatically. Generally, it is a good thing, but it may backfire during initial setup because the library does it quietly and will do it forever, with the rest of the system appearing stuck. Use with care.
 
-### sensors & switches
+### sensors, switches, fans
 
-See [sensors & switches](./sensors-and-switches.md).
+See [sensors, switches, fans](./sensors-switches-fans.md).
 
 ### Property of
 * [home-climate-control](./home-climate-control.md)

docs/configuration/sensors-and-switches.md → docs/configuration/sensors-switches-fans.md

@@ -1,4 +1,4 @@
-sensors & switches
+sensors, switches, fans
 ==
 
 ### sensors
@@ -61,7 +61,7 @@ switches:
     reversed: <boolean flag>
     heartbeat: <Duration>
     pace: <Duration>
-    optimistic: <boolean flag>
+    availability-topic: <MQTT topic for availability information>
 ```
 
 #### reversed
@@ -73,8 +73,48 @@ Optional. Send the command to hardware this often even if the logical state hasn
 #### pace
 Optional. Send the same command to hardware no more often that this. Some bridges (notably `zigbee2mqtt`) are known to become unresponsive with no error indication when incoming traffic exceeds their bandwidth.
 
-### optimistic
-Optional. Send the command to hardware and don't wait for confirmation. Normally, you wouldn't have to do this, but some firmware (notably, [ESPHome](./esphome.md)) doesn't provide reliable confirmation so this may save the situation (and is a default for known hardware types). Use only if you must, and consider using [heartbeat](#heartbeat) to offset the risk.
+#### availability-topic
+* Mandatory for [ESPHome](./esphome.md) devices (see [esphome #5030](https://github.com/esphome/issues/issues/5030) for more information);
+* Disallowed for [Zigbee](./zigbee2mqtt.md) and [Z-Wave](./zwave2mqtt.md) devices.
+
+Log messages at `ERROR` level will provide enough details to resolve the problem.
+
+### fans
+Similar to above:
+```yaml
+fans:
+  - id: ac-infinity-a6
+    address: /esphome/550212/fan/a6-0
+    availability: /esphome/550212/status
+    heartbeat: <Duration>
+    pace: <Duration>
+    availability-topic: <MQTT topic for availability information>
+```
+`id`, `address`, `heartbeat`, `pace`, and `availability-topic` parameters are identical to those above.
+
+This is how ESPHome configuration section looks like (`pin` and `min_power` depend on your particular hardware setup):
+
+```yaml
+output:
+  - platform: esp8266_pwm
+    id: pwm_output
+    pin: D1
+    frequency: 5000 Hz
+    min_power: 0.2
+    max_power: 1.0
+    zero_means_zero: true
+    inverted: true
+
+fan:
+  - platform: speed
+    output: pwm_output
+    name: "A6-0"
+
+```
+
+For more information, see [ESPHome Fan Component](https://esphome.io/components/fan/).
+
+> **NOTE:** Leave ESPHome `speed_count` at default (100), or this integration will not work.
 
 ### Property of
 * [esphome](./esphome.md)

docs/configuration/variants.md

@@ -0,0 +1,33 @@
+Home Climate Control: Configuration Reference
+==
+
+## Variants
+
+There are currently four ways to run the application (see [build](../build/index.md) for details):
+* Standalone ("minimal")
+* SpringBoot
+* Quarkus
+* Docker
+
+The "minimal" variant is the only one that requires things to be spelled out exactly, the rest follow the usual Spring and Quarkus conventions (splitting configuration into many files, specifying active profiles, using YAML anchors, etc.).
+
+> **NOTE:** YAML merging is not so smart. Verify the effective configuration, it is logged at debug level at the start of the application.
+
+### YAML Anchors
+
+Configuration file for HCC can be quite big (400+ lines is not unheard of), do take advantage of [YAML Anchors](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) to make it stable.
+
+## Infrastructure Specific
+This part contains what you would usually provide for your standard Spring or Quarkus applications. For your convenience, basic
+[localhost](../../dz3r-app-springboot/src/main/resources/application-localhost.yaml) and
+[docker](../../dz3r-app-springboot/src/main/resources/application-docker.yaml) profiles are included into default configuration - feel free to override them as you see fit.
+## Home Climate Control Specific
+
+> **NOTE:** There are two source trees, [Spring specific](../../dz3r-app-springboot/src/main/java/net/sf/dz3/runtime/config/HccRawRecordConfig.java) and
+> [Quarkus specific](../../dz3r-app-quarkus/src/main/java/net/sf/dz3/runtime/config/quarkus/HccRawInterfaceConfig.java) that directly map to configuration entries.
+> They are expected to behave the same way (the reason two of them exist is very different conventions followed by Spring and Quarkus), if there's ever any discrepancy (the application works invoked with Spring and doesn't work invoked with Quarkus, or the other way around), please [file an issue](https://github.com/home-climate-control/dz/issues).
+
+> **NOTE:** You can use your IDE to edit configuration files, this will give you code completion and extended documentation, thanks to [Spring Configuration Metadata](https://docs.spring.io/spring-boot/docs/current/reference/html/configuration-metadata.html), and "code walking" if you are using YAML anchors.
+
+---
+[^^^ Index](./index.md)

docs/configuration/web-ui.md

@@ -7,15 +7,19 @@ Best explained by example:
 
 ```yaml
   web-ui:
-    port: 9999
+    http-port: 6666
+    duplex-port: 7777
     directors:
       - house-unit1
       - house-unit2
       - server-room
 ```
 
-### port
-Port to listen on. Defaults to 3939.
+### http-port
+HTTP port to listen on. Defaults to 3939.
+
+### duplex-port
+Duplex protocol port to listen on. Defaults to 3940.
 
 ### interface
 Interfaces to listen on. Defaults to `0.0.0.0`.
@@ -28,7 +32,7 @@ Set of references to [directors](./directors.md). If you skip it HCC will assume
 > It is best to include at least one non-empty keyword (in this case, `port`).
 
 ### sensors
-Unlike the [console](./console.md#sensors), WebUI takes all the configured [sensors](./sensors-and-switches.md) as a part of the implied configuration.
+Unlike the [console](./console.md#sensors), WebUI takes all the configured [sensors](./sensors-switches-fans.md) as a part of the implied configuration.
 
 ### units