Support program budget in update_program service

Adds an optional `budget` field (0-200%) to the update_program service,
which scales zone run times. Addresses #345.

Author: sebr

README.md

@@ -185,7 +185,7 @@ This integration provides the following services:
 | `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 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` | `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`) <br/> `budget` - _(optional)_ watering budget as a percentage (0-200) | Update the configuration of an existing non-smart program. At least one of `start_times`, `frequency` or `budget` must be provided |
 
 ### `bhyve.update_program` example
 
@@ -201,6 +201,7 @@ data:
     days: [1, 3, 5]
     interval: 1
     interval_hours: 0
+  budget: 75
 ```
 
 The `frequency` object mirrors the B-Hyve API structure. Common `type` values:
@@ -209,6 +210,8 @@ The `frequency` object mirrors the B-Hyve API structure. Common `type` values:
 - `interval` with `interval: N` to water every N days
 - `even` / `odd` to water on even or odd calendar days
 
+The `budget` is a percentage that scales each zone's run time. `100` means unchanged, `50` halves every run time, `200` doubles it. Valid range is 0&ndash;200.
+
 ## Python Script
 
 > [!CAUTION]

custom_components/bhyve/services.yaml

@@ -60,7 +60,7 @@ start_program:
       example: "valve.backyard_zone"
 
 update_program:
-  description: Update a program's configuration. Provide at least one of start_times or frequency
+  description: Update a program's configuration. Provide at least one of start_times, frequency or budget
   fields:
     entity_id:
       description: Program switch
@@ -71,3 +71,6 @@ update_program:
     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}'
+    budget:
+      description: Watering budget as a percentage (0-200). Scales run times up or down
+      example: 50

custom_components/bhyve/strings.json

@@ -136,7 +136,7 @@
     },
     "update_program": {
       "name": "Update program",
-      "description": "Update a program's configuration. Provide at least one of start_times or frequency",
+      "description": "Update a program's configuration. Provide at least one of start_times, frequency or budget",
       "fields": {
         "entity_id": {
           "name": "Program switch",
@@ -149,6 +149,10 @@
         "frequency": {
           "name": "Frequency",
           "description": "Frequency configuration object. Must include a 'type' key (e.g. days, interval, even, odd)"
+        },
+        "budget": {
+          "name": "Budget",
+          "description": "Watering budget as a percentage (0-200). Scales run times up or down"
         }
       }
     }

custom_components/bhyve/switch.py

@@ -87,6 +87,10 @@
 SERVICE_UPDATE_PROGRAM = "update_program"
 ATTR_START_TIMES = "start_times"
 ATTR_FREQUENCY = "frequency"
+ATTR_BUDGET = "budget"
+
+BUDGET_MIN = 0
+BUDGET_MAX = 200
 
 _TIME_RE = re.compile(r"^([01]\d|2[0-3]):[0-5]\d$")
 
@@ -116,6 +120,9 @@ def _validate_time_string(value: Any) -> str:
             cv.ensure_list, [_validate_time_string]
         ),
         vol.Optional(ATTR_FREQUENCY): FREQUENCY_SCHEMA,
+        vol.Optional(ATTR_BUDGET): vol.All(
+            vol.Coerce(int), vol.Range(min=BUDGET_MIN, max=BUDGET_MAX)
+        ),
     }
 )
 
@@ -330,14 +337,15 @@ async def async_update_program_config(
         self,
         start_times: list[str] | None = None,
         frequency: dict | None = None,
+        budget: int | None = None,
     ) -> None:
-        """Update start times and/or frequency on a non-smart program."""
+        """Update configurable fields 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"
+        if start_times is None and frequency is None and budget is None:
+            msg = "At least one of start_times, frequency or budget must be provided"
             raise ServiceValidationError(msg)
 
         program = BHyveTimerProgram(
@@ -350,6 +358,9 @@ async def async_update_program_config(
         if frequency is not None:
             program["frequency"] = frequency
             changed.append("frequency")
+        if budget is not None:
+            program["budget"] = budget
+            changed.append("budget")
 
         _LOGGER.info(
             "Updating program %s, changed fields: %s", self._program_id, changed

custom_components/bhyve/translations/en.json

@@ -136,7 +136,7 @@
     },
     "update_program": {
       "name": "Update program",
-      "description": "Update a program's configuration. Provide at least one of start_times or frequency",
+      "description": "Update a program's configuration. Provide at least one of start_times, frequency or budget",
       "fields": {
         "entity_id": {
           "name": "Program switch",
@@ -149,6 +149,10 @@
         "frequency": {
           "name": "Frequency",
           "description": "Frequency configuration object. Must include a 'type' key (e.g. days, interval, even, odd)"
+        },
+        "budget": {
+          "name": "Budget",
+          "description": "Watering budget as a percentage (0-200). Scales run times up or down"
         }
       }
     }

tests/test_switch.py

@@ -604,6 +604,32 @@ async def test_update_program_config_both_fields(
         assert payload["id"] == TEST_PROGRAM_ID
         assert payload["device_id"] == TEST_DEVICE_ID
 
+    async def test_update_program_config_budget_only(
+        self,
+        mock_sprinkler_device: BHyveDevice,
+        mock_timer_program: BHyveTimerProgram,
+        mock_coordinator: MagicMock,
+    ) -> None:
+        """Test updating only the budget overrides that field only."""
+        description = create_program_switch_description()
+        switch = BHyveProgramSwitch(
+            coordinator=mock_coordinator,
+            device=mock_sprinkler_device,
+            program=mock_timer_program,
+            description=description,
+        )
+
+        await switch.async_update_program_config(budget=150)
+
+        mock_coordinator.client.update_program.assert_called_once()
+        program_id, payload = mock_coordinator.client.update_program.call_args[0]
+        assert program_id == TEST_PROGRAM_ID
+        assert payload["budget"] == 150
+        # Unchanged fields are preserved
+        assert payload["start_times"] == mock_timer_program["start_times"]
+        assert payload["frequency"] == mock_timer_program["frequency"]
+        assert payload["enabled"] is True
+
     async def test_update_program_config_requires_at_least_one_field(
         self,
         mock_sprinkler_device: BHyveDevice,