Trice - Trace IDs for Embedded C/C++

🅃🅁ace 🄸d’s for 🄲 🄴mbedded

View Github Pages

TriceGirlS.png Hi, I am Trice.

Trice is an ultra-low-overhead logging framework for embedded C/C++. It provides printf-like usability with only ~6–100 CPU cycles per log call, making logging practical even when used from interrupt handlers in real-time firmware systems.

License GitHub release (latest by date) GitHub commits since latest release Downloads GitHub issues PRs Welcome Go Version Go Report Card Coverage TRICE Library CI (Nightly Full) <!– Go Reference Go Coverage (PR + Monthly) Clang-Format Check TRICE Library CI (Nightly Quick) Mark stale issues and pull requests GitHub code size in bytes CodeQL GitHub watchers test GitHub Workflow Status Sponsor rokath

–>

Log in a trice — with Trice, even from ↯ interrupt handlers in less than 1 µs ❗

Trice User Manual: GitHub • GH Pages • PDF

What is Trice?

Trice is designed for systems where traditional logging is too slow, too large, or not safe to use in interrupt or real-time contexts.

Trice replaces printf-style logging in embedded C/C++ systems with a much faster and more efficient approach.

Instead of formatting and storing strings on the target, Trice encodes log messages as compact IDs and keeps the actual strings on the host. This reduces runtime overhead, memory usage, and data transfer size.

Key Benefits

How it works

  1. Use Trice macros instead of printf in your firmware (or use the trice i -alias option)
  2. Each log message is replaced by a compact ID
  3. The target sends only IDs and data
  4. The host reconstructs the original messages using the Trice ID list
- printf("Temperature: %d°C", t);
+ trice("Temperature: %d°C", t);   // fast, compact, ID-based

Result

Two Parts of Trice

  1. C code macros - Provide a familiar printf-like interface at the application level, but internally send just ID and values instead of full format strings. The Trice tool maps these IDs back to readable text.
  2. Trice tool - Manages and displays the logs
    • Written in Go - works on all platforms that Go supports
    • You can also build your own tool to receive Trice packages, replace IDs with text, and display the output

Ready to use: Start with Trice

Install the trice tool. Use a latest release binary and put it into your PATH.

For a first setup, SEGGER RTT is usually fastest: it needs no MCU-specific UART driver and works via J-Link. Install the SEGGER J-Link software package so JLinkRTTLogger is in PATH.

  1. Add the complete src folder to your target project unchanged and add ./src to the compiler include path.
  2. Create a project-specific triceConfig.h file with this minimal direct RTT configuration:
#define TRICE_DIRECT_OUTPUT 1
#define TRICE_BUFFER TRICE_STACK_BUFFER
#define TRICE_DIRECT_SEGGER_RTT_32BIT_WRITE 1
  1. Add Trice to your code, for example in main.c:
#include "trice.h"

int main(void) {
    TriceInit(); // RTT-specific
    // ... system init
    trice("Hello world!\n");
    // ...
}
  1. Create empty til.json and li.json files in your project root and run trice insert -src ./ before compiling. This assigns IDs to your trice(...) calls and fills both JSON files.
  2. Build and flash your target.
  3. Start logging with your device name (add -v for details)
trice log -p JLINK -args "-Device STM32G0B1RE -if SWD -Speed 4000 -RTTChannel 0" -pf none -prefix off -hs off -d16 -i ./til.json -li ./li.json

Or use the file-based RTT logger workflow manually:

# Terminal 1
rm -f ./temp/trice.bin
JLinkRTTLogger -Device STM32G0B1RE -If SWD -Speed 4000 -RTTChannel 0 ./temp/trice.bin

# Terminal 2
touch ./temp/trice.bin
trice log -p FILE -args ./temp/trice.bin -pf none -prefix off -hs off -d16 -ts ms -i ./til.json -li ./li.json

For more setup details, see Start with Trice, Configuration file triceConfig.h, and Trice over RTT.

When to Use Trice

Logging and Debugging

You can use Trice for printf debugging and as a logging system. The advantage is very short messages (no strings) for data transfer. Keep your project-specific til.json file available to decode field logs later. The repository example file is demoTIL.json.

Data Compression

Trice looks like data compression (IDs instead of strings), which is useful for IoT devices, especially NB-IoT with very low data rates.

FLASH Memory Storage

Store Trice messages in FLASH memory for later analysis. A typical trice uses only 4 bytes, no matter how long the format string is.

Encryption

You can encrypt Trice transfer packets for security.

Translation

Translate the til.json file into different languages. Change the language by changing the til.json file without changing the target binary.

Timing Analysis

Trice makes timing analysis easy on distributed embedded systems. It supports both host and target timestamps.

How Trice Works (UART Example)

This simplified diagram shows how Trice works. Read the detailed explanation here.

trice

Data Transfer Options

Implemented Transfer Methods

Other Transfer Options

Display Server

Documentation

The Trice User Manual includes all information from the Memfault Interrupt Blog which is slightly outdated.

Debugging with VS Code and Clang

Debug a Trice project in Direct-Out Mode over SEGGER-RTT. (See Development Environment Setup for details.)

Trice Cache

(click to expand)

You can use the -cache CLI switch with trice insert and trice clean commands. This only works when you create the .trice/cache folder in your home directory. (Trice Cache Details)

When to Use Cache

Use cache when you:

How Cache Works

The Trice cache saves copies of all files after processing them with trice i or trice c. This avoids inserting and removing IDs repeatedly. The copies are used to get the same results for files that have not been edited. Edited files are processed normally and the cache updates afterwards. File modification times do not change, so the build system does not reprocess unchanged files even when IDs are temporarily removed.

Important Note

-> Be careful when your build system also modifies source files!

For example, run an auto-formatter before the trice insert command.

Which Mode Should You Use?

Project Status

Trice is fully usable.

+ Use the latest release or main branch to build from source.
- Do not use the "dev" branch. It may not work properly.

Future Plans

Support the Project

Similar Projects

(click to expand)

Additional comparison material:

(back to top)