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.

Note: Windows may silently block the zip file. Windows often restrict applications in downloaded zip-files for security reasons. This may cause the Tracealyzer tool (included in the Windows Client) to fail loading traces (error message “Failed to find handler for opening this trace…”). To avoid this issue, run the following powershell command in the Detect directory:

Get-ChildItem -Path . -Recurse | Unblock-File

Another option is to right-click on the zip file before extracting it, select “Properties” and check the “Unblock” option at the bottom of the General page, if this is present.

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

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.

Update 2025.1.2

Fixed a bug fix in the Linux client related to file permissions (permission denied error in certain cases).
Changed how the Linux Client stores persistent files. Now using a mounted host folder (“settings” subfolder) instead of a docker volume.
Solved a license check issue in Tracealyzer on Linux. In some cases, the hardware id changed after restarting the client container. Now persistent.
Updated the Windows client to use a signed version of the Dispatcher tool.

To update the Linux client, delete the old image by running “docker image rm percepio/percepio-client:2025.1”, and make sure to use the updated start script from the latest .tgz file. Note: You will need to enter your Tracealyzer license key again.

If using Linux and updating to the 2025.1.2 version, you can remove the old docker volume for the Client. Run “docker volume ls” to see the volume names and use “docker volume rm volumename” to delete a volume. Note that “percepio_database” is used by the Server.

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).

If the payload links doesn’t seem to work, make sure the client is started. If started and nothing appears in the client terminal log when you click a payload link, it might be because of a caching issue noted with Firefox on certain Linux distributions. A workaround is to open the Developer Tools in the web browser (F12 button), select “Network” and there check the checkbox “Disable cache”. Keep the Developer Tools open and try clicking the payload link again.

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.