trice

README

trice - TRace Ids C Embedded (printf() - replacement)

embedded device C printf-like trace code and real-time PC logging (trace ID visualization) over serial port

Info shields

Link shields

Search counters

About

• C trace code (TRICE macros) and real-time PC logging with trice (tool written in Go).
• Communication without string transfer, just with IDs. Prerequisite: byte transmission to PC, low bandwidth is ok:
  • method does'nt matter: serial port, i2c, spi, DAC->ADC, toggle pin, ...
• "log in (a) trice"
• Main idea: Logging strings not into an embedded device to display them later on a PC but keep usage comfortable and simple. The TRICE macros look like printf() but work under the hood completely different.

TRICE macros for C|C++ code

• Real fast (~16 CPU clocks per trace!!!) and small loggging technique, a tracer in software usable
  • for debugging dynamic behaviour during development,
  • as runtime logger or simply for narrow bandwidth logging in the field even with encryption.
• Usage is similar to 'printf()', but the format strings go not into the target image.
• The needed code instrumentation is minimal:
  • Adapt a config file (hardware specific).
  • Add one small C-file to your project and include a C-header where trices are used.
  • Core instrumentation needs less 150 bytes FLASH and about 100 bytes RAM.

trice PC tool

• Manages TRICE macro IDs inside a C|C++ source tree and extracts the strings in an ID-string list during target device compile time.
• Displays TRICE macros like printf() output in realtime during target device runtime. The received IDs and parameters are printed out.
• Written in Go, simply usage, no installer.

Quick setup

• add trice.c as is to your project
• #include trice.h as is in your source file to use trice
• copy proj_config.h, rename to config.h and adapt to your needs
• triceCheck.c is example code and for testing
• run trice u in root of your C|Cpp source project after code instrumentation with TRICE* statements to generate a project specific til.json file
• compile, flash & run trice log -port COMm -baud n with correct values m and n

Possible Use Cases

• Using trice not only for dynamic debugging but also as logging technique is possible and gives the advantage to have very short messages (no strings) for transmission, but keep in mind that the file til.json is the key to read all output if your devices in the field for 10 or more years.
• You can consider TRICE also as a kind of intelligent data compression what could be interesting for IoT things, especially NB-IoT, where you have very low data rates.
• Also it is possible to encrypt the 8 byte transfer packets to get a reasonable protection for many cases.
  • This way you can deliver firmware images with encrypted TRICE output only readable with the appropriate key and til.json.
  • XTEA is a recommendation and implemented as option.
• You can even translate the til.json in different languages, so changing a language is just changing the til.json file.
• trice has intentionally no timestamps for performance reasons. But you can add own timestamps as parameters. Having several devices with trice timestamps, network timing measurements are possible.
• Using trice with an RTOS gives the option for detailed task timing analysis. Because of the very short execution time of a trice you could add TRICE16( Id(0), "tim:%d us, task=%d\n", us, nexTask ); to the scheduler and vizualize the output on PC. The same is possible for interrupt timing analysis.
• TRICE16( "%d us\n", sysTick ); before and after a function call lets you easy measure the function execution time.
• As graphical vizualisation you could use a tool similar to https://github.com/sqshq/sampler.

Documentation

• see ./doc/ReadMe.md