Skip to content

Commit

Permalink
Merge pull request #175 from erlingrj/zephyr-update
Browse files Browse the repository at this point in the history 
More Zephyr doc updates
  • Loading branch information
@erlingrj
erlingrj authored Oct 27, 2023
2 parents cd79825 + 48221f4 commit c7525e3
Showing 1 changed file with 79 additions and 70 deletions.
149 changes: 79 additions & 70 deletions packages/documentation/copy/en/embedded/Zephyr.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,100 +11,97 @@ programming [hundreds](https://docs.zephyrproject.org/latest/boards/index.html)
of resource-constrained microcontrollers. In this guide we will see how LF
programs can be built, programmed and debugged both in emulation and on real
hardware. When developing LF programs for Zephyr we use a `west`-centric
approach. Using `west`, which is the preferred build tool for Zephyr projects,
requires structuring the code base and development flow as expected by `west`. To interact
with the Lingua Franca Compiler we provide custom `west`-extensions which invoke
`lfc` before building the Zephyr application. This in contrast to our
Arduino-support, which is `lfc`-centric.
approach. Using `west`, which is the preferred build tool for Zephyr projects,
requires structuring the code base and development flow as expected by `west`.
We use a [T3 Forest
Topology](https://docs.zephyrproject.org/latest/develop/west/workspaces.html#west-t3).
for our workspace. This means that we create a workspace where multiple
different LF Zephyr projects can be hosted together with a single copy of the
Zephyr RTOS sources.

## Prerequisites
- Linux or macOS development system
- Linux or macOS development system. (The guide is written for Linux)
- nrf52 Development Kit (optional)

# Getting started
The first step is to set up a proper Zephyr development environment. This includes:
1. Installing dependencies
2. Installing Zephyr SDK

This section consists in part of borrowed sections from the [Zephyr Getting
Started
Follow the relevant parts of the official [Zephyr Getting Started
Guide](https://docs.zephyrproject.org/latest/develop/getting_started/index.html).
Please refer to the official Zephyr documentation for more background and
specifics regarding the use of `west`.
**It is not necessary to perform the steps under "Get Zephyr and install Python
dependencies"**. These steps will be performed inside the LF Zephyr workspace we
are going to create next.

## Pull the lf-west-template
## Setting up the LF Zephyr workspace

1. Clone the template repository
```
git clone https://github.com/lf-lang/lf-west-template lf-west && cd lf-west
git clone https://github.com/lf-lang/lf-west-template lf-zephyr-workspace && cd lf-west
```

## Install `west`

1. Setup and activate a virtual environment
2. Setup and activate a virtual environment
```
python3 -m venv .venv
source .venv/bin/activate
```

2. Install `west`
3. Install `west`
```
pip3 install west
```

Now `west` is installed within a virtual environment. **This environment has to
be activated every time you want to use west with LF**

## Installing Zephyr SDK
1. Download and install Zephyr SDK to `/opt`
4. Get the Zephyr source code
```
cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.1/zephyr-sdk-0.16.1_linux-x86_64.tar.xz
wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.1/sha256.sum | shasum --check --ignore-missing
tar xvf zephyr-sdk-0.16.1_linux-x86_64.tar.xz --directory /opt/
cd /opt/zephyr-sdk-0.16.1
./setup.sh
west update
```

2. Install udev rules for flashing and debugging boards
5. Export CMake packages for Zephyr
```
sudo cp /opt/zephyr-sdk-0.16.1/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
sudo udevadm control --reload
west zephyr-export
```

## Download the Zephyr RTOS
1. Remove old Zephyr installations from your system.
6. Install Python dependencies
```
echo $ZEPHYR_BASE
pip install -r deps/zephyr/scripts/requirements.txt
```
should be empty.

```
ls ~/.cmake/packages
```
should not contain `Zephyr` or `ZephyrUnittest`. If they do, delete them. They will be replaced later when we do `west zephyr-export`.
## Workspace organization
Now you should have the following installed:
-`west`; Verify with `west boards`
- Zephyr SDK located at `/opt/zephyr-sdk-VERSION`
- Zephyr RTOS pulled down to `deps/zephyr`
- A few example applications under `apps/`

2. Download the Zephyr RTOS to the template repository. This step will take some time
This workspace is meant to house all of your different LF Zephyr apps, as long
as they are using the same version of Zephyr. Each app has to contain the
following:
```
west update
<app>
├── app.overlay
├── prj.conf
├── Kconfig
└── src
└── MyApplication.lf
```

3. Export CMake packages for Zephyr
```
west zephyr-export
```
Our custom west-extension will invoke `lfc` and create a `src-gen` directory
structured as a [Zephyr
application](https://docs.zephyrproject.org/latest/develop/application/index.html).
Wish can then be built, emulated or flashed by `west`.

4. Install Python dependencies
```
pip install -r deps/zephyr/scripts/requirements.txt
```

# Hello World!
Now you should have the following installed:
1. `west`; Verify with `west boards`
2. Zephyr SDK located at `/opt/zephyr-sdk-0.16.1`
3. Zephyr RTOS pulled down to `/deps/zephyr`

You should now be able to build and emulate a simple Hello World! LF program:
## Hello World!

You should now be able to build and emulate a simple "Hello World" LF program:

```
cd application
cd apps/HelloWorld
lfc src/HelloWorld.lf -n
west build src-gen/HelloWorld -t run
```
Expand All @@ -121,38 +118,51 @@ west lfc src/HelloWorld.lf --build "-t run"

The string within the quotation marks after `--build` is passed on to `west build`.

# Nrf52 blinky
## Nrf52 blinky
In this example we will program a simple Blinky program onto an nrf52dk. This
requires an actual nrf52 board and also the `nrfjprog` utility is installed. See
the following installation guide
[here](https://www.nordicsemi.com/Products/Development-tools/nrf-command-line-tools/download).

```
cd application
cd apps/NrfBliny
west lfc src/NrfBlinky.lf --build "-p always -b nrf52dk_nrf52832"
west flash
```
In this example we use the `-p always` to tell west to do a clean build and `-b nrf52dk_nrf52832` to target the nrf52dk. These parameters are west-specific so
refer to west documentation for more info. `west flash` is used to interact with
`nrfjprog` and flash the application into the dev-board.

## Bare-bones Zephyr app
We also have a simple example of a bare-bones Zephyr app. This requires a
physical board.

```
cd apps/HelloZephyr
west build -b nrf52dk_nrf52832 -p always
west flash
```


# Zephyr configuration options
The Lingua Franca Zephyr platform depends on some specific [Zephyr Kernel configurations](https://docs.zephyrproject.org/latest/build/kconfig/index.html#).
The Lingua Franca Zephyr platform depends on some specific [Zephyr Kernel
configurations](https://docs.zephyrproject.org/latest/build/kconfig/index.html#).
For instance, the Counter drivers must be linked with the application to provide
hi-resolution timing. These required configurations are stored in a file called
`prj_lf.conf` which is copied to the generated `src-gen` folder by `lfc`. You
can also supply your own configuration options in a file called `prj.conf` which
has to be located in the same folder as `west lfc` is invoked from.
There is such a file located in `~/application` in the template. There is also
a `Kconfig` file. Both are copied into the `src-gen` folder when invoking
`west lfc`.
`prj_lf.conf` which `lfc` generates into the `src-gen` folder. You can provide
your own configurations through the following three files that `west lfc`
expects to find at the root of each app:
1. `prj.conf`, see [Seeting symbols in configuration files](https://docs.zephyrproject.org/latest/build/kconfig/setting.html#setting-symbols-in-configuration-files)
2. `Kconfig`, see [Configuration system (Kconfig)](https://docs.zephyrproject.org/latest/build/kconfig/index.html)
3. `app.overlay`, see [Devicetree](https://docs.zephyrproject.org/latest/build/dts/index.html#devicetree)


# The `west lfc` command
The custom `lfc` west command has already been used in previous sections.
It can be inspected in `scripts/lf_build.py`.
It invokes `lfc` on the provided LF source file. It also copies `prj.conf` and `Kconfig`
into the src-gen directory before it, optionally, calls `west build` on the
resulting project.
The custom `lfc` west command has already been used in previous sections. It can
be inspected in `scripts/lf_build.py`. It invokes `lfc` on the provided LF
source file. It also copies `app.overlay`,`prj.conf` and `Kconfig` into the
src-gen directory before it, optionally, calls `west build` on the resulting
project.

Please see `west lfc --help` for more information and the `scripts/lf_build.py`.

Expand All @@ -161,7 +171,7 @@ In this section we will see how a LF program can be debugged while running in QE

1. Compile `HelloWorld.lf` for `qemu_cortex_m3`
```
cd application
cd apps/HelloWorld
west lfc src/HelloWorld.lf --build "-b qemu_cortex_m3 -p always"
```
Note that we here, unlike the very first example, explicitly tell `lfc` that we are targeting a `qemu_cortex_m3` platform. This is the default platform which is used unless another is specified. It is added here for clarity.
Expand All @@ -173,8 +183,7 @@ ninja -C build debugserver

3. In another terminal start `gdb` and connect to the qemu server. Load the application image and run until main.
```
$ZEPHYR_SDK/arm-zephyr-eabi/bin/arm-zephyr-eabi-gdb
(gdb) arm-zephyr-eabi/bin/arm-zephyr-eabi-gdb
/ZEPHYR_SDK_INSTALL_DIR/arm-zephyr-eabi/bin/arm-zephyr-eabi-gdb
(gdb) target remote localhost:1234
(gdb) file build/zephyr/zephyr.elf
(gdb) b main
Expand Down

0 comments on commit c7525e3

Please sign in to comment.