# Getting started with the Mender-MCU client - ESP32-S3-DevKitC **URL:** \ **Category:** Zephyr\ **Tags:** esp32, zephyr\ **Created:** [January 23, 2025, 1:43pm UTC](https://hub.mender.io/t/getting-started-with-the-mender-mcu-client-esp32-s3-devkitc/7480 "2025-01-23T13:43:55Z")\ **Posts on this page:** 1\ **Page:** 1
**Author:** ![TheYoctoJester](https://yyz2.discourse-cdn.com/flex036/user_avatar/hub.mender.io/theyoctojester/32/1444_2.png) [@TheYoctoJester](https://hub.mender.io/u/TheYoctoJester)\ **Post date:** [January 23, 2025, 1:43pm UTC](https://hub.mender.io/t/getting-started-with-the-mender-mcu-client-esp32-s3-devkitc/7480/1 "2025-01-23T13:43:55Z")
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. ![ESP32-S3-DevKitC-1_v2-annotated-photo](https://canada1.discourse-cdn.com/flex036/uploads/mender/original/2X/8/825d3c33f65d69e36487a2db1fb7cccc33f3f4d9.png) **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](https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s3/esp32-s3-devkitc-1/index.html) including USB cable to connect it to your computer - organization token of your [Hosted Mender](https://hosted.mender.io) account - the `mender-artifact` tool 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. 1. local computer setup. Only required once. 2. Zephyr toolchain. Only required once per major/incompatible version. 3. 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](https://docs.zephyrproject.org/4.0.0/develop/getting_started/index.html) of Zephyr 4.0. First, install the required packages. ```auto 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 ```auto cmake --version python3 --version dtc --version ``` which should fulfill or exceed: | Tool | Min. Version | | --- | --- | | [CMake](https://cmake.org/) | 3.20.5 | | [Python](https://www.python.org/) | 3.10 | | [Devicetree compiler](https://www.devicetree.org/) | 1.4.6 | ### `west` and `esptool` tools Install the `west` tool which is used by Zephyr to manage development tasks ```auto pip install west==1.2.0 ``` Install the `esptool` which is required to wipe the MCUs flash before first setup: ```auto pip install esptool ``` ### `mender-artifact`tool Download `mender-artifact` package and install ```auto 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 [Download | Mender documentation](https://docs.mender.io/downloads#mender-artifact) for other download options. ### Environment Add the following to your shells environment settings, usually `~/.bashrc`: ```auto 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: ```auto 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: ```auto west --version ``` should return `West version: v1.2.0` Check the `esptool`: ```auto esptool.py version ``` should return output similar to: ```auto esptool.py v4.7.0 4.7.0 ``` Check the group addition: ```auto id | grep dialout ``` should return a line in which `dialout` is part of the `groups=` listing. Check the variable assigments: ```auto env | grep "ZEPHYR_SDK_VERSION\|ZEPHYR_SDK_INSTALL_DIR\|CMAKE_PREFIX_PATH" ``` should return the following for your `$USER`: ```auto 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. ```auto 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: ```auto 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:** _ ```auto pip install -r zephyr/scripts/requirements.txt ``` to download all Python dependencies. Then last, run ```auto west blobs fetch hal_espressif ``` to download the WiFi firmware blobs for the ESP32. ## Configure the project Create the file `mender.conf` in the `mender-mcu-integration` directory to hold your local WiFi credentials and Hosted Mender tenant token. ```auto 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. ## Build and run - first time Prepare the device by erasing its flash storage: ```auto python3 -m esptool --chip esp32s3 erase_flash ``` Finally build, flash and run: ```auto west build --sysbuild --board esp32s3_devkitc/esp32s3/procpu mender-mcu-integration -- \ -DEXTRA_CONF_FILE=mender.conf \ -DCONFIG_MENDER_ARTIFACT_NAME=\"release-1\" west flash && west espressif monitor ``` **Note that the artifact name is passed here!** This serves two purposes: - it enables the device to report a software version right after flashing - a Mender Artifact is created along each build, so you can immediately upload and deploy later. This opens a log view, which should output something similar to ```auto Hello World! esp32s3_devkitc/esp32s3/procpu ***Booting Zephyr OS build v4.0.0*** [00:00:00.211,000] mender_app: Using net interface wifi, index=1 [00:00:00.211,000] mender_app: Connecting to wireless network NT_PAF... [00:00:00.245,000] mender_app: Waiting for network up... [00:00:07.796,000] net_dhcpv4: Received: 192.168.89.10 [00:00:07.796,000] mender_app: Address[1]: 192.168.89.10 [00:00:07.796,000] mender_app: Subnet[1]: 255.255.255.0 [00:00:07.796,000] mender_app: Router[1]: 192.168.89.1 [00:00:07.796,000] mender_app: Lease time[1]: 600 seconds [00:00:07.796,000] mender_app: Initializing Mender Client with: [00:00:07.796,000] mender_app: Device type: 'esp32s3_devkitc/esp32s3/procpu' [00:00:07.796,000] mender_app: Identity: '{"mac": "f4:12:fa:e6:46:c0"}' [00:00:07.796,000] mender: Device type: [esp32s3_devkitc/esp32s3/procpu] [00:00:07.810,000] fs_nvs: 2 Sectors of 4096 bytes [00:00:07.810,000] fs_nvs: alloc wra: 0, fe8 [00:00:07.810,000] fs_nvs: data wra: 0, 0 [00:00:07.811,000] mender_app: Mender client initialized [00:00:07.811,000] mender_app: Update Module 'zephyr-image' initialized [00:00:07.811,000] mender_app: Mender inventory set [00:00:07.811,000] mender_app: Mender client activated and running! [00:00:08.811,000] mender: Generating authentication keys [00:00:08.872,000] mender: Initialization done [00:00:08.872,000] mender_app: network_connect_cb: network_connect_cb [00:00:08.872,000] mender: Checking for deployment... [00:00:08.873,000] mender_app: get_identity_cb: get_identity_cb [00:00:10.983,000] mender: [401] Unauthorized: dev auth: unauthorized [00:00:10.983,000] mender: Authentication failed [00:00:10.983,000] mender: Unable to perform HTTP request [00:00:10.983,000] mender: Unable to check for deployment [00:00:10.983,000] mender: Work mender_client_main failed [00:00:10.984,000] mender_app: get_identity_cb: get_identity_cb [00:00:13.030,000] mender: [401] Unauthorized: dev auth: unauthorized [00:00:13.030,000] mender: Authentication failed [00:00:13.030,000] mender: Unable to perform HTTP request [00:00:13.030,000] mender: Unable to publish inventory data [00:00:13.030,000] 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 it’s time to check your Mender dashboard and accept it there. Then open the inventory tab of the device to inspect the default information provided about it: ![Screenshot 2025-04-04 at 09.42.44](https://canada1.discourse-cdn.com/flex036/uploads/mender/original/2X/a/a4b27b0547228653925fdbbd44d4cdb5cd4874af.png) **Congratulations, you’ve just run the Mender MCU client for the first time!** After accepting the device, the log will cyclically print ```auto [00:00:10.070,000] mender: Checking for deployment... [00:00:12.012,000] 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: ```auto west build --pristine --board esp32s3_devkitc/esp32s3/procpu mender-mcu-integration -- \ -DEXTRA_CONF_FILE=mender.conf \ -DCONFIG_MENDER_ARTIFACT_NAME=\"release-x\" ``` ## Build and run - subsequent times ### Building All further builds for a can be run with the same invocation as the preparation one. ```auto west build --board esp32s3_devkitc/esp32s3/procpu mender-mcu-integration -- \ -DEXTRA_CONF_FILE=mender.conf \ -DCONFIG_MENDER_ARTIFACT_NAME=\"my-release\" ``` where you adjust the `\"my-release\"` for your desired software identifier. Please note the escaped quotation marks which are required for correct string handling. Running the new version can now be done in two ways: #### Option 1: Flashing You can flash and inspect with ```auto west flash && west espressif monitor ``` #### Option 2: Deploying through Mender The created artifact is located at `build/zephyr/zephyr.mender`. Upload it to your Hosted Mender account and update your device over the air. You can watch the process by keeping the console monitor open: ```auto west espressif monitor ``` Remember to adjust ## 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? 🙂 Other ideas to try are in our tutorials: > [@Adding a W5500 ethernet adapter to Zephyr (ESP32)](https://hub.mender.io/t/adding-a-w5500-ethernet-adapter-to-zephyr-esp32/7692): > > Introduction The ESP32 family is a very popular platform for getting started with Zephyr. It is cheap, easy to obtain and offers integrated WiFi connectivity. It’s also the reference board for the Mender MCU client. But there are times when WiFi doesn’t cut it, right? Sometimes you just want a plain old wired connection. Good news is that Zephyr offers a rich variety of drivers for hardware support. Amongst these is the [W5500](https://wiznet.io/products/iethernet-chips/w5500), specifically as a shield such as [ARCELI W5500 ETH — Zephyr Project …](https://docs.zephyrproject.org/latest/boards/shields/arceli_eth_w5500/doc/index.html) We would love to get your feedback!