trice

README

Trice <- TRace Ids C Embedded

github.io/trice/

"log in (a) trice" (S>G)

About

• The aim is to replace printf in any microcontroller code for getting:
  • SPEED, to be usable also inside interrupts
  • SPACE, to reduce FLASH memory size
  • COLOR, to improve visibility
  • Compile time and/or runtime ON-OFF.
• Main idea: Logging strings not into an embedded device to display them later on a PC but keep usage comfortable and simple.
• Trice consists of 2 parts:
  1. C code TRICE macros generating tiny & super fast embedded device real-time trace/log code
  2. Tool trice for managing and visualization.
     • Written in Go and therefore usable on all platforms Go supports.
     • You can also use your own environment to receive the trice packges, exchange the carried IDs with the format string and print out.
• Usage guide

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.
  • Optionally add til.json as a (compressed) resource to your target image. One possibility is using SRecord.
• You can see trice also as a kind of data compression what could be interesting for IoT things, especially NB-IoT, where you have very low data rates.
• Storing trice messages in FLASH memory for later log analysis saves memory because a typical TRICE occupies only about 8 bytes independently of the format string length.
• Also it is possible to encrypt the trice 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 implemented as one option.
• You can even translate the til.json file in different languages, so changing a language is just changing the til.json file without touching the target binary.
• With trice it is easy to do timing analysis. Host and target timestamps are supported.

How it approximately works (UART example)

This is a slightly simplified view:

• When the program flow passes the line TRICE( Id(12345), "msg: %d Kelvin\n", k ); two or three 32-bit values transferred into the trice buffer:
  1. Optional embedded device timestamp: You can decide about the time base.
  2. Combined: the 16-bit ID, the 32-bit values count as 8-bit value and an 8-bit cycle counter.
  3. The 32 bit value. The total data payload per trice can be 1008 bytes (252 32-bit units).
• The few values, written inside a typical TRICE macro, allow its usage inside time critical code like scheduler or interrupt.
  • If target timestamps disabled and no data values carried, a TRICE macro writes just one 32-bit value to the trice buffer.
• In direct mode the trice buffer is on the stack and the TRICE macro execution includes the COBS encoding and the data transfer. This more straightforward architecture (not shown here) forbids usage inside time critical code but can be interesting for many cases.
• In indirect mode for output a background service is needed. About every 100ms (configurable):
  • The trice double buffer is swapped.
  • A 32-bit buffer mode value is prefixed:
  • Optionally buffer mode and the trice buffer can get encrypted at his stage (not shown here).
  • The COBS encoding takes part.
  • The out buffer is filled and the UART interrupt is triggered to start the transmission.
    • Out buffer and half trice buffer share the same memory.
• During runtime the PC trice tool receives the triceBuffer (all what happened in the last 100ms) as a COBS package from the UART port.
  • After COBS decoding, an optional decryption takes part (trice tool command line switch)
  • The very first 32-bit value is the buffer mode, expected to be 0 or 1. Otherwise the trice tool will ignore the package.
• The 0x30 0x39 is the ID 12345 and a map lookup delivers the format string "msg: %d Kelvin\n" and also the format information "TRICE", which is needed for the parameter bit width information (usually 32 bit).
• Now the trice tool can:
  • Write host timestamp
  • Write prefix
  • Write target timestamp
  • Set msg color
  • Execute printf("%d Kelvin\n", 0x0000000e);

Data Transfer

• Inplemented:
  • UART or virtual UART over USB
  • RTT over J-Link
  • RTT over ST-Link
• A small separate micro controller is always usable as bridge to interfaces like: GPIO, I²C, SPI, CAN, LIN, ...

Display server option?

Yes, you can simply start trice ds inside a console, option: third_party/alacritty, locally or on a remote PC and connect with several trice tool instances like with trice log -p COM15 -ds for example.

Documentation is partially obsolete and will be updated soon (in December 2021)

No need to read all this stuff - is is just for help and reference.

• fix color issues under windows
• Command Line Examples
• Common.md
• TriceEncodings.md
• ID management
• OneWireOption
• SeggerRTT

Support?

• Yes please: May be
  • a port to other hardware
  • some correction
  • a cool idea
  • or simply like to ⭐ it. ☺
• Cloning the repo:

git clone https://github.com/rokath/trice.git

• Edit, test, commit, push & pull request

Similar projects

Maybe you find this project interesting too: baical.net