15. Logging and Debugging

Logging and Debugging

Language: English. Chinese version: 15. Logging and Debugging (中文)

Many Trail Mate problems are hard to diagnose without logs. In a system that combines multiple hardware targets, multiple protocol roles, offline maps, and Team behavior, a single screenshot usually shows only what the failure looks like, not where it actually occurs.

This page focuses on the practical logging and debugging entry points that already matter today, rather than trying to copy every print statement in the repository.

When You Should Capture Logs First

Logs are more important than screenshots when:

• the device boots but wireless behavior is wrong
• a target reboots abnormally after flashing
• GPS initialization fails or GPS behavior is inconsistent
• SD initialization fails
• one feature disappears only on a specific hardware target
• Team, HostLink, or protocol-switch behavior does not make sense

Current Ready-Made Debug Builds

The PlatformIO path already includes several _debug environments, for example:

platformio run -e tlora_pager_sx1262_debug
platformio run -e tlora_pager_sx1280_debug
platformio run -e tdeck_debug
platformio run -e lilygo_twatch_s3_debug

These currently enable additional macros such as:

• MESHCORE_LOG_ENABLE
• LORA_LOG_ENABLE
• APP_EVENT_LOG_ENABLE

That makes them especially useful for protocol, radio, and event-flow diagnosis.

GPS Logging Boundary

GPS_LOG_ENABLE is not enabled by default in the current setup. In other words, the standard _debug environments mainly help with protocol and radio paths. They do not automatically guarantee the deepest GPS loop logs.

If you need detailed GPS parsing or time-sync traces, you may need to add or adjust the relevant logging macros for the target rather than assuming they are already present.

How To Collect Logs

PlatformIO targets

The most direct route is:

platformio device monitor

You can also use any serial monitor you normally prefer after uploading.

ESP-IDF targets

The standard route looks like:

idf.py -B build.tab5 -DTRAIL_MATE_IDF_TARGET=tab5 monitor

For Tab5, the repository already notes that flash and monitor are better run separately.

How To Read Common Log Prefixes

[Setup]

These lines usually come from the startup shell and indicate broad startup progress such as system init, board init, AppContext binding, and shell assembly.

Board-specific prefixes

Different boards produce their own prefixes, for example:

• [TDeckBoard]
• [TLoRaPagerBoard::begin]
• [TWatchS3Board]

These are good for confirming whether:

• display init succeeded
• radio init succeeded
• SD, GPS, keyboard, or touch setup completed

[Team]

These lines usually relate to Team service assembly, Team key restoration, or Team routing behavior. When Team functionality is missing or wrong, these logs often reveal whether the issue is in the runtime assembly layer rather than in the visible UI.

[gat562]

The GAT562 route uses more detailed prefixes, including:

• [gat562][cfg]
• [gat562][settings]
• [gat562][gps]
• [gat562][mt]

These help separate configuration normalization, settings persistence, GPS runtime, and Meshtastic send or receive behavior.

idf-screen-sleep

This tag is used for current IDF screen-sleep logging. It is useful on large-screen targets where the symptom may be “touch seems dead” when the real behavior is simply “the screen was waking first”.

Which Log Moments Matter Most

Startup

If the device is wrong from boot, look for the earliest abnormal line rather than only copying the last few lines. Current code already produces strong hints such as:

• radio init failed
• GPS init: FAIL
• SD init failed
• display init failed

These are much closer to root cause than “the page never appeared”.

Configuration apply stage

For protocol changes, region changes, or MeshCore preset application, configuration-normalization and apply-stage logs are especially valuable. The GAT562 [cfg] prefix is a good example of where those clues appear.

Receive and transmit stage

If the symptom is “can receive but cannot send” or “packet arrives but does not appear on screen”, preserve:

• protocol logs around transmit attempts
• decode-failure or de-duplication logs
• errors associated with Team-related app-data handling

Trail Mate Center Is Also A Debugging Tool

Debugging should not be reduced to serial output alone. Inside the wider system, Trail Mate Center can also help you:

• inspect HostLink output
• inspect raw frames
• inspect event streams
• export messages and events

If the problem involves more than one node, the desktop tool can be more informative than a single handheld log.

What To Attach To An Issue

A high-quality issue should include at least:

1. device model and radio variant
2. build target, such as tdeck or tlora_pager_sx1262
3. active protocol: Meshtastic, MeshCore, or Reticulum; for Reticulum, include whether the configuration source is SD, Cached, or Defaults
4. whether settings such as region, preset, channel, PSK, or BW / SF / CR / TX Power / Override Freq were changed
5. Reticulum configuration source, status message, and a redacted /trailmate/reticulum/config.json
6. whether SD and offline maps were involved
7. the key log fragment, especially the earliest abnormal part
8. whether the issue reproduces reliably and how

What A Useful Log Fragment Looks Like

Something like this is helpful:

[TDeckBoard] radio init failed: ...
[Setup] AppContext initialized handles=...
[gat562][cfg] applyMesh start proto=...

A fragment like this is not:

it stopped working

Trail Mate issues often cross board, configuration, protocol, and UI boundaries. The log needs enough context to show where in the stack things started to diverge.

Current Limits Of The Logging Story

The current logging system is already good enough for most mainline troubleshooting, but it is not perfectly uniform:

• some _debug environments cover protocol logging more heavily than others
• deep GPS logging is not always enabled by default
• different boards and platforms still expose different log granularity

That is not ideal, but it is already enough to support the current troubleshooting workflow documented here.

Information Still Worth Expanding

Good future additions include:

• a fuller prefix index
• differences in log collection between PlatformIO, ESP-IDF, and nRF52 paths
• dedicated Team, HostLink, map, and GPS logging notes

For now, the goal is to keep the practical parts clear: how to enable logs, how to recognize prefixes, and what maintainers need to see in an issue.