doc: SUIT recovery button documentation #19217

ahasztag · 2024-12-03T12:48:34Z

This commit documents the feature allowing to enter SUIT recovery via a button press.

NordicBuilder · 2024-12-03T13:00:59Z

CI Information

^{To view the history of this post, clich the 'edited' button above}
Build number: 16

Inputs:

Sources:

sdk-nrf: PR head: 56069f204a27be83ecb124b040d640146a58c8a3

more details

sdk-nrf:

PR head: 56069f204a27be83ecb124b040d640146a58c8a3
merge base: baaa9aaa55239a0b36ac27f2f3a6a11eb3692f8b
target head (main): 4c6ab4d0e83046e0040f82a507bfd6826f0f4d9e
Diff

Github labels

Enabled	Name	Description
	ci-disabled	Disable the ci execution
	ci-all-test	Run all of ci, no test spec filtering will be done
	ci-force-downstream	Force execution of downstream even if twister fails
	ci-run-twister	Force run twister
	ci-run-zephyr-twister	Force run zephyr twister

List of changed files detected by CI (1)

doc
│  ├── nrf
│  │  ├── app_dev
│  │  │  ├── device_guides
│  │  │  │  ├── nrf54h
│  │  │  │  │  │ ug_nrf54h20_suit_recovery.rst

Outputs:

Toolchain

Version:
Build docker image:

Test Spec & Results: ✅ Success; ❌ Failure; 🟠 Queued; 🟡 Progress; ◻️ Skipped; ⚠️ Quarantine

◻️ Toolchain
◻️ Build twister
◻️ Integration tests

Disabled integration tests

- desktop52_verification
- test_ble_nrf_config
- test-fw-nrfconnect-apps
- test-fw-nrfconnect-ble_mesh
- test-fw-nrfconnect-ble_samples
- test-fw-nrfconnect-boot
- test-fw-nrfconnect-chip
- test-fw-nrfconnect-fem
- test-fw-nrfconnect-nfc
- test-fw-nrfconnect-nrf-iot_libmodem-nrf
- test-fw-nrfconnect-nrf-iot_lwm2m
- test-fw-nrfconnect-nrf-iot_mosh
- test-fw-nrfconnect-nrf-iot_nrf_provisioning
- test-fw-nrfconnect-nrf-iot_positioning
- test-fw-nrfconnect-nrf-iot_samples
- test-fw-nrfconnect-nrf-iot_serial_lte_modem
- test-fw-nrfconnect-nrf-iot_thingy91
- test-fw-nrfconnect-nrf-iot_zephyr_lwm2m
- test-fw-nrfconnect-nrf_crypto
- test-fw-nrfconnect-ps
- test-fw-nrfconnect-rpc
- test-fw-nrfconnect-rs
- test-fw-nrfconnect-tfm
- test-fw-nrfconnect-thread
- test-fw-nrfconnect-zigbee
- test-low-level
- test-sdk-audio
- test-sdk-dfu
- test-sdk-find-my
- test-sdk-mcuboot
- test-sdk-pmic-samples
- test-sdk-sidewalk
- test-sdk-wifi
- test-secdom-samples-public

Note: This message is automatically posted and updated by the CI

NordicBuilder · 2024-12-03T13:06:00Z

You can find the documentation preview for this PR at this link. It will be updated about 10 minutes after the documentation build succeeds.

Note: This comment is automatically posted by the Documentation Publish GitHub Action.

tomchy · 2024-12-03T16:04:58Z

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst

+
+   Replace ``button0`` with the appropriate button node.
+
+2. Enable :kconfig:option:`CONFIG_SUIT_RECOVERY_BUTTON` in the main application configuration.


Just thinking - since SUIT_RECOVERY_BUTTON already depends on DTS: $(dt_chosen_enabled,$(DT_CHOSEN_NCS_RECOVERY_BUTTON)), maybe we can state default y in that symbol too, so the DTS modification will be the only one required to enable this feature?

In other words - is there a practical case, in which the ncs,recovery-button is defined, yet the recovery button should not be checked?

You are probably right, I've changed this in the other PR and removed the second step

maciejpietras

Small suggestions to be verified by Tech writers

maciejpietras · 2024-12-04T06:29:53Z

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst

+When this feature is enabled, the device will enter recovery mode if the button is pressed during boot.
+
+.. note::
+   To exit the recovery mode, a device firmware update must be performed.


Cold boot will not allow to leave this mode? Any other possibility to leave?

maciejpietras · 2024-12-04T06:32:40Z

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst

+Recovery button checked in the recovery application
+===================================================
+
+In this variant the recovery application is run as a companion image before the main application when the device boots.


Suggested change

In this variant the recovery application is run as a companion image before the main application when the device boots.

In this variant, during the boot the recovery application is run as a companion image before the main application .

I've modified it in a slightly different way, but I think it's better now

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst

FrancescoSer · 2024-12-05T14:30:58Z

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst

+:ref:`Entering recovery via button press <ug_nrf54h20_suit_recovery_enter_via_button>` uses such requests.
+The code for this feature is located in the :file:`nrf/subsys/suit/app_tools/recovery_button` directory.
+It can be used as a reference design.
+
+To request entering the recovery mode, the ``suit_foreground_dfu_required()`` function must be called.


Suggested change

:ref:`Entering recovery via button press <ug_nrf54h20_suit_recovery_enter_via_button>` uses such requests.

The code for this feature is located in the :file:`nrf/subsys/suit/app_tools/recovery_button` directory.

It can be used as a reference design.

To request entering the recovery mode, the ``suit_foreground_dfu_required()`` function must be called.

For additional details, see :ref:`Entering recovery via button press <ug_nrf54h20_suit_recovery_enter_via_button>`, which demonstrates similar request-based entry.

The implementation of this feature is available in the :file:`nrf/subsys/suit/app_tools/recovery_button` directory.

This directory contains a reference design that can be adapted as needed.

To request the device to enter recovery mode, invoke the ``suit_foreground_dfu_required()`` function.

Additional to these changes, line 252:

"For additional details, see :ref:Entering recovery mode through button press <ug_nrf54h20_suit_recovery_enter_through_button>, which demonstrates similar request-based entry."

The suggested change has a bit different meaning than I intended - the recovery_button is a module which uses the described feature (entering recovery through a request - by the way, it uses it exactly, it does not use a "similar entry") - however it is not strictly a reference design/sample, it is a full-fledged feature. However, it is currently the only code which uses this feature, so I wanted to suggest to the documentation reader that if he wants to see an example, this module is the best place to start with.

I've modified the text a bit, please take a look now

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst

richabp · 2024-12-05T20:29:41Z

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst

+:ref:`Entering recovery via button press <ug_nrf54h20_suit_recovery_enter_via_button>` uses such requests.
+The code for this feature is located in the :file:`nrf/subsys/suit/app_tools/recovery_button` directory.
+It can be used as a reference design.
+
+To request entering the recovery mode, the ``suit_foreground_dfu_required()`` function must be called.


Additional to these changes, line 252:

"For additional details, see :ref:Entering recovery mode through button press <ug_nrf54h20_suit_recovery_enter_through_button>, which demonstrates similar request-based entry."

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst

FrancescoSer

Approving but please fix this one issue

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst

This commit documents the feature allowing to enter SUIT recovery via a button press. Signed-off-by: Artur Hadasz <[email protected]>

ahasztag requested review from tomchy, SylwesterKonczyk, jnsgsr, maciejpietras, robertstypa and kszromek-nordic December 3, 2024 12:48

ahasztag requested a review from a team as a code owner December 3, 2024 12:48

github-actions bot added doc-required PR must not be merged without tech writer approval. changelog-entry-required Update changelog before merge. Remove label if entry is not needed or already added. labels Dec 3, 2024

ahasztag requested review from FrancescoSer and removed request for FrancescoSer December 3, 2024 14:34

tomchy approved these changes Dec 3, 2024

View reviewed changes

maciejpietras approved these changes Dec 4, 2024

View reviewed changes

ahasztag marked this pull request as draft December 4, 2024 13:41

ahasztag force-pushed the NCSDK-29999_recovery_button_doc branch 2 times, most recently from b3829d0 to 47727d9 Compare December 5, 2024 12:22

ahasztag marked this pull request as ready for review December 5, 2024 12:23

ahasztag requested review from tomchy and maciejpietras December 5, 2024 12:23

ahasztag force-pushed the NCSDK-29999_recovery_button_doc branch 3 times, most recently from 1ff5cd7 to 737710e Compare December 5, 2024 13:10

maciejpietras requested a review from FrancescoSer December 5, 2024 13:12

ahasztag force-pushed the NCSDK-29999_recovery_button_doc branch from 737710e to 3ecf3d3 Compare December 5, 2024 13:47

FrancescoSer requested changes Dec 5, 2024

View reviewed changes

richabp requested changes Dec 5, 2024

View reviewed changes

ahasztag force-pushed the NCSDK-29999_recovery_button_doc branch from 2246468 to 0811777 Compare December 6, 2024 07:50

ahasztag force-pushed the NCSDK-29999_recovery_button_doc branch from 0811777 to 1a5ae57 Compare December 6, 2024 13:30

tomchy approved these changes Dec 6, 2024

View reviewed changes

richabp requested changes Dec 9, 2024

View reviewed changes

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst Outdated Show resolved Hide resolved

richabp added this to the 2.9.0-nRF54H20 milestone Dec 10, 2024

FrancescoSer requested changes Dec 11, 2024

View reviewed changes

ahasztag force-pushed the NCSDK-29999_recovery_button_doc branch from 2d74809 to 35536bd Compare December 11, 2024 15:10

FrancescoSer approved these changes Dec 11, 2024

View reviewed changes

doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_suit_recovery.rst Outdated Show resolved Hide resolved

doc: SUIT recovery button documentation

56069f2

This commit documents the feature allowing to enter SUIT recovery via a button press. Signed-off-by: Artur Hadasz <[email protected]>

ahasztag force-pushed the NCSDK-29999_recovery_button_doc branch from 0f7b3db to 56069f2 Compare December 11, 2024 15:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: SUIT recovery button documentation #19217

doc: SUIT recovery button documentation #19217

ahasztag commented Dec 3, 2024

NordicBuilder commented Dec 3, 2024 •

edited

Loading

NordicBuilder commented Dec 3, 2024

tomchy Dec 3, 2024

ahasztag Dec 5, 2024

maciejpietras left a comment •

edited

Loading

maciejpietras Dec 4, 2024 •

edited

Loading

maciejpietras Dec 4, 2024

ahasztag Dec 5, 2024

FrancescoSer Dec 5, 2024

richabp Dec 5, 2024

ahasztag Dec 6, 2024

richabp Dec 5, 2024

FrancescoSer left a comment


		Replace ``button0`` with the appropriate button node.

		2. Enable :kconfig:option:`CONFIG_SUIT_RECOVERY_BUTTON` in the main application configuration.

	In this variant the recovery application is run as a companion image before the main application when the device boots.
	In this variant, during the boot the recovery application is run as a companion image before the main application .

doc: SUIT recovery button documentation #19217

Are you sure you want to change the base?

doc: SUIT recovery button documentation #19217

Conversation

ahasztag commented Dec 3, 2024

NordicBuilder commented Dec 3, 2024 • edited Loading

CI Information

Inputs:

Sources:

Github labels

Outputs:

Toolchain

Test Spec & Results: ✅ Success; ❌ Failure; 🟠 Queued; 🟡 Progress; ◻️ Skipped; ⚠️ Quarantine

NordicBuilder commented Dec 3, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maciejpietras left a comment • edited Loading

Choose a reason for hiding this comment

maciejpietras Dec 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

FrancescoSer left a comment

Choose a reason for hiding this comment

NordicBuilder commented Dec 3, 2024 •

edited

Loading

maciejpietras left a comment •

edited

Loading

maciejpietras Dec 4, 2024 •

edited

Loading