diff --git a/docs/changelog.mdx b/docs/changelog.mdx index ec08f4f..ed87104 100644 --- 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 index 23216f8..faf375d 100644 --- 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` | Supported | Supported | -| Energy Socket | `HWE-SKT` | Supported | In development | -| Watermeter (Only when powered over USB) | `HWE-WTR` | Supported | In development | -| kWh Meter (1 phase and 3-phase) | `HWE-KWH1`,
`HWE-KWH3`,
`SDM230-wifi` and
`SDM630-wifi` | Supported | Supported | -| Energy Display | `HWE-DSP` | Not planned | In development | -| Plug-In Battery | `HWE-BAT` | Not planned | Supported | +| Device | Device type | API v1 | API v2 | +| --------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| P1 Meter | `HWE-P1` | Supported | SupportedIn beta, available from firmware 6.03xx | +| Energy Socket | `HWE-SKT` | Supported | In development | +| Watermeter (Only when powered over USB) | `HWE-WTR` | Supported | In development | +| kWh Meter (1 phase and 3-phase) | `HWE-KWH1`,
`HWE-KWH3`,
`SDM230-wifi` and
`SDM630-wifi` | Supported | Supported In beta, available from firmware 5.01xx | +| Energy Display | `HWE-DSP` | Not planned | In development | +| Plug-In Battery | `HWE-BAT` | Not planned | Supported | ## Beta Program. diff --git a/docs/v2/batteries.mdx b/docs/v2/batteries.mdx index b827e3f..bcf76ca 100644 --- 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 */} -P1 Meter +P1 Meter Energy Socket Energy Display kWh Meter @@ -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) | Available | String | Read/Write | Control mode of the Plug-In Battery. Can be either `zero`, `to_full`, or `standby`. | +| [permissions](#permissions) | In beta | Array[String] | Read/Write\* | Permissions to allow charging, discharging, both, or neither. _Note: Read-only in `to_full` mode._ | +| battery_count | In beta | Number | Read-only | Number of connected Plug-In Batteries. | +| power_w | Available | Number | Read-only | Current combined power consumption/production of the controlled Plug-In Batteries. | +| target_power_w | Available | Number | Read-only | Target power consumption/production of the controlled Plug-In Batteries. | +| max_consumption_w | Available | Number | Read-only | Maximum allowed consumption power of the controlled Plug-In Batteries. | +| max_production_w | Available | 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:///api/batteries \ @@ -57,6 +76,8 @@ 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, @@ -64,7 +85,7 @@ Content-Type: application/json } ``` -#### Change Control Mode +### Change Control Mode ```shell title="Request" curl https:///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:///api/batteries \ + --insecure \ + -H "Authorization: Bearer " \ + -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:///api/batteries \ + --insecure \ + -H "Authorization: Bearer " \ + -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 index 1722b4b..a074218 100644 --- 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"}