elastic-ai.runtime.enV5

• elastic-ai.runtime.enV5
  • System Requirements
  • Set Up
    • Get the Source Code
    • Setup devenv
      • Python Environment (OPTIONAL)
    • Compile the Source Code
    • Local Test Execution
    • enV5 Node Execution
    • Flash the enV5
    • Get Output from the enV5 Node
  • External Dependencies
  • Troubleshooting
  • Glossary

Important

If you want to create your own project with the enV5 platform refer to the base-project as a starting point.

This repository provides the Elastic-AI runtime implementation for the Elastic Node version 5 (enV5). A modular hardware platform with FPGA integration.

Tip

The project homepage provides additional information.

System requirements

• devenv -> Tool for reproducible development environments
• GCC (through devenv) -> C Compiler
• ARM-None-EABI GCC (through devenv) -> C Cross-Compiler for ARM
• CMake (through devenv) -> Build System
• Ninja (through devenv) -> Build Tool
• Astral-UV (through devenv) -> Python Runtime/Package Manager

Set up

Important

This Guide assumes you are using a devenv compatible operating system.

Get the source code

At first, you have to download the source code from GitHub:

# Download the Repository
git clone https://github.com/es-ude/elastic-ai.runtime.enV5.git enV5

# Move inside the repository
cd enV5

Setup devenv

1. At first you have to install devenv, by following their instructions in their Getting-Started-Guide.
2. Install direnv, to automatically load the development environment provided by devenv.

Python environment

Important

If you use devenv this step is not required, devenv automatically initializes and syncs a virtual Python environment.

Note

The Python environment is only required if you want to use the provided python utilities to interact with the enV5 Node.

To minimize the potential corruption of your system we recommend installing the dependencies inside a virtual environment. Create a python environment by running:

# create a virtual python environment under `.venv/`
uv venv .venv
uv sync --all-groups       # install all python dependencies

Compile the source code

Important

You have to adjust the network/MQTT broker credentials as mentioned in network README!

Note

We use CMake to build this project.

We offer three predefined profiles with the CMakePresets.json:

• unit_test
• env5_rev2_release
• env5_rev2_debug

These profiles offer the required settings to either build for your local system (unit_test) to locally run test, or to build for the enV5 Node (env5_rev2_release and env5_rev_2_debug). The profile with the suffix debug also provides additional console output for debugging purposes.

To initialize the CMake Tool run:

# directly
cmake --preset unit_test
cmake --preset env5_rev2_debug
cmake --preset env5_rev2_release

# custom function provided by devenv
devenv tasks run prepare:cmake

Warning

Loading all required external dependencies from the internet can take a while. See external dependencies.

After initializing the CMake Project you can compile the source code:

# directly
cmake --build --preset unit_test
cmake --build --preset env5_rev2_debug
cmake --build --preset env5_rev2_release

# custom function provided by devenv
devenv tasks run -m before build

Local test execution

The local execution of the unit tests is possible by using the ctest function as follows:

# directly
cmake --build --preset unit_test
ctest --preset unit_test

# as a task provided by devenv
devenv tasks run -m before check:unit-test

Note

You can then find the unit-test executables under build/unit-test/test/unit.

Elastic-node executables

You can find the hardware test executables for the enV5 Node under build/env5_rev2_release and build/env5_rev2_debug. You can then find the *.uf2 files to flash the hardware inside their directories, mirroring the source code structure.

Flash the elastic-node

Run

# script provided by devenv
flash_node <path_to_uf2>

OR

1. Press and hold MCU BOOT on the enV5 Node
2. Press MCU RST on the enV5 Node
3. Release MCU BOOT
4. Copy the *.uf2 File to the RPI-RP2 device
   • Via the USB device through your file manager
   • Via the command line by executing sudo cp <file>.uf2 /dev/sdX

Get output from the elastic-node

To receive output from the enV5 you have to connect the enV5 to your local machine. Connect the USB-C port of the enV5 with a USB port of your local machine to do this.

After you connect the enV5 to your computer, read the debug output from the device with a serial port reader such as screen, minicom, or putty.

Important

The serial port differs depending on the host machine! You can find the device path via ls /dev/tty* (Linux) or ls /dev/tty.* (macOS) from the terminal.

We recommend using minicom as it is the most versatile of the aforementioned tools. You can receive the output of the device by executing

minicom
-o \             #  Disable modem initialisation
-w \             # Enable line wrap
-b 115200 \      # Set the baud rate to 115200
-D /dev/ttyACM0  # Define the serial port to read

in your shell prompt.

Caution

If you cannot receive any output from the enV5 the problem is possibly caused by a bug in the source code. If the serial output is not initialized properly (see integration tests), the enV5 is not able to send the output to your device!

External dependencies

Important

CMake will automatically download and initialize these dependencies!

This project uses the following external dependencies:

• es-ude/elastic-ai.runtime.c
• raspberrypi/pico-sdk
• FreeTROS/FreeRTOS-Kernel
• ThrowTheSwitch/CException
• ThrowTheSwitch/Unity

Troubleshooting

• To generate a clean CMake Build without deleting and initializing the build directory again run cmake --build --target clean --preset <preset_to_clean>.
• If the device does not connect to the Wi-Fi or MQTT broker make sure that you set up the correct credentials! (NetworkConfig.c)
• Debugging the FPGA

Glossary

Term	Scope	Description
enV5	–	Hardware with the MCU, Flash, FPGA, ...
Flash	–	Flash storage on the board
HAL	–	Hardware Abstraction Layer Libraries to bundle direct hardware dependencies (UART, SPI, GPIO, ...)
configuration	FPGA, Middleware	bin file used to configure the FPGA
FreeRTOS	Network	Open Source Real Time operating system Used to emulate Threads
ESP32 / ESP	Network	Wi-Fi Module from espressif
AT Commands	Network, MQTT, HTTP	String based command set to control the ESP32 Wi-Fi module
Broker	MQTT, Network	MQTT User implementation used to publish and subscribe to topics