This step by step tutorial will show the process to set up a build environment and run the Mender MCU client for Zephyr on the reference board ESP32-S3-DevKitC.
Attention: currently mender-mcu is still in preview mode. Do not expect production quality.
Prerequisites
- computer running Ubuntu 22.04 x86-64 with root (sudo) access
- accessible WiFi with known credentials (PSK): SSID and password
- ESP32-S3-DevKitC including USB cable to connect it to your computer
- organization token of your Hosted Mender account
- the
mender-artifacttool being installed
Concept
Building, running and developing on a Zephyr project such as the Mender MCU client involves three main building blocks to be set up.
- local computer setup. Only required once.
- Zephyr toolchain. Only required once per major/incompatible version.
- actual project. Can be done multiple times side by side.
Setting up the computer
Required software packages
This tutorial describes a user-confined setup of the toolchain, so multiple users on the computer can have non-conflicting setups. For the current version of the Mender MCU client, this is based on the getting started documentation of Zephyr 4.0.
First, install the required packages.
sudo apt install --no-install-recommends git cmake ninja-build gperf \
ccache dfu-util device-tree-compiler wget \
python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \
make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1
Check the versions of the installed main dependencies
cmake --version
python3 --version
dtc --version
which should fulfill or exceed:
| Tool | Min. Version |
|---|---|
| CMake | 3.20.5 |
| Python | 3.10 |
| Devicetree compiler | 1.4.6 |
west and esptool tools
Install the west tool which is used by Zephyr to manage development tasks
pip install west==1.2.0
Install the esptool which is required to wipe the MCUs flash before first setup:
pip install esptool
mender-artifacttool
Download mender-artifact package and install
wget https://downloads.mender.io/repos/debian/pool/main/m/mender-artifact/mender-artifact_4.0.0-1+ubuntu+jammy_amd64.deb -O mender-artifact.deb
sudo dpkg -i mender-artifact.deb
See also Downloads | Mender documentation for other download options.
Environment
Add the following to your shells environment settings, usually ~/.bashrc:
export ZEPHYR_SDK_VERSION="0.17.0"
export CMAKE_PREFIX_PATH="/home/mender/toolchains"
export ZEPHYR_SDK_INSTALL_DIR="/home/mender/toolchains/zephyr-sdk-${ZEPHYR_SDK_VERSION}"
Group permissions
Add your current user to the dialout group:
sudo gpasswd -a ${USER} dialout
Re-login and check
Log out of your session (also close eventually active screen multiplexers such as screen and tmux), and log in again to check that user-wide path modification, group and variables have been applied correctly.
Check the west tool:
west --version
should return West version: v1.2.0
Check the esptool:
esptool.py version
should return output similar to:
esptool.py v4.7.0
4.7.0
Check the group addition:
id | grep dialout
should return a line in which dialout is part of the groups= listing.
Check the variable assigments:
env | grep "ZEPHYR_SDK_VERSION\|ZEPHYR_SDK_INSTALL_DIR\|CMAKE_PREFIX_PATH"
should return the following for your $USER:
ZEPHYR_SDK_VERSION=0.17.0
CMAKE_PREFIX_PATH=/home/$USER/toolchains
ZEPHYR_SDK_INSTALL_DIR=/home/$USER/toolchains/zephyr-sdk-0.17.0
Connecting the ESP-S3-DevKitC
The board has two Micro-USB ports. Make sure to use the one marked as “UART”, otherwise the monitoring tool will not work.
Setting up the toolchain
Download and run the Zephyr toolchain installer. To avoid cluttering and useless downloads, only the specific toolchains relevant for Mender MCU will be installed.
mkdir ~/toolchains
wget -qO- https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZEPHYR_SDK_VERSION}/zephyr-sdk-${ZEPHYR_SDK_VERSION}_linux-x86_64_minimal.tar.xz \
| tar -xJ -C ~/toolchains
~/toolchains/zephyr-sdk-${ZEPHYR_SDK_VERSION}/setup.sh -c \
-t arm-zephyr-eabi \
-t xtensa-espressif_esp32_zephyr-elf \
-t xtensa-espressif_esp32s3_zephyr-elf
Setting up the project
Clone the project and download the subcomponents:
west init workspace --manifest-url https://github.com/mendersoftware/mender-mcu-integration
cd workspace && west update
This will obtain the full project ready for building and running.
After the first project setup by the user, this additional action is needed:
pip install -r zephyr/scripts/requirements.txt
to download all Python dependencies.
Then last, run
west blobs fetch hal_espressif
to download the WiFi firmware blobs for the ESP32.
Configure the project
Adjust the included template overlay-wifi.conf in the mender-mcu-integration directory to hold your local WiFi credentials and Hosted Mender tenant token.
CONFIG_MENDER_APP_WIFI_SSID="demoSSID"
CONFIG_MENDER_APP_WIFI_PSK="demoPASSWORD"
CONFIG_MENDER_SERVER_TENANT_TOKEN="..."
If not using the main US Hosted Mender instance, then you additionally need to set CONFIG_MENDER_SERVER_HOST accordingly.
IMPORTANT: add the following line to the overlay-wifi.conf file, otherwise deployments will fail
CONFIG_MENDER_SCHEDULER_SEPARATE_WORK_QUEUE=n
This is due to the work queue feature still being WIP, and will not be required later.
Build and run - first time
Prepare the device by erasing its flash storage:
python3 -m esptool --chip esp32s3 erase_flash
Finally build, flash and run:
west build --sysbuild -b esp32s3_devkitc/esp32s3/procpu mender-mcu-integration -- -DEXTRA_CONF_FILE=overlay-wifi.conf
west flash && west espressif monitor
This opens a log view, which should output something similar to
Hello World! esp32s3_devkitc/esp32s3/procpu
*** Booting Zephyr OS build v4.0.0 ***
[00:00:00.211,000] <inf> mender_app: Using net interface wifi, index=1
[00:00:00.211,000] <inf> mender_app: Connecting to wireless network NT_PAF...
[00:00:00.245,000] <inf> mender_app: Waiting for network up...
[00:00:07.796,000] <inf> net_dhcpv4: Received: 192.168.89.10
[00:00:07.796,000] <inf> mender_app: Address[1]: 192.168.89.10
[00:00:07.796,000] <inf> mender_app: Subnet[1]: 255.255.255.0
[00:00:07.796,000] <inf> mender_app: Router[1]: 192.168.89.1
[00:00:07.796,000] <inf> mender_app: Lease time[1]: 600 seconds
[00:00:07.796,000] <inf> mender_app: Initializing Mender Client with:
[00:00:07.796,000] <inf> mender_app: Device type: 'esp32s3_devkitc/esp32s3/procpu'
[00:00:07.796,000] <inf> mender_app: Identity: '{"mac": "f4:12:fa:e6:46:c0"}'
[00:00:07.796,000] <inf> mender: Device type: [esp32s3_devkitc/esp32s3/procpu]
[00:00:07.810,000] <inf> fs_nvs: 2 Sectors of 4096 bytes
[00:00:07.810,000] <inf> fs_nvs: alloc wra: 0, fe8
[00:00:07.810,000] <inf> fs_nvs: data wra: 0, 0
[00:00:07.811,000] <inf> mender_app: Mender client initialized
[00:00:07.811,000] <inf> mender_app: Update Module 'zephyr-image' initialized
[00:00:07.811,000] <inf> mender_app: Mender inventory set
[00:00:07.811,000] <inf> mender_app: Mender client activated and running!
[00:00:08.811,000] <inf> mender: Generating authentication keys
[00:00:08.872,000] <inf> mender: Initialization done
[00:00:08.872,000] <dbg> mender_app: network_connect_cb: network_connect_cb
[00:00:08.872,000] <inf> mender: Checking for deployment...
[00:00:08.873,000] <dbg> mender_app: get_identity_cb: get_identity_cb
[00:00:10.983,000] <err> mender: [401] Unauthorized: dev auth: unauthorized
[00:00:10.983,000] <err> mender: Authentication failed
[00:00:10.983,000] <err> mender: Unable to perform HTTP request
[00:00:10.983,000] <err> mender: Unable to check for deployment
[00:00:10.983,000] <err> mender: Work mender_client_main failed
[00:00:10.984,000] <dbg> mender_app: get_identity_cb: get_identity_cb
[00:00:13.030,000] <err> mender: [401] Unauthorized: dev auth: unauthorized
[00:00:13.030,000] <err> mender: Authentication failed
[00:00:13.030,000] <err> mender: Unable to perform HTTP request
[00:00:13.030,000] <err> mender: Unable to publish inventory data
[00:00:13.030,000] <err> mender: Work mender_inventory failed
You can close the monitor log view by pressing Ctrl-C.
The 401 Authentication failed means that the device is not accepted yet, so its time to check your Mender dashboard and accept it there.
Congratulations, you’ve just run the Mender MCU client for the first time!
After accepting the device, the log will cyclically print
[00:00:10.070,000] <inf> mender: Checking for deployment...
[00:00:12.012,000] <inf> mender: No deployment available
which means that checking for updates is now functional.
Prepare for subsequent builds
After the first build, there is no need to build the mcuboot loader anymore, so you change from --sysbuild to a standard build. Hence we re-run with the -p flag (for “pristine”) to adjust the build:
west build -p -b esp32s3_devkitc/esp32s3/procpu mender-mcu-integration -- -DEXTRA_CONF_FILE=overlay-wifi.conf
Build and run - subsequent times
Building
All further builds can be run with
west build -b esp32s3_devkitc/esp32s3/procpu mender-mcu-integration -- -DEXTRA_CONF_FILE=overlay-wifi.conf
Flashing and running
You can flash and inspect with
west flash && west espressif monitor
Generating artifacts
With the board already running the Mender MCU client, you can start deploying new software through Mender. To create a Mender Artifact with the Zephyr built payload run mender-artifact like this:
mender-artifact write module-image \
--type zephyr-image \
--file build/zephyr/zephyr.signed.bin \
--compression none \
--artifact-name myartifact1 \
--device-type esp32s3_devkitc/esp32s3/procpu \
--output-path myartifact1.mender
After this, you can upload the newly created artifact to your Hosted Mender account and deploy as usual!
Next steps
The application source code is located under mender-mcu-integration/src. Check out main.c there and start tinkering. An easy first step would be to modify the inventory. Can you figure it out? 
We would love to get your feedback!