Merge branch 'develop' into feat/intelligent-current-state

.github/actions/setup/action.yml

@@ -0,0 +1,14 @@
+name: Setup dependencies
+description: Sets up required dependencies
+runs:
+  using: composite
+  steps:
+    - name: Install dependencies
+      run: sudo apt install libffi-dev libncurses5-dev zlib1g zlib1g-dev libssl-dev libreadline-dev libbz2-dev libsqlite3-dev
+      shell: bash
+    - name: asdf_install
+      uses: asdf-vm/actions/install@v3
+    - name: Install Python modules
+      run: |
+        pip install -r requirements.test.txt
+      shell: bash

.github/workflows/docs.yml

@@ -6,6 +6,10 @@ on:
       - 'mkdocs.yml'
       - '_docs/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 env:
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -30,7 +34,7 @@ jobs:
           restore-keys: |
             mkdocs-material-
       - run: pip install -r requirements.txt
-      - run: mkdocs build --strict 
+      - run: mkdocs build
 
   deploy_docs:
     if: ${{ github.repository_owner == 'BottlecapDave' && (github.event_name == 'workflow_dispatch' || github.ref == 'refs/heads/main') }}

.github/workflows/main.yml

@@ -16,6 +16,11 @@ on:
     paths-ignore:
       - 'mkdocs.yml'
       - '_docs/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   validate:
     if: ${{ github.event_name != 'schedule' || github.repository_owner == 'BottlecapDave' }}
@@ -37,11 +42,8 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: asdf_install
-        uses: asdf-vm/actions/install@v3
-      - name: Install Python modules
-        run: |
-          pip install -r requirements.test.txt
+      - name: Setup
+        uses: ./.github/actions/setup
       - name: Run unit tests
         run: |
           python -m pytest tests/unit
@@ -55,11 +57,8 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: asdf_install
-        uses: asdf-vm/actions/install@v3
-      - name: Install Python modules
-        run: |
-          pip install -r requirements.test.txt
+      - name: Setup
+        uses: ./.github/actions/setup
       - name: Run integration tests
         run: |
           python -m pytest tests/integration

CHANGELOG.md

@@ -1,3 +1,20 @@
+# [13.4.0](https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/compare/v13.3.0...v13.4.0) (2024-12-26)
+
+
+### Bug Fixes
+
+* Fixed state class for current total consumption sensors (5 minutes dev time) ([9af97a5](https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/commit/9af97a54b7a9dfb091f4e48f0cd66f758e7e2629))
+* Updated total consumption sensors to ignore zero based results reported by home pro (10 minute dev time) ([78748d1](https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/commit/78748d169887227de1a2f1f8bc73dfd1bf281190))
+
+
+### Features
+
+* Added ability to apply weightings to rates from external sources for use with target rate and rolling target rate sensors (4 hours 30 minutes dev time) ([9350c3f](https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/commit/9350c3fbdb46514033a175e1db7e521b2fc07835))
+* Added support for INDRA intelligent provider (5 minutes dev time) ([7c3596c](https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/commit/7c3596cc920957dfe7ca23e42828aad826e44c43))
+* Updated Home Pro config to support custom API being optional if certain features are not required (see docs for more information) (45 minutes dev time) ([8b94c7d](https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/commit/8b94c7d15109476acb53f930762c7ee17a4e0ed6))
+* Updated Home Pro to contact local API directly instead of via custom API (45 minutes dev time) ([0ace45e](https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/commit/0ace45e325bdbb104a24787bc26556e09e3d804e))
+* Updated target rates to support additional re-evaluation modes for target times. This is to assist with external weightings changing (30 minutes dev time) ([05db8c2](https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/commit/05db8c2ffcbdc39341a6e419c77bf9113a6aebe6))
+
 # [13.3.0](https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/compare/v13.2.1...v13.3.0) (2024-12-16)
 
 

_docs/entities/home_pro.md

@@ -13,4 +13,8 @@ Once configured, the following entities will retrieve data locally from your Oct
 
 `text.octopus_energy_{{ACCOUNT_ID}}_home_pro_screen`
 
-Allows you to set scrolling text for the home pro device. If the text is greater than 3 characters, then it will scroll on the device, otherwise it will be statically displayed.
+!!! info
+
+    This is only available if you have setup the [Custom API](../setup/account.md#home-pro).
+
+Allows you to set scrolling text on the home pro device. If the text is greater than 3 characters, then it will scroll on the device, otherwise it will be statically displayed.

_docs/entities/intelligent.md

@@ -52,6 +52,27 @@ Each item in `planned_dispatch` or `completed_dispatches` have the following att
 
     You can use the [data_last_retrieved sensor](./diagnostics.md#intelligent-dispatches-data-last-retrieved) to determine when the underlying data was last retrieved from the OE servers.
 
+### Current State
+
+`sensor.octopus_energy_{{ACCOUNT_ID}}_intelligent_state`
+
+This sensor displays the current state of your intelligent provider. The value of this sensor can be one of the following
+
+* `AUTHENTICATION_PENDING` - ready to start authentication and authorization, or auth is in progress.
+* `AUTHENTICATION_FAILED` - failed to connect and ready to restart authentication and authorization.
+* `AUTHENTICATION_COMPLETE`- ready to start test (if needed) or pending live where auth or telemetry is delayed.
+* `TEST_CHARGE_IN_PROGRESS` - connection and smart control test has successfully started and is occurring.
+* `TEST_CHARGE_FAILED` - connection or smart control test has failed or could not start, ready to retry test.
+* `TEST_CHARGE_NOT_AVAILABLE` - not currently capable of smart control test (e.g. away from home or unplugged).
+* `SETUP_COMPLETE` - test is complete (if needed) and device is live, but not ready for smart control.
+* `SMART_CONTROL_CAPABLE` - live and ready for smart control (e.g. at home and plugged in) but none is scheduled.
+* `SMART_CONTROL_IN_PROGRESS` - smart control (e.g. smart charging) is scheduled or is currently occurring.
+* `BOOSTING` - user has overridden the schedule to immediately boost (e.g. bump charge now).
+* `SMART_CONTROL_OFF` - smart control has been (temporarily) disabled (e.g. by the user with holiday mode).
+* `SMART_CONTROL_NOT_AVAILABLE` - not currently capable of smart control (e.g. away from home or unplugged).
+* `LOST_CONNECTION` - lost connection to the device, ready to re-auth (if not temporary / automatic fix).
+* `RETIRED` - / de-authed (re-auth not possible, re-register device to onboard again).
+
 ### Bump Charge
 
 `switch.octopus_energy_{{ACCOUNT_ID}}_intelligent_bump_charge`
@@ -127,5 +148,5 @@ If you're moving to this integration from [megakid/ha_octopus_intelligent](https
 * `sensor.octopus_intelligent_offpeak_end` - The default off peak end date/time can be found as an attribute on the [off peak sensor](./electricity.md#off-peak). This can be extracted using a [template sensor](https://www.home-assistant.io/integrations/template/).
 * `switch.octopus_intelligent_bump_charge` - Use the [bump charge sensor](#bump-charge)
 * `switch.octopus_intelligent_smart_charging` - Use the [smart charge sensor](#smart-charge)
-* `select.octopus_intelligent_target_time` - Use the [ready time sensor](#ready-time)
-* `select.octopus_intelligent_target_soc` - Use the [charge limit sensor](#charge-limit)
+* `select.octopus_intelligent_target_time` - Use the [target time sensor](#target-time)
+* `select.octopus_intelligent_target_soc` - Use the [charge target sensor](#charge-target)

_docs/events.md

@@ -126,34 +126,6 @@ This is fired when the [previous consumption's](./entities/electricity.md#previo
         New rates available for {{ trigger.event.data.mpan }}. Starting value is {{ trigger.event.data.rates[0]["value_inc_vat"] }}
 ```
 
-## Electricity Previous Consumption Override Rates
-
-`octopus_energy_electricity_previous_consumption_override_rates`
-
-This is fired when the [previous consumption override's](./entities/electricity.md#tariff-overrides) rates are updated.
-
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `rates` | `array` | The list of rates applicable for the previous consumption override |
-| `tariff_code` | `string` | The tariff code associated with previous consumption override's rates |
-| `mpan` | `string` | The mpan of the meter associated with these rates |
-| `serial_number` | `string` | The serial number of the meter associated with these rates |
-
-### Automation Example
-
-```yaml
-- trigger:
-  - platform: event
-    event_type: octopus_energy_electricity_previous_consumption_override_rates
-  condition: []
-  action:
-  - service: persistent_notification.create
-    data:
-      title: "Rates Updated"
-      message: >
-        New rates available for {{ trigger.event.data.mpan }}. Starting value is {{ trigger.event.data.rates[0]["value_inc_vat"] }}
-```
-
 ## Gas Current Day Rates
 
 `octopus_energy_gas_current_day_rates`
@@ -278,34 +250,6 @@ This is fired when the [previous consumption's](./entities/gas.md#previous-accum
         New rates available for {{ trigger.event.data.mprn }}. Starting value is {{ trigger.event.data.rates[0]["value_inc_vat"] }}
 ```
 
-## Gas Previous Consumption Override Rates
-
-`octopus_energy_gas_previous_consumption_override_rates`
-
-This is fired when the [previous consumption override's](./entities/gas.md#tariff-overrides) rates are updated.
-
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `rates` | `array` | The list of rates applicable for the previous consumption override |
-| `tariff_code` | `string` | The tariff code associated with previous consumption override's rates |
-| `mprn` | `string` | The mprn of the meter associated with these rates |
-| `serial_number` | `string` | The serial number of the meter associated with these rates |
-
-### Automation Example
-
-```yaml
-- trigger:
-  - platform: event
-    event_type: octopus_energy_gas_previous_consumption_override_rates
-  condition: []
-  action:
-  - service: persistent_notification.create
-    data:
-      title: "Rates Updated"
-      message: >
-        New rates available for {{ trigger.event.data.mprn }}. Starting value is {{ trigger.event.data.rates[0]["value_inc_vat"] }}
-```
-
 ## New Saving Session
 
 `octopus_energy_new_octoplus_saving_session`

_docs/services.md

@@ -235,4 +235,36 @@ Allows you to adjust the consumption for any given period recorded by a [cost tr
 | ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
 | `target.entity_id`       | `no`     | The name of the cost tracker sensor(s) that should be updated (e.g. `sensor.octopus_energy_cost_tracker_{{COST_TRACKER_NAME}}`). |
 | `data.date`              | `no`     | The date of the data within the cost tracker to be adjusted. |
-| `data.consumption`       | `no`     | The new consumption recorded against the specified date. |
+| `data.consumption`       | `no`     | The new consumption recorded against the specified date. |
+
+## octopus_energy.register_rate_weightings
+
+Allows you to configure weightings against rates at given times using factors external to the integration. These are applied when calculating [target rates](./setup/target_rate.md#external-rate-weightings) or [rolling target rates](./setup/rolling_target_rate.md#external-rate-weightings).
+
+Rate weightings are added to any existing rate weightings that have been previously configured. Any rate weightings that are more than 24 hours old are removed. Any rate weightings for periods that have been previously configured are overridden. 
+
+| Attribute                | Optional | Description                                                                                                           |
+| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `target.entity_id`       | `no`     | The name of the electricity current rate sensor for the rates the weighting should be applied to (e.g. `sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_current_rate`). |
+| `data.weightings`        | `no`     | The collection of weightings to add. Each item in the array should represent a given 30 minute period. Example array is `[{ "start": "2025-01-01T00:00:00Z", "end": "2025-01-01T00:30:00Z", "weighting": 0.1 }]` |
+
+### Automation Example
+
+This automation adds weightings based on the national grids carbon intensity, as provided by [Carbon Intensity](https://github.com/BottlecapDave/HomeAssistant-CarbonIntensity).
+
+```yaml
+- alias: Carbon Intensity Rate Weightings
+  triggers:
+  - platform: state
+    entity_id: event.carbon_intensity_national_current_day_rates
+  actions:
+  - action: octopus_energy.register_rate_weightings
+    target:
+      entity_id: sensor.octopus_energy_electricity_xxx_xxx_current_rate
+    data:
+      weightings: >
+        {% set forecast = state_attr('event.carbon_intensity_national_current_day_rates', 'rates') + state_attr('event.carbon_intensity_national_next_day_rates', 'rates') %}
+        {% set ns = namespace(list = [])  %}   {%- for a in forecast -%} 
+          {%- set ns.list = ns.list + [{ "start": a.from.strftime('%Y-%m-%dT%H:%M:%SZ'), "end": a.to.strftime('%Y-%m-%dT%H:%M:%SZ'), "weighting": a.intensity_forecast | float }] -%} 
+        {%- endfor -%} {{ ns.list }}
+```

_docs/setup/account.md

@@ -14,7 +14,7 @@ If you are lucky enough to own an [Octopus Home Mini](https://octopus.energy/blo
 
     Export sensors are not provided as the data is not available
 
-See [electricity entities](../entities/electricity.md#home-mini-entities) and [gas entities](../entities/gas.md#home-mini-entities) for more information.
+See [electricity entities](../entities/electricity.md#home-minipro-entities) and [gas entities](../entities/gas.md#home-minipro-entities) for more information.
 
 ### Refresh Rate In Minutes
 
@@ -57,7 +57,13 @@ If you are lucky enough to own an [Octopus Home Pro](https://forum.octopus.energ
 
 ### Prerequisites
 
-The Octopus Home Pro has an internal API which is not currently exposed. In order to make this data available for consumption by this integration you will need to expose a custom API on your device by following the instructions below
+The Octopus Home Pro has a local API which is used to get consumption and demand data. If this is all you need, then you can jump straight to the [settings](./account.md#settings).
+
+However, there is also an internal API for setting the display which is not currently exposed. In order to make this available for consumption by this integration you will need to expose a custom API on your device by following the instructions below
+
+!!! warning
+
+    This custom API can only be configured with the default Home Pro setup. If you set up Home Assistant on your Home Pro device, then it won't be possible to expose this custom API.
 
 1. Follow [the instructions](https://github.com/OctopusSmartEnergy/Home-Pro-SDK-Public/blob/main/Home.md#sdk) to connect to your Octopus Home Pro via SSH
 2. Run the command `wget -O setup_ha.sh https://raw.githubusercontent.com/BottlecapDave/HomeAssistant-OctopusEnergy/main/home_pro_server/setup.sh` to download the installation script
@@ -90,8 +96,9 @@ export SERVER_AUTH_TOKEN=thisisasecrettoken # Replace with your own unique strin
 
 ### Settings
 
-Once the API has been configured, you will need to set the address to the IP address of your Octopus Home Pro followed by the port 8000 (e.g. `http://192.168.1.2:8000`) and the api key to the value you set `SERVER_AUTH_TOKEN` to.
+Once the API has been configured, you will need to set the address to the IP address of your Octopus Home Pro (e.g. `http://192.168.1.2`).
 
+If you have setup the custom API, then you will need to set api key to the value you set `SERVER_AUTH_TOKEN` to.
 
 ### Entities
 

_docs/setup/energy_dashboard.md

@@ -21,6 +21,21 @@ If you have an Octopus Home Mini and a smart electricity meter you can obtain li
 
     Data will only appear in the energy dashboard from the point you configure the Home Mini within the integration. It doesn't backport any data.
 
+#### Octopus Home Pro
+
+If you have an Octopus Home Pro and a smart electricity meter you can obtain live meter reading data into Home Assistant:
+
+1. Go to your [energy dashboard configuration](https://my.home-assistant.io/redirect/config_energy/)
+2. Click `Add Consumption` under `Electricity grid`
+3. For `Consumed energy` you want `sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_current_total_consumption`
+4. Choose the `Use an entity with current price` option and the entity is `sensor.octopus_energy_electricity_{{METER_SERIAL_NUMBER}}_{{MPAN_NUMBER}}_current_rate`
+
+![HA modal electricity example](../assets/total_consumption_electricity.png){: style="height:500px"}
+
+!!! note
+
+    Data will only appear in the energy dashboard from the point you configure the Home Pro within the integration. It doesn't backport any data.
+
 #### Alternative methods to measure current Home Consumption
 
 If you don't have an Octopus Home mini you may have another way to get live or near-live daily consumption into Home Assistant such as a Hildebrand Glow In Home Display, an Energy CT Clamp such as the Shelly EM on the incoming supply cable, or your existing Solar/Battery inverter may have a sensor that provides Grid import information that you can use in the Energy dashboard.
@@ -33,19 +48,36 @@ Do be aware that as you are not directly capturing the smart meter readings in H
 
 ### For Gas
 
-![HA modal gas example](../assets/current_consumption_gas.png){: style="height:500px"}
+#### Octopus Home Mini
 
-This is only available if you have an Octopus Home Mini and a smart gas meter.
+If you have an Octopus Home Mini and a smart electricity meter you can obtain live meter reading data into Home Assistant:
 
 1. Go to your [energy dashboard configuration](https://my.home-assistant.io/redirect/config_energy/)
 2. Click `Add Gas Source` under `Gas consumption`
 3. For `Gas usage` you want `sensor.octopus_energy_gas_{{METER_SERIAL_NUMBER}}_{{MPRN_NUMBER}}_current_accumulative_consumption_kwh`
 4. For `Use an entity tracking the total costs` option you want `sensor.octopus_energy_gas_{{METER_SERIAL_NUMBER}}_{{MPRN_NUMBER}}_current_accumulative_cost` 
 
+![HA modal gas example](../assets/current_consumption_gas.png){: style="height:500px"}
+
 !!! note
 
     Data will only appear in the energy dashboard from the point you configure the Home Mini within the integration. It doesn't backport any data.
 
+#### Octopus Home Pro
+
+If you have an Octopus Home Pro and a smart gas meter you can obtain live meter reading data into Home Assistant:
+
+1. Go to your [energy dashboard configuration](https://my.home-assistant.io/redirect/config_energy/)
+2. Click `Add Consumption` under `Electricity grid`
+3. For `Consumed energy` you want `sensor.octopus_energy_gas_{{METER_SERIAL_NUMBER}}_{{MPRN_NUMBER}}_current_total_consumption_kwh`
+4. Choose the `Use an entity with current price` option and the entity is `sensor.octopus_energy_gas_{{METER_SERIAL_NUMBER}}_{{MPRN_NUMBER}}_current_rate`
+
+![HA modal electricity example](../assets/total_consumption_gas.png){: style="height:500px"}
+
+!!! note
+
+    Data will only appear in the energy dashboard from the point you configure the Home Pro within the integration. It doesn't backport any data.
+
 ## Previous Day Consumption
 
 If none of the methods above for feeding Current Day Consumption information into the Energy dashboard are suitable, you can add `previous consumption` information to the dashboard, using information retrieved via the Octopus API. Note that the consumption information is only available on the following day so "today's" Energy dashboard will show zero values, but "yesterday's", "day before", etc will show the correct consumption for each day.