Skip to content

Commit 8f7a3f7

Browse files
asmellbyasmellby
committed
doc: Add introductory information
Add introductory information to the README, and move Linux getting started details to a dedicated document. Signed-off-by: Aksel Skauge Mellbye <[email protected]>
1 parent dda8f9f commit 8f7a3f7

File tree

2 files changed

+202
-118
lines changed

2 files changed

+202
-118
lines changed

‎README.md‎

Lines changed: 92 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -3,121 +3,95 @@
33
[badge]: https://github.com/SiliconLabsSoftware/zephyr-silabs/actions/workflows/upstream-build.yml/badge.svg
44
[recipe]: https://github.com/SiliconLabsSoftware/zephyr-silabs/actions/workflows/upstream-build.yml
55

6-
Silicon Labs Zephyr repository
7-
==============================
8-
9-
This repository includes support for devices and features not yet included in
10-
the Zephyr mainstream for various reasons.
11-
12-
Quick start guide
13-
-----------------
14-
15-
The steps below applies on common Linux hosts. Please refer to the [full
16-
documentation][main-doc] for detailed steps.
17-
18-
First, install packages required for Zephyr development, as described in the
19-
[Zephyr documentation][sysdeps]:
20-
21-
sudo apt install --no-install-recommends git cmake ninja-build gperf \
22-
ccache dfu-util device-tree-compiler wget python3-dev python3-pip \
23-
python3-setuptools python3-tk python3-wheel xz-utils file make gcc \
24-
gcc-multilib g++-multilib libsdl2-dev libmagic1
25-
26-
Also [install `west` command][west]. Since no package is provided for `west`, it
27-
can be done through `pip`:
28-
29-
pip install west
30-
31-
Retrieve this repository using `west init`:
32-
33-
mkdir workspace
34-
cd workspace
35-
west init -m [email protected]:siliconlabssoftware/zephyr-silabs
36-
37-
Retrieve modules:
38-
39-
west update
40-
41-
You can now [install extra Python packages][pydeps] required by Zephyr:
42-
43-
pip install -r zephyr/scripts/requirements.txt
44-
45-
Retrieve the blobs:
46-
47-
west blobs fetch
48-
49-
Install [a toolchain][toolchain]. [Zephyr SDK][sdk] is recommended:
50-
51-
west sdk install
52-
53-
Then, [Simplicity Commander][commander] is required to flash some targets (eg.
54-
SiWG917 can only be flashed using Simplicity Commander):
55-
56-
ARCH=x86_64 # Also consider "aarch32" or "aarch64"
57-
wget https://www.silabs.com/documents/login/software/SimplicityCommander-Linux.zip
58-
unzip SimplicityCommander-Linux.zip
59-
sudo mkdir -p /opt/commander
60-
sudo chown $(id -un):$(id -gn) /opt/commander
61-
tar -C /opt -xvf SimplicityCommander-Linux/Commander_linux_${ARCH}_*.tar.bz
62-
sudo ln -sfn /opt/commander/commander /usr/local/bin/
63-
64-
In order to debug the target, you will need [J-Link software pack][jlink]:
65-
66-
ARCH=x86_64 # Also consider "arm" or "arm64"
67-
wget --post-data accept_license_agreement=accepted https://www.segger.com/downloads/jlink/JLink_Linux_$ARCH.deb
68-
sudo dpkg -i JLink_Linux_$ARCH.deb
69-
70-
Your environment is now installed. You can run all the Zephyr commands, ie.
71-
build an application:
72-
73-
west build -b siwx917_rb4338a zephyr/samples/hello_world
74-
75-
... then flash it:
76-
77-
west flash
78-
79-
... and debug it:
80-
81-
west attach
82-
83-
[main-doc]: https://docs.zephyrproject.org/latest/develop/getting_started/index.html
84-
[sysdeps]: https://docs.zephyrproject.org/latest/develop/getting_started/index.html#install-dependencies
85-
[west]: https://docs.zephyrproject.org/latest/develop/west/install.html
86-
[pydeps]: https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies
87-
[toolchain]: https://docs.zephyrproject.org/latest/develop/toolchains/index.html
88-
[sdk]: https://docs.zephyrproject.org/latest/develop/toolchains/zephyr_sdk.html
89-
[commander]: https://www.silabs.com/developers/simplicity-studio/simplicity-commander?tab=downloads
90-
[jlink]: https://www.segger.com/jlink-software.html
91-
92-
Troubleshooting
93-
---------------
94-
95-
### `pip` says "This environment is externally managed".
96-
97-
On recent version of Debian (>= bookworm) and derivative, you need to use `pipx`
98-
(or use Python venv) instead of `pip`:
99-
100-
pipx install west
101-
pipx runpip west install crc
102-
pipx runpip west install -r zephyr/scripts/requirements.txt
103-
104-
105-
### I am not able to install JLink and Simplicity Commander on Raspberry Pi
106-
107-
You probably need to retrieve the binary that match with your architecture. Here
108-
is a table to identify your system:
109-
110-
| `uname -m` | `dpkg --print-architecture` | JLink | Commander |
111-
|------------|-----------------------------|----------|-----------|
112-
| `x86_64` | `amd64` | `x86_64` | `x86_64` |
113-
| `aarch64` | `arm64` | `arm64` | `aarch64` |
114-
| `arm` | `armhf` | `arm` | `aarch32` |
115-
116-
117-
### I am not able to debug my target
118-
119-
J-Link software package may not support the Silicon Labs parts. Commander is
120-
generally up to date. You can try to copy Commander J-Link customisation files
121-
to J-Link software pack:
122-
123-
sudo cp -fr /opt/commander/resources/jlink/* /opt/SEGGER/JLink_V*/
6+
# Silicon Labs SDK for Zephyr
7+
8+
This repository contains the Silicon Labs SDK for Zephyr, which is Silicon Labs'
9+
primary downstream enablement for Zephyr.
10+
11+
Silicon Labs is a [Platinum Member][project-members] of the Zephyr Project, and
12+
is committed to providing upstream support for [Silicon Labs hardware][boards].
13+
In addition to upstream support, Silicon Labs provides this downstream
14+
[manifest repository][west-manifest] to provide access to features that are not
15+
yet available upstream, such as new hardware support, as well as features that
16+
cannot be upstreamed, such as content that does not have an open source license
17+
compatible with the upstream. The downstream repository also enables additional
18+
quality assurance of releases for Silicon Labs platforms.
19+
20+
Silicon Labs is committed to an upstream-first development methodology. We
21+
strive to keep the number of patches applied in Silicon Labs SDK for Zephyr
22+
down by basing the downstream release on upstream stable releases.
23+
24+
[project-members]: https://zephyrproject.org/project-members/
25+
[boards]: https://docs.zephyrproject.org/latest/boards/silabs/index.html
26+
[west]: https://docs.zephyrproject.org/latest/develop/west/index.html
27+
[west-manifest]: https://docs.zephyrproject.org/latest/develop/west/manifest.html
28+
29+
## Structure
30+
31+
This repository is the top-level [manifest repository][west-manifest] for the
32+
Silicon Labs SDK for Zephyr. The SDK uses the [West][west] tool to check out
33+
and organize the different repositories that are part of it. The
34+
[manifest file](./west.yml) tells West which repositories to check out at
35+
which revision. Important repos include:
36+
37+
* [zephyr-silabs][repo-zephyr-silabs] - The manifest repository for Silicon
38+
Labs SDK for Zephyr. Functions as the entry point for the SDK, and points to
39+
a mix of upstream repositories, downstream forks and additional downstream
40+
repositories. Filters out HAL repositories not related to Silicon Labs targets
41+
to optimize the download size and disk usage of the SDK.
42+
* [zephyr][repo-zephyr] - Silicon Labs fork of the Zephyr repository. Kept in
43+
sync with the upstream for every release. May add additional patches that are
44+
not yet available upstream.
45+
* [hal_silabs][repo-hal-silabs] - Silicon Labs fork of the Silicon Labs HAL for
46+
Zephyr. Includes the parts of Simplicity SDK and WiSeConnect used by Zephyr.
47+
48+
[repo-zephyr-silabs]: https://github.com/SiliconLabsSoftware/zephyr-silabs
49+
[repo-zephyr]: https://github.com/SiliconLabsSoftware/zephyr
50+
[repo-hal-silabs]: https://github.com/SiliconLabsSoftware/hal_silabs
51+
52+
The workspace directory structure looks like this, with additional modules
53+
as specified by the manifest:
54+
55+
```
56+
workspace/
57+
├── modules/
58+
│ ├── crypto/
59+
│ │ └── mbedtls/ # Silicon Labs fork with hardware acceleration
60+
│ └── hal/
61+
│ ├── cmsis_6/ # Upstream CMSIS 6 repository
62+
│ └── silabs/ # Silicon Labs HAL
63+
├── zephyr/ # Silicon Labs downstream fork of Zephyr
64+
└── zephyr-silabs/ # Silicon Labs SDK for Zephyr manifest repository
65+
```
66+
67+
## Getting Started
68+
69+
To get started with Silicon Labs SDK for Zephyr, follow the
70+
[Getting Started Guide from the Zephyr Project][zephyr-getting-started].
71+
Instead of doing `west init` to initialize a workspace based on the upstream
72+
manifest, use the following commands, where `silabs_zephyr` is an example name
73+
for your workspace directory:
74+
75+
```
76+
west init -m https://github.com/SiliconLabsSoftware/zephyr-silabs silabs_zephyr
77+
cd silabs_zephyr
78+
west update
79+
west blobs fetch
80+
```
81+
82+
It is also possible to clone the repository manually, and use `west init -l` to
83+
perform initialization from local sources.
84+
85+
The Getting Started Guide covers setting up the build environment, as well as
86+
building and flashing an example.
87+
88+
To use Zephyr with Silicon Labs devices, certain pre-built libraries are
89+
required for the radio. The `west blobs fetch` command downloads these
90+
libraries.
91+
92+
[zephyr-getting-started]: https://docs.zephyrproject.org/latest/develop/getting_started/index.html
93+
94+
### Linux
95+
96+
For Linux users, see also the more detailed
97+
[Getting Started on Linux](./doc/getting-started-linux.md) guide.

‎doc/getting-started-linux.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Getting Started with Silicon Labs SDK for Zephyr on Linux
2+
3+
The steps below applies on common Linux hosts. Please refer to the [full
4+
documentation][main-doc] for detailed steps.
5+
6+
First, install packages required for Zephyr development, as described in the
7+
[Zephyr documentation][sysdeps]:
8+
9+
sudo apt install --no-install-recommends git cmake ninja-build gperf \
10+
ccache dfu-util device-tree-compiler wget python3-dev python3-pip \
11+
python3-setuptools python3-tk python3-wheel xz-utils file make gcc \
12+
gcc-multilib g++-multilib libsdl2-dev libmagic1
13+
14+
Also [install `west` command][west]. Since no package is provided for `west`, it
15+
can be done through `pip`:
16+
17+
pip install west
18+
19+
Retrieve this repository using `west init`:
20+
21+
mkdir workspace
22+
cd workspace
23+
west init -m [email protected]:siliconlabssoftware/zephyr-silabs
24+
25+
Retrieve modules:
26+
27+
west update
28+
29+
You can now [install extra Python packages][pydeps] required by Zephyr:
30+
31+
pip install -r zephyr/scripts/requirements.txt
32+
33+
Retrieve the blobs:
34+
35+
west blobs fetch
36+
37+
Install [a toolchain][toolchain]. [Zephyr SDK][sdk] is recommended:
38+
39+
west sdk install
40+
41+
Then, [Simplicity Commander][commander] is required to flash some targets (eg.
42+
SiWG917 can only be flashed using Simplicity Commander):
43+
44+
ARCH=x86_64 # Also consider "aarch32" or "aarch64"
45+
wget https://www.silabs.com/documents/login/software/SimplicityCommander-Linux.zip
46+
unzip SimplicityCommander-Linux.zip
47+
sudo mkdir -p /opt/commander
48+
sudo chown $(id -un):$(id -gn) /opt/commander
49+
tar -C /opt -xvf SimplicityCommander-Linux/Commander_linux_${ARCH}_*.tar.bz
50+
sudo ln -sfn /opt/commander/commander /usr/local/bin/
51+
52+
In order to debug the target, you will need [J-Link software pack][jlink]:
53+
54+
ARCH=x86_64 # Also consider "arm" or "arm64"
55+
wget --post-data accept_license_agreement=accepted https://www.segger.com/downloads/jlink/JLink_Linux_$ARCH.deb
56+
sudo dpkg -i JLink_Linux_$ARCH.deb
57+
58+
Your environment is now installed. You can run all the Zephyr commands, ie.
59+
build an application:
60+
61+
west build -b siwx917_rb4338a zephyr/samples/hello_world
62+
63+
... then flash it:
64+
65+
west flash
66+
67+
... and debug it:
68+
69+
west attach
70+
71+
[main-doc]: https://docs.zephyrproject.org/latest/develop/getting_started/index.html
72+
[sysdeps]: https://docs.zephyrproject.org/latest/develop/getting_started/index.html#install-dependencies
73+
[west]: https://docs.zephyrproject.org/latest/develop/west/install.html
74+
[pydeps]: https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies
75+
[toolchain]: https://docs.zephyrproject.org/latest/develop/toolchains/index.html
76+
[sdk]: https://docs.zephyrproject.org/latest/develop/toolchains/zephyr_sdk.html
77+
[commander]: https://www.silabs.com/developers/simplicity-studio/simplicity-commander?tab=downloads
78+
[jlink]: https://www.segger.com/jlink-software.html
79+
80+
## Troubleshooting
81+
82+
### `pip` says "This environment is externally managed".
83+
84+
On recent version of Debian (>= bookworm) and derivative, you need to use `pipx`
85+
(or use Python venv) instead of `pip`:
86+
87+
pipx install west
88+
pipx runpip west install crc
89+
pipx runpip west install -r zephyr/scripts/requirements.txt
90+
91+
92+
### I am not able to install JLink and Simplicity Commander on Raspberry Pi
93+
94+
You probably need to retrieve the binary that match with your architecture. Here
95+
is a table to identify your system:
96+
97+
| `uname -m` | `dpkg --print-architecture` | JLink | Commander |
98+
|------------|-----------------------------|----------|-----------|
99+
| `x86_64` | `amd64` | `x86_64` | `x86_64` |
100+
| `aarch64` | `arm64` | `arm64` | `aarch64` |
101+
| `arm` | `armhf` | `arm` | `aarch32` |
102+
103+
104+
### I am not able to debug my target
105+
106+
J-Link software package may not support the Silicon Labs parts. Commander is
107+
generally up to date. You can try to copy Commander J-Link customisation files
108+
to J-Link software pack:
109+
110+
sudo cp -fr /opt/commander/resources/jlink/* /opt/SEGGER/JLink_V*/

0 commit comments

Comments
 (0)