Percepio Detect – Evaluation Package

Percepio Detect™ brings Continuous Observability® targeting crashes and stability risks in RTOS-based embedded software. Built for seamless integration into your in-house testing, CI/CT pipelines, and field testing, Detect helps your development team spot and solve issues early—long before they reach production.

The current version is targeting Arm Cortex-M devices with FreeRTOS or bare-metal code. Download the evaluation package for your host OS from the links below.

• percepio-detect-2025.1.1-linux.tar.gz
• percepio-detect-2025.1.1-windows.zip

If using Windows: Before you extract the zip file, make sure that the included executables are not blocked by Windows. Right-click on the zip file, select “Properties” and check for an “Unblock” checkbox at the bottom of the General page. If the checkbox is displayed, check it to unblock the zip file. If not displayed, the zip file is not blocked.

Documentation, guides, examples

Get started by following the Percepio Detect Demo Guide, found in the root folder of the download package. Note that you need a license key for the Detect Server. This is provided by Percepio on request.

When ready to integrate Detect with your own system, see readme.txt for instructions and pointers.

You find more guides, code examples and the target libraries in the device-integration folder, including two pdf files. The main guide for device integration is “Percepio Detect – Device Integration Guide – 2025.1.pdf”. The other guide, “Tracealyzer Bare Metal Intro.pdf”, explains how to use Tracealyzer with the RTOS-independent “bare-metal” port of the TraceRecorder library.

A demo project is included for the STM32 development board B-L475E-IoT01A.

What’s new in 2025.1?

• Major improvement of Linux host support by a new version of the Detect Client for Linux, i.e. the host-side tools for debugging of alerts. Has been successfully tested on multiple distributions of different types, including Ubuntu 22, Ubuntu 24, Linux Mint, OpenSUSE and Manjaro.
• Added possibility for user-defined actions when an alert payload is selected by providing a script hook with documentation. For example, to download the .elf file from an artifact repository over a HTTP, if the file is not accessible via the local file system.
• Now possible to use the “product” and “revision” attributes in the Client settings. This way, the Client can load the right version of the build artifacts (e.g. elf file) based on the selected alert and the device that generated it.
• Fixed permission problem when accessing new alert files on Linux. Solved by running the Client container as the host user (same UID and GID).
• Improved demo guide, device integration guide and readme files.
• Reduced size of Linux Client image by about 70%.
• Updated demo example data.
• Updated base images for all docker images.

Update 2025.1.1
This minor update removed some undesired test-data files, accidentally included in the original 2025.1 release. This may have prevented the demo data from being displayed in some cases.

Roadmap

The next release (2025.2) is planned for June 2025 and will support broad anomaly detection via CPU load alerts and other data transfer methods. The Receiver tool is being updated to allow batch processing of raw binary data from DFM. For example, if the device has a web server, this allows for providing the DFM data as a single file download with all stored alerts.

Next up, Percepio Detect 2025.3, will add Zephyr support. Note that an older version of DFM is already available in the Zephyr repository, but this is not intended for Percepio Detect.

Troubleshooting

When starting the server on Linux, there might be an error message in the terminal about the permissions for the alert-files folder. In that case, make sure to follow the provided instruction to grant access to the folder (chmod …). This is needed since the server containers run as a different user and need to write some files to the alert-files folder.

If the demo data is not displayed within 10 seconds after the Dashboard is opened in the web browser, check for a red bar in the bottom of the Dashboard with an error message. This shows up for example if the license key has not been provided in the server start script or if there is some problem with the license check.

Otherwise, if there is no error message about the license but no alerts are displayed, check the test-data/alert-files folder for a file called lasttrace.txt. This is generated when alerts are processed and contains the timestamp of the last processed alert. Try removing this file, in case it comes from a previous test. This makes the server process all alert files, no matter when they where created. The file lasttrace.txt will be regenerated, but keep the updated file.

If this doesn’t help, check the log file “failure.txt” may contain the line “Percepio Detect is not available (ServiceUnavailable)”. It is common this happens once during the startup. But there should not be repeated lines like that or other errors. In that case, run the server start script with the “logs” argument and provide the logs to Percepio.

If using Windows and the Tracealyzer tool fails to open the trace files, this is most likely because the zip file was blocked for security reasons. Perhaps you missed to unblock the zip file before extracting it? (See above). To ensure the Detect files are not blocked by Windows, use the following PowerShell command:

cd <Percepio Detect folder>
Get-ChildItem -Path . -Recurse | Unblock-File

If your device application does not have enough flash space for adding the device libraries, you may reduce the the flash usage by setting the compiler optimization setting to “Optimize for size” (at least for these libraries). Flash usage can also be reduced by disabling the GCC stack integrity checking used in the demo (-fstack-protector-strong flag).

You can a reduce the device-side RAM usage of the solution by tweaking the following settings:

• DFM_CFG_MAX_PAYLOAD_CHUNK_SIZE in DFM/config/dfmconfig.h: This controls the main RAM buffer in DFM, that holds the current payload chunk. If the payload is larger than this buffer size, it is divided into multiple smaller chunks that are sent one by one. Default is 2000 bytes. Reducing this will result in more chunks (files) created, but each one is smaller and less RAM is needed by DFM.
• DFM_CFG_STACKDUMP_SIZE in DFM/config/dfmCrashCatcherConfig.h: How much of the current stack to include in core dumps. This affects the size of an internal buffer for this data. Default is 300 bytes. This is the majority of the core dump payload (and RAM usage), but registers and other information is also included, making the total payload size somewhat larger.
• TRC_CFG_STREAM_PORT_BUFFER_SIZE in TraceRecorder/streamports/RingBuffer/config/trcStreamPortConfig.h: The size of the TraceRecorder event buffer. Default is 5000 bytes. This decides how long trace history that is provided with the alerts.
• TRC_CFG_ENTRY_SLOTS in TraceRecorder/config/trcStreamingConfig.h: The number of object entries allowed in the TraceRecorder symbol table. This is used to store names of tasks, traced ISRs, user event channels etc.
• TRC_CFG_ENTRY_SYMBOL_MAX_LENGTH, also in TraceRecorder/config/trcStreamingConfig.h: The number of bytes used to store an object name in the symbol table. If longer names would be used, they are truncated.

If you have questions, please contact the Percepio team.