doc: migration guide for new radio architecture

- sample hardware description with shields
- new devicetree source configuration

Signed-off-by: Krzysztof Taborowski <[email protected]>

Author: ktaborowski

doc/releases_and_migration/migration_guide_addon_v110.rst

@@ -0,0 +1,217 @@
+.. _migration_guide_addon_v110:
+
+Migration guide for moving to Sidewalk Add-on v1.1.0
+####################################################
+
+
+Semtech radio
+=============
+
+Key changes:
+- **Architecture**: from single-radio to multi-radio architecture
+- **Samples**: from board-specific to shield-based configuration
+- **Devicetree Sources**: from basic GPIO and SPI label to advanced radio description
+
+radio configuration:
+- DTS : pinout, spi instance, tcxo, ...
+- subGHz_config.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
+*******************
+
+.. tabs::
+
+    .. tab:: New radio description
+
+        .. code-block:: dts
+
+            #include <zephyr/dt-bindings/lora_lbm/sx126x.h>
+
+            / {
+                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 = <DT_FREQ_M(8)>;
+                    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 = <SX126X_REG_MODE_LDO>;
+                    tcxo-wakeup-time = <0>;
+                    tcxo-voltage = <SX126X_TCXO_SUPPLY_1_8V>;
+                };
+            };
+
+            &pinctrl {
+                spi30_default_alt: spi30_default_alt {
+                    group1 {
+                        psels = <NRF_PSEL(SPIM_SCK, 0, 3)>,
+                                <NRF_PSEL(SPIM_MISO, 0, 2)>,
+                                <NRF_PSEL(SPIM_MOSI, 0, 1)>;
+                    };
+                };
+
+                spi30_sleep_alt: spi30_sleep_alt {
+                    group1 {
+                        psels = <NRF_PSEL(SPIM_SCK, 0, 3)>,
+                                <NRF_PSEL(SPIM_MISO, 0, 2)>,
+                                <NRF_PSEL(SPIM_MOSI, 0, 1)>;
+                        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 = <DT_FREQ_M(8)>;
+            };
+
+            &pinctrl {
+                spi30_default_alt: spi30_default_alt {
+                    group1 {
+                        psels = <NRF_PSEL(SPIM_SCK, 0, 3)>,
+                            <NRF_PSEL(SPIM_MISO, 0, 2)>,
+                            <NRF_PSEL(SPIM_MOSI, 0, 1)>;
+                    };
+                };
+
+                spi30_sleep_alt: spi30_sleep_alt {
+                    group1 {
+                        psels = <NRF_PSEL(SPIM_SCK, 0, 3)>,
+                            <NRF_PSEL(SPIM_MISO, 0, 2)>,
+                            <NRF_PSEL(SPIM_MOSI, 0, 1)>;
+                        low-power-enable;
+                    };
+                };
+            };
+
+        Notes:
+
+        - SPI instance alias ``sid_semtech``
+        - Semtech gpios defined separately
+        - For nRF52 with nrfx spi driver see: 
+        .. TODO: add nrfx spi snippet section
+
+
+
+Compare Zephyr LBM and Sidewalk
+*******************************
+Rationale. Simplify moving from LoRaWAN to Sidewalk.
+The Semtech radio was added based on Semtech Lora Basic Modem for Zephyr project.
+Sidewalk configuration uses similar dts configuration, but different driver implementation.
+
+Troubleshooting
+***************
+- no sidewalk in west (no boards, dts, sources)
+- sid_semtech left
+- nrfx spi as snippet (for FSK issues on nRF52)
+
+
+Links:
+- Nordic Academy Device Tree lesson https://academy.nordicsemi.com/courses/nrf-connect-sdk-fundamentals/lessons/lesson-2-reading-buttons-and-controlling-leds/topic/devicetree/ 
+- Shields https://docs.nordicsemi.com/bundle/ncs-3.0.0/page/zephyr/hardware/porting/shields.html#shield_activation