Trice Guide for Orientation

New to Trice? Follow the User Manual from your first PC log to your own firmware. The first experiments need no board.

Already using Trice? Jump to a task under 2. Entry Points. The manuals contain the explanations; this guide helps you find them.

Table of Contents

1. Document Overview

Document Content
trice/README.md Project Entry
trice/docs/TriceUserManual.md From your first PC log to your own firmware. The first experiments need no board.
trice/docs/rm/README.md The complete technical reference
trice/docs/TriceGuide.md This file
trice/docs/ref/trice-help-all.txt - CLI help output CLI help snapshot; run trice help -all for your installed tool
trice/src/triceDefaultConfig.h - Source Code Target configuration switches explained and their default values
trice/_test/testdata/triceCheck.c - Test Code Extensive executable Trice test inputs; not a beginner tutorial
trice/docs/ref/ - included material documentation images and CLI-help data
trice/docs/_scratchPad/ Internal plans, drafts and historical material - no prerequisites for using Trice.
trice/CHANGELOG.md Release history
trice/CONTRIBUTING.md Contribution and validation guidance

2. Entry Points

2.1. Integration

What you need Where to look
A guided start with runnable examples User Manual, from installation through fields, filters and context to target integration
Setup, syntax, configuration and limits Reference Manual, the complete technical reference
Printf-like calls and their differences Trice and printf, including floating-point values and extended formatting
An example to build and modify Central example guide, with links to the executable projects
Command-line options CLI help snapshot; run trice help -all for your installed tool
Target configuration defaults triceDefaultConfig.h, explained in the Reference Manual
An existing byte writer, RTT, or UART Quickstarts
Use trice bind Trice Bind, build integration, and bind-limits
Trice ID management with insert and clean ID management and Insert algorithm and workflow
Which dictionaries and generated files to keep Files to keep, dictionary compatibility, and Bind artifact report
Local text output without a host decoder Local deferred text log and local logging examples; requires target-side formatting and a generated dictionary
Generate supporting files Trice Generate: local C format tables, readable JSON views, and artifact reports
Avoid unnecessary recompilation Trice Cache

2.2. Log output and analysis

What you need Where to look
Log levels Tag weights and selecting tags and priority; these filters operate on the host
Tag colors and aliases Trice tags and colors and user-defined tags
Select or exclude individual tags Selecting tags and priority (-pick, -ban)
Tag-specific routing on the target ID Routing; ID assignment and output-channel configuration are separate steps
Structured fields in JSON or KV Structured Logging; JSON output is NDJSON, one event per line
Context Enrichment Context Enrichment and supported log sites and alternatives
Runtime strings or buffers triceS strings, triceN counted strings, and triceB buffers
Timing analysis Target stamps and delta columns; stamp units and meaning are application-defined
Source-file and line information Location information
Event counts Event statistics
Graphical visualization Visualization output and LabPlot demo
Record decoded text or raw bytes Logfile output and binary logfile
Integrating multiple targets Several targets at the same time

2.3. Target behavior and transport

What you need Where to look
Minimize log-call execution time Trice Speed; compare direct and deferred modes and their RAM needs
Logging from interrupts or multiple tasks Critical sections and Trice checks
Work without heap allocation No dynamic memory management in the target logging path
Reduce target image size Memory needs and image size optimization; some measurements describe older versions
Reduce transferred bytes Minimal transfer bytes, parameter bit widths, and framing
Understand binary records Binary encoding, including record layout and COBS/TCOBS framing
SEGGER RTT RTT quickstart and Trice over RTT
SD-card or custom output writer SD-card and user-specific output
Big-endian targets Endianness
User protocol packets in the log stream typeX0 user packets
Encryption Optional XTEA encryption
Buffer protection and overflow diagnostics Trice Protection and avoiding buffer overruns
Disable logging at compile time Switching Trice on and off
Remote commands with Trice ABC Asynchronous Broadcast Commands, including what ABC is not
Stimulate the target from the host User commands over UART; application code interprets the received command
Adapt existing logging and assert macros Legacy aliases and alias example; the assert test configuration demonstrates application-specific assert integration

2.4. Troubleshooting and contributions

What you need Where to look
Missing or incorrect log output User Manual troubleshooting and Reference Manual troubleshooting
Bind-specific errors Bind diagnostics
Release changes or contributing CHANGELOG and CONTRIBUTING
Run tests or add test cases Testing the target library
Questions and bug reports Community and contributions

2.5. Project resources

What you need Where to look
Downloads and installation Get Trice: released host tools, source builds, and version compatibility
Compare approaches Alternative projects for logging, tracing, and visualization
Support the project Support and sponsoring, including GitHub Sponsors, Buy Me a Coffee, and PayPal
Licensing MIT License

The User Manual is the short learning path; the Reference Manual contains the full contracts and detailed example instructions. Example READMEs link to the central manuals so each example has one maintained explanation.

3. Project Folder Structure

Start with demo to see a first log, examples/PC_features to experiment, or src to integrate the target library. Most firmware users do not need to explore the host implementation or repository maintenance files.

3.1. Sources, examples, and documentation

Folder Purpose and useful entry point
src The target C library. Include trice.h and provide a project-specific triceConfig.h; firmware integration shows the steps. triceDefaultConfig.h documents the defaults.
src/default_conf Fallback RTT configuration. Search this directory last, after project/generated headers and src, so your own SEGGER_RTT_Conf.h takes precedence. See Trice over RTT.
demo Minimal direct and deferred PC demos. Start with the first-log walkthrough.
examples PC and STM32 applications, plus shared example producers in exampleData. Choose a project through the central example guide; board projects can include their own vendor code.
docs This Guide, the short User Manual, and the detailed Reference Manual. ref holds images and the CLI-help snapshot.
cmd Go entry points for trice, the tlog logging shortcut, and developer utilities. Use buildTriceTool.sh to build the host tools.
internal Host-tool implementation: argument handling, ID workflows, receiving, decoding, and output. Relevant Go tests live beside the code.
pkg Supporting Go packages, including cipher, message, and test helpers. Target firmware integrates src, not these host packages.
_test C target configurations, test harnesses, and shared cases such as testdata/triceCheck.c. See testing the target library.
scripts Host-tool builds, formatting, validation, and release helpers. testAll.sh runs the repository checks; CONTRIBUTING explains development workflows.
third_party Retained external packages and tool archives. Their licenses and setup requirements are separate; see third-party packages and retained versions.

3.2. Repository configuration and history

Location Purpose
.github CI, release, and documentation workflows, issue templates, and funding configuration. See the workflow reference.
.vscode and .idea Optional VS Code and GoLand project settings; not target-library dependencies.
.code_snippets Retained legacy helper snippets; not the recommended integration path.
docs/_scratchPad Internal plans and drafts. Its obsolete subtree is archived history, not current usage guidance or a build prerequisite.
experiments/ Experimental or local working material, if present. Use the documented examples for supported entry points.
go.mod and go.sum Go version, module requirements, and dependency checksums for the host tools.
Root metadata Release notes, licenses, contribution guidance, formatter/linter settings, and publishing configuration. The Reference Manual lists individual files.

3.3. Generated and local files

These directories may appear after building or testing; they are not additional source libraries to integrate.

Location Typical contents and handling
generated/ Default -genDir output: Bind sidecars, the structured-field registry, optional one-line JSON views, and generated C tables. Bind projects add it to the compiler include path. See persistent and generated files.
build/ or example-specific output folders Compiler output. The example’s build script determines the path.
dist/ Local GoReleaser archives and release artifacts.
temp/ Local recordings, test logs, and recovery snapshots. Failure details from testAll.sh are under temp/log.
.gocache/, coverage.out, and other local tool outputs Build/test caches and coverage results; not firmware inputs.

til.json maps IDs to messages; li.json connects IDs to source positions and helps ID processing reuse existing assignments, including identical messages at different sites. Keep the local LI between builds even when logging without source locations: trice log -li off disables location output without disabling LI use during bind or insert.

The root demoTIL.json serves repository examples and tests. Their build and ID-workflow scripts initialize a missing demoLI.json or project-local li.json and regenerate it; these active demo location tables are ignored by Git. The historical test fixture remains versioned. Your application should use its own files. Preserve dictionaries and matching location tables needed for released firmware and recordings. Generated sidecars can also contain historical ID bindings, so do not assume every file in generated can be deleted without reviewing its role. See which files to keep and the read-only Bind artifact report.