From 3e3c865ec1f35e545b0f82e1e818fdef464d9f7f Mon Sep 17 00:00:00 2001 From: Krzysztof Taborowski Date: Mon, 1 Sep 2025 15:15:59 +0200 Subject: [PATCH 1/2] doc: migration guide for new radio architecture - architecture overview - sample hardware description with shields - new devicetree source configuration - external links Signed-off-by: Krzysztof Taborowski --- .../migration_guide_addon_v110.rst | 252 ++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 doc/releases_and_migration/migration_guide_addon_v110.rst diff --git a/doc/releases_and_migration/migration_guide_addon_v110.rst b/doc/releases_and_migration/migration_guide_addon_v110.rst new file mode 100644 index 000000000..b492758ca --- /dev/null +++ b/doc/releases_and_migration/migration_guide_addon_v110.rst @@ -0,0 +1,252 @@ +.. _migration_guide_addon_v110: + +Migration guide for moving to Sidewalk Add-on v1.1.0 +#################################################### + + +Semtech radio +============= + +Starting from this release, the direct board overlay configuration for Semtech SX126x radio only was replaced with standardized DTS bindings for Semtech SX126x and LR1110 radios. + +Key changes: +- **Architecture**: from single-radio to multi-radio architecture +- **Devicetree Sources**: from basic GPIO and SPI label to advanced radio description +- **Samples**: from board-specific to shield-based configuration + +Architecture +************ + +SubGHz radio configuration in Sidewalk is based on `Zephyr Devicetree Sources `_ with a hardware description. It a common approach for all nRF Connect SDK applications. + +Starting from this release, Semtech radios devicetree bindings (YAML files) are based on `LoRa Basics Modem integration in Zephyr OS `_. It standardize radio description and allows to faster transition form LoRaWAN to Sidewalk projects based on Zephyr OS. + +Sidewalk Platform Abstraction Layer for subGHz radio uses Sidewalk specific implementation (different than Lora Basic Modem in Zephyr). Sidewalk drivers doesn't follow Zephyr Device Driver model, instead hardware configuration form devicetree sources is translated to Sidewalk driver configuration structures in app_subGHz_config files. + +Semtech radio parameters configured in devicetree: +- GPIOs +- SPI +- TCXO config +- regulator mode +- rx boost +- rfswitch (lr110 only) + +Semtech radio parameters configured only in app_subGHz_config file: +- lna gain +- state timings +- regional config + +File changes +************ + +The following files was impacted by new radio approach: +- app_subGHz_config: ``subsys/config/common/src/app_subGHz_config.c ``was deleted and replaced with radio specyfic files: ``app_subGHz_config_lr11xx.c`` and ``app_subGHz_config_sx126x.c``. +- get_radio_cfg: ``const radio_sx126x_device_config_t* get_radio_cfg(void)`` was replaced with ``const void* get_radio_cfg(void);``. It affects sidewalk platform initialization in ``sidewalk_event_platform_init`` (from ``samples/sid_end_device/src/sidewalk_events.c``) and ``sid_pal_common_init``(from ``subsys/sal/sid_pal/src/sid_common.c``) +- Devicetree: Added radio hardware description in: ``dts/bindings/lora_lbm`` and ``include/zephyr/dt-bindings/lora_lbm``. +- Shields: Added Arduino compatible Semtech radio shields in ``sidewalk/boards/shields`` + +New radio lr1110 +**************** + +The support for new Semtech radio was added. The major changes included: + +- DTS bindings dts/bindings/lora_lbm/semtech,lr1110.yaml +- Driver subsys/semtech/lr1110 +- Shield boards/shields/semtech_lr11xxmb1xxs/ +- Radio config ubsys/config/common/src/app_subGHz_config_lr11xx.c + +Samples +******* + +Sidewalk transport protocol configuration (BLE, FSK, LoRa) is chosen automatically based on hardware description. Use Zephyr `shield `_ to describe your hardware (nRF development boards and attached modules). + +.. tabs:: + .. tab:: New Shield-based configuration + + BLE only + + .. code-block:: console + + west build -b nrf52840dk/nrf52840 + + Semtech sx1262 radio + + .. code-block:: console + + west build -b nrf52840dk/nrf52840 --shield semtech_sx1262mb2cas + + Semtech lr1110 radio + + .. code-block:: console + + west build -b nrf52840dk/nrf52840 --shield semtech_lr1110mb1kas + + Semtech radio on nRF54L15 DK + + .. code-block:: console + + west build -b nrf54l15dk/nrf54l15/cpuapp --shield simple_arduino_adapter --shield semtech_sx1262mb2cas + + .. tab:: Old board-specific configuration + + BLE only + + .. code-block:: console + + west build -b nrf52840dk/nrf52840 -- -DCONFIG_SIDEWALK_SUBGHZ_SUPPORT=n + + Semtech sx1262 radio + + .. code-block:: console + + west build -b nrf52840dk/nrf52840 + + Semtech lr1110 radio + + Not supported + + Semtech radio on nRF54L15 DK + + .. code-block:: console + + west build -b nrf54l15dk/nrf54l15/cpuapp + +Devicetree Sources +****************** + +Example dts code snippet for nRF54l15 and sx126x hardware are shown below. + +.. tabs:: + + .. tab:: New radio description + + .. code-block:: dts + + #include + + / { + chosen { + zephyr,lora-transceiver = &lora_semtech_sx126xmb2xxs; + }; + aliases { + lora-transceiver = &lora_semtech_sx126xmb2xxs; + }; + }; + + &spi30 { + status = "okay"; + pinctrl-0 = <&spi30_default_alt>; + pinctrl-1 = <&spi30_sleep_alt>; + pinctrl-names = "default", "sleep"; + cs-gpios = <&gpio0 0 GPIO_ACTIVE_LOW>; + lora_semtech_sx126xmb2xxs: lora@0 { + reg = <0>; + spi-max-frequency = ; + reset-gpios = <&gpio2 8 GPIO_ACTIVE_LOW>; + busy-gpios = <&gpio2 6 GPIO_ACTIVE_HIGH>; + dio1-gpios = <&&gpio1 11 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>; + dio2-as-rf-switch; + reg-mode = ; + tcxo-wakeup-time = <0>; + tcxo-voltage = ; + }; + }; + + &pinctrl { + spi30_default_alt: spi30_default_alt { + group1 { + psels = , + , + ; + }; + }; + + spi30_sleep_alt: spi30_sleep_alt { + group1 { + psels = , + , + ; + low-power-enable; + }; + }; + }; + + Notes: + + - Compatible with ``sidewalk/dts/bindings/lora_lbm`` + - Semtech radio ``chosen`` as zephyr lora transceiver + - Semtech radio is a sub-node for spi node + + .. tab:: Old GPIO and SPI labels + .. code-block:: dts + + /{ + semtech_sx1262_gpios{ + compatible = "gpio-keys"; + semtech_sx1262_reset_gpios: reset { + gpios = <&gpio2 8 (GPIO_ACTIVE_LOW|GPIO_PULL_UP)>; + label = "semtech_sx1262 Reset"; + }; + semtech_sx1262_busy_gpios: busy { + gpios = <&gpio2 6 (GPIO_ACTIVE_HIGH)>; + label = "semtech_sx1262 Busy"; + }; + semtech_sx1262_antenna_enable_gpios: antena_enable { + gpios = <&gpio2 10 (GPIO_ACTIVE_HIGH)>; + label = "semtech_sx1262 Antena Enable"; + }; + semtech_sx1262_dio1_gpios: dio1 { + gpios = <&gpio1 11 (GPIO_ACTIVE_HIGH|GPIO_PULL_DOWN)>; + label = "semtech_sx1262 DIO1"; + }; + }; + }; + + sid_semtech: &spi30 { + compatible = "nordic,nrf-spim"; + status = "okay"; + cs-gpios = <&gpio0 0 GPIO_ACTIVE_LOW>; + pinctrl-0 = <&spi30_default_alt>; + pinctrl-1 = <&spi30_sleep_alt>; + pinctrl-names = "default", "sleep"; + clock-frequency = ; + }; + + &pinctrl { + spi30_default_alt: spi30_default_alt { + group1 { + psels = , + , + ; + }; + }; + + spi30_sleep_alt: spi30_sleep_alt { + group1 { + psels = , + , + ; + low-power-enable; + }; + }; + }; + + Notes: + + - SPI instance alias ``sid_semtech`` + - Semtech gpios defined separately + +SPI driver from nrfx instead of Zephyr +************************************** + +The ``spi_nrfx`` `snippet `_ in Sidewalk sample added necessary changes in kconfigs and dts to use nrfx spi driver. The nrfx spi driver is recommended on nRF52 design with FSK transport protocol. +It's important to add snippet to ``sid_end_device`` namespace only. In other case build issues in mcuboot image build fails. + +.. code-block:: console + + west build -b nrf52840dk/nrf52840 -p -- -DSHIELD="semtech_sx1262mb2cas" -Dsid_end_device_SNIPPET="spi_nrfx" + +.. TODO: Troubleshooting: +.. no sidewalk in west (no boards, dts, sources) +.. no lora-transceiver in zephyr, no spi +.. etc From 99e0ea0b71770524c5e8104268f2c06cf3bf18e0 Mon Sep 17 00:00:00 2001 From: Krzysztof Taborowski Date: Mon, 1 Sep 2025 15:15:59 +0200 Subject: [PATCH 2/2] doc: self review ai review, fix doc build issues Signed-off-by: Krzysztof Taborowski --- doc/release_notes_and_migration.rst | 1 + .../migration_guide_addon_v110.rst | 111 ++++++++++++------ 2 files changed, 73 insertions(+), 39 deletions(-) diff --git a/doc/release_notes_and_migration.rst b/doc/release_notes_and_migration.rst index 36e66faa8..a381ecb1d 100644 --- a/doc/release_notes_and_migration.rst +++ b/doc/release_notes_and_migration.rst @@ -23,4 +23,5 @@ See the available migration guides that will assist you in the transitioning fro :maxdepth: 1 :glob: + releases_and_migration/migration_guide_addon_v110.rst releases_and_migration/migration_guide_addon_v010.rst diff --git a/doc/releases_and_migration/migration_guide_addon_v110.rst b/doc/releases_and_migration/migration_guide_addon_v110.rst index b492758ca..2a2069d46 100644 --- a/doc/releases_and_migration/migration_guide_addon_v110.rst +++ b/doc/releases_and_migration/migration_guide_addon_v110.rst @@ -3,57 +3,81 @@ Migration guide for moving to Sidewalk Add-on v1.1.0 #################################################### +Overview +======== + +This migration guide covers the transition from Sidewalk Add-on v1.0.1 to v1.1.0. +The main changes include: + +- :ref:`Semtech radio ` - Add new radio, refactor the radio configuration (see ). + +.. Important: Existing SX126x users can continue without changes, + but new features require migration to the shield system. + +Breaking Changes +================ + +.. Important: These changes require code modifications + +- **API Change**: ``get_radio_cfg()`` function signature changed from ``const radio_sx126x_device_config_t*`` to ``const void*`` +- **File Deletion**: :file:`subsys/config/common/src/app_subGHz_config.c` removed and replaced with radio-specific files +- **Build System**: Radio drivers now use conditional compilation based on devicetree + +.. _semtech_radio_migration: Semtech radio ============= -Starting from this release, the direct board overlay configuration for Semtech SX126x radio only was replaced with standardized DTS bindings for Semtech SX126x and LR1110 radios. +Starting from this release, the direct board overlay configuration for Semtech SX126x radio only has been replaced with standardized DTS bindings for Semtech SX126x and LR1110 radios. Key changes: -- **Architecture**: from single-radio to multi-radio architecture -- **Devicetree Sources**: from basic GPIO and SPI label to advanced radio description -- **Samples**: from board-specific to shield-based configuration +- **Architecture**: From single-radio to configurable radio architecture +- **Devicetree Sources**: From basic GPIO and SPI labels to advanced radio description +- **Samples**: From board-specific to shield-based configuration Architecture ************ -SubGHz radio configuration in Sidewalk is based on `Zephyr Devicetree Sources `_ with a hardware description. It a common approach for all nRF Connect SDK applications. +SubGHz radio configuration in Sidewalk is based on `Zephyr Devicetree Sources `_ with hardware description. It is a common approach for all nRF Connect SDK applications. -Starting from this release, Semtech radios devicetree bindings (YAML files) are based on `LoRa Basics Modem integration in Zephyr OS `_. It standardize radio description and allows to faster transition form LoRaWAN to Sidewalk projects based on Zephyr OS. +Starting from this release, Semtech radio devicetree bindings (YAML files) are based on `LoRa Basics Modem integration in Zephyr OS `_. This standardizes radio description and allows faster transition from LoRaWAN to Sidewalk projects based on Zephyr OS. -Sidewalk Platform Abstraction Layer for subGHz radio uses Sidewalk specific implementation (different than Lora Basic Modem in Zephyr). Sidewalk drivers doesn't follow Zephyr Device Driver model, instead hardware configuration form devicetree sources is translated to Sidewalk driver configuration structures in app_subGHz_config files. +Sidewalk Platform Abstraction Layer for subGHz radio uses Sidewalk-specific implementation (different from LoRa Basic Modem in Zephyr). Sidewalk drivers do not follow the Zephyr Device Driver model. Instead, hardware configuration from devicetree sources is translated to Sidewalk driver configuration structures in app_subGHz_config files. Semtech radio parameters configured in devicetree: + - GPIOs - SPI - TCXO config -- regulator mode -- rx boost -- rfswitch (lr110 only) +- Regulator mode +- RX boost +- RF switch (LR1110 only) Semtech radio parameters configured only in app_subGHz_config file: -- lna gain -- state timings -- regional config + +- LNA gain +- State timings +- Regional config File changes ************ -The following files was impacted by new radio approach: -- app_subGHz_config: ``subsys/config/common/src/app_subGHz_config.c ``was deleted and replaced with radio specyfic files: ``app_subGHz_config_lr11xx.c`` and ``app_subGHz_config_sx126x.c``. -- get_radio_cfg: ``const radio_sx126x_device_config_t* get_radio_cfg(void)`` was replaced with ``const void* get_radio_cfg(void);``. It affects sidewalk platform initialization in ``sidewalk_event_platform_init`` (from ``samples/sid_end_device/src/sidewalk_events.c``) and ``sid_pal_common_init``(from ``subsys/sal/sid_pal/src/sid_common.c``) -- Devicetree: Added radio hardware description in: ``dts/bindings/lora_lbm`` and ``include/zephyr/dt-bindings/lora_lbm``. -- Shields: Added Arduino compatible Semtech radio shields in ``sidewalk/boards/shields`` +The following files were impacted by the new radio approach: + +- **app_subGHz_config**: :file:`subsys/config/common/src/app_subGHz_config.c` was deleted and replaced with radio-specific files: :file:`app_subGHz_config_lr11xx.c` and :file:`app_subGHz_config_sx126x.c`. +- **get_radio_cfg**: ``const radio_sx126x_device_config_t* get_radio_cfg(void)`` was replaced with ``const void* get_radio_cfg(void);``. This affects sidewalk platform initialization in :file:`samples/sid_end_device/src/sidewalk_events.c` and :file:`subsys/sal/sid_pal/src/sid_common.c`. +- **Devicetree**: Added radio hardware description in: :file:`dts/bindings/lora_lbm` and :file:`include/zephyr/dt-bindings/lora_lbm`. +- **Shields**: Added Arduino-compatible Semtech radio shields in :file:`boards/shields`. -New radio lr1110 +New radio LR1110 **************** -The support for new Semtech radio was added. The major changes included: +Support for the new Semtech LR1110 radio was added. The major changes included: -- DTS bindings dts/bindings/lora_lbm/semtech,lr1110.yaml -- Driver subsys/semtech/lr1110 -- Shield boards/shields/semtech_lr11xxmb1xxs/ -- Radio config ubsys/config/common/src/app_subGHz_config_lr11xx.c +- DTS bindings: :file:`dts/bindings/lora_lbm/semtech,lr1110.yaml` +- Driver: :file:`subsys/semtech/lr1110` +- Shield: :file:`boards/shields/semtech_lr11xxmb1xxs/` +- Radio config: :file:`subsys/config/common/src/app_subGHz_config_lr11xx.c` Samples ******* @@ -69,23 +93,23 @@ Sidewalk transport protocol configuration (BLE, FSK, LoRa) is chosen automatical west build -b nrf52840dk/nrf52840 - Semtech sx1262 radio + Semtech SX126x radio .. code-block:: console - west build -b nrf52840dk/nrf52840 --shield semtech_sx1262mb2cas + west build -b nrf52840dk/nrf52840 --shield semtech_sx126xmb2xxs - Semtech lr1110 radio + Semtech LR1110 radio .. code-block:: console - west build -b nrf52840dk/nrf52840 --shield semtech_lr1110mb1kas + west build -b nrf52840dk/nrf52840 --shield semtech_lr11xxmb1xxs Semtech radio on nRF54L15 DK .. code-block:: console - west build -b nrf54l15dk/nrf54l15/cpuapp --shield simple_arduino_adapter --shield semtech_sx1262mb2cas + west build -b nrf54l15dk/nrf54l15/cpuapp --shield simple_arduino_adapter --shield semtech_sx126xmb2xxs .. tab:: Old board-specific configuration @@ -95,13 +119,13 @@ Sidewalk transport protocol configuration (BLE, FSK, LoRa) is chosen automatical west build -b nrf52840dk/nrf52840 -- -DCONFIG_SIDEWALK_SUBGHZ_SUPPORT=n - Semtech sx1262 radio + Semtech SX126x radio .. code-block:: console west build -b nrf52840dk/nrf52840 - Semtech lr1110 radio + Semtech LR1110 radio Not supported @@ -114,7 +138,7 @@ Sidewalk transport protocol configuration (BLE, FSK, LoRa) is chosen automatical Devicetree Sources ****************** -Example dts code snippet for nRF54l15 and sx126x hardware are shown below. +Example DTS code snippets for nRF54L15 and SX126x hardware are shown below. .. tabs:: @@ -144,7 +168,7 @@ Example dts code snippet for nRF54l15 and sx126x hardware are shown below. spi-max-frequency = ; reset-gpios = <&gpio2 8 GPIO_ACTIVE_LOW>; busy-gpios = <&gpio2 6 GPIO_ACTIVE_HIGH>; - dio1-gpios = <&&gpio1 11 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>; + dio1-gpios = <&gpio1 11 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>; dio2-as-rf-switch; reg-mode = ; tcxo-wakeup-time = <0>; @@ -173,11 +197,12 @@ Example dts code snippet for nRF54l15 and sx126x hardware are shown below. Notes: - - Compatible with ``sidewalk/dts/bindings/lora_lbm`` + - Compatible with :file:`dts/bindings/lora_lbm` - Semtech radio ``chosen`` as zephyr lora transceiver - - Semtech radio is a sub-node for spi node + - Semtech radio is a sub-node for SPI node .. tab:: Old GPIO and SPI labels + .. code-block:: dts /{ @@ -234,17 +259,25 @@ Example dts code snippet for nRF54l15 and sx126x hardware are shown below. Notes: - SPI instance alias ``sid_semtech`` - - Semtech gpios defined separately + - Semtech GPIOs defined separately SPI driver from nrfx instead of Zephyr ************************************** -The ``spi_nrfx`` `snippet `_ in Sidewalk sample added necessary changes in kconfigs and dts to use nrfx spi driver. The nrfx spi driver is recommended on nRF52 design with FSK transport protocol. -It's important to add snippet to ``sid_end_device`` namespace only. In other case build issues in mcuboot image build fails. +The ``spi_nrfx`` `snippet `_ in Sidewalk sample adds necessary changes in Kconfigs and DTS to use nrfx SPI driver. The nrfx SPI driver is recommended on nRF52 designs with FSK transport protocol. + +.. Important: It is important to add the snippet to the ``sid_end_device`` namespace only. + Otherwise, build issues in mcuboot image build will fail. .. code-block:: console - west build -b nrf52840dk/nrf52840 -p -- -DSHIELD="semtech_sx1262mb2cas" -Dsid_end_device_SNIPPET="spi_nrfx" + west build -b nrf52840dk/nrf52840 -p -- -DSHIELD="semtech_sx126xmb2xxs" -Dsid_end_device_SNIPPET="spi_nrfx" + + +Troubleshooting +=============== + +Common issues and solutions: .. TODO: Troubleshooting: .. no sidewalk in west (no boards, dts, sources)