Quickstarts

Contents

1. Quickstart: Existing non-blocking byte writer, deferred auxiliary 8-bit

Use this path when your project already has a tested output function, for example:

This is often the most universal first integration because Trice does not need to know your peripheral driver. It only needs a function that accepts a byte buffer and length.

1.1. Add Trice target sources

Add the complete src folder to your target project unchanged, including its default_conf subdirectory. Search project and generated header directories first, followed by src and finally src/default_conf, for example -Iproject -Igenerated -Isrc -Isrc/default_conf. Create a project-specific triceConfig.h in your application include path.

1.2. Configure deferred auxiliary 8-bit output

Minimal triceConfig.h starting point:

#ifndef TRICE_CONFIG_H_
#define TRICE_CONFIG_H_

#define TRICE_DEFERRED_OUTPUT 1
#define TRICE_BUFFER TRICE_RING_BUFFER
#define TRICE_DEFERRED_AUXILIARY8 1

/* Adapt these to your target if Trice can run from interrupts or multiple contexts. */
#define TRICE_ENTER_CRITICAL_SECTION {
#define TRICE_LEAVE_CRITICAL_SECTION }

#endif /* TRICE_CONFIG_H_ */

Notes:

1.3. Assign your writer function

Example:

#include "trice.h"

static void MyNonBlockingByteWrite(const uint8_t* data, size_t len) {
    /* Replace this with your project's existing writer. */
    ExistingTxQueueWrite(data, len);
}

void AppInit(void) {
    BoardInit();
    TriceInit(); // normally only needed when SEGGER_RTT is used. Otherwise it is an empty function.

    UserNonBlockingDeferredWrite8AuxiliaryFn = MyNonBlockingByteWrite;

    trice("boot\n");
}

void AppMainLoop(void) {
    for (;;) {
        AppRun();
        TriceTransfer();
    }
}

TriceTransfer() moves accumulated Trice records from the deferred buffer to your writer. Call it cyclically from the main loop, a low-priority task, or another context that is safe for your output driver.

1.4. Insert IDs before compiling

From your project root:

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

Then build and flash your target.

1.5. Decode on the PC

For a serial or USB virtual COM port:

trice log -p COM15 -baud 921600 -i ./til.json -li ./li.json

On Linux/macOS, adapt the port:

trice log -p /dev/ttyACM0 -baud 921600 -i ./til.json -li ./li.json

If your writer produces a file, pipe, TCP stream, or another source, use the matching trice log -p ... input port.

1.6. Common first checks

1.7. Why this quickstart matters

The old README led many first-time readers toward SEGGER RTT because it is convenient and fast. That path is still valuable, but it also implies J-Link hardware and SEGGER tooling. The auxiliary writer path is more portable: many projects already have a byte-stream output, and Trice can reuse it.

Use this path when you have a SEGGER J-Link and want the smallest amount of target-specific transport code. See Convert Evaluation Board onboard ST-Link to J-Link for a cheap option.

2.1. Install tools

2.2. Add target sources

Add the complete src folder to your target project unchanged, including its default_conf subdirectory. Search project and generated header directories first, followed by src and finally src/default_conf, for example -Iproject -Igenerated -Isrc -Isrc/default_conf.

2.3. Configure direct RTT

Minimal triceConfig.h:

#ifndef TRICE_CONFIG_H_
#define TRICE_CONFIG_H_

#define TRICE_DIRECT_OUTPUT 1
#define TRICE_BUFFER TRICE_STACK_BUFFER
#define TRICE_DIRECT_SEGGER_RTT_32BIT_WRITE 1

#endif /* TRICE_CONFIG_H_ */

2.4. Add a first Trice call

#include "trice.h"

int main(void) {
    BoardInit();
    TriceInit(); // normally only needed when SEGGER_RTT is used. Otherwise it is an empty function.

    trice("Hello RTT\n");

    for (;;) {
        AppRun();
    }
}

Direct RTT does not require TriceTransfer() for the normal direct output path.

2.5. Insert, build, flash

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

Build and flash the target.

Example command; adapt the device name and speed:

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

Alternative file-based workflow:

rm -f ./temp/trice.bin
mkdir -p ./temp
touch ./temp/trice.bin
JLinkRTTLogger -Device STM32G0B1RE -If SWD -Speed 4000 -RTTChannel 0 ./temp/trice.bin

In a second terminal:

trice log -p FILE -args ./temp/trice.bin \
  -pf none -prefix off -hs off -d16 \
  -i ./til.json -li ./li.json

2.7. When this path is ideal

Direct RTT is excellent for lab development because the target writes to RTT memory and the probe drains it. It avoids UART setup and usually feels close to printf debugging.

2.8. When this path is not ideal

It depends on J-Link/RTT infrastructure. If that hardware or closed host tooling is a blocker, start with the Quickstart: Existing non-blocking byte writer, deferred auxiliary 8-bit or a UART/VCOM deferred path.

3. Quickstart: UART or USB-VCOM deferred output

See also Communication Ports, the example projects, and the UART-related configuration examples. This section is intentionally short because UART setup is MCU/vendor-specific.

Use this path when the target has a UART, USB CDC/VCOM, or board-specific serial path and you want Trice to use the built-in UART backend rather than an auxiliary writer.

Minimal shape of triceConfig.h:

#ifndef TRICE_CONFIG_H_
#define TRICE_CONFIG_H_

#include "main.h" /* or your MCU/vendor header */

#define TRICE_DEFERRED_OUTPUT 1
#define TRICE_BUFFER TRICE_RING_BUFFER
#define TRICE_DEFERRED_UARTA 1
#define TRICE_UARTA USART2 /* adapt to your project */

#endif /* TRICE_CONFIG_H_ */

Application shape:

#include "trice.h"

int main(void) {
    BoardInit();
    UartInit();
    TriceInit(); // normally only needed when SEGGER_RTT is used. Otherwise it is an empty function.

    trice("boot\n");

    for (;;) {
        AppRun();
        TriceTransfer();
    }
}

Host side:

trice log -p COM15 -baud 921600 -i ./til.json -li ./li.json

On Linux/macOS:

trice log -p /dev/ttyACM0 -baud 921600 -i ./til.json -li ./li.json

For a quick first success, the Quickstart: Existing non-blocking byte writer, deferred auxiliary 8-bit may be easier if your project already has a working serial or USB write function.

(back to top)