--- title: "Install and run TrustEdge with Zephyr RTOS" source_url: https://dev.digicert.com/trustedge/install-and-configure/install-and-run-trustedge-with-zephyr-rtos.html --- You can install and run TrustEdge with [Zephyr RTOS](https://www.zephyrproject.org/wp-content/uploads/2025/01/Zephyr-Overview-20250113.pdf) using either the native simulator ([native_sim 64-bit board](https://docs.zephyrproject.org/latest/boards/native/native_sim/doc/index.html)) or the *STM32H745 Discovery Kit*. ## Before you begin Ensure you have the following: **System requirements**: - Ubuntu 64-bit (the minimum version we have tested is on 22.04). - A minimum of 40 GB of disk space (for all the tools and resources). **Environment variable**: The ${MOCN_MSS} should point to the root of your TrustCore package. **Zephyr base path**: Set the environment variable **ZEPHYR_BASE** to the Zephyr root folder on your machine: ``` export ZEPHYR_BASE=~/zephyrproject/zephyr ``` **TrustEdge Zephyr patch**: Keep the **trustedge.zephyr.patch** ready. To get this patch file, contact your DigiCert account representative. ## Install Zephyr This script installs Zephyr OS, all required dependencies, and the Zephyr SDK. It also sets the necessary environment variables in `.bashrc` for TrustEdge development and builds. > **Info** > > This script is tested on **Ubuntu 64-bit** (the minimum version we have tested is on 22.04). This script automates all the steps mentioned in: > > - [Getting Started Guide](https://docs.zephyrproject.org/latest/develop/getting_started/index.html) > - [Beyond the Getting Started Guide](https://docs.zephyrproject.org/latest/develop/beyond-GSG.html) Run the following command: ``` cd ${MOCN_MSS} ./scripts/ci/trustedge/ci_trustedge_build_zephyr.sh --zephyr-install ``` ## Build TrustEdge on native sim (64-bit) Perform the following steps: 1. Download the `trustedge.zephyr.patch` and copy it to your host machine. > **Info** > > You can get this patch from DigiCert Support. 2. Run the following command to apply the patch: ``` cd ${ZEPHYR_BASE} git apply /trustedge_zephyr.patch cd ${MOCN_MSS} ./scripts/ci/trustedge/ci_trustedge_build_zephyr.sh --board native_sim ``` This command builds TrustEdge with Zephyr runtime and places the binary in `./bin/trustedge`. It also builds *device_provision*, a tool used to prepare the flash file system. 3. Add a host entry to /etc/hosts for provisioning: ``` 127.0.0.1 provision.digicert.com ``` 4. Run the following command to prepare the **flash.bin**: ``` cd ${MOCN_MSS} ./src/examples/zephyr_examples/device_provision/provision_flash.sh --bootstrap ``` If flash provisioning is skipped, use the following Python script for TrustEdge binary to get the bootstrap file onto the system: ``` cd ${MOCN_MSS} cd ./src/examples/zephyr_examples/trustedge_sample/helper python tcp_server.py --bootstrap --filesys ``` 5. Run the following command to execute TrustEdge in another terminal: ``` cd ${MOCN_MSS} ./bin/trustedge ``` The above command runs the TrustEdge agent flow. You can now test device provisioning and certificate policy handling scenarios. ### TrustEdge examples TrustEdge includes a built-in REST API over HTTPS. You can use `curl` to test functions like: - Key generation - EST enrolment 1. Run the following command to install the required tools: ``` sudo apt install zip unzip ``` 2. Run the following command to load certificates into flash: ``` ./scripts/ci/trustedge/ci_trustedge_build_zephyr.sh --board native_sim ./src/examples/zephyr_examples/device_provision/provision_flash.sh --load-certs --bootstrap ./bin/trustedge ``` The above command loads both the Root CA certificate and the server’s private key and certificate into the device’s flash storage. The Root CA certificate is necessary for the EST protocol when connecting to the DigiCert® Device Trust Manager, while the server key and certificate pair are needed to authenticate and secure the TLS communications with the TrustEdge REST API server. 3. Run the following command to build and run TrustEdge: ``` ./scripts/ci/trustedge/ci_trustedge_build_zephyr.sh --board native_sim ./src/examples/zephyr_examples/device_provision/provision_flash.sh --load-certs --bootstrap ./bin/trustedge ``` 4. Run a `curl` request to verify the TrustEdge build: ``` curl --cacert ${MOCN_MSS}/pki_certs/rootCA.pem https://localhost:8443/v1/key/asymmetric -H 'Content-Type: application/json' -d '{ "keyCertAttributes": { "outputMode": "buffered", "algorithm": "rsa+2048", "keySource": "SW" } }' ``` 5. Run the `curl` request once again to trigger an enrollment flow: ``` curl --cacert ${MOCN_MSS/co}/pki_certs/rootCA.pem https://localhost:8443/v1/certificate/enroll -H 'Content-Type: application/json' -d@${MOCN_MSS}/src/trustedge/test/data/est_request.json ``` 6. Inspect Flash (LittleFS) on host machine using a provisioning tool called **FUSE**: ``` $ ./src/examples/zephyr_examples/device_provision/build/zephyr/zephyr.exe Mounting flash at flash/ uart connected to pseudotty: /dev/pts/2 [00:00:00.000,000] littlefs: littlefs partition at /lfs1 *** Booting Zephyr OS build v4.0.0-3113-g5aeda6fe7dfa *** [00:00:00.000,000] littlefs: LittleFS version 2.9, disk version 2.1 [00:00:00.000,000] littlefs: FS at flash-controller@0:0x100000 is 768 0x1000-byte blocks with 512 cycle [00:00:00.000,000] littlefs: partition sizes: rd 16 ; pr 16 ; ca 64 ; la 32 [00:00:00.000,000] app: Total partition size: 12288 bytes [00:00:00.000,000] app: Available size: 11376 bytes ``` 7. Run the following command in another terminal to view the lfs1 directory structure, including config, certs, and logs. ``` $ cd ${MOCN_MSS} $ tree flash/ flash └── lfs1 ├── bootstrap.zip ├── etc │   └── digicert │   ├── conf │   │   ├── applied_policy.json │   │   ├── bootstrap_config.json │   │   ├── failed_policy.json │   │   ├── metrics.pb │   │   ├── pending_policy.json │   │   ├── processing_policy.json │   │   └── version.txt │   ├── keystore │   │   ├── ca │   │   │   ├── devtm-integration-account-intermediate-ca.crt │   │   │   ├── devtm-integration-account-root-ca.crt │   │   │   ├── DigiCertGlobalRootCA.crt │   │   │   ├── DigiCertGlobalRootG2.crt │   │   │   ├── Rendezvous-zone-1-0.crt │   │   │   └── Rendezvous-zone-2-0.crt │   │   ├── certs │   │   │   ├── be_zephy00.crt │   │   │   └── te-api-server.pem │   │   ├── conf │   │   ├── crls │   │   ├── keys │   │   │   ├── be_zephy00-key.crt │   │   │   ├── server_key_gen.pem │   │   │   └── te-api-server.pem │   │   ├── psks │   │   └── req │   │   └── issued │   ├── scripts │   ├── service │   │   ├── completed │   │   ├── failed │   │   ├── processing │   │   └── request │   └── trustedge.json └── tmp 20 directories, 20 files ``` ## Build TrustEdge on STM32H745 Discovery Kit Perform the following steps: 1. Download the `trustedge.zephyr.patch` and copy it to your host machine. > **Info** > > You can get this patch from DigiCert Support. 2. Run the following command to apply the patch: ``` cd ${ZEPHYR_BASE} git apply /trustedge_zephyr.patch cd ${MOCN_MSS} ./scripts/ci/trustedge/ci_trustedge_build_zephyr.sh --board stm32h745i_disco ``` This command builds TrustEdge with Zephyr runtime and places the binary in `./bin/trustedge`. It also builds *device_provision*, a tool used to prepare the flash file system. 3. Run the following command to prepare the flash: ``` cd ${MOCN_MSS}/src/examples/zephyr_examples/trustedge_sample west flash ``` 4. Run the following command to start the TCP server to allow the device to fetch the file system and bootstrap files: ``` cd ${MOCN_MSS} cd ./src/examples/zephyr_examples/trustedge_sample/helper python tcp_server.py --bootstrap --filesys ``` 5. Run the following command to connect to UART: ``` minicom --device /dev/pts/ ``` 6. Run the following command to start TrustEdge from the UART shell: ``` uart:~$ trustedge start ``` 7. Run the following command to check logs: ``` uart:~$ fs cat /lfs1/log/log.0000 ``` 8. (Optional), run the following command to check the TrustEdge status: ``` trustedge status ``` 9. (Optional) run the following command to check the TrustEdge connection: ``` trustedge state ``` ## Build TrustEdge on ESP32-S3-DevKitC ### Supported features: The following features have been tested on ESP32-S3-DevKitC: - Device provisioning workflow with bootstrap certificates - EST enrollment workflow ### Before you begin Ensure you have the following: **System requirements**: - Zephyr version `4.2.0`. - Zephyr SDK version `0.17.2`. **Memory requirements**: - TrustEdge binary size: `1,487,308 bytes (~1.5 MB)` for a full build. - Available flash: `~8 MB` on ESP32-S3-DevKitC - Internal RAM: `642 KB` total (329 KB + 313 KB), with ~512 KB total effectively usable. **ESP32-S3 memory usage breakdown** | Memory region | Used size | Region size | Percentage used | | --- | --- | --- | --- | | mcuboot_hdr | 32 bytes | 32 bytes | 100 percent | | metadata | 80 bytes | 96 bytes | 83.33 percent | | FLASH | 1,487,180 bytes | 8,388,480 bytes | 17.73 percent | | iram0_0_seg | 60,764 bytes | 329 KB | 18.04 percent | | dram0_0_seg | 240,728 bytes | 313 KB | 75.11 percent | | irom0_0_seg | 1,034,314 bytes | 32 MB | 3.08 percent | | drom0_0_seg | 1,356,236 bytes | 32 MB | 4.04 percent | | ext_dram_seg | 5,902,720 bytes | 8 MB | 70.37 percent | | ext_iram_seg | 0 bytes | 8 MB | Zero percent | | rtc_iram_seg | 0 bytes | 8 KB | Zero percent | | rtc_slow_seg | 0 bytes | 8 KB | Zero percent | | IDT_LIST | 0 bytes | 8 KB | Zero percent | ## Pre-requisites for Using ESP32‑S3 with Zephyr Below are the required setup steps before you start building or flashing Zephyr applications onto an ESP32‑S3 board: 1. Run the following command to download the Espressif HAL (Hardware Abstraction Layer) blobs, which is required for the networking support: ``` cd ~/zephyrproject west blobs fetch hal_espressif ``` 2. Run the following command to add the current user to the dialout group to access the serial port: ``` sudo usermod -a -G dialout $USER ``` 3. After plugging in the ESP32‑S3 board, verify the device file created for the serial port. Usually, it is: - /dev/ttyS* - /dev/ttyUSB* For this tutorial, we assume the serial device is: ``` /dev/ttyUSB0 ``` **Environment setup**: Fetch the espressif hal modules to enable networking: ``` cd ~/zephyrproject west blobs fetch hal_espressif ``` Add the current user to dialout group to access serial port ``` sudo usermod -a -G dialout $USER ``` After connecting the esp32s3, verify that the device file is created for the serial port (usually it’s /dev/ttyS* or /dev/ttyUSB*) For this guide, we are using /dev/ttyUSB0 as the device file. ### Step 1: Build Perform the following steps to build all required libraries against Zephyr, compile the TrustEdge binary with the Zephyr runtime. Also, build the *device_provision* tool for preparing the flash filesystem: 1. Navigate to the TrustEdge workspace. 2. Run the following command: ``` cd ${MOCN_MSS} ``` 3. Run the Zephyr build script: ``` ./scripts/ci/trustedge/ci_trustedge_build_zephyr.sh --board esp32s3_devkitc --clean ``` After a successful build, two directories are created: - **MCUbootloader**: ``` ./src/examples/zephyr_examples/trustedge_sample/build_mcuboot/ ``` **TrustEdge**: ``` ./src/examples/zephyr_examples/trustedge_sample/build/ ``` ### Step 2: Flash Flashing is done in two stages; perform the following steps: 1. Run the following command to navigate to the sample directory. ``` cd ./src/examples/zephyr_examples/trustedge_sample ``` 3. Run the following command to flash the MCUbootloader: ``` west flash --esp-flash-bootloader build_mcuboot/zephyr/zephyr.bin --esp-boot-address 0x0 ``` 4. Run the following command to flash the TrustEdge binary: ``` west flash ``` ### Step 3: Run Perform the following steps: 1. Navigate to the helper scripts directory: ``` cd ${MOCN_MSS} cd ./src/examples/zephyr_examples/trustedge_sample/helper ``` 2. Run the following command to prepare the file for an EST enrollment. This command creates a new filesystem zip with EST-related files. ``` ./prepare_trustedge_est.sh ``` 3. Run a TCP server to allow filesystem and the bootstrap files: ``` python tcp_server.py --bootstrap --filesys ``` 4. Run the following command to connect to the ESP32-S3 serial port using a **minicom**: ``` sudo minicom -b 115200 -D /dev/ttyUSB0 ``` > **Tip** > > You can find the correct serial port in the output of the `west flash` command. 5. Run the following command from the UART shell to reboot and connect to a wireless network: ``` uart:~$ kernel reboot uart:~$ wifi connect -k -s -p ``` Where: - `-s `: Your wireless network username - `-k `: Key management type Valid values for `-k` are: ``` 0: None 1: WPA2-PSK 2: WPA2-PSK-256 3: SAE-HNP 4: SAE-H2E 5: SAE-AUTO 6: WAPI 7: EAP-TLS 8: WEP 9: WPA-PSK 10: WPA-Auto-Personal 11: DPP ``` 6. Run the following command to start TrustEdge: ``` uart:~$ trustedge start ``` 7. Run the following command to check the TrustEdge logs: ``` uart:~$ fs cat /lfs1/log/log.0000 ``` 8. Run the following command to verify if TrustEdge is connected: ``` uart:~$ trustedge state ``` 9. Run the following command to verify if TrustEdge is provisioned: ``` uart:~$ trustedge status ``` > **Important** > > **Known Issue** > > During device provisioning, a known issue in the **ESP32 Wi-Fi driver** might cause the console to hang and drop the connection. If this happens, reconnect to the wireless network and restart TrustEdge to complete provisioning. ## Frequently asked questions (FAQs) **How do I list available TrustEdge commands at the UART console?** From the Zephyr shell, run the following command: ``` uart:~$ trustedge ``` Output: ``` trustedge - Demo commands Subcommands: start : Run TrustEdge. state : Show TrustEdge state. status : Show TrustEdge status. reboot : reboot device. reset : reset file system. confirm : confirm image. ``` **How do I reset the TrustEdge filesystem?** Use this when switching to a **different bootstrap** or when you need a clean state: ``` uart:~$ trustedge reset ``` **What if Wi‑Fi connection drops while TrustEdge is running?** Run the following command to reconnect to Wi‑Fi manually: ``` uart:~$ wifi connect -k -s -p ``` Run the following command to resume the TrustEdge flow: ``` uart:~$ trustedge start ``` **What if Wi‑Fi connect fails with error -120?** If you see: ``` Connection request failed (UNKNOWN/-1) Connection request failed with error: -120 ``` This usually indicates the Wi‑Fi subsystem is stuck. Run the following command to reboot the kernel and retry the connection: ``` uart:~$ kernel reboot ``` Then reconnect using the following command: ``` uart:~$ wifi connect -k -s -p ```