Zephelin project

Zephelin is implemented as a West module. The Zephelin repository consists of the following elements:

  • Zephelin library

  • Custom configurations of boards based on MAX78002 and MAX32690 - for testing purposes

  • Sample applications, which also serve as integration tests

  • Unit tests

  • Patches to Zephyr RTOS

Initializing the workspace

First, make sure all dependencies required by Zephyr RTOS are installed - follow the Getting started guide.

Secondly, create a workspace and clone the Zephelin repository:

mkdir workspace && cd workspace
git clone --recursive git@github.com:antmicro/zephelin.git
cd zephelin

Then, install west and additional dependencies listed in project’s requirements.txt with pip:

pip install -r requirements.txt

Next, initialize the workspace using West. To do that, run the following command:

west init -l .

Download, patch and prepare the project sources using the following commands:

west update
west patch apply
west zephyr-export
west packages pip --install

For testing without hardware in the loop, download Renode portable and add the download path to PATH environment variable:

wget https://builds.renode.io/renode-latest.linux-portable-dotnet.tar.gz
mkdir renode-portable
tar --strip-components=1 -C ./renode-portable -xvf renode-latest.linux-portable-dotnet.tar.gz
export PATH=$(pwd)/renode-portable:$PATH

Finally, download Zephyr SDK:

west sdk install

Running a sample project with Zephelin

To collect traces and visualize them using Zephelin Trace Viewer, you can run a simple demo with gesture recognition, based on the data from an accelerometer. The default configuration in this demo collects traces along with all possible additional information, like memory usage, die temperature, inference statistics, and more. One UART provides logs from the application, whereas the other UART returns CTF traces.

Running the demo in Renode simulation

To build the demo, run:

west build -p -b stm32f746g_disco/stm32f746xx samples/demo

To run it in a Renode simulation, run:

python ./scripts/run_renode.py \
    --repl ./samples/demo/boards/stm32f746g_disco_lis2ds12.repl \
    --sensor i2c1.lis2ds12 \
    --sensor-samples ./samples/common/data/magic_wand/magic_wand.data \
    --trace-output trace.ctf \
    --timeout 10

This demo will run for 10 seconds, until a timeout is reached. After this time, CTF traces returned over the secondary UART will be stored in trace.ctf.

Note

For trace collection on actual hardware, refer to Trace collection.

The trace needs to be converted to the TEF format, so that it can be loaded into Zephelin Trace Viewer.

For that purpose, run:

west zpl-prepare-trace ./trace.ctf --tvm-model-path samples/common/tvm/model/magic-wand-graph.json -o ./tef_tvm_profiler.json

The part --tvm-model-path is an input argument with the path to a TVM model graph, which is used to introduce additional model data to the TEF trace file metadata.

To get an overview of the traces, load the output tef_tvm_profiler.json file in Zephelin Trace Viewer.

Running the demo on HW

This demo can be also run on physical MAX32690 Evaluation Kit using ADXL345 accelerometer. The accelerometer can be connected to i2c0 as follows:

  • VIN -> any 3v3 pin

  • GND -> any ground pin

  • SDA -> pin 7 on port JH4

  • SCL -> pin 8 on port JH4

It is also required to connect following jumpers to enable i2c0:

  • JP2

  • JP3

  • JP4

To program the board, connect MAX32625 Pico using USB cable to PC and via SWD header to the board. Then, connect another USB cable to CN2 - this will be used to collect data via UART (uart2). Finally, to collect the traces, connect USB-UART converter to uart0 using following pins:

  • RX - pin 11 on port JH4

  • TX - pin 12 on port JH4

Alternatively, when USB-UART converter is not available, it is possible to switch UARTs in board overlay and collect traces the same way as logs - using uart2.

To build the demo, run:

west build -p -b max32690evkit/max32690/m4 samples/demo

And then, to flash the board, run:

openocd \
    -c 'source [find interface/cmsis-dap.cfg]' \
    -c 'source [find target/max32690.cfg]' \
    -c 'init' \
    -c 'targets' \
    -c 'reset init' \
    -c 'flash write_image erase ./build/zephyr/zephyr.hex' \
    -c 'reset run' \
    -c 'shutdown'

using openocd from Analog Devices MSDK.

After flashing there should be logged readings from sensor to the UART.

*** Booting Zephyr OS build v4.2.0-rc2-49-g732a3a5c6655 ***
adxl345@53: x=+0.312 y=+0.906 z=+0.046
adxl345@53: x=+0.296 y=+0.906 z=+0.031
adxl345@53: x=+0.312 y=+0.890 z=+0.015
adxl345@53: x=+0.312 y=+0.890 z=+0.015
adxl345@53: x=+0.312 y=+0.890 z=+0.031
...

To trigger gesture recognition, move the sensor.

...
adxl345@53: x=-0.015 y=+0.374 z=+0.078
model output: wing=1.000 ring=0.000 slope=0.000 negative=0.000

Then, the traces collected via UART can be analyzed the same way as in Running the demo in Renode simulation.

Customizing and using Zephelin

Zephelin can be enabled by y-selecting the CONFIG_ZPL symbol in the project configuration file. To initialize Zephelin in a runtime, use the zpl_init() function defined by the zpl/lib.h header. You can enable various Zephelin components by using Kconfig and runtime configuration, as described in following sections.

Configuration

The library can be configured both during building and during a run on a device. To find out how to configure the library and how to add new configurations, check Zephelin configuration.

Trace collection

To enable Zephelin tracing support, the user should enable the symbol CONFIG_ZPL_TRACE in Kconfig. You can then select one of the following formats:

  • Plaintext format, by y-selecting CONFIG_ZPL_TRACE_FORMAT_PLAINTEXT

  • Common Trace Format (CTF), by y-selecting CONFIG_ZPL_TRACE_FORMAT_CTF

You can choose how the traces will be delivered to the host PC by selecting one of the available tracing backends:

  • UART, by y-selecting CONFIG_ZPL_TRACE_BACKEND_UART

  • USB, by y-selecting CONFIG_ZPL_TRACE_BACKEND_USB

  • Debugger, by y-selecting CONFIG_ZPL_TRACE_BACKEND_DEBUGGER

  • Renode’s simulated trivial UART, by y-selecting CONFIG_ZPL_TRACE_BACKEND_TRIVIAL_UART

Depending on the tracing backend used, the following commands can be used for trace capture.

UART

  • Config option - CONFIG_ZPL_TRACE_BACKEND_UART

  • Command:

    west zpl-uart-capture [-h] serial_port serial_baudrate output_path

Capture traces using UART. This command capures traces using the serial interface.

positional arguments:
  serial_port      Seral port
  serial_baudrate  Seral baudrate
  output_path      Capture output path

options:
  -h, --help       show this help message and exit

USB

  • Config option - CONFIG_ZPL_TRACE_BACKEND_USB

  • Command:

    west zpl-usb-capture [-h] [-t TIMEOUT] [-w] vendor_id product_id output_path

Capture traces using USB. This command capures traces using USB.

positional arguments:
  vendor_id             Vendor ID
  product_id            Product ID
  output_path           Capture output path

options:
  -h, --help            show this help message and exit
  -t, --timeout TIMEOUT
                        Timeout of the USB capture in seconds
  -w, --wait-for-device
                        When this flag is set, the command will wait for the device to connect

Debugger

  • Config option - CONFIG_ZPL_TRACE_BACKEND_DEBUGGER

  • Command:

    west zpl-gdb-capture [-h] elf_path output_path

Capture traces using GDB. This command captures traces using GDB from RAM using the `dump` command.

positional arguments:
elf_path     Zephyr ELF path
output_path  Capture output path

options:
-h, --help   show this help message and exit

Trivial UART in Renode

On top of the above, Renode’s simulated trivial UART can be used as well to collect traces in a simulation: CONFIG_ZPL_TRACE_BACKEND_TRIVIAL_UART.

Adding named events to traces

Zephelin provides methods for introducing custom named events to traces from the source code level. To use named events, include the header zpl/lib.h, and use the function sys_trace_named_event() to generate named events.

Memory profiler

To use Zephelin memory profiler, y-select the CONFIG_ZPL_MEMORY_PROFILING in Kconfig. No further actions are needed in the application code to generate memory profiling events in the generated trace. Memory profiling along with memory events are described in Memory profiling.

TLFM events

To use Zephelin custom events with Tensorflow Lite Micro (TLFM), use the functions zpl_emit_tflm_begin_event() and zpl_emit_tflm_end_event(), provided by zpl/tflm_events.h.

Testing Zephelin

To run unit and integration tests, use the following commands:

west twister -v -p max78002evkit/max78002/m4 -p max32690fthr/max32690/m4 -p qemu_cortex_m3 -T samples -T tests
Last update: 2025-09-05