Skip to content

Commit 1d51f81

Browse files
DCSBLCopilotRonvanderPlas
authored
Update documentation for API 2.2.0 (#219)
* Update batteries documentation with new parameters * Add badges * Tell permissions and target_power_w are now pushed over ws * Add 2.2.0 to API versions * Update changelog * Use correct heading for examples * Remove 'supported' reference in P1 Meter * Revert package.json * Use correct permissions value for to_full * b'eta to beta * Update example * Update docs/v2/batteries.mdx Co-authored-by: Copilot <[email protected]> Signed-off-by: Duco Sebel <[email protected]> * Update docs/v2/batteries.mdx Co-authored-by: Copilot <[email protected]> Signed-off-by: Duco Sebel <[email protected]> * Update docs/v2/batteries.mdx Co-authored-by: Copilot <[email protected]> Signed-off-by: Duco Sebel <[email protected]> * Update docs/v2/batteries.mdx Co-authored-by: RonvanderPlas <[email protected]> Signed-off-by: Duco Sebel <[email protected]> * Formatter --------- Signed-off-by: Duco Sebel <[email protected]> Co-authored-by: Copilot <[email protected]> Co-authored-by: RonvanderPlas <[email protected]>
1 parent 95fb410 commit 1d51f81

File tree

4 files changed

+116
-25
lines changed

4 files changed

+116
-25
lines changed

‎docs/changelog.mdx‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,23 @@ Feature development of the v1 API has been stopped. No new features will be adde
2121

2222
### v2
2323

24-
- **2.0.0** - 21-01-2025 - Initial release of the v2 API.
25-
- **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.
26-
- **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.
24+
#### 2.0.0 - 21-01-2025
25+
26+
- Initial release of the v2 API.
27+
28+
#### 2.0.1 - 30-01-2025
29+
30+
- 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.
31+
32+
#### 2.1.0 - 01-05-2025
33+
34+
- 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.
35+
36+
#### 2.2.0 - 01-12-2025 (in beta)
37+
38+
- 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.
39+
- A new field has been added to `api/batteries`: `battery_count`, which indicates the number of connected Plug-In Batteries.
40+
- When `target_power_w` field in `api/batteries` is updated, it is now pushed over WebSocket connections as well.
2741

2842
## Subscribe to Updates.
2943

‎docs/introduction.mdx‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -39,14 +39,14 @@ To understand the basics of the API, you can read the [getting-started](/docs/ge
3939

4040
The following table shows which devices are supported by the API and which API version they support.
4141

42-
| Device | Device type | API v1 | API v2 |
43-
| --------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
44-
| 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> |
45-
| 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> |
46-
| 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> |
47-
| 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> |
48-
| Energy Display | `HWE-DSP` | <Badge colorName='hw-grey' icon="mdi:close">Not planned</Badge> | <Badge colorName='hw-grey' icon="mdi:wrench">In development</Badge> |
49-
| 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> |
42+
| Device | Device type | API v1 | API v2 |
43+
| --------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
44+
| 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> |
45+
| 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> |
46+
| 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> |
47+
| 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> |
48+
| Energy Display | `HWE-DSP` | <Badge colorName='hw-grey' icon="mdi:close">Not planned</Badge> | <Badge colorName='hw-grey' icon="mdi:wrench">In development</Badge> |
49+
| 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> |
5050

5151
## Beta Program.
5252

‎docs/v2/batteries.mdx‎

Lines changed: 90 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import Badge from '@site/src/components/Badge.js'
99
# Batteries `/api/batteries`.
1010

1111
{/* prettier-ignore */}
12-
<Badge colorName='hw-green' icon='mdi:check' subtext='Requires Firmware 6.0200 or later'>P1 Meter</Badge>
12+
<Badge colorName='hw-green' icon='mdi:check' subtext='Supported'>P1 Meter</Badge>
1313
<Badge colorName='hw-grey' icon='mdi:close' subtext='Not supported'>Energy Socket</Badge>
1414
<Badge colorName='hw-grey' icon='mdi:close' subtext='Not supported'>Energy Display</Badge>
1515
<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
2424

2525
## Parameters
2626

27-
| Data | Type | Access | Description |
28-
| ----------------- | ------ | ---------- | ----------------------------------------------------------------------------------- |
29-
| [mode](#mode) | String | Read/Write | Control mode of the Plug-In Battery. Can be either `zero`, `to_full`, or `standby`. |
30-
| power_w | Number | Read-only | Current combined power consumption/production of the controlled Plug-In Batteries. |
31-
| target_power_w | Number | Read-only | Target power consumption/production of the controlled Plug-In Batteries. |
32-
| max_consumption_w | Number | Read-only | Maximum allowed consumption power of the controlled Plug-In Batteries. |
33-
| max_production_w | Number | Read-only | Maximum allowed production power of the controlled Plug-In Batteries. |
27+
| Data | Availability | Type | Access | Description |
28+
| --------------------------- | -------------------------------------------------------------------------------- | ------------- | ------------ | -------------------------------------------------------------------------------------------------- |
29+
| [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`. |
30+
| [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._ |
31+
| 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. |
32+
| 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. |
33+
| 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. |
34+
| 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. |
35+
| 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. |
3436

35-
## Mode.
37+
## Mode
3638

3739
The group of connected batteries can be controlled in three different modes:
3840

3941
- `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.
4042
- `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.
41-
- `standby` - Batteries will enter standby mode. This means that the Plug-In Battery will neither charge nor discharge.
43+
- `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._
4244

43-
### Examples
45+
## Permissions
4446

45-
#### Get Battery Group Information
47+
The `permissions` field can be used to set specific permissions for charging and discharging the connected Plug-In Batteries. The possible values are:
48+
49+
- `charge_allowed` - Allow the Plug-In Battery to charge.
50+
- `discharge_allowed` - Allow the Plug-In Battery to discharge.
51+
52+
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 `[]`.
53+
54+
### Backwards compatibility with `standby` mode
55+
56+
Mode `standby` is exactly the same as mode `zero` with both charging and discharging disallowed, therefore the following rules apply for backwards compatibility:
57+
58+
- When switching to `standby` mode, the `permissions` field will be set to an empty array `[]`.
59+
- When adding a permission to the `permissions` field while in `standby` mode, the mode will automatically switch to `zero`.
60+
- `zero` mode with both permissions allowed is the same as the default `zero` mode.
61+
62+
## Examples
63+
64+
### Get Battery Group Information
4665

4766
```shell title="Request"
4867
curl https://<IP ADDRESS>/api/batteries \
@@ -57,14 +76,16 @@ Content-Type: application/json
5776
5877
{
5978
"mode": "zero",
79+
"permissions" : ["charge_allowed", "discharge_allowed"],
80+
"battery_count": 2,
6081
"power_w": -404,
6182
"target_power_w": -400,
6283
"max_consumption_w": 1600,
6384
"max_production_w": 800
6485
}
6586
```
6687

67-
#### Change Control Mode
88+
### Change Control Mode
6889

6990
```shell title="Request"
7091
curl https://<IP ADDRESS>/api/batteries \
@@ -81,9 +102,65 @@ Content-Type: application/json
81102
82103
{
83104
"mode": "to_full",
105+
"permissions" : [],
106+
"battery_count": 2,
84107
"power_w": 1599,
85108
"target_power_w": 1600,
86109
"max_consumption_w": 1600,
87110
"max_production_w": 800
88111
}
89112
```
113+
114+
### Change permissions
115+
116+
```shell title="Request"
117+
curl https://<IP ADDRESS>/api/batteries \
118+
--insecure \
119+
-H "Authorization: Bearer <TOKEN>" \
120+
-H "X-Api-Version: 2" \
121+
-d '{"permissions": ["charge_allowed"]}'
122+
```
123+
124+
```http title="Response"
125+
https/1.1 200 OK
126+
Content-Type: application/json
127+
128+
{
129+
"mode": "zero",
130+
"permissions" : ["charge_allowed"],
131+
"battery_count": 2,
132+
"power_w": 404,
133+
"target_power_w": 400,
134+
"max_consumption_w": 1600,
135+
"max_production_w": 800
136+
}
137+
```
138+
139+
### Change permissions and mode
140+
141+
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.
142+
143+
Mode will change to standby or zero depending on the provided permissions.
144+
145+
```shell title="Request"
146+
curl https://<IP ADDRESS>/api/batteries \
147+
--insecure \
148+
-H "Authorization: Bearer <TOKEN>" \
149+
-H "X-Api-Version: 2" \
150+
-d '{"permissions": ["discharge_allowed"], "mode": "zero"}'
151+
```
152+
153+
```http title="Response"
154+
https/1.1 200 OK
155+
Content-Type: application/json
156+
157+
{
158+
"mode": "zero",
159+
"permissions": ["discharge_allowed"],
160+
"battery_count": 2,
161+
"power_w": -404,
162+
"target_power_w": -400,
163+
"max_consumption_w": 1600,
164+
"max_production_w": 800
165+
}
166+
```

‎docs/v2/websocket.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ After authentication, you can subscribe to topics. Topics correspond to availabl
6767
- **`user`** - Subscribe to [user list](/docs/v2/authorization#list-users) updates
6868
- **`measurement`** - Subscribe to [measurement](/docs/v2/measurement) updates
6969
- **`system`** - Subscribe to [system](/docs/v2/system) updates. Only `cloud_enabled` and `status_led_brightness_pct` are updated in real time.
70-
- **`batteries`** - Subscribe to [battery group](/docs/v2/batteries) updates. Only `mode` is updated in real time.
70+
- **`batteries`** - Subscribe to [battery group](/docs/v2/batteries) updates. Only `mode`, `permissions` and `target_power_w` are updated in real time.
7171

7272
```json title="Example"
7373
{"type": "subscribe", "data": "system"}

0 commit comments

Comments
 (0)