homewizard · DCSBL · Dec 4, 2025 · Dec 3, 2025 · Dec 3, 2025 · Dec 3, 2025
diff --git a/docs/changelog.mdx b/docs/changelog.mdx
@@ -21,9 +21,23 @@ Feature development of the v1 API has been stopped. No new features will be adde
 
 ### v2
 
--   **2.0.0** - 21-01-2025 - Initial release of the v2 API.
--   **2.0.1** - 30-01-2025 - An issue has been resolved where `energy_import_kwh` and `energy_export_kwh` values in the Plug-In Battery [Measurement API](/docs/v2/measurement#plug-in-battery-hwe-bat) were returning invalid values. The values are now the same as those in the HomeWizard Energy app.
--   **2.1.0** - 01-05-2025 - Support has been added to the P1 Meter to control the Plug-In Battery group mode. See [Plug-In Battery API](/docs/v2/batteries) for more information. This feature is currently in beta.
+#### 2.0.0 - 21-01-2025
+
+-   Initial release of the v2 API.
+
+#### 2.0.1 - 30-01-2025
+
+-   An issue has been resolved where `energy_import_kwh` and `energy_export_kwh` values in the Plug-In Battery [Measurement API](/docs/v2/measurement#plug-in-battery-hwe-bat) were returning invalid values. The values are now the same as those in the HomeWizard Energy app.
+
+#### 2.1.0 - 01-05-2025
+
+-   Support has been added to the P1 Meter to control the Plug-In Battery group mode. See [Plug-In Battery API](/docs/v2/batteries) for more information.
+
+#### 2.2.0 - 01-12-2025 (in beta)
+
+-   You can now set charge and discharge permissions for the Plug-In Battery group via the `permissions` field in the [Plug-In Battery API](/docs/v2/batteries). See the documentation for more information.
+-   A new field has been added to `api/batteries`: `battery_count`, which indicates the number of connected Plug-In Batteries.
+-   When `target_power_w` field in `api/batteries` is updated, it is now pushed over WebSocket connections as well.
 
 ## Subscribe to Updates.
 

diff --git a/docs/introduction.mdx b/docs/introduction.mdx
@@ -39,14 +39,14 @@ To understand the basics of the API, you can read the [getting-started](/docs/ge
 
 The following table shows which devices are supported by the API and which API version they support.
 
-| Device                                  | Device type                                                             | API v1                                                                     | API v2                                                                        |
-| --------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| P1 Meter                                | `HWE-P1`                                                                | <Badge colorName='hw-green' icon="mdi:check" detail='v1'>Supported</Badge> | <Badge colorName='hw-green' icon="mdi:check" detail='2.1.0'>Supported</Badge> |
-| Energy Socket                           | `HWE-SKT`                                                               | <Badge colorName='hw-green' icon="mdi:check" detail='v1'>Supported</Badge> | <Badge colorName='hw-grey' icon="mdi:wrench">In development</Badge>           |
-| Watermeter (Only when powered over USB) | `HWE-WTR`                                                               | <Badge colorName='hw-green' icon="mdi:check" detail='v1'>Supported</Badge> | <Badge colorName='hw-grey' icon="mdi:wrench">In development</Badge>           |
-| kWh Meter (1 phase and 3-phase)         | `HWE-KWH1`,<br /> `HWE-KWH3`,<br />`SDM230-wifi` and<br />`SDM630-wifi` | <Badge colorName='hw-green' icon="mdi:check" detail='v1'>Supported</Badge> | <Badge colorName='hw-green' icon="mdi:check" detail='2.1.0'>Supported</Badge> |
-| Energy Display                          | `HWE-DSP`                                                               | <Badge colorName='hw-grey' icon="mdi:close">Not planned</Badge>            | <Badge colorName='hw-grey' icon="mdi:wrench">In development</Badge>           |
-| Plug-In Battery                         | `HWE-BAT`                                                               | <Badge colorName='hw-grey' icon="mdi:close">Not planned</Badge>            | <Badge colorName='hw-green' icon="mdi:check" detail='2.0.1'>Supported</Badge> |
+| Device                                  | Device type                                                             | API v1                                                                     | API v2                                                                                                                                                                                         |
+| --------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| P1 Meter                                | `HWE-P1`                                                                | <Badge colorName='hw-green' icon="mdi:check" detail='v1'>Supported</Badge> | <Badge colorName='hw-green' icon="mdi:check" detail='2.1.0'>Supported</Badge><Badge colorName='hw-purple' icon="mdi:test-tube" detail='2.2.0'>In beta, available from firmware 6.03xx</Badge>  |
+| Energy Socket                           | `HWE-SKT`                                                               | <Badge colorName='hw-green' icon="mdi:check" detail='v1'>Supported</Badge> | <Badge colorName='hw-grey' icon="mdi:wrench">In development</Badge>                                                                                                                            |
+| Watermeter (Only when powered over USB) | `HWE-WTR`                                                               | <Badge colorName='hw-green' icon="mdi:check" detail='v1'>Supported</Badge> | <Badge colorName='hw-grey' icon="mdi:wrench">In development</Badge>                                                                                                                            |
+| kWh Meter (1 phase and 3-phase)         | `HWE-KWH1`,<br /> `HWE-KWH3`,<br />`SDM230-wifi` and<br />`SDM630-wifi` | <Badge colorName='hw-green' icon="mdi:check" detail='v1'>Supported</Badge> | <Badge colorName='hw-green' icon="mdi:check" detail='2.1.0'>Supported</Badge> <Badge colorName='hw-purple' icon="mdi:test-tube" detail='2.2.0'>In beta, available from firmware 5.01xx</Badge> |
+| Energy Display                          | `HWE-DSP`                                                               | <Badge colorName='hw-grey' icon="mdi:close">Not planned</Badge>            | <Badge colorName='hw-grey' icon="mdi:wrench">In development</Badge>                                                                                                                            |
+| Plug-In Battery                         | `HWE-BAT`                                                               | <Badge colorName='hw-grey' icon="mdi:close">Not planned</Badge>            | <Badge colorName='hw-green' icon="mdi:check" detail='2.0.1'>Supported</Badge>                                                                                                                  |
 
 ## Beta Program.
 

diff --git a/docs/v2/batteries.mdx b/docs/v2/batteries.mdx
@@ -9,7 +9,7 @@ import Badge from '@site/src/components/Badge.js'
 # Batteries `/api/batteries`.
 
 {/* prettier-ignore */}
-<Badge colorName='hw-green' icon='mdi:check' subtext='Requires Firmware 6.0200 or later'>P1 Meter</Badge>
+<Badge colorName='hw-green' icon='mdi:check' subtext='Supported'>P1 Meter</Badge>
 <Badge colorName='hw-grey' icon='mdi:close' subtext='Not supported'>Energy Socket</Badge>
 <Badge colorName='hw-grey' icon='mdi:close' subtext='Not supported'>Energy Display</Badge>
 <Badge colorName='hw-green' icon='mdi:check' subtext='Supported'>kWh Meter</Badge>
@@ -24,25 +24,44 @@ The `/api/batteries` endpoint can be used to retrieve information about the cont
 
 ## Parameters
 
-| Data              | Type   | Access     | Description                                                                         |
-| ----------------- | ------ | ---------- | ----------------------------------------------------------------------------------- |
-| [mode](#mode)     | String | Read/Write | Control mode of the Plug-In Battery. Can be either `zero`, `to_full`, or `standby`. |
-| power_w           | Number | Read-only  | Current combined power consumption/production of the controlled Plug-In Batteries.  |
-| target_power_w    | Number | Read-only  | Target power consumption/production of the controlled Plug-In Batteries.            |
-| max_consumption_w | Number | Read-only  | Maximum allowed consumption power of the controlled Plug-In Batteries.              |
-| max_production_w  | Number | Read-only  | Maximum allowed production power of the controlled Plug-In Batteries.               |
+| Data                        | Availability                                                                     | Type          | Access       | Description                                                                                        |
+| --------------------------- | -------------------------------------------------------------------------------- | ------------- | ------------ | -------------------------------------------------------------------------------------------------- |
+| [mode](#mode)               | <Badge colorName='hw-green' icon="mdi:check" detail='2.1.0'>Available</Badge>    | String        | Read/Write   | Control mode of the Plug-In Battery. Can be either `zero`, `to_full`, or `standby`.                |
+| [permissions](#permissions) | <Badge colorName='hw-purple' icon="mdi:test-tube" detail='2.2.0'>In beta</Badge> | Array[String] | Read/Write\* | Permissions to allow charging, discharging, both, or neither. _Note: Read-only in `to_full` mode._ |
+| battery_count               | <Badge colorName='hw-purple' icon="mdi:test-tube" detail='2.2.0'>In beta</Badge> | Number        | Read-only    | Number of connected Plug-In Batteries.                                                             |
+| power_w                     | <Badge colorName='hw-green' icon="mdi:check" detail='2.1.0'>Available</Badge>    | Number        | Read-only    | Current combined power consumption/production of the controlled Plug-In Batteries.                 |
+| target_power_w              | <Badge colorName='hw-green' icon="mdi:check" detail='2.1.0'>Available</Badge>    | Number        | Read-only    | Target power consumption/production of the controlled Plug-In Batteries.                           |
+| max_consumption_w           | <Badge colorName='hw-green' icon="mdi:check" detail='2.1.0'>Available</Badge>    | Number        | Read-only    | Maximum allowed consumption power of the controlled Plug-In Batteries.                             |
+| max_production_w            | <Badge colorName='hw-green' icon="mdi:check" detail='2.1.0'>Available</Badge>    | Number        | Read-only    | Maximum allowed production power of the controlled Plug-In Batteries.                              |
 
-## Mode.
+## Mode
 
 The group of connected batteries can be controlled in three different modes:
 
 -   `zero` - The Plug-In Battery will try to keep the power consumption/production of your home at zero. This means that the Plug-In Battery will charge or discharge to maintain a net-zero power balance. This is the default mode.
 -   `to_full` - All connected Plug-In Batteries will be charged to 100%, regardless of the power consumption/production of your home. When all batteries are fully charged, the Plug-In Battery will switch to the **zero** mode.
--   `standby` - Batteries will enter standby mode. This means that the Plug-In Battery will neither charge nor discharge.
+-   `standby` - Batteries will enter standby mode. This means that the Plug-In Battery will neither charge nor discharge. _For new implementations we recommend to use the `permissions` field to disallow both charging and discharging instead of using this mode._
 
-### Examples
+## Permissions
 
-#### Get Battery Group Information
+The `permissions` field can be used to set specific permissions for charging and discharging the connected Plug-In Batteries. The possible values are:
+
+-   `charge_allowed` - Allow the Plug-In Battery to charge.
+-   `discharge_allowed` - Allow the Plug-In Battery to discharge.
+
+Provide these via an array when updating the `permissions` field. For example, to allow both charging and discharging, set `permissions` to `["charge_allowed", "discharge_allowed"]`. To disallow both, set it to an empty array `[]`.
+
+### Backwards compatibility with `standby` mode
+
+Mode `standby` is exactly the same as mode `zero` with both charging and discharging disallowed, therefore the following rules apply for backwards compatibility:
+
+-   When switching to `standby` mode, the `permissions` field will be set to an empty array `[]`.
+-   When adding a permission to the `permissions` field while in `standby` mode, the mode will automatically switch to `zero`.
+-   `zero` mode with both permissions allowed is the same as the default `zero` mode.
+
+## Examples
+
+### Get Battery Group Information
 
 ```shell title="Request"
 curl https://<IP ADDRESS>/api/batteries \
@@ -57,14 +76,16 @@ Content-Type: application/json
 
 {
     "mode": "zero",
+    "permissions" : ["charge_allowed", "discharge_allowed"],
+    "battery_count": 2,
     "power_w": -404,
     "target_power_w": -400,
     "max_consumption_w": 1600,
     "max_production_w": 800
 }
 ```
 
-#### Change Control Mode
+### Change Control Mode
 
 ```shell title="Request"
 curl https://<IP ADDRESS>/api/batteries \
@@ -81,9 +102,65 @@ Content-Type: application/json
 
 {
     "mode": "to_full",
+    "permissions" : [],
+    "battery_count": 2,
     "power_w": 1599,
     "target_power_w": 1600,
     "max_consumption_w": 1600,
     "max_production_w": 800
 }
 ```
+
+### Change permissions
+
+```shell title="Request"
+curl https://<IP ADDRESS>/api/batteries \
+  --insecure \
+  -H "Authorization: Bearer <TOKEN>" \
+  -H "X-Api-Version: 2" \
+  -d '{"permissions": ["charge_allowed"]}'
+```
+
+```http title="Response"
+https/1.1 200 OK
+Content-Type: application/json
+
+{
+    "mode": "zero",
+    "permissions" : ["charge_allowed"],
+    "battery_count": 2,
+    "power_w": 404,
+    "target_power_w": 400,
+    "max_consumption_w": 1600,
+    "max_production_w": 800
+}
+```
+
+### Change permissions and mode
+
+You can set mode and permissions in one request. You cannot set `mode` to `to_full` and change `permissions` at the same time, as `permissions` is read-only in `to_full` mode.
+
+Mode will change to standby or zero depending on the provided permissions.
+
+```shell title="Request"
+curl https://<IP ADDRESS>/api/batteries \
+  --insecure \
+  -H "Authorization: Bearer <TOKEN>" \
+  -H "X-Api-Version: 2" \
+  -d '{"permissions": ["discharge_allowed"], "mode": "zero"}'
+```
+
+```http title="Response"
+https/1.1 200 OK
+Content-Type: application/json
+
+{
+    "mode": "zero",
+    "permissions": ["discharge_allowed"],
+    "battery_count": 2,
+    "power_w": -404,
+    "target_power_w": -400,
+    "max_consumption_w": 1600,
+    "max_production_w": 800
+}
+```
diff --git a/docs/v2/websocket.mdx b/docs/v2/websocket.mdx
@@ -67,7 +67,7 @@ After authentication, you can subscribe to topics. Topics correspond to availabl
 -   **`user`** - Subscribe to [user list](/docs/v2/authorization#list-users) updates
 -   **`measurement`** - Subscribe to [measurement](/docs/v2/measurement) updates
 -   **`system`** - Subscribe to [system](/docs/v2/system) updates. Only `cloud_enabled` and `status_led_brightness_pct` are updated in real time.
--   **`batteries`** - Subscribe to [battery group](/docs/v2/batteries) updates. Only `mode` is updated in real time.
+-   **`batteries`** - Subscribe to [battery group](/docs/v2/batteries) updates. Only `mode`, `permissions` and `target_power_w` are updated in real time.
 
 ```json title="Example"
 {"type": "subscribe", "data": "system"}