Add update_program service for editing program config (#388)

sebr · web-flow · commit 1bd2cda21a67 · 2026-04-17T10:49:09.000+10:00
* Add update_program service for editing program configuration

Exposes a new `bhyve.update_program` service that PUTs to
`sprinkler_timer_programs/{program_id}` with only the changed fields
(start_times and/or frequency). The method on BHyveProgramSwitch
validates input, rejects smart programs, and requires at least one
field to be provided.

* Send full program payload when updating config

The B-hyve API rejects partial PUTs to sprinkler_timer_programs/{id}
with a 400. Start with the filtered program data (same keys used by
the enabled-toggle path) and override only the fields the caller is
changing.
diff --git a/README.md b/README.md
@@ -184,7 +184,30 @@ This integration provides the following services:
 | `bhyve.disable_rain_delay`        | `entity_id` - device to enable a rain delay. This can reference either a zone or rain delay switch                                                          | Cancel a rain delay on a given device                            |
 | `bhyve.set_manual_preset_runtime` | `entity_id` - zone(s) entity to set the preset runtime. This should be a reference to a zone switch entity <br/> `minutes` - number of minutes to water for | Set the default time a switch is activated for when enabled. Support for this service appears to be patchy, and it has been difficult to identify the devices or under which conditions it works      |
 | `bhyve.set_smart_watering_soil_moisture` | `entity_id` - zone(s) entity to set the moisture level for. This should be a reference to a zone switch entity <br/> `percentage` - soil moisture level between 0 - 100 | Set Smart Watering soil moisture level for a zone     |
-| `bhyve.start_program` | `entity_id` - program entity to start. This should be a reference to a program switch entity | Starts a pre-configured watering program. Watering programs cannot be created nor configured via this integration, and require the B-Hyve app to create or modify |
+| `bhyve.start_program` | `entity_id` - program entity to start. This should be a reference to a program switch entity | Starts a pre-configured watering program. Watering programs cannot be created via this integration and must first be set up in the B-Hyve app |
+| `bhyve.update_program` | `entity_id` - program switch to update <br/> `start_times` - _(optional)_ list of watering start times in `HH:MM` format <br/> `frequency` - _(optional)_ frequency configuration object (must include a `type`, e.g. `days`, `interval`, `even`, `odd`) | Update the `start_times` and/or `frequency` of an existing non-smart program. At least one of `start_times` or `frequency` must be provided |
+
+### `bhyve.update_program` example
+
+```yaml
+service: bhyve.update_program
+data:
+  entity_id: switch.front_yard_usual_programming_program
+  start_times:
+    - "06:00"
+    - "18:30"
+  frequency:
+    type: days
+    days: [1, 3, 5]
+    interval: 1
+    interval_hours: 0
+```
+
+The `frequency` object mirrors the B-Hyve API structure. Common `type` values:
+
+- `days` with `days: [0-6]` (where 0 is Sunday) to water on specific weekdays
+- `interval` with `interval: N` to water every N days
+- `even` / `odd` to water on even or odd calendar days
 
 ## Python Script
 
diff --git a/custom_components/bhyve/services.yaml b/custom_components/bhyve/services.yaml
@@ -57,4 +57,17 @@ start_program:
   fields:
     entity_id:
       description: Program
-      example: "valve.front_yard_program"
+      example: "valve.backyard_zone"
+
+update_program:
+  description: Update a program's configuration. Provide at least one of start_times or frequency
+  fields:
+    entity_id:
+      description: Program switch
+      example: "switch.front_yard_program"
+    start_times:
+      description: List of watering start times in HH:MM format
+      example: '["06:00", "18:00"]'
+    frequency:
+      description: Frequency configuration. `type` is required (e.g. days, interval, even, odd)
+      example: '{"type": "days", "days": [1, 3, 5], "interval": 1, "interval_hours": 0}'
diff --git a/custom_components/bhyve/strings.json b/custom_components/bhyve/strings.json
@@ -133,6 +133,24 @@
           "description": "The program to start"
         }
       }
+    },
+    "update_program": {
+      "name": "Update program",
+      "description": "Update a program's configuration. Provide at least one of start_times or frequency",
+      "fields": {
+        "entity_id": {
+          "name": "Program switch",
+          "description": "The program switch to update"
+        },
+        "start_times": {
+          "name": "Start times",
+          "description": "List of watering start times in HH:MM format"
+        },
+        "frequency": {
+          "name": "Frequency",
+          "description": "Frequency configuration object. Must include a 'type' key (e.g. days, interval, even, odd)"
+        }
+      }
     }
   },
   "entity": {
diff --git a/custom_components/bhyve/switch.py b/custom_components/bhyve/switch.py
@@ -4,15 +4,20 @@
 
 import datetime
 import logging
+import re
 from dataclasses import dataclass
 from datetime import timedelta
 from typing import TYPE_CHECKING, Any
 
+import voluptuous as vol
 from homeassistant.components.switch import (
     SwitchEntity,
     SwitchEntityDescription,
 )
-from homeassistant.const import EntityCategory
+from homeassistant.components.switch.const import DOMAIN as SWITCH_DOMAIN
+from homeassistant.const import ATTR_ENTITY_ID, EntityCategory
+from homeassistant.exceptions import ServiceValidationError
+from homeassistant.helpers import config_validation as cv
 
 from . import BHyveCoordinatorEntity
 from .const import (
@@ -26,7 +31,7 @@
 
 if TYPE_CHECKING:
     from homeassistant.config_entries import ConfigEntry
-    from homeassistant.core import HomeAssistant
+    from homeassistant.core import HomeAssistant, ServiceCall
     from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
     from .coordinator import BHyveDataUpdateCoordinator
@@ -78,6 +83,42 @@
     "start_times",
 }
 
+# Service constants
+SERVICE_UPDATE_PROGRAM = "update_program"
+ATTR_START_TIMES = "start_times"
+ATTR_FREQUENCY = "frequency"
+
+_TIME_RE = re.compile(r"^([01]\d|2[0-3]):[0-5]\d$")
+
+
+def _validate_time_string(value: Any) -> str:
+    """Validate an HH:MM time string."""
+    if not isinstance(value, str) or not _TIME_RE.match(value):
+        msg = f"Invalid time '{value}', expected HH:MM"
+        raise vol.Invalid(msg)
+    return value
+
+
+FREQUENCY_SCHEMA = vol.Schema(
+    {
+        vol.Required("type"): cv.string,
+        vol.Optional("days"): [vol.All(int, vol.Range(min=0, max=6))],
+        vol.Optional("interval"): vol.All(int, vol.Range(min=0)),
+        vol.Optional("interval_hours"): vol.All(int, vol.Range(min=0)),
+    },
+    extra=vol.ALLOW_EXTRA,
+)
+
+UPDATE_PROGRAM_SCHEMA = vol.Schema(
+    {
+        vol.Required(ATTR_ENTITY_ID): cv.comp_entity_ids,
+        vol.Optional(ATTR_START_TIMES): vol.All(
+            cv.ensure_list, [_validate_time_string]
+        ),
+        vol.Optional(ATTR_FREQUENCY): FREQUENCY_SCHEMA,
+    }
+)
+
 
 @dataclass(frozen=True, kw_only=True)
 class BHyveSwitchEntityDescription(SwitchEntityDescription):
@@ -170,6 +211,31 @@ async def async_setup_entry(
 
     async_add_entities(switches)
 
+    async def async_update_program_service(call: ServiceCall) -> None:
+        """Handle the update_program service call."""
+        entity_ids = call.data.get(ATTR_ENTITY_ID) or []
+        params = {k: v for k, v in call.data.items() if k != ATTR_ENTITY_ID}
+
+        component = hass.data.get(SWITCH_DOMAIN)
+        if component is None:
+            _LOGGER.warning("Switch component not available, cannot update program")
+            return
+
+        for entity_id in entity_ids:
+            entity = component.get_entity(entity_id)
+            if not isinstance(entity, BHyveProgramSwitch):
+                msg = f"Entity {entity_id} is not a BHyve program switch"
+                raise ServiceValidationError(msg)
+            await entity.async_update_program_config(**params)
+
+    if not hass.services.has_service(DOMAIN, SERVICE_UPDATE_PROGRAM):
+        hass.services.async_register(
+            DOMAIN,
+            SERVICE_UPDATE_PROGRAM,
+            async_update_program_service,
+            schema=UPDATE_PROGRAM_SCHEMA,
+        )
+
     # Listen for new programs created via WebSocket
     async def async_handle_program_created(event: Any) -> None:
         """Handle creation of new programs."""
@@ -260,6 +326,36 @@ async def _update_program(self, *, enabled: bool) -> None:
         program["enabled"] = enabled
         await self.coordinator.client.update_program(self._program_id, program)
 
+    async def async_update_program_config(
+        self,
+        start_times: list[str] | None = None,
+        frequency: dict | None = None,
+    ) -> None:
+        """Update start times and/or frequency on a non-smart program."""
+        if self.program_data.get("is_smart_program"):
+            msg = "Cannot update configuration of a smart program"
+            raise ServiceValidationError(msg)
+
+        if start_times is None and frequency is None:
+            msg = "At least one of start_times or frequency must be provided"
+            raise ServiceValidationError(msg)
+
+        program = BHyveTimerProgram(
+            {k: v for k, v in self.program_data.items() if k in PROGRAM_UPDATE_KEYS}
+        )
+        changed: list[str] = []
+        if start_times is not None:
+            program["start_times"] = start_times
+            changed.append("start_times")
+        if frequency is not None:
+            program["frequency"] = frequency
+            changed.append("frequency")
+
+        _LOGGER.info(
+            "Updating program %s, changed fields: %s", self._program_id, changed
+        )
+        await self.coordinator.client.update_program(self._program_id, program)
+
     async def start_program(self) -> None:
         """Begins running a program."""
         program_payload = self.program_data.get("program")
diff --git a/custom_components/bhyve/translations/en.json b/custom_components/bhyve/translations/en.json
@@ -133,6 +133,24 @@
           "description": "The program to start"
         }
       }
+    },
+    "update_program": {
+      "name": "Update program",
+      "description": "Update a program's configuration. Provide at least one of start_times or frequency",
+      "fields": {
+        "entity_id": {
+          "name": "Program switch",
+          "description": "The program switch to update"
+        },
+        "start_times": {
+          "name": "Start times",
+          "description": "List of watering start times in HH:MM format"
+        },
+        "frequency": {
+          "name": "Frequency",
+          "description": "Frequency configuration object. Must include a 'type' key (e.g. days, interval, even, odd)"
+        }
+      }
     }
   },
   "entity": {
diff --git a/tests/test_switch.py b/tests/test_switch.py
