Repository navigation
Conversation
This commit adds documentation describing the functionality of the V2 version of the API for the Energy Socket. In many cases, this just amounts to setting the 'in development' badge to 'Supported'. In some cases more documentation is added. The measurement file is updated to document the values that are returned when querying a socket for its most recent measurements. The system file is updated to include the new socket-specific properties (switch lock & power state).
This commit marks the API v2 of the socket as being in beta in all relevant places. Additionally, the changelog was updated to reflect the changes made to the protocol to support the Energy Socket.
|
Visit the preview URL for this PR (updated for commit 8125878): https://hw-api-documentation--pr303-add-api-v2-for-socke-tpr7etam.web.app (expires Fri, 27 Nov 2026 15:49:25 GMT) 🔥 via Firebase Hosting GitHub Action 🌎 Sign: 4accc1c887f1346ec9c563d5645c74c94f610c07 |
There was a problem hiding this comment.
🟡 Changes recommended
The discovery badge still says “In development,” conflicting with the v2 endpoint pages’ “Supported” beta status and leaving availability unclear.
1 open issue
What changed in this PR
This PR documents beta API v2 support for Energy Socket over HTTPS, with WebSocket support planned for a later release. Publication is intended to wait for the corresponding firmware release.
Changes:
- Updates device availability and endpoint support badges for the beta.
- Documents Energy Socket measurements, a response example, and socket-specific system controls.
- Adds a firmware 2.3.1 changelog entry.
| File | Description |
|---|---|
| docs/v2/system.mdx | Adds socket support, switch_lock, and power_on. |
| docs/v2/measurement.mdx | Adds socket measurements and an HTTPS example. |
| docs/v2/error-handling.mdx | Marks socket error handling as supported in beta. |
| docs/v2/device_information.mdx | Marks socket device information as supported in beta. |
| docs/v2/authorization.mdx | Marks socket authorization as supported in beta. |
| docs/introduction.mdx | Lists beta availability and planned WebSocket support. |
| docs/discovery.mdx | Updates the socket discovery badge for beta support. |
| docs/changelog.mdx | Records socket API v2 support and new system fields. |
Review effort: Balanced
Accidentally forgot to change this
This commit documents the socket-specific `power_on` and `switch_lock` parameters of the v2 system endpoint as thoroughly as the v1 state endpoint: the behavior of the switch lock, the rules for combined requests and request/response examples for turning the socket on and off and enabling the switch lock. The error returned for an invalid `power_on`/`switch_lock` combination still has to be confirmed with firmware; a TODO marks this in the page. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Questions about the v2
Commits ab8a874 and f36df53 in this PR document this in Notes for the Embedded team (not changed in this PR):
|
This commit replaces the switch lock TODO with the behavior of the
socket firmware (`components/app_api/app_api_v2.cpp` and
`components/relay/relay.cpp`):
- While the switch lock is enabled, a request that sets `power_on`
without `switch_lock` is refused with `400 Bad Request` and
`request:switch-lock-enabled`, for both `true` and `false`.
- `switch_lock` is always applied before `power_on`, so the order of
parameters does not matter.
- `{"power_on": false, "switch_lock": true}` is accepted, and the switch
lock takes precedence: the socket is turned on.
It adds an example of the refused request and lists
`request:switch-lock-enabled` in the v2 error codes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit moves around the documentation for features exclusive to the Energy Socket. Other features that are not exclusive to the Energy Socket should take precedence. Additionally, I reworded a statement to make it sound more in line with the 'dev-speak' of the other error descriptions.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This PR adds documentation for the beta version of the APIv2 for the Energy Socket. The firmware for this will be released in a future version, and this PR should not be merged until that is the case. This new version will include only the https part of the API and not the ws. This will be added in a future release.
This PR was tested by locally running the website and looking at all the changed pages. They correctly identified which parts of the API were included (in beta) for the socket and which aren't.