Logging with TI SimpleLink SDK#

Introduction#

Logging is the act of producing an append-only sequence of records that contain information about the state or variables of a program. Logging is a useful debugging tool. This SimpleLink Academy aims to explain the SimpleLink Log driver and how to use it.

In this lab we will go through the process of setting up the Log example, along with all the tools necessary to read the logs. In the bonus tasks, you can find information on adding logging to other examples.

Task 1: Simple logging output with the TI logger and UART

Task 2: Log display with UART and Wireshark

Task 3: Save log to file and replay from file

Bonus Task: Adding logging to an RF driver example and learn how to see log statements from instrumented TI drivers

Useful Links#

Prerequisites#

This SimpleLink Academy lab assumes you have some knowledge of embedded programming and working with the SimpleLink SDK.

Software#

SIMPLELINK-LOWPOWER-F3-SDK
Code Composer Studio You can find supported CCS versions in the SimpleLink™ Low Power F3 SDK Release Notes.
Python (specific version requirement, see Task 1)
(Optional) Wireshark 3.4.x or newer

Hardware#

1 x CC23xx LaunchPad
1 x XDS110ET LaunchPad Debugger

TI Logger Ecosystem#

The TI logger is a tool to get useful debug information from the various software components running on the embedded device. Architecturally, the system has three components:

Log modules are embedded software components that produce log statements.
Log sink is the transport method for the log statements to a readable output.
Data stream capturer, decoder and visualizer are tools that visualize the log.

../../_images/architecture.png — Logger System Architecture#

Within this ecosystem there are several options. You can see a full overview in the figure below.

../../_images/log_paths.png — Logger System Alternatives#

Log Modules#

When adding log statements to the target software, it is recommended to create a logging module for each software component. This way it’s easy to filter the log statements. Each log module can produce log statements and send them to a log sink.

Several of the software components in the SimpleLink SDK already have logging enabled:

The Power driver (LogModule_Power)
The UART2 driver (LogModule_UART2)

You can also add your own application log module.

Log Sink#

The log sink transports the log statement from the embedded device to where you want to read it. The CC23xx uses the LogSinkUART to use the UART to transport the log. You must have an available UART.

tilogger#

This tool receives the log stream and formats it for the visualizer. All log statements are saved in the elf file (.out file), but not on the device. This means the TI Log driver is very lean, only 40 bytes per log statement. However it means we need a tool to assemble the log statements to a human readable format. This is handled by the tilogger.

Log Visualizer#

The following tools are available to view the log:

Wireshark - Well known tool for visualizing logs, packets etc. Has endless options for filtering. Only supported on Windows. (Wireshark + LogSinkUART is not supported on Linux)
tilogger - The tilogger tool can use the stdoutput format to display logs. Simple tool with both Windows and Linux support.

Log Level#

Each log statement is printed with an attached log level. You can configure which log levels you want to subscribe to in the Log Sink configuration view in SysConfig.

The following levels are defined:

Log_DEBUG: This level is recommended for application level for debugging. (In general, SDK components will not use this level.)
Log_VERBOSE: This level is recommended to be used in libraries for verbose information (long statements or statements that appear frequently).
Log_INFO: This level is recommended to be used in libraries for simple information.
Log_WARNING: This level is recommended to be used in libraries for warnings, typically indicates something unexpected, but not something that leads to system failure.
Log_ERROR: This level is recommended to be used in libraries for errors. Typically, this should be used when something has failed and the system is unable to continue correct operation.
Log_ALL: This enables all levels.
Log_ENABLED: This is used to enable or disable the log module, independently of the log levels.

Task 1: Simple Logging Output With TI Logger#

In this task we will install the necessary tools, run the Log application project and view the output with TI logger.

Install Python#

You can install Python from this link: Python download page. You can find the required Python version in the CoreSDK release notes. (E.g. for SimpleLink F3 SDK version 9.11, use Python 3.10.12.)

Hint

It’s possible to use the tilogger with a virtual environment (venv). You can find instructions for this in the tilogger User’s Guide.

Since we’re using a global installation, we need to add Python and our Scripts folder to PATH. Open the Windows Start menu and search for Edit the system environment variables
This opens the System Properties window. Select the Advanced tab and click on Environment variables.
In the User Variables section, double-click on the entry that says Path. Press New. Enter the path for your python.exe location. Press New again. Enter the same path + \Scripts. Press Ok to save your new settings.

../../_images/python_path.png — Add Python 3.10.12 to PATHS#

On Windows, it’s necessary to log in again for this to take effect. Exit any open CMD prompts, then log out of Windows and back in.
If you have several versions of Python installed, you can control which one is used with the py launcher. Open a cmd prompt.
Enter “py -0p” to get a list of your installed Python versions.

Enter just “py” to see which version is the default with the “py” command.

PS C:\> py -0p
Installed Pythons found by C:\Windows\py.exe Launcher for Windows
-3.10-64       C:\Users\XXXXXXXX\AppData\Local\Programs\Python\Python310\python.exe *

PS C:\> py
Python 3.10.12 
Type "help", "copyright", "credits" or "license" for more information.
>>>

If Python 3.10 is not your default, use py -3.10 to make sure you’re invoking this version.

Install the tilogger command line tool.#

We’ll use py launcher to make sure we’re using the correct Python version.

Open a cmd prompt
Navigate to <SDK_INSTALL_DIR>/tools/log/tiutils/
Call the following command. (If you are behind a proxy you will need to add --proxy yourproxy.com after install in the pip calls below)
```
# Install the tilogger tool
py -3.10 -m pip install [--proxy yourproxy.com] -r requirements.txt
```

Import the Log example to your IDE#

The Log project outputs log statements over all three log sinks. In the instructions below, CCS is used.

Select File -> Import Project.

Browse to your LaunchPad/EM folder, Drivers and select the version of the Log project you want to use. (e.g. TI Clang compiler, FreeRTOS version)

# General file path structure
/simplelink_lowpower_f3_sdk_<sdk-version>/examples/rtos/<LaunchPad-version>/drivers/log

# File path for this example
/simplelink_lowpower_f3_sdk_9_10_00_83/examples/rtos/LP_EM_CC2340R5/drivers/log

Make sure your LaunchPad is connected with a debugger to your PC.
Press the Debug button (or F5) to flash your device and start a debug session.
If you are prompted to update the Debug FW, go ahead with the FW upgrade.
Press the red square to stop the debug session. When the Log example is running, the red LED is on.

../../_images/stop_session.png — Stop the debug session#

Locate your elf file#

When you have built the Log example, the elf file is found in the Debug folder. It has the ending .out. If you right-click on this file you have the option to “Copy Path”.

../../_images/elf_file.png — Elf file location in the output folder.#

Find your device COM port#

On Windows, open the Device Manager tool. We are looking for the COM port of the XDS110. For UART output, we will use the “Class Application/User UART” port.

../../_images/com_port.png — Windows Device Manager. UART port is COM6.#

Start tilogger#

We will now start the tilogger log extraction process. These processes need to be started in a particular order:

Open or reuse your cmd terminal window. Navigate to <SDK_INSTALL_DIR>/tools/log/tiutils/
Run the tilogger command. We will use the UART log sink and output to stdout. Remember to replace the COM port number with the number you found in step 7. (The “Class Application/User UART” port, in this case COM6.)
```
tilogger uart --elf C:\Users\XXXXXXXX\workspace_ccstheia\log_LP_EM_CC2340R5_freertos_ticlang\Debug\log_LP_EM_CC2340R5_freertos_ticlang.out COM6 3000000 stdout
```
Immediately restart the device by pressing the reset button on the XDS110 part of the board.
You will now start getting log statements in the command window. Note that the tenth log statement in the below window has a different log level than the rest, as well as a different message. This log statement was generated by pressing the reset button on the XDS110

../../_images/uart_log.png — Log statements#

Hint

The most up to date documentation about the options and commands is available by running tilogger --help.

Let’s take a look at what the log is actually telling us!

Since we’re using the stdout output, we can use the --help command to see which fields can be transmitted.

$ tilogger stdout --help

Usage: tilogger stdout [OPTIONS]

Add log output as standard output stream.

If custom format is wanted, use --format "<FORMAT_SPEC>" with desired format specifiers.
Supported Specifiers
{I}: Identifier (for example COM7, or the provided alias)
{T}: Timestamp
{M}: Module  (for example LogMod_App1)
{L}: Log level (for example Log_INFO)
{F}: File and line number (for example path/log.c:134)
{D}: Log data

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────╮
│ --format                    -f      TEXT  [default: "{I} | {T} | {M} | {L} | {F} | {D}"]            │
│ --disable-column-alignment                Disable dynamic column alignment                          │
│ --help                                    Show this message and exit.                               │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯

The identifier is the COM port we gave it (COM6).
The timestamp is generated by the device (it indicates when the log statement was sent, not the time it was received by tilogger).
The module refers to which log module is being called with the log statement. In our case, LogMod_LogModule_App2 refers to the UART module. (You can find all the modules implemented in the Log example in the Log example readme file.)
The log level is Log_VERBOSE. This is appended when the log statements are sent. You can read about the different log levels in TI Log driver API description.
The file and line number indicate that the log statement is sent from log.c, line 130.
The log data is appended with the log statement and can contain up to eight arguments. In this case it’s just a string.

Opening log.c, line 130 in the application project we can see the following:

Log_printf(LogModule_App2, Log_VERBOSE, "log_clkFxn: post semaphore");

Hint

Yay! We have our first log!

Task 2: Log Display with UART and Wireshark#

In this task we will use the UART log sink, and look at the output in Wireshark. If you don’t already have Wireshark installed, you can download it from the Wireshark website. TI logger has been tested with Wireshark 3.4.x, but it should work with later versions as well.

Configure Wireshark#

Copy <SDK_INSTALL_DIR>/tools/log/tiutils/streams/wireshark/tilog_dissector.lua to C:/Program Files /Wireshark/plugins/x.y/tilogger_dissector.lua. Where x.y is your Wireshark version.
Let’s add Wireshark to PATHS as well. This time, open Environment Variables and press the New button to create a new user path. Create a path with the name WIRESHARK_EXE_PATH and the path to your Wireshark exe file (e.g. C:\Program Files\Wireshark). Again, remember to log out of Windows and restart cmd prompt for this to take effect.

../../_images/wireshark_paths.png — Add Wireshark to PATHS.#

Run tilogger#

Open cmd prompt. Remember to replace the out file path with your own. Run the following tilogger command:

tilogger uart --elf C:\Users\XXXXXXXX\workspace_ccstheia\log_LP_EM_CC2340R5_freertos_ticlang\Debug\log_LP_EM_CC2340R5_freertos_ticlang.out COM6 3000000 wireshark --start

This command will start Wireshark.

Log statements in Wireshark.#

Since we have the log in Wireshark, we have the option to save it as a Wireshark file (.pncap). This can be useful, e.g. if you need to send the log to someone who is helping you debug an issue!

Task 3: Save a Log to a File and Replay From a Log File#

Up until this point we have streamed the logs and looked at them immediately. With the tilogger, it’s possible to save the log to a file instead. It’s also possible to use the tilogger to stream/read from a file into Wireshark.

One use for this could be a Linux user who saves the log file and sends it to a Windows user. The Windows user can then read the file into Wireshark.

Saving the Log to a File#

We will store the log in a json file. Let’s prepare an empty file. For simplicity, let’s store it in the CCS workspace. In CCS, left click on your workspace. Make a new file called replayfile.json.

When you have the Log example running on your device, open the cmd prompt. You can use the following command, just remember to replace the paths and COM port.

tilogger uart --elf C:\Users\XXXXXXXX\workspace_ccstheia\log_LP_EM_CC2340R5_freertos_ticlang\Debug\log_LP_EM_CC2340R5_freertos_ticlang.out COM6 3000000 to-replayfile –-file C:\Users\XXXXXXXX\workspace_ccstheia\log_LP_EM_CC2340R5_freertos_ticlang\replayfile.json

../../_images/logs_to_file.png — Cmd prompt when logging to file.#

After a while, you can stop tilogger by pressing Ctrl + c. You can open your json file and see the log output.

../../_images/logs_json.png — Json file with log statements.#

Reading log from file#

Let’s try using tilogger to read from our file and into Wireshark. This time the json file is the “from” replayfile.

tilogger from-replayfile C:\Users\XXXXXXXX\workspace_ccstheia\log_LP_EM_CC2340R5_freertos_ticlang\replayfile.json wireshark --start

If you use the wireshark --start arguments, this will open Wireshark and display your log. (You can of course use stdout instead.)

Bonus Task: Add Logging to an RF driver Example#

OK so we looked at the Log example. But in the real world we have our own example we want to debug with logging! In this bonus task we’ll see how to add a logging module to a prop RF example, but the steps should be transferable to any project in the SimpleLink F3 SDK.

Import your project to CCS. I will use the rfPacketTx example from the prop_rf folder.
Open the sysconfig file (rfPacketTx.syscfg). Scroll down to LOGGING.
Add a log module by pressing the + symbol next to Log Modules.

../../_images/log_syscfg_add.png — Add a Log module in SysConfig.#

Per default the log module is added with an Buffer sink. You can change this by choosing a different sink. I will choose a UART sink.

../../_images/log_syscfg_choosesink.png — Choose the log sink.#

SysConfig will automatically create a module for your log sink (in this case LogSinkUART). You can open it and configure settings such as the baud rate.
For LogSinkUART you need to manually select the UART in Use Hardware.

../../_images/log_syscfg_uart.png — LogSinkUART settings in SysConfig.#

When you have configured the log and log sink modules to your preferences, don’t forget to save the SysConfig file.
Jump over to your application source file, in this case rfPacketTx.c. The first code change is to add an include statement for Log.h at the top of the file.

    #include <ti/log/Log.h>

Let’s add the same “Hello World” statement that we can find in the Log example. In this case I will add it where the mainThread() starts (line 96). Make sure to use the LogModule name that we defined in SysConfig (LogModule0). Since this is application level debug information, I use the Log_DEBUG log level.

    void *mainThread(void *arg0)
    {
       /* Greet the user*/
       Log_printf(LogModule0, Log_DEBUG, "Hello World!");

In addition you can add as many log statements as you want throughout your application file. E.g. add a statement with log level ERROR for any failing status checks. You can also add log statements in other files, with this Log Module or a different one.
When you’re ready, save your file, build your project and load it onto your device. Start your preferred log view. In my case I will use tilogger to see my UART log.

tilogger uart --elf C:\Users\XXXXXXXX\workspace_ccstheia\rfPacketTx_LP_EM_CC2340R5_freertos_ticlang\Debug\rfPacketTx_LP_EM_CC2340R5_freertos_ticlang.out COM6 3000000 stdout

../../_images/user_log1.png — Hello World log displayed.#

Certain TI drivers are already instrumented with log statements. This is true for the Power driver. If we want to get the Power driver log statements, all we need to do is add a Log Module called LogModule_Power in SysConfig. Use the same log sink as your application log module. Re-build and reload the application to your device.

../../_images/logmodule_power.png — Add a log module called `LogModule_Power` to get log statements from the Power driver.#

Warning

The Power driver sends a lot of log statements thus it may not be suitable for the stdout view in tilogger. Switch to Wireshark or use SysConfig to limit which log levels you want to receive. In the image below, the rfPacketTx example ran for just a couple of seconds, and generated almost 10,000 log statements.

../../_images/user_log2.png — Log statements from the Power driver.#

The following drivers are instrumented with log statements:

Power driver (LogModule_Power)
UART2 driver (LogModule_UART2)

Success

We have enabled logging on the CC23xx Wireless MCU!