Skip to content

Add documentation for the beta version of APIv2 for Energy Socket - #303

Open
xlenstra wants to merge 8 commits into
mainfrom
add-api-v2-for-socket
Open

xlenstra wants to merge 8 commits into
mainfrom
add-api-v2-for-socket

Conversation

@xlenstra

Copy link
Copy Markdown
Member

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.

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.
@xlenstra
xlenstra requested review from a team and lexpostma and a balanced review from Copilot November 17, 2026 14:32
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread docs/discovery.mdx Resolved
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>
@lexpostma

lexpostma commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Questions about the v2 power_on / switch_lock behavior on the Energy Socket. They're now answered from the socket firmware (energysocket-appliance, branch development at 1217521: components/app_api/app_api_v2.cpp, components/app_api/app_api.cpp and components/relay/relay.cpp).

  1. Invalid combination: what does PUT /api/system return for {"power_on": false, "switch_lock": true}?
    Answer: it isn't rejected. switch_lock is applied first and enables the lock, which turns the socket on. power_on: false is then accepted, but the relay ignores it while the lock is on. The result is 200 OK, with the socket on and locked.
  2. Turning off while locked: is {"power_on": false} on its own rejected while switch_lock is enabled?
    Answer: yes, with 400 Bad Request and {"error": "request:switch-lock-enabled"}. This also applies to {"power_on": true}: any request that sets power_on without switch_lock is refused while the lock is on.
  3. Combined requests: is the order of fields still irrelevant?
    Answer: yes. switch_lock is always applied before power_on, so {"power_on": false, "switch_lock": false} turns a locked socket off.
  4. Enabling the lock while off: does {"switch_lock": true} turn the socket on?
    Answer: yes, the relay switches on when the lock is enabled.
  5. Response shape: does a v2 socket return api_v1_enabled, power_on and switch_lock in /api/system?
    Answer: yes, all three are always present. The response also contains an undocumented uptime_ms.

Commits ab8a874 and f36df53 in this PR document this in docs/v2/system.mdx and add request:switch-lock-enabled to docs/v2/error-handling.mdx.

Notes for the Embedded team (not changed in this PR):

  • Partial updates: a refused request isn't atomic. cloud_enabled, status_led_brightness_pct and api_v1_enabled are applied before power_on is checked, so they stay changed even when the request returns request:switch-lock-enabled.
  • Outdated feature file: docs/features/200_api/003_api_actions.feature still describes PUT /api/v2/state and the error state:switch-lock-enabled, but the code uses /api/system and request:switch-lock-enabled.
  • API version: API_VERSION on development is 2.3.0, while these docs say the socket supports 2.3.1.
  • v1 docs: the v1 state docs say power_on: false with switch_lock: true is not possible, but v1 shares the same code path and also accepts it.

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>
xlenstra and others added 2 commits November 20, 2026 14:23
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.

@lexpostma lexpostma left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👌

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants