Add pending dataset visibility and cancellation to OTBR WebSocket API by raman325 · Pull Request #168441 · home-assistant/core

raman325 · 2026-04-17T17:11:20Z

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.

When otbr/set_channel is called, a pending dataset with a delay timer is created on the OTBR. Previously, the frontend had no way to check if a channel migration was pending or to cancel it after the initial response. This adds two new WebSocket commands: - otbr/get_pending_dataset: returns the pending channel and remaining delay in seconds, or None if no migration is pending - otbr/delete_pending_dataset: cancels a pending channel migration Also adds OTBRData.delete_pending_dataset() wrapper in util.py. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

home-assistant · 2026-04-17T17:11:28Z

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.

The OTBR REST API may not support DELETE on /node/dataset/pending (returns 405). Fall back to creating a pending dataset with the current active dataset and delay=0, which immediately applies the current state and clears the pending migration. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

raman325 · 2026-04-17T18:12:14Z

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.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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.

…nding - Only trigger delete_pending_dataset fallback on 405 (Method Not Allowed), re-raise other OTBRError and connectivity/timeout errors immediately - Remove @require_admin from get_pending_dataset so non-admin users can view pending migrations in the frontend - Add test for non-405 error raising instead of falling back Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

agners

Let's wait until we better understand what operations are safe when it comes to pending dataset cancellation from upstream maintainers before implementing this feature on our end.

agners · 2026-04-28T12:32:34Z

+        Tries DELETE first (spec-compliant). Falls back to creating a pending
+        dataset with the current active dataset and delay=0, which immediately
+        applies the current state and clears the pending migration.
+        """


While I totally get why we'd want this, I'd like to better understand how the BR behave when it comes to cancelling pending dataset (see openthread/ot-br-posix#3308 (comment)).

Also not sure if this work around is a good idea. From what I understand the delay is really required to have the dataset propagate through the network. The 5 minutes we choose by default is a conservative high number which makes sure that even battery operated devices with long idle times get the new pending dataset (through the current channel) before we switch to the new channel.

home-assistant · 2026-04-28T12:35:36Z

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

raman325 requested a review from a team as a code owner April 17, 2026 17:11

Copilot AI review requested due to automatic review settings April 17, 2026 17:11

home-assistant Bot added cla-signed has-tests integration: otbr Top 200 Integration is ranked within the top 200 by usage Quality Scale: No score labels Apr 17, 2026

Copilot started reviewing on behalf of raman325 April 17, 2026 17:12 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread homeassistant/components/otbr/websocket_api.py

raman325 added the new-feature label Apr 17, 2026

raman325 mentioned this pull request Apr 17, 2026

Show pending channel migration status on Thread config page home-assistant/frontend#51608

Open

13 tasks

raman325 mentioned this pull request Apr 17, 2026

[rest] add DELETE method for pending dataset endpoint openthread/ot-br-posix#3308

Open

Refactor delete_pending_dataset to use try/else instead of nested try

8ebcedf

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings April 18, 2026 13:11

Copilot started reviewing on behalf of raman325 April 18, 2026 13:11 View session

raman325 and others added 2 commits April 18, 2026 09:12

Narrow try blocks in delete_pending_dataset fallback to API calls only

d4da8ad

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add comments explaining delete_pending_dataset control flow

b53e631

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot AI reviewed Apr 18, 2026

View reviewed changes

Comment thread homeassistant/components/otbr/util.py Outdated

agners requested changes Apr 28, 2026

View reviewed changes

home-assistant Bot marked this pull request as draft April 28, 2026 12:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add pending dataset visibility and cancellation to OTBR WebSocket API#168441

Add pending dataset visibility and cancellation to OTBR WebSocket API#168441
raman325 wants to merge 6 commits intohome-assistant:devfrom
raman325:otbr-pending-dataset-websocket-api

raman325 commented Apr 17, 2026 •

edited

Loading

Uh oh!

home-assistant Bot commented Apr 17, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

raman325 commented Apr 17, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

agners left a comment

Uh oh!

agners Apr 28, 2026

Uh oh!

home-assistant Bot commented Apr 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

raman325 commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed change

Type of change

Additional information

Checklist

Uh oh!

home-assistant Bot commented Apr 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

raman325 commented Apr 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

agners left a comment

Choose a reason for hiding this comment

Uh oh!

agners Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

home-assistant Bot commented Apr 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

raman325 commented Apr 17, 2026 •

edited

Loading