Install and run TrustEdge with Zephyr RTOS

9 minute read

You can install and run TrustEdge with Zephyr RTOS using either the native simulator (native_sim 64-bit board) 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).

Clone TrustCore SDK: Clone the TrustCore SDK repository and navigate into the cloned directory.

git clone https://github.com/digicert/trustcore.git
cd trustcore

Environment variable: The ${TRUSTCORE} should point to the root of your TrustCore package. This environment variable is used throughout this document and refers to the root directory of the DigiCert TrustCore public repository.

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.

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:

To install the script, run the following command:

cd ${TRUSTCORE}
./scripts/ci/trustedge/ci_trustedge_build_zephyr.sh --zephyr-install

Build TrustEdge on native sim (64-bit)

Perform the following steps:

Download the trustedge.zephyr.patch and copy it to your host machine.
You can get this patch from DigiCert Support.
Run the following command to apply the patch:
```
cd ${ZEPHYR_BASE}
git apply <path-to>/trustedge_zephyr.patch
cd ${TRUSTCORE}
./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.
Add a host entry to /etc/hosts for provisioning:
```
127.0.0.1       provision.digicert.com
```

Run the following command to prepare the flash.bin:

cd ${TRUSTCORE}
./src/examples/zephyr_examples/device_provision/provision_flash.sh --bootstrap <path/to/boostrap/zip>

If flash provisioning is skipped, use the following Python script for TrustEdge binary to get the bootstrap file onto the system:

cd ${TRUSTCORE}
cd ./src/examples/zephyr_examples/trustedge_sample/helper
python tcp_server.py --bootstrap <path-to-bootstrap-zip> --filesys <path-to-filesystem-zip>

Run the following command to execute TrustEdge in another terminal:
```
cd ${TRUSTCORE}
./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

Run the following command to install the required tools:
```
sudo apt install zip unzip
```
Run the following command to load the 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 <path/to/boostrap/zip>
./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.

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 <path/to/boostrap/zip>
./bin/trustedge

Run a curl request to verify the TrustEdge key generation flow:

curl --cacert ${TRUSTCORE}/pki_certs/rootCA.pem https://localhost:8443/v1/key/asymmetric -H 'Content-Type: application/json' -d '{
    "keyCertAttributes": {
        "outputMode": "buffered",
        "algorithm": "rsa+2048",
        "keySource": "SW"
    }
}'

Run the curl request once again to trigger an enrollment flow:

curl --cacert ${TRUSTCORE/co}/pki_certs/rootCA.pem https://localhost:8443/v1/certificate/enroll -H 'Content-Type: application/json' -d@${TRUSTCORE}/src/trustedge/test/data/est_request.json

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] <inf> littlefs: littlefs partition at /lfs1
*** Booting Zephyr OS build v4.0.0-3113-g5aeda6fe7dfa ***
[00:00:00.000,000] <inf> littlefs: LittleFS version 2.9, disk version 2.1
[00:00:00.000,000] <inf> littlefs: FS at flash-controller@0:0x100000 is 768 0x1000-byte blocks with 512 cycle
[00:00:00.000,000] <inf> littlefs: partition sizes: rd 16 ; pr 16 ; ca 64 ; la 32
[00:00:00.000,000] <inf> app: Total partition size: 12288 bytes
[00:00:00.000,000] <inf> app: Available size: 11376 bytes

Run the following command in another terminal to view the lfs1 directory structure, including config, certs, and logs.

$ cd ${TRUSTCORE}
$ 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:

Download the trustedge.zephyr.patch and copy it to your host machine.
You can get this patch from DigiCert Support.
Run the following command to apply the patch:
```
cd ${ZEPHYR_BASE}
git apply <path-to>/trustedge_zephyr.patch
cd ${TRUSTCORE}
./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.

Run the following command to prepare the flash:

cd ${TRUSTCORE}/src/examples/zephyr_examples/trustedge_sample
west flash

Run the following command to start the TCP server to allow the device to fetch the the bootstrap files and store them in the file system:

cd ${TRUSTCORE}
cd ./src/examples/zephyr_examples/trustedge_sample/helper
python tcp_server.py --bootstrap <path-to-bootstrap-zip> --filesys <path-to-filesystem-zip>

Run the following command to connect to UART:
```
minicom --device /dev/pts/<num>
```
Run the following command to start TrustEdge from the UART shell:
```
uart:~$ trustedge start
```
Run the following command to check logs:
```
uart:~$ fs cat /lfs1/log/log.0000
```
(Optional), run the following command to check the TrustEdge status:
```
trustedge status
```
(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.

For memory used by TrustEdge, ncluding Zephyr components, see src/examples/zephyr_examples/trustedge_sample/esp32s3_prj.conf

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	319,656 bytes	313 KB	99.73 percent
irom0_0_seg	1,035,678 bytes	32 MB	3.09 percent
drom0_0_seg	1,356,196 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:

Run the following command to fetch the espressif hal modules to enable networking:

cd ~/zephyrproject
west blobs fetch hal_espressif

Run the following command to add the current user to the dialout group to access the serial port:

sudo usermod -a -G dialout $USER

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

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:

Navigate to the TrustEdge workspace.
Run the following command:
```
cd ${TRUSTCORE}
```

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:

Run the following command to navigate to the sample directory.
```
cd ./src/examples/zephyr_examples/trustedge_sample
```

Run the following command to flash the MCUbootloader:

west flash --esp-flash-bootloader build_mcuboot/zephyr/zephyr.bin --esp-boot-address 0x0

Run the following command to flash the TrustEdge binary:
```
west flash
```

Step 3: Run

Perform the following steps:

Navigate to the helper scripts directory:

cd ${TRUSTCORE}
cd ./src/examples/zephyr_examples/trustedge_sample/helper

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 <path-to-filesystem-zip>
```

Run a TCP server to allow filesystem and the bootstrap files:

python tcp_server.py --bootstrap <path-to-bootstrap-zip> --filesys <path-to-filesystem-zip>

Run the following command to connect to the ESP32-S3 serial port using a minicom:
```
sudo minicom -b 115200 -D /dev/ttyUSB0
```
You can find the correct serial port in the output of the west flash command.

Run the following command from the UART shell to reboot and connect to a wireless network:

uart:~$ kernel reboot
uart:~$ wifi connect -k <num> -s <SSID> -p <password>

Where:

-s <SSID>: Your wireless network username

-k <num>: 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

Run the following command to start TrustEdge:
```
uart:~$ trustedge start
```
Run the following command to check the TrustEdge logs:
```
uart:~$ fs cat /lfs1/log/log.0000
```
Run the following command to verify if TrustEdge is connected:
```
uart:~$ trustedge state
```
Run the following command to verify if TrustEdge is provisioned:
```
uart:~$ trustedge status
```

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 <num> -s <SSID> -p <password>

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 <num> -s <SSID> -p <password>

Was this page helpful?

Provide feedback

Need more help?

Account and platform

Certificates and PKI

Signing

Devices and IoT

Other resources

Install and run TrustEdge with Zephyr RTOS

Before you begin

Install Zephyr

Build TrustEdge on native sim (64-bit)

TrustEdge examples

Build TrustEdge on STM32H745 Discovery Kit

Build TrustEdge on ESP32-S3-DevKitC

Supported features:

Before you begin

Pre-requisites for Using ESP32‑S3 with Zephyr

Step 1: Build

Step 2: Flash

Step 3: Run

Frequently asked questions (FAQs)