trice

Trice gives embedded firmware a fast logging path with a familiar source-code style:

trice("boot\n");
trice("adc=%d mV\n", adc_mV);

Instead of formatting strings on the target, Trice stores the human-readable text on the host and transfers compact binary records from the target. This reduces target FLASH usage, transfer bandwidth, log files and log-call execution time.

1. Write trice(...) calls in firmware code.
2. Run trice insert before compilation.
3. The compiler sees stable numeric IDs.
4. The target emits compact binary Trice records.
5. The PC tool decodes them with the accumulated til.json.

A typical source-level idea is:

- printf("Temperature: %d °C\n", t);
+ trice("Temperature: %d °C\n", t);

Trice assigns IDs by processing source files with trice insert. A call such as this:

trice("boot\n");

becomes similar to this before compilation:

trice(iD(12345), "boot\n");

This is intentional: the target binary contains the ID, while the host keeps the text in til.json.

You can choose how visible those IDs are in your workflow:

• keep inserted IDs in source,
• run trice clean after the build,
• use the Trice cache to avoid needless rebuilds of unchanged files.

For team projects, define this policy early and treat til.json like any other build artifact needed for field diagnostics. See Trice ID management.

• Easy Migration – reuse existing printf-style code with minimal changes via the -alias option
• Long-term field decoding – decode logs from released firmware when the matching or accumulated til.json is preserved.
• Reduced target FLASH - format strings are kept in til.json, not in the target image.
• Very low target overhead - down to a few CPU cycles in optimized configurations; see Trice Speed.
• Transport friendly - UART, RTT, TCP/UDP, files, or your own non-blocking byte writer.
• Compact transfer – a Trice record contains one 32-bit ID plus optional runtime values, reducing bandwidth and log-file size.
• Portable tooling - the host tool is written in Go and runs on common desktop platforms.
• Further features - like encryption, timestamps, flexible logging, transport options and tooling are described here.
• Fully documented: Trice User Manual

Direct mode writes each record immediately to the selected backend. Deferred mode writes first into a target buffer; TriceTransfer() sends later.

Trice has two cooperating parts:

• Target-side C/C++ macros provide a familiar printf-like interface but emit IDs and values instead of full format strings.
• The PC-side trice tool manages IDs, receives binary data, and reconstructs readable log output.

The host tool is written in Go and runs on common desktop platforms. You can also build your own receiver that reads Trice packages, maps IDs to format strings, and displays or stores the decoded output.

Keep the one accumulated til.json to decode all previously released firmware versions. The repository example file is demoTIL.json.

Keep IDs in source - good for small projects and maximum robustness.

trice insert -src ./ -i ./til.json -li ./li.json
# build normally

Insert before build, clean after build - good when the repository should stay visually free of IDs.

trice insert -src ./ -i ./til.json -li ./li.json
# build
trice clean -src ./ -i ./til.json -li ./li.json

Use the Trice cache - good when repeated insert/clean would otherwise cause unnecessary recompilation.

mkdir -p ~/.trice/cache
trice insert -cache -src ./ -i ./til.json -li ./li.json
# build
trice clean -cache -src ./ -i ./til.json -li ./li.json

Pick one workflow and document it in the project build instructions. If other tools also rewrite source files, such as formatters or code generators, run them before trice insert.

The Trice cache avoids unnecessary rebuilds when using trice insert and trice clean around the build. It keeps cached inserted and cleaned copies of unchanged files.

Typical use:

mkdir -p ~/.trice/cache
trice insert -cache -src ./ -i ./til.json -li ./li.json
# build
trice clean -cache -src ./ -i ./til.json -li ./li.json

Use cache when you want to keep IDs out of your source code while avoiding repeated recompilation of unchanged files. Be careful when your build system also modifies source files; for example, run auto-formatters before trice insert.

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.

See Trice Cache for Compilation Speed.

1. Add the Trice target sources from src/ to your firmware project.
2. Add a project-specific triceConfig.h.
3. Write Trice calls in your code.
4. Run trice insert before compiling. This assigns stable IDs and updates til.json and li.json.
5. Build and flash the target.
6. Run trice log on the PC to decode the binary stream.

Minimal firmware shape:

#include "trice.h"

int main(void) {
    BoardInit();
    TriceInit();

    trice("boot\n");
    trice("adc=%d mV\n", adc_mV);

    for (;;) {
        AppRun();
        TriceTransfer(); // needed for deferred outputs
    }
}

Create the ID files once, then insert IDs:

touch til.json li.json
trice insert -src ./ -i ./til.json -li ./li.json

Start logging from a serial or USB-VCOM port:

trice log -p COM15 -baud 921600 -i ./til.json -li ./li.json
# or, on Linux/macOS:
trice log -p /dev/ttyACM0 -baud 921600 -i ./til.json -li ./li.json

Existing projects do not have to migrate all logs at once. Best strategy:

Use Trice aliases so project-specific log macros are processed by trice insert without renaming every call site.

See Legacy User Code Option Trice Aliases Adaptation.

Alternatively:

1. Keep legacy printf output and send Trice on a separate physical channel.
2. Replace selected printf calls with Trice calls where speed, bandwidth, or FLASH matters.
3. Use triceS macros to emit runtime generated printf strings.
4. Shared the output channel with typeX0 User Packets.

For a first integration, prefer a small vertical slice:

• one source file,
• one working output path,
• one til.json,
• one build pre-step,
• one host trice log command.

Then expand to aliases and larger source trees. See Trice and legacy User Code.

A practical rule:

• Start with deferred auxiliary 8-bit output when your project already has a write function.
• Start with direct SEGGER RTT when you have J-Link and want the easiest lab setup.
• Use deferred ring buffer for a balanced RAM/speed setup.
• Use deferred double buffer when minimizing the target-side log-call cost is more important than RAM.

A slow physical output path, especially a blocking UART, can dominate direct-mode timing. Deferred mode avoids this during the log call, but you must call TriceTransfer() often enough and size buffers for burst load.

See Trice Speed and Trice memory needs.

Auxiliary hooks are useful when the project already owns the physical transport. They can write Trice binary data to an SD card, flash partition, UART/USB queue, socket, pipe, file, or other byte sink.

The deferred 8-bit hook is usually the safest first quickstart because almost every transport can consume bytes. See Writing the Trice logs into an SD-card or a user-specific output.

Implemented transfer methods include:

• UART, including virtual UART over USB,
• RTT, including J-Link and ST-Link related paths,
• TCP4 input/output,
• UDP4 input.

Other possible transport approaches include a small bridge microcontroller or FTDI-style adapters for GPIO, I2C, SPI, CAN, LIN, UART, FIFO, or file-based capture. Start with a supported path first; optimize transport later.

trice ds can act as a display server. Multiple trice log instances can send completed log lines to one display server so several targets appear in one combined output.

trice ds
trice log -p COM15 -ds
trice log -p COM16 -ds

See Logging Over a Display Server and Several Targets at the same time.

Replacing format strings with IDs at compile time acts like compression for target FLASH and transferred log data. A typical Trice record can be only a few bytes plus parameters, independent of the human-readable format-string length.

See also:

• Small Size - using Trice frees FLASH Memory
• Minimal Transfer Bytes Amount
• Trice Memory Needs

Trice can be used as a fast printf-debugging replacement and as a compact logging system for field diagnostics. The target emits short binary records; the host produces the readable log later.

Keep the newest accumulated til.json so logs from any field devices (also older versions) can be decoded after release. Optionally store project-specific til.json and li.json together with firmware images or diagnostic packages.

Trice binary logs can be written to FLASH, SD-card, a file, or another project-specific output for later analysis. This can be useful when a target is not permanently connected to a PC.

See Writing the Trice logs into an SD-card or a user-specific output.

Trice supports optional XTEA encryption for transport packets. This can be useful when field logs should only be readable with the matching key and ID list.

Enable encryption in triceConfig.h and pass the matching password/key option to trice log. See Optional XTEA encryption.

Because the target sends IDs and values, the host-side til.json can map an ID to different text as long as the ID and parameter format remain compatible. This allows host-side wording changes or language variants without changing the target binary.

See Switch the language without changing a bit inside the target code.

Trice supports host and target timestamps and can help with distributed timing analysis, interrupt timing, and observing target behavior without stopping firmware in a debugger.

See Trice Timestamps (Formatting and Delta Columns).

Trice ABC extends the normal Trice idea from logging to compact command records.

A sender emits a normal Trice record, for example:

trice8C("cmd:setLeds", &mask, 1);

After trice insert, the command name is represented by a numeric ID in til.json. With trice generate -abc, receiver-side dispatch tables are generated so each receiver can select which command IDs become local handler calls.

ABC is intentionally not a full RPC layer by itself. Addressing, ACKs, retries, authentication, timeouts, and return-value semantics remain application policy.

See Trice ABC in the User Manual and the host-native ABC demo.

This simplified draw.io diagram shows how Trice works over a UART-style path. Read the detailed explanation in How it works - the main idea.

Trice can route different ID ranges or tagged messages to different outputs depending on configuration. See the User Manual for the current configuration details and examples.

The Trice buffer macros allow to transfer any data. But with typeX0 User Packets the user can also inject own counted buffers in the Trice data stream. The Trice tool will optionally display them as raw bytes using a "%02x" format and could get an extension to forward those packages in any possible direction.

Use one of these options:

# macOS with Homebrew
brew install rokath/tap/trice

Or download a release binary from the latest release and put trice into your PATH.

Developers with Go installed can also build/install from source:

go install github.com/rokath/trice/cmd/trice@latest

Check the installation:

trice --version
trice help -insert
trice help -log

• Trice User Manual
• GitHub Pages documentation
• Generated CLI help
• Target source configuration defaults
• Examples
• Issues, including closed items
• Discussions, including closed items

The example projects show Trice integration with VS Code, Makefiles, Clang/GCC, STM32 projects, RTT, and UART-style output. Use bare/instrumented project pairs to inspect the minimal integration diff.

Debug a Trice project in Direct-Out Mode over SEGGER-RTT.

See Development Environment Setup.

Trice is usable today and actively maintained. Use the latest release or the main branch when building from source. Avoid development branches unless you intentionally want unreleased work.

Contributions are welcome: examples, platform recipes, transport backends, documentation improvements, and reproducible benchmark reports are especially valuable.

Potential future work includes:

• a small tlog tool in C, Python, Rust, TinyGo, Wasm, or another runtime for environments where Go is not the best fit,
• more structured logging support; see the structured logging specification draft,
• additional transport recipes,
• adaptation for a visual RTOS/event timeline tool.

• Star this project if it helps you.
• Contribute examples, fixes, documentation, or platform recipes.
• If Trice helps a commercial product, consider supporting continued maintenance through the sponsor links on the GitHub project page.

Support options:

• Become a Sponsor with your GitHub account
• 
• 

Trice overlaps with several logging, tracing, and tokenization approaches, but it targets a specific niche: compact printf-like logging for embedded C/C++ with host-side ID decoding.

• plain printf / UART logging
• ARM ITM/SWO (hardware-native)
• ARM Keil Event Recorder (hardware-native)
• baical.net (C)
• call stack logger function instrumentation (trace program execution flow)
• Debugging with Dynamic Printf Breakpoints (Eclipse IDE option)
• defmt (Rust)
• Diagnostic Log and Trace (AUTOSAR)
• Embedded Logger (elog) (Embedded logger with minimal footprint and memory usage)
• Logging with symbols - The Embedonomicon
• McuLog (McuOnEclipse)
• MCUViewer
• Memfault Compact Log Library (part of firmware SDK)
• Minimal Structured Logging for Autonomous Vehicles (C++, closed source talk)
• NanoLog (C++11) (Linux C++)
• Percepio Tracealyzer (with TraceRecorder) (Visual Trace Diagnostics)
• Pigweed Trace Tokenized
• Postform (Postponed formatting experiments with string interning in C++, inspired by the defmt Rust crate)
• qpspy (C/C++)
• Real-time binary data logging/tracing toolkit
• SEGGER RTT
• SEGGER System View
• Serial-Studio (Data visualisation)
• Tonbandgerät (Small embedded systems tracer with support for bare-metal and FreeRTOS-based targets)
• Traces (API tracing framework for Linux C/C++ applications)
• uLog (RD Poor)
• Zephyr Dictionary Based Logging
• project-specific binary loggers.

Additional generated comparison material:

• Trice Compare (generated 2025-05-26) - compact generated comparison with related tools
• Logging & Tracing Solutions for Embedded Systems (generated 2026-02-16) - longer generated overview of the broader tool landscape