v0.4.1

docs/API.md

@@ -55,58 +55,110 @@ curl -X POST "$BASE/api/discovery" -H "$AUTH" -H 'Content-Type: application/json
 
 Supported modes: `auto`, `cool`, `dry`, `fan`, `heat`. Fan speed: `0..5`. Physical GREE Celsius setpoints are normalized to whole degrees in the `8..30°C` range.
 
-## Zone
+## Smart thermostat / house control
+
+The controller separates the seasonal house mode from per-zone profiles. Normal operation uses setpoint modulation: units remain powered while the controller moves the device target between an active and satisfied setpoint. `off` is the explicit hard-off house mode.
+
+```bash
+curl -X POST "$BASE/api/house/control" -H "$AUTH" -H 'Content-Type: application/json' \
+  -d '{"mode":"cool"}'
+
+curl -X POST "$BASE/api/house/preset" -H "$AUTH" -H 'Content-Type: application/json' \
+  -d '{"preset":"sleep"}'
+```
+
+House modes: `cool`, `heat`, `off`. House presets: `auto`, `comfort`, `sleep`, `away`. A non-`auto` house preset creates temporary per-zone overrides that expire at each zone's next schedule boundary.
+
+A zone stores separate profile temperatures for both seasons:
 
 ```json
 {
-  "name": "Living room",
+  "name": "Paweł",
   "device_id": "gree-aabbccddeeff",
   "enabled": true,
   "mode": "cool",
+  "inherit_house_mode": true,
   "setpoint": 23.0,
+  "cool_comfort_setpoint": 23.0,
+  "cool_sleep_setpoint": 24.5,
+  "cool_away_setpoint": 27.0,
+  "heat_comfort_setpoint": 21.0,
+  "heat_sleep_setpoint": 19.0,
+  "heat_away_setpoint": 17.0,
   "hysteresis": 0.6,
-  "min_on_seconds": 180,
-  "min_off_seconds": 180,
+  "min_adjust_seconds": 120,
+  "standby_offset_c": 2.0,
+  "smart_fan": true,
   "sensor_source": "combined",
-  "ha_entity_id": "sensor.living_room_temperature",
+  "ha_entity_id": "sensor.pawel_temperature",
   "external_sensor_weight": 0.4,
   "max_sensor_difference": 3.0
 }
 ```
 
-`sensor_source` supports:
-
-- `device` — GREE indoor sensor only,
-- `combined` — GREE + this zone's HA room sensor,
-- `home_assistant` — this zone's HA room sensor, with GREE fallback.
-
-For `combined` and `home_assistant`, set a per-zone `ha_entity_id`. `external_sensor_weight` is `0.0..1.0`. If a combined sensor pair differs by more than `max_sensor_difference`, the controller falls back to GREE. The returned zone object includes `device_temperature`, `external_temperature`, `current_temperature`, and `control_temperature_source`.
-
-### Quick zone control
+Quick control does not directly fight the schedule engine:
 
 ```bash
+# Sleep now until the next schedule boundary
 curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
-  -d '{"setpoint":21.5,"mode":"heat"}'
+  -d '{"preset":"sleep"}'
+
+# Return to automatic schedule
+curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
+  -d '{"preset":"auto"}'
+
+# Temporary custom room target
+curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
+  -d '{"setpoint":22.5}'
 ```
 
-Fields are optional: `setpoint`, `mode` (`heat`/`cool`) and `enabled`. The zone setpoint may use 0.5°C precision for controller hysteresis; when the quick control changes setpoint/mode, the paired GREE unit is updated immediately while its current power state is preserved.
+`mode` on the quick zone endpoint accepts `house`, `cool`, or `heat`. Global `off` always wins over local zone mode overrides.
 
-## Schedule
+### Ready-made schedule templates
 
-Weekdays use ISO numbers: Monday `1`, Sunday `7`.
+Templates generate normal schedule records and replace the current schedules for the selected zone. Every generated entry remains editable.
+
+```bash
+curl -X POST "$BASE/api/zones/ZONE_ID/schedule-template" -H "$AUTH" -H 'Content-Type: application/json' \
+  -d '{"template":"child"}'
+```
+
+Templates: `family`, `child`, `bedroom`, `workday`, `always`.
+
+Schedules use a profile (`comfort`, `sleep`, `away`) or a custom temperature:
 
 ```json
 {
   "zone_id": "UUID",
-  "name": "Night",
+  "name": "Sleep",
   "enabled": true,
   "weekdays": [1,2,3,4,5,6,7],
-  "start_time": "22:00",
-  "end_time": "06:00",
+  "start_time": "20:30",
+  "end_time": "06:30",
+  "preset": "sleep",
   "setpoint": 24.0
 }
 ```
 
+For non-`custom` schedules, `setpoint` is only a compatibility value; the actual target comes from the zone's seasonal profile.
+
+### Home Assistant outdoor assist and local HTTPS
+
+Runtime settings can specify `home_assistant.outdoor_entity_id` and `outdoor_assist_enabled`. Outdoor temperature never replaces the zone room temperature. It is only used to make active setpoints/fan speed slightly more assertive in extreme weather.
+
+For trusted local Home Assistant servers with self-signed/invalid HTTPS certificates, set:
+
+```json
+{
+  "home_assistant": {
+    "url": "https://10.87.65.2",
+    "allow_invalid_tls": true
+  }
+}
+```
+
+This setting is opt-in and applies only to the controller's outbound Home Assistant sensor client.
+
 ## WebSocket
 
 Connect to `ws://HOST:8787/ws?token=TOKEN`. The first message uses event type `bootstrap`; later events include `device.updated`, `zone.updated`, `settings.updated` and `log.created`.