Add pending dataset visibility and cancellation to OTBR WebSocket API

[raman325]

Proposed change

The frontend exposes a "change channel" action which triggers a channel migration with a 5-minute delay on the OTBR. Once initiated, users have no way of knowing a channel change is in flight without checking the logs. These new WebSocket commands provide the backend support needed to improve the frontend UX so users can see when a channel migration is pending and how much time remains. As a bonus, we can also let users cancel a pending change if they made a mistake.

Changes:

• otbr/get_pending_dataset — returns the pending target channel and remaining delay (in seconds), or None if no migration is pending. Available to all authenticated users so the frontend can display pending migration status.
• otbr/delete_pending_dataset (admin-only) — cancels a pending channel migration. Includes a fallback for OTBR firmware that doesn't support DELETE /node/dataset/pending (405 only — other errors are raised immediately): creates a pending dataset with the current active dataset and delay=0, which immediately clears the pending migration.
• OTBRData.delete_pending_dataset() wrapper in util.py with DELETE + fallback logic

Tested against a live OTBR (official HA addon + ZBT-2).

Type of change

• New feature (which adds functionality to an existing integration)

Additional information

• This PR fixes or closes issue: fixes #
• This PR is related to issue:
• Link to documentation pull request:
• Link to developer documentation pull request:
• Link to frontend pull request: Show pending channel migration status on Thread config page frontend#51608

Checklist

• I understand the code I am submitting and can explain how it works.
• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• I have followed the perfect PR recommendations
• The code has been formatted using Ruff (ruff format homeassistant tests)
• Tests have been added to verify that the new code works.
• Any generated code has been carefully reviewed for correctness and compliance with project standards.

To help with the load of incoming pull requests:

• I have reviewed two other open pull requests in this repository.

[home-assistant]

Hey there @home-assistant/core, mind taking a look at this pull request as it has been labeled with an integration (otbr) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of otbr can trigger bot actions by commenting:

• @home-assistant close Closes the pull request.
• @home-assistant mark-draft Mark the pull request as draft.
• @home-assistant ready-for-review Remove the draft status from the pull request.
• @home-assistant rename Awesome new title Renames the pull request.
• @home-assistant reopen Reopen the pull request.
• @home-assistant unassign otbr Removes the current integration label and assignees on the pull request, add the integration domain after the command.
• @home-assistant update-branch Update the pull request branch with the base branch.
• @home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component, problem in config, problem in device, feature-request) to the pull request.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component, problem in config, problem in device, feature-request) on the pull request.

[Copilot]

Pull request overview

Adds WebSocket endpoints to expose and cancel a pending OTBR channel migration so the frontend can display scheduled migrations and allow cancellation.

Changes:

• Register otbr/get_pending_dataset to return pending channel + remaining delay (or None).
• Register otbr/delete_pending_dataset to cancel a pending dataset.
• Add OTBRData.delete_pending_dataset() wrapper and associated WebSocket API tests.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
homeassistant/components/otbr/websocket_api.py	Adds and registers two new OTBR WebSocket commands for pending dataset visibility/cancellation.
homeassistant/components/otbr/util.py	Adds an OTBRData.delete_pending_dataset() helper wrapping the python-otbr-api call with existing error handling.
tests/components/otbr/test_websocket_api.py	Adds test coverage for the new WebSocket commands across success/none/malformed/error cases.

[raman325]

Upstream PR to add DELETE support to the OTBR REST API: openthread/ot-br-posix#3308. The fallback in this PR handles OTBR firmware that doesn't yet have that change.

[Copilot]

Pull request overview

Adds OTBR WebSocket API support for observing and canceling pending Thread channel migrations, enabling the frontend to surface “pending change” status and provide a cancel action.

Changes:

• Add otbr/get_pending_dataset WebSocket command to report pending channel and delay timer from the pending dataset TLVs.
• Add otbr/delete_pending_dataset WebSocket command backed by a new OTBRData.delete_pending_dataset() helper with DELETE + fallback behavior.
• Add test coverage for the new WebSocket commands, including error and fallback scenarios.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
homeassistant/components/otbr/websocket_api.py	Registers and implements the two new admin-only WebSocket commands.
homeassistant/components/otbr/util.py	Adds OTBRData.delete_pending_dataset() with DELETE + fallback logic.
tests/components/otbr/test_websocket_api.py	Adds tests validating pending dataset parsing and deletion/fallback behaviors.