Skip to content

Commit 4541067

Browse files
RobertGalatNordicRobertGalatNordic
committed
docs: update Sidewalk documentation for standalone west.yml [KRKNWK-20070]
- Update index.rst to reflect Sidewalk's move to standalone west.yml - Add migration_guide.rst to the main documentation toctree - Update include_building_and_running.txt to reference new setup process - Revise setting_up_sdk.rst with new setup process and migration steps - Add toolchain and Python package installation instructions - Update NCS documentation about Sidewalk configuration The changes reflect that Sidewalk is no longer part of the NCS manifest and now uses its own west.yml configuration, providing clearer setup instructions for both new users and those migrating from NCS. Signed-off-by: Robert Gałat <[email protected]>
1 parent 5af9273 commit 4541067

File tree

4 files changed

+192
-24
lines changed

4 files changed

+192
-24
lines changed

‎doc/includes/include_building_and_running.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ This sample can be found under :file:`samples/sid_end_device`.
33
.. note::
44
Before you flash your Sidewalk sample, make sure you have completed the following:
55

6-
* You downloaded the Sidewalk repository and updated west according to the :ref:`dk_building_sample_app` section.
6+
* You have set up the Sidewalk repository using the standalone west.yml configuration as described in the :ref:`setting_up_sdk` section.
77
* You provisioned your device during the :ref:`setting_up_sidewalk_prototype`.
88

99
This step needs to be completed only once.

‎doc/index.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77

88
Be aware, that by downloading and including the Sidewalk repository, you accept the above-mentioned license.
99

10-
Due to these restrictions, Sidewalk cannot be automatically fetched through the nRF Connect SDK and will require performing a dedicated setup.
11-
All information regarding completing it is included in this guide, so ensure you follow it in order.
10+
Due to these restrictions, Sidewalk is now managed through its own west.yml configuration, separate from the nRF Connect SDK manifest.
11+
All information regarding completing the setup is included in this guide, so ensure you follow it in order.
1212

1313
Welcome to the nRF Connect SDK - Amazon Sidewalk
1414
################################################
@@ -41,6 +41,7 @@ Browse the content by referring to the following pages:
4141
:caption: Subpages:
4242

4343
setting_up_sidewalk_environment/setting_up_environment.rst
44+
setting_up_sidewalk_environment/migration_guide.rst
4445
samples/samples_list.rst
4546
compatibility_matrix.rst
4647
releases_and_migration.rst

‎doc/setting_up_sidewalk_environment/migration_guide.rst‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
.. _migration_guide:
2+
3+
Migration Guide: Moving from NCS Manifest to Standalone west.yml
4+
###############################################################
5+
6+
This guide explains how to migrate your Sidewalk development environment from using the NCS manifest to the new standalone west.yml setup.
7+
8+
Overview
9+
========
10+
11+
The Sidewalk repository has been moved out of the NCS manifest into its own west.yml configuration. This change provides more flexibility and better control over the Sidewalk development environment. The Sidewalk release cycle will be detached from NCS, allowing for faster releases of new libraries on stable versions of NCS. The Sidewalk repository is now visible in the NCS add-on index repository, which enables an alternative setup method using the VSCode NRF Connect add-on.
12+
13+
Prerequisites
14+
============
15+
16+
Before starting the migration, ensure you have:
17+
18+
* Git installed on your system
19+
* Python 3.8 or later installed
20+
* The west tool installed
21+
* nrfutil installed (version 10.24.0 or later)
22+
23+
Alternative Setup Method
24+
=======================
25+
26+
If you prefer using VSCode, you can set up a clean environment using the NRF Connect add-on:
27+
28+
1. Install VSCode and the NRF Connect add-on
29+
2. Open VSCode and click on the NRF Connect icon in the sidebar
30+
3. Click on "Add Application" and select "Sidewalk" from the list of available applications
31+
4. Follow the prompts to set up your development environment
32+
33+
This method will automatically handle the repository setup and dependencies installation.
34+
35+
Migration Steps
36+
=============
37+
38+
1. Clone the New Sidewalk Repository
39+
----------------------------------
40+
41+
.. code-block:: console
42+
43+
# Clone the new Sidewalk repository into sidewalk directory
44+
git clone https://github.com/nordicsemiconductor/sidewalk.git sidewalk
45+
46+
2. Clean Existing West Configuration (if applicable)
47+
-------------------------------------------------
48+
49+
If you already have an NCS setup with Sidewalk, you need to remove the existing west configuration and ensure Sidewalk is checked out to the correct revision after the NCS separation:
50+
51+
.. code-block:: console
52+
53+
# Remove the .west directory to clean the west configuration
54+
rm -rf .west
55+
# Checkout and pull main branch in Sidewalk repository
56+
cd sidewalk
57+
git checkout main
58+
git pull origin main
59+
cd ..
60+
61+
3. Initialize West
62+
-----------------
63+
64+
.. code-block:: console
65+
66+
# Initialize west with the new manifest
67+
west init -l sidewalk
68+
69+
4. Update Repositories
70+
---------------------
71+
72+
.. code-block:: console
73+
74+
# Update all repositories
75+
west update
76+
77+
5. Update Toolchain and Install Dependencies
78+
------------------------------------------
79+
80+
.. code-block:: console
81+
82+
# Get the toolchain hash and download it
83+
nrf/scripts/toolchain.py
84+
nrfutil toolchain install --ncs-version $(nrf/scripts/toolchain.py --ncs-version)
85+
# Install Python dependencies for nRF and Zephyr
86+
pip install -r nrf/scripts/requirements.txt
87+
pip install -r zephyr/scripts/requirements.txt
88+
# Install Sidewalk Python requirements
89+
pip install -r requirements.txt
90+
91+
Verification
92+
===========
93+
94+
To verify your migration was successful:
95+
96+
1. Check that all repositories are properly cloned:
97+
98+
.. code-block:: console
99+
100+
west list
101+
102+
Expected output should show all required repositories with their paths and revisions. For example:
103+
104+
.. code-block:: console
105+
106+
name path revision
107+
---------------------- ---------------------- ----------------------
108+
manifest sidewalk main
109+
nrf nrf v2.5.0
110+
zephyr zephyr v3.5.0-ncs1
111+
...
112+
113+
Invalid output would be:
114+
* Empty list
115+
* Missing repositories
116+
* Error messages
117+
* "Not found" status for any repository
118+
119+
2. Verify the build process:
120+
121+
.. code-block:: console
122+
123+
west build -b nrf54l15dk/nrf54l15/cpuapp samples/sid_end_device
124+
125+
This will build the Sidewalk end device sample application. If the build succeeds, your migration was successful.
126+
127+
Common Issues and Solutions
128+
=========================
129+
130+
1. Repository Conflicts
131+
----------------------
132+
133+
If you encounter repository conflicts during the migration:
134+
135+
.. code-block:: console
136+
137+
# Remove the .west directory
138+
rm -rf .west
139+
# Reinitialize west
140+
west init -l sidewalk
141+
# Update repositories
142+
west update
143+
144+
2. Build Errors
145+
--------------
146+
147+
If you encounter build errors:
148+
149+
* Ensure all dependencies are installed
150+
* Check that the NCS environment is properly sourced
151+
* Verify that you're using the correct board target
152+
* Try building the Zephyr hello world sample to verify your basic build environment:
153+
154+
.. code-block:: console
155+
156+
west build -b nrf54l15dk/nrf54l15/cpuapp zephyr/samples/basic/hello_world
157+
158+
Additional Resources
159+
==================
160+
161+
* :ref:`setting_up_environment`
162+
* :ref:`samples_list`
163+
* :ref:`compatibility_matrix`

‎doc/setting_up_sidewalk_environment/setting_up_sdk.rst‎

Lines changed: 25 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -12,51 +12,55 @@ Once confirmed, follow the `Installing the nRF Connect SDK`_ instructions.
1212

1313
.. _dk_building_sample_app:
1414

15-
Downloading the Sidewalk repository
15+
Setting up the Sidewalk Repository
1616
***********************************
1717

18-
Once you have installed the nRF Connect SDK, download the Sidewalk application:
18+
The Sidewalk repository is now managed through its own west.yml configuration. To set up the Sidewalk development environment:
1919

20-
1. Open a terminal window in the ncs folder.
21-
Your directory structure should look as follows:
20+
1. Clone the Sidewalk repository:
2221

2322
.. code-block:: console
2423
25-
.
26-
|___ .west
27-
|___ bootloader
28-
|___ modules
29-
|___ nrf
30-
|___ nrfxlib
31-
|___ zephyr
32-
|___ ...
24+
git clone https://github.com/nordicsemiconductor/sidewalk.git sidewalk
3325
34-
#. Enable the Sidewalk group filter for west.
26+
2. If you are migrating from an existing NCS setup with Sidewalk, clean the west configuration:
3527

3628
.. code-block:: console
3729
38-
$ west config manifest.group-filter "+sidewalk"
30+
# Remove the .west directory to clean the west configuration
31+
rm -rf .west
32+
# Checkout and pull main branch in Sidewalk repository
33+
cd sidewalk
34+
git checkout main
35+
git pull origin main
36+
cd ..
3937
40-
Check for Sidewalk presence in west:
38+
3. Initialize west with the new manifest:
4139

4240
.. code-block:: console
4341
44-
$ west list sidewalk
45-
sidewalk sidewalk <sidewalk_revision> https://github.com/nrfconnect/sdk-sidewalk
42+
west init -l sidewalk
4643
47-
#. Update all repositories:
44+
4. Update all repositories:
4845

4946
.. code-block:: console
5047
51-
$ west update
48+
west update
5249
5350
Depending on your connection, the update might take some time.
5451

55-
#. Install Python requirements for Sidewalk.
52+
5. Install the toolchain and update Python packages:
5653

5754
.. code-block:: console
5855
59-
$ pip install -r sidewalk/requirements.txt
56+
# Get the toolchain hash and download it
57+
nrf/scripts/toolchain.py
58+
nrfutil toolchain install --ncs-version $(nrf/scripts/toolchain.py --ncs-version)
59+
# Install Python dependencies for nRF and Zephyr
60+
pip install -r nrf/scripts/requirements.txt
61+
pip install -r zephyr/scripts/requirements.txt
62+
# Install Sidewalk Python requirements
63+
pip install -r requirements.txt
6064
6165
Extracting nRF Command Line Tools
6266
*********************************

0 commit comments

Comments
 (0)