diff --git a/docs/changelog.mdx b/docs/changelog.mdx index 10de621..2155f44 100644 --- a/docs/changelog.mdx +++ b/docs/changelog.mdx @@ -44,6 +44,11 @@ Feature development of the v1 API has been stopped. No new features will be adde - The `mode` field in the [Plug-In Battery API](/docs/v2/batteries) now supports a new mode: `predictive`. In this mode, the control system will automatically select between `charge_allowed`, `discharge_allowed`, both or neither based on the current and predicted power consumption/production of your home and the current energy prices. - A new field is added to the [Plug-In Battery API](/docs/v2/batteries): `charge_to_full`. This field can be set to `true` to charge all connected Plug-In Batteries to 100% and can be set to `false` to disable this behavior. +#### 2.3.1 - 17-11-2026 + +- Support has been added for the v2 of the API to the Energy Socket +- New fields are added to the [System API](/docs/v2/system): 'switch_lock' and 'power_on'. These properties are only relevant for the Energy Socket. + ## Subscribe to Updates. Get notified for changes in the API and its documentation when something has changed. Subscribe to changes at GitHub. Click the "Watch" button in the top-right to select your notifications type. We recommend you to select "Watch → "Custom" → "Releases". diff --git a/docs/discovery.mdx b/docs/discovery.mdx index 8015848..a8ab4bd 100644 --- a/docs/discovery.mdx +++ b/docs/discovery.mdx @@ -46,12 +46,12 @@ A discovery response contains additional data to enhance the setup in your appli ## `_homewizard._tcp`. {/* prettier-ignore */} -P1 Meter -Energy Socket -Energy Display -kWh Meter +P1 Meter +Energy Socket +Energy Display +kWh Meter Watermeter -Plug-In Battery +Plug-In Battery --- diff --git a/docs/introduction.mdx b/docs/introduction.mdx index 03d646e..265b316 100644 --- a/docs/introduction.mdx +++ b/docs/introduction.mdx @@ -39,15 +39,15 @@ 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 | Planned | -| Watermeter (only when powered over USB) | `HWE-WTR` | Supported | Planned | -| kWh Meter (1-phase and 3-phase) | `HWE-KWH1`,
`HWE-KWH3`,
`SDM230-wifi` and
`SDM630-wifi` | Supported | Supported | -| Energy Display | `HWE-DSP` | Not planned | Planned | -| Plug-In Battery | `HWE-BAT` | Not planned | Supported | -| Temperature Humidity Meter (always battery powered) | `HWE-TMP` | Not planned | Exploring alternatives | +| Device | Device type | API v1 | API v2 | +| --------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| P1 Meter | `HWE-P1` | Supported | Supported | +| Energy Socket | `HWE-SKT` | Supported | API support in beta WebSocket support planned | +| Watermeter (only when powered over USB) | `HWE-WTR` | Supported | Planned | +| kWh Meter (1-phase and 3-phase) | `HWE-KWH1`,
`HWE-KWH3`,
`SDM230-wifi` and
`SDM630-wifi` | Supported | Supported | +| Energy Display | `HWE-DSP` | Not planned | Planned | +| Plug-In Battery | `HWE-BAT` | Not planned | Supported | +| Temperature Humidity Meter (always battery powered) | `HWE-TMP` | Not planned | Exploring alternatives | ## Beta Program. diff --git a/docs/v2/authorization.mdx b/docs/v2/authorization.mdx index 17165f8..c836358 100644 --- a/docs/v2/authorization.mdx +++ b/docs/v2/authorization.mdx @@ -10,7 +10,7 @@ import Badge from '@site/src/components/Badge.js' {/* prettier-ignore */} P1 Meter -Energy Socket +Energy Socket Energy Display kWh Meter Watermeter diff --git a/docs/v2/device_information.mdx b/docs/v2/device_information.mdx index 3c06c49..89b9ef8 100644 --- a/docs/v2/device_information.mdx +++ b/docs/v2/device_information.mdx @@ -10,7 +10,7 @@ import Badge from '@site/src/components/Badge.js' {/* prettier-ignore */} P1 Meter -Energy Socket +Energy Socket Energy Display kWh Meter Watermeter diff --git a/docs/v2/error-handling.mdx b/docs/v2/error-handling.mdx index 48233de..7e63193 100644 --- a/docs/v2/error-handling.mdx +++ b/docs/v2/error-handling.mdx @@ -10,7 +10,7 @@ import Badge from '@site/src/components/Badge.js' {/* prettier-ignore */} P1 Meter -Energy Socket +Energy Socket Energy Display kWh Meter Watermeter @@ -29,27 +29,28 @@ Each error is represented as a set of 'scope' and 'error' fields. The 'scope' fi ### List of Errors -| Code | Description | -| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `request:invalid-json` | Server was unable to parse the JSON data. | -| `json:no-parameters-recognized` | JSON was correct, but no required parameters were found. | -| `json:parameter-invalid-type:` | Invalid type for a parameter, e.g. a string where a number is expected. | -| `json:parameter-missing:` | Required parameter is missing. | -| `json:parameter-not-exclusive` | Two or more parameters are mutually exclusive. | -| `request:api-version-not-supported` | Requested API version not supported, see [versioning](/docs/versioning). | -| `request:internal-server-error` | Something went wrong on the server side. | -| `request:too-large` | Request too large. | -| `request:unknown-subscription` | WebSocket subscription topic not recognized, see [WebSocket subscriptions](/docs/v2/websocket#subscribe). | -| `request:unknown-type` | WebSocket `type` parameter not recognized, see [WebSocket structure](/docs/v2/websocket#structure). | -| `telegram:no-telegram-received` | No telegram received, see [telegram](/docs/v2/telegram#error-handling). | -| `user:creation-not-enabled` | User creation is not enabled, button press required. | -| `user:invalid-prefix` | Invalid name prefix provided, see [create user](/docs/v2/authorization#create-user-and-get-token). | -| `user:name-empty` | Upon creating a user, the name was empty. | -| `user:name-invalid` | Upon creating a user, the name contained invalid tokens, see [create user](/docs/v2/authorization#create-user-and-get-token). | -| `user:name-too-long` | Upon creating a user, the name was too long. | -| `user:no-storage` | No storage available to store a new user, delete existing users. | -| `user:not-found` | Tried to delete a user which does not exist. | -| `user:unauthorized` | User token is invalid or not authorized, see [authorization](/docs/v2/authorization). | +| Code | Description | +| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `request:invalid-json` | Server was unable to parse the JSON data. | +| `json:no-parameters-recognized` | JSON was correct, but no required parameters were found. | +| `json:parameter-invalid-type:` | Invalid type for a parameter, e.g. a string where a number is expected. | +| `json:parameter-missing:` | Required parameter is missing. | +| `json:parameter-not-exclusive` | Two or more parameters are mutually exclusive. | +| `request:api-version-not-supported` | Requested API version not supported, see [versioning](/docs/versioning). | +| `request:internal-server-error` | Something went wrong on the server side. | +| `request:switch-lock-enabled` | Disabling the power flow is impossible when switch lock is enabled, see [switch lock](/docs/v2/system#energy-socket-power-and-switch-lock). | +| `request:too-large` | Request too large. | +| `request:unknown-subscription` | WebSocket subscription topic not recognized, see [WebSocket subscriptions](/docs/v2/websocket#subscribe). | +| `request:unknown-type` | WebSocket `type` parameter not recognized, see [WebSocket structure](/docs/v2/websocket#structure). | +| `telegram:no-telegram-received` | No telegram received, see [telegram](/docs/v2/telegram#error-handling). | +| `user:creation-not-enabled` | User creation is not enabled, button press required. | +| `user:invalid-prefix` | Invalid name prefix provided, see [create user](/docs/v2/authorization#create-user-and-get-token). | +| `user:name-empty` | Upon creating a user, the name was empty. | +| `user:name-invalid` | Upon creating a user, the name contained invalid tokens, see [create user](/docs/v2/authorization#create-user-and-get-token). | +| `user:name-too-long` | Upon creating a user, the name was too long. | +| `user:no-storage` | No storage available to store a new user, delete existing users. | +| `user:not-found` | Tried to delete a user which does not exist. | +| `user:unauthorized` | User token is invalid or not authorized, see [authorization](/docs/v2/authorization). | :::tip The list of error codes may be extended in the future. We recommend that you prepare for new error codes by having a generic error handling mechanism in place. diff --git a/docs/v2/measurement.mdx b/docs/v2/measurement.mdx index 509df31..21ba0da 100644 --- a/docs/v2/measurement.mdx +++ b/docs/v2/measurement.mdx @@ -11,7 +11,7 @@ import Badge from '@site/src/components/Badge.js' {/* prettier-ignore */} P1 Meter -Energy Socket +Energy Socket Energy Display kWh Meter Watermeter @@ -166,6 +166,22 @@ Belgian users may be charged for the peak usage per month (see /api/measurement --insecure \ + -H "Authorization: Bearer " \ + -H "X-Api-Version: 2" +``` + +```http title="Response" +https/1.1 200 OK +Content-Type: application/json + +{ + "energy_import_kwh": 123.456, + "energy_export_kwh": 78.910, + "power_w": 123, + "voltage_v": 230, + "current_a": 1.5, + "frequency_hz": 50, + "reactive_power_var": 67, + "apparent_power_va": 345, + "power_factor": 0.95 + } +``` diff --git a/docs/v2/system.mdx b/docs/v2/system.mdx index 0147c90..af9232f 100644 --- a/docs/v2/system.mdx +++ b/docs/v2/system.mdx @@ -10,7 +10,7 @@ import Badge from '@site/src/components/Badge.js' {/* prettier-ignore */} P1 Meter -Energy Socket +Energy Socket Energy Display kWh Meter Watermeter @@ -24,21 +24,23 @@ The `/api/system` endpoint can be used to get and set some system information, l ## Parameters. -| Data | Type | Access | Description | Availability | -| --------------------------------------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| wifi_ssid | String | Read-only | The SSID of the Wi-Fi network. | P1 Meter kWh Meter Plug-In Battery | -| wifi_rssi_db | Number | Read-only | The signal strength of the Wi-Fi network. | P1 Meter kWh Meter Plug-In Battery | -| uptime_s | Number | Read-only | The uptime of the device in seconds. | P1 Meter kWh Meter Plug-In Battery | -| [cloud_enabled](#cloud-communication) | Boolean | Read/Write | The state of the cloud communication. | P1 Meter kWh Meter Plug-In Battery | -| [status_led_brightness_pct](#status-led-brightness) | Number | Read/Write | The brightness of the status LED in percent. | P1 Meter kWh Meter Plug-In Battery | -| [api_v1_enabled](#enable-or-disable-the-v1-api) | Optional Boolean | Read/Write | The state of the v1 API, will be removed when API v1 is removed, so this parameter is optional. | P1 Meter kWh Meter Plug-In Battery | +| Data | Type | Access | Description | Availability | +| --------------------------------------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| wifi_ssid | String | Read-only | The SSID of the Wi-Fi network. | P1 Meter kWh Meter Plug-In Battery Energy Socket | +| wifi_rssi_db | Number | Read-only | The signal strength of the Wi-Fi network. | P1 Meter kWh Meter Plug-In Battery Energy Socket | +| uptime_s | Number | Read-only | The uptime of the device in seconds. | P1 Meter kWh Meter Plug-In Battery Energy Socket | +| [cloud_enabled](#cloud-communication) | Boolean | Read/Write | The state of the cloud communication. | P1 Meter kWh Meter Plug-In Battery Energy Socket | +| [status_led_brightness_pct](#status-led-brightness) | Number | Read/Write | The brightness of the status LED in percent. | P1 Meter kWh Meter Plug-In Battery Energy Socket | +| [api_v1_enabled](#enable-or-disable-the-v1-api) | Optional Boolean | Read/Write | The state of the v1 API, will be removed when API v1 is removed, so this parameter is optional. | P1 Meter kWh Meter Plug-In Battery Energy Socket | +| [switch_lock](#energy-socket-power-and-switch-lock) | Boolean | Read/Write | The state of the switch lock. When enabled, the socket power cannot be disabled. | P1 Meter kWh Meter Plug-In Battery Energy Socket | +| [power_on](#energy-socket-power-and-switch-lock) | Boolean | Read/Write | The power state of the socket. | P1 Meter kWh Meter Plug-In Battery Energy Socket | ## Actions. -| Action | Description | Availability | -| --------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [Reboot](#reboot) | Reboot the device | P1 Meter kWh Meter Plug-In Battery | -| [Identify](#identify) | Let the device identify itself by blinking the status LED | P1 Meter kWh Meter Plug-In Battery | +| Action | Description | Availability | +| --------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Reboot](#reboot) | Reboot the device | P1 Meter kWh Meter Plug-In Battery Energy Socket | +| [Identify](#identify) | Let the device identify itself by blinking the status LED | P1 Meter kWh Meter Plug-In Battery Energy Socket | ## Plug-In Battery exceptions. @@ -154,6 +156,123 @@ Content-Type: application/json To protect the device from unauthorized access, the v1 API can be disabled. When the v1 API is disabled, the device will only allow authorized request via the v2 API. +## Energy Socket Power and Switch Lock. + +The Energy Socket can be controlled with the `power_on` and `switch_lock` parameters. In API v1 these parameters were part of the [state endpoint](/docs/v1/state); in API v2 they are part of the system endpoint. + +- `power_on` returns `true` when the relay is in the 'on' state. Set it to `true` or `false` to turn the socket on or off. +- `switch_lock` keeps the socket turned on. When `switch_lock` is enabled, the socket is turned on and cannot be turned off until `switch_lock` is disabled again. + +While `switch_lock` is enabled, a request that sets `power_on` without also setting `switch_lock` is refused with `400 Bad Request` and the error `request:switch-lock-enabled`, see [error handling](/docs/v2/error-handling). This applies to both `true` and `false`. + +When a request contains both parameters, `switch_lock` is always applied before `power_on`, so the order of the parameters does not matter: + +- If `switch_lock` was enabled, sending `{"power_on": false, "switch_lock": false}` disables the switch lock and turns the socket off. +- Sending `{"power_on": false, "switch_lock": true}` is accepted, but the switch lock takes precedence: the socket is turned on. + +### Examples + +#### Turn on Socket + +```http title="Request" +curl https:///api/system --insecure \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "X-Api-Version: 2" \ + -d '{"power_on": true}' +``` + +```http title="Response" +https/1.1 200 OK +Content-Type: application/json + +{ + "wifi_ssid": "My Wi-Fi", + "wifi_rssi_db": -77, + "cloud_enabled": true, + "uptime_s": 356, + "status_led_brightness_pct": 100, + "api_v1_enabled": true, + "switch_lock": false, + "power_on": true +} +``` + +#### Enable Switch Lock + +After enabling `switch_lock`, the socket is 'on' and cannot be turned off until `switch_lock` is disabled. + +```http title="Request" +curl https:///api/system --insecure \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "X-Api-Version: 2" \ + -d '{"switch_lock": true}' +``` + +```http title="Response" +https/1.1 200 OK +Content-Type: application/json + +{ + "wifi_ssid": "My Wi-Fi", + "wifi_rssi_db": -77, + "cloud_enabled": true, + "uptime_s": 356, + "status_led_brightness_pct": 100, + "api_v1_enabled": true, + "switch_lock": true, + "power_on": true +} +``` + +#### Turn off Socket when Switch Lock is Enabled + +```http title="Request" +curl https:///api/system --insecure \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "X-Api-Version: 2" \ + -d '{"power_on": false}' +``` + +```http title="Response" +https/1.1 400 Bad Request +Content-Type: application/json + +{ + "error": "request:switch-lock-enabled" +} +``` + +#### Disable Switch Lock and Turn off Socket + +Both parameters can be set in a single request. The order does not matter: the socket turns off even though `switch_lock` was enabled. + +```http title="Request" +curl https:///api/system --insecure \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "X-Api-Version: 2" \ + -d '{"power_on": false, "switch_lock": false}' +``` + +```http title="Response" +https/1.1 200 OK +Content-Type: application/json + +{ + "wifi_ssid": "My Wi-Fi", + "wifi_rssi_db": -77, + "cloud_enabled": true, + "uptime_s": 356, + "status_led_brightness_pct": 100, + "api_v1_enabled": true, + "switch_lock": false, + "power_on": false +} +``` + ### Example #### Disable the v1 API