Next release (#1140)

.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

_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

@@ -127,5 +127,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.

_docs/setup/rolling_target_rate.md

@@ -136,6 +136,12 @@ If we had a target rate sensor of 1 hour, the following would occur with the fol
 | 0.2 | `2024-11-26 11:00:00`-`2024-11-26 12:00:00` | Cheapest period would be 0.1p, free electricity period would be 0.02p. |
 | 0 | `2024-11-26 11:00:00`-`2024-11-26 12:00:00` | Cheapest period would be 0.1p, free electricity period would be 0p. This will always go for free electricity sessions if available. |
 
+## External Rate Weightings
+
+There may be times when you want to calculate the best times using factors that are external to data available via the integration, like grid carbon intensity or solar forecasts. This is where external rate weightings come in. Using the [Register Rate Weightings service](../services.md#octopus_energyregister_rate_weightings), you can configured weightings against given rates which are then multiplied against the associated rate. For example if you have a weighting of `2` set and a rate of `0.20`, then the rate will be interpreted as `0.40` during calculation. 
+
+These weightings are used in addition to any [weightings](#weighting) configured against the sensor and [free electricity weightings](#free-electricity-weighting). For example if you have rate weight of `2`, a rate of `0.20`, a sensor weight of `3` and free electricity weight of `0.5`, then rate will be interpreted as `0.6` (2 * 0.20 * 3 * 0.5).
+
 ## Attributes
 
 The following attributes are available on each sensor