Migration guide for Amazon Sidewalk Add-On v1.3.0

This guide assists you in migrating from Amazon Sidewalk Add-On v1.2.0 to v1.3.0.

Overview

Amazon Sidewalk Add-On v1.3.0 upgrades the nRF Connect SDK to v3.4.0, aligns MCUboot configuration with NCS security recommendations, and moves persistent Sidewalk key storage to Key Management Unit (KMU) on nRF54L Series platforms.

Refer to the release_notes_addon_v130 for more details.

Migration steps

  1. Navigate to the Amazon Sidewalk Add-on repository (the sidewalk directory in your west workspace).

  2. Update the Add-on repository to the release tag v1.3.0-add-on from the sdk-sidewalk GitHub repository.

    The commands below assume a Git remote named ncs that points to sdk-sidewalk. If your remote uses a different name, substitute it for ncs.

    git fetch ncs
git checkout v1.3.0-add-on

  3. From your west workspace root (the parent directory of sidewalk), update the nRF Connect SDK and other west manifest projects:

    west update

  4. Perform a clean build:

    west build -p -b <board_target> <sidewalk_application>

Keeping RSA MCUboot signatures

Earlier add-on releases forced the RSA signature type (SB_CONFIG_BOOT_SIGNATURE_TYPE_RSA) for MCUboot across all platforms. This release removes that override and uses the nRF Connect SDK defaults (ED25519 on nRF54L Series platforms, ECDSA with P-256 curve on nRF52 Series platforms).

If your product was based on a previous add-on version, you must keep using RSA for signing application images to stay compatible with MCUboot on already-deployed devices. To force RSA signature type in your application, add the following to your application’s Kconfig.sysbuild file:

choice BOOT_SIGNATURE_TYPE
        default BOOT_SIGNATURE_TYPE_RSA
endchoice

Perform a pristine build of the application after adding this override.

Note

A device running MCUboot configured for RSA will not boot ED25519-signed images until MCUboot is updated and re-flashed with a matching configuration.

Persistent Sidewalk keys in KMU

Persistent Sidewalk cryptographic keys are now stored in the Key Management Unit (KMU) by default on supported nRF54L Series platforms. Use the CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE_KMU Kconfig option to control this feature. This option is not available on nRF52 Series platforms, which continue to use the default settings-based PSA trusted storage backend.

If you update devices that already have keys stored by an earlier firmware version, set CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE_KMU=n to keep the keys accessible. Switching a provisioned product from the PSA trusted storage to KMU changes both the storage location and the PSA key IDs, so Sidewalk cannot find the existing keys.

For new products, use the KMU default. Make sure that your application does not use the same KMU slots for other keys. Sidewalk starts at the slot defined by the CONFIG_SIDEWALK_CRYPTO_PSA_KEY_STORAGE_KMU_SLOT_START Kconfig option and reserves seven consecutive KMU slots:

  • Two slots for the manufacturing ED25519 private key.

  • Two slots for the manufacturing secp256r1 private key.

  • One slot each for the WAN master, app key, and device-to-device AES keys.

Removed platform support

Amazon Sidewalk Add-On v1.3.0 no longer supports the following development kits:

  • nRF5340 DK (nrf5340dk/nrf5340/cpuapp)

  • Thingy:53 (thingy53/nrf5340/cpuapp)

If your product uses one of these platforms, continue using the Sidewalk Add-On version earlier than v1.3.0.

Troubleshooting

When encountering issues, check the following:

  • For linker error or boot issues, perform a pristine build:

    west build -p -b <board_target> <your_application>

  • For other issues, ensure all dependencies are up to date:

    west update