Skip to content

Commit 17f9a6e

Browse files
ktaborowskiktaborowski
committed
doc: self review
ai review, fix doc build issues Signed-off-by: Krzysztof Taborowski <[email protected]>
1 parent e0843b6 commit 17f9a6e

File tree

2 files changed

+73
-39
lines changed

2 files changed

+73
-39
lines changed

‎doc/release_notes_and_migration.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,5 @@ See the available migration guides that will assist you in the transitioning fro
2323
:maxdepth: 1
2424
:glob:
2525

26+
releases_and_migration/migration_guide_addon_v110.rst
2627
releases_and_migration/migration_guide_addon_v010.rst

‎doc/releases_and_migration/migration_guide_addon_v110.rst‎

Lines changed: 72 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -3,57 +3,81 @@
33
Migration guide for moving to Sidewalk Add-on v1.1.0
44
####################################################
55

6+
Overview
7+
========
8+
9+
This migration guide covers the transition from Sidewalk Add-on v1.0.1 to v1.1.0.
10+
The main changes include:
11+
12+
- :ref:`Semtech radio <semtech_radio_migration>` - Add new radio, refactor the radio configuration (see ).
13+
14+
.. Important: Existing SX126x users can continue without changes,
15+
but new features require migration to the shield system.
16+
17+
Breaking Changes
18+
================
19+
20+
.. Important: These changes require code modifications
21+
22+
- **API Change**: ``get_radio_cfg()`` function signature changed from ``const radio_sx126x_device_config_t*`` to ``const void*``
23+
- **File Deletion**: :file:`subsys/config/common/src/app_subGHz_config.c` removed and replaced with radio-specific files
24+
- **Build System**: Radio drivers now use conditional compilation based on devicetree
25+
26+
.. _semtech_radio_migration:
627

728
Semtech radio
829
=============
930

10-
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.
31+
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.
1132

1233
Key changes:
13-
- **Architecture**: from single-radio to multi-radio architecture
14-
- **Devicetree Sources**: from basic GPIO and SPI label to advanced radio description
15-
- **Samples**: from board-specific to shield-based configuration
34+
- **Architecture**: From single-radio to configurable radio architecture
35+
- **Devicetree Sources**: From basic GPIO and SPI labels to advanced radio description
36+
- **Samples**: From board-specific to shield-based configuration
1637

1738
Architecture
1839
************
1940

20-
SubGHz radio configuration in Sidewalk is based on `Zephyr Devicetree Sources <https://academy.nordicsemi.com/courses/nrf-connect-sdk-fundamentals/lessons/lesson-2-reading-buttons-and-controlling-leds/topic/devicetree>`_ with a hardware description. It a common approach for all nRF Connect SDK applications.
41+
SubGHz radio configuration in Sidewalk is based on `Zephyr Devicetree Sources <https://academy.nordicsemi.com/courses/nrf-connect-sdk-fundamentals/lessons/lesson-2-reading-buttons-and-controlling-leds/topic/devicetree>`_ with hardware description. It is a common approach for all nRF Connect SDK applications.
2142

22-
Starting from this release, Semtech radios devicetree bindings (YAML files) are based on `LoRa Basics Modem integration in Zephyr OS <https://github.com/Lora-net/LBM_Zephyr>`_. It standardize radio description and allows to faster transition form LoRaWAN to Sidewalk projects based on Zephyr OS.
43+
Starting from this release, Semtech radio devicetree bindings (YAML files) are based on `LoRa Basics Modem integration in Zephyr OS <https://github.com/Lora-net/LBM_Zephyr>`_. This standardizes radio description and allows faster transition from LoRaWAN to Sidewalk projects based on Zephyr OS.
2344

24-
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.
45+
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.
2546

2647
Semtech radio parameters configured in devicetree:
48+
2749
- GPIOs
2850
- SPI
2951
- TCXO config
30-
- regulator mode
31-
- rx boost
32-
- rfswitch (lr110 only)
52+
- Regulator mode
53+
- RX boost
54+
- RF switch (LR1110 only)
3355

3456
Semtech radio parameters configured only in app_subGHz_config file:
35-
- lna gain
36-
- state timings
37-
- regional config
57+
58+
- LNA gain
59+
- State timings
60+
- Regional config
3861

3962
File changes
4063
************
4164

42-
The following files was impacted by new radio approach:
43-
- 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``.
44-
- 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``)
45-
- Devicetree: Added radio hardware description in: ``dts/bindings/lora_lbm`` and ``include/zephyr/dt-bindings/lora_lbm``.
46-
- Shields: Added Arduino compatible Semtech radio shields in ``sidewalk/boards/shields``
65+
The following files were impacted by the new radio approach:
66+
67+
- **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`.
68+
- **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`.
69+
- **Devicetree**: Added radio hardware description in: :file:`dts/bindings/lora_lbm` and :file:`include/zephyr/dt-bindings/lora_lbm`.
70+
- **Shields**: Added Arduino-compatible Semtech radio shields in :file:`boards/shields`.
4771

48-
New radio lr1110
72+
New radio LR1110
4973
****************
5074

51-
The support for new Semtech radio was added. The major changes included:
75+
Support for the new Semtech LR1110 radio was added. The major changes included:
5276

53-
- DTS bindings dts/bindings/lora_lbm/semtech,lr1110.yaml
54-
- Driver subsys/semtech/lr1110
55-
- Shield boards/shields/semtech_lr11xxmb1xxs/
56-
- Radio config ubsys/config/common/src/app_subGHz_config_lr11xx.c
77+
- DTS bindings: :file:`dts/bindings/lora_lbm/semtech,lr1110.yaml`
78+
- Driver: :file:`subsys/semtech/lr1110`
79+
- Shield: :file:`boards/shields/semtech_lr11xxmb1xxs/`
80+
- Radio config: :file:`subsys/config/common/src/app_subGHz_config_lr11xx.c`
5781

5882
Samples
5983
*******
@@ -69,23 +93,23 @@ Sidewalk transport protocol configuration (BLE, FSK, LoRa) is chosen automatical
6993
7094
west build -b nrf52840dk/nrf52840
7195
72-
Semtech sx1262 radio
96+
Semtech SX126x radio
7397

7498
.. code-block:: console
7599
76-
west build -b nrf52840dk/nrf52840 --shield semtech_sx1262mb2cas
100+
west build -b nrf52840dk/nrf52840 --shield semtech_sx126xmb2xxs
77101
78-
Semtech lr1110 radio
102+
Semtech LR1110 radio
79103

80104
.. code-block:: console
81105
82-
west build -b nrf52840dk/nrf52840 --shield semtech_lr1110mb1kas
106+
west build -b nrf52840dk/nrf52840 --shield semtech_lr11xxmb1xxs
83107
84108
Semtech radio on nRF54L15 DK
85109

86110
.. code-block:: console
87111
88-
west build -b nrf54l15dk/nrf54l15/cpuapp --shield simple_arduino_adapter --shield semtech_sx1262mb2cas
112+
west build -b nrf54l15dk/nrf54l15/cpuapp --shield simple_arduino_adapter --shield semtech_sx126xmb2xxs
89113
90114
.. tab:: Old board-specific configuration
91115

@@ -95,13 +119,13 @@ Sidewalk transport protocol configuration (BLE, FSK, LoRa) is chosen automatical
95119
96120
west build -b nrf52840dk/nrf52840 -- -DCONFIG_SIDEWALK_SUBGHZ_SUPPORT=n
97121
98-
Semtech sx1262 radio
122+
Semtech SX126x radio
99123

100124
.. code-block:: console
101125
102126
west build -b nrf52840dk/nrf52840
103127
104-
Semtech lr1110 radio
128+
Semtech LR1110 radio
105129

106130
Not supported
107131

@@ -114,7 +138,7 @@ Sidewalk transport protocol configuration (BLE, FSK, LoRa) is chosen automatical
114138
Devicetree Sources
115139
******************
116140

117-
Example dts code snippet for nRF54l15 and sx126x hardware are shown below.
141+
Example DTS code snippets for nRF54L15 and SX126x hardware are shown below.
118142

119143
.. tabs::
120144

@@ -144,7 +168,7 @@ Example dts code snippet for nRF54l15 and sx126x hardware are shown below.
144168
spi-max-frequency = <DT_FREQ_M(8)>;
145169
reset-gpios = <&gpio2 8 GPIO_ACTIVE_LOW>;
146170
busy-gpios = <&gpio2 6 GPIO_ACTIVE_HIGH>;
147-
dio1-gpios = <&&gpio1 11 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>;
171+
dio1-gpios = <&gpio1 11 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>;
148172
dio2-as-rf-switch;
149173
reg-mode = <SX126X_REG_MODE_LDO>;
150174
tcxo-wakeup-time = <0>;
@@ -173,11 +197,12 @@ Example dts code snippet for nRF54l15 and sx126x hardware are shown below.
173197
174198
Notes:
175199

176-
- Compatible with ``sidewalk/dts/bindings/lora_lbm``
200+
- Compatible with :file:`dts/bindings/lora_lbm`
177201
- Semtech radio ``chosen`` as zephyr lora transceiver
178-
- Semtech radio is a sub-node for spi node
202+
- Semtech radio is a sub-node for SPI node
179203

180204
.. tab:: Old GPIO and SPI labels
205+
181206
.. code-block:: dts
182207
183208
/{
@@ -234,17 +259,25 @@ Example dts code snippet for nRF54l15 and sx126x hardware are shown below.
234259
Notes:
235260

236261
- SPI instance alias ``sid_semtech``
237-
- Semtech gpios defined separately
262+
- Semtech GPIOs defined separately
238263

239264
SPI driver from nrfx instead of Zephyr
240265
**************************************
241266

242-
The ``spi_nrfx`` `snippet <https://docs.nordicsemi.com/bundle/ncs-3.0.0/page/zephyr/build/snippets/using.html>`_ 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.
243-
It's important to add snippet to ``sid_end_device`` namespace only. In other case build issues in mcuboot image build fails.
267+
The ``spi_nrfx`` `snippet <https://docs.nordicsemi.com/bundle/ncs-3.0.0/page/zephyr/build/snippets/using.html>`_ 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.
268+
269+
.. Important: It is important to add the snippet to the ``sid_end_device`` namespace only.
270+
Otherwise, build issues in mcuboot image build will fail.
244271
245272
.. code-block:: console
246273
247-
west build -b nrf52840dk/nrf52840 -p -- -DSHIELD="semtech_sx1262mb2cas" -Dsid_end_device_SNIPPET="spi_nrfx"
274+
west build -b nrf52840dk/nrf52840 -p -- -DSHIELD="semtech_sx126xmb2xxs" -Dsid_end_device_SNIPPET="spi_nrfx"
275+
276+
277+
Troubleshooting
278+
===============
279+
280+
Common issues and solutions:
248281

249282
.. TODO: Troubleshooting:
250283
.. no sidewalk in west (no boards, dts, sources)

0 commit comments

Comments
 (0)