14. Troubleshooting

Troubleshooting

Language: English. Chinese version: 14. Troubleshooting (中文)

This page is organized by symptom rather than by module. Many Trail Mate problems look like “the system is broken” when the real cause is that the target, protocol choice, resource layout, or board boundary was never aligned first.

If you plan to file an issue, it is worth walking through the relevant branch here before doing so.

The Device Will Not Flash, Or The Computer Cannot See A Serial Port

Check the target and toolchain first

1. confirm that the environment matches the physical device, especially T-LoRa-Pager SX1262 versus SX1280
2. use PlatformIO for the ESP32 and nRF52 handheld paths, and reserve ESP-IDF for Tab5 and T-Display P4
3. if serial auto-detection is unstable, add --upload-port COMx explicitly

Then check for generic serial problems

1. try a USB cable that is known to carry data
2. close any serial monitor, IDE, or host tool that may already hold the port
3. on the large-screen IDF path, run flash first and avoid chaining flash monitor on the first attempt

When to assume it is not a Trail Mate-specific problem

If the device never exposes a port at all, or the same port is unusable everywhere else too, start by treating it as a cable, driver, or serial-permission problem rather than as a map or protocol bug.

The Device Boots, But LoRa Does Not Work

First separate “completely dead” from “cannot transmit”

If the device neither receives nor transmits, start by suspecting the target, board radio variant, region, or carrier parameters.

If it can receive but not transmit, jump to the next section.

Then confirm the protocol path

Trail Mate does not switch automatically between Meshtastic, MeshCore, and Reticulum. Confirm:

1. which protocol role is active on the device
2. whether the peer device or external host uses the same role
3. for Reticulum, whether SD config.json is valid, source reports SD, and at least one interface is ready
4. whether the contact has a complete identity hash plus encryption/signing public keys; Address pending is expected when only a destination hash is known
5. whether both sides match on the relevant parameter model

The matching parameters differ by role:

• Meshtastic mostly depends on region, channel, and PSK
• MeshCore depends more on preset, frequency, bandwidth, spread factor, and coding rate
• LXMF and RNode Bridge depend on RNode carrier settings

Confirm that the hardware target is correct

On boards with multiple radio variants, such as T-LoRa-Pager, a wrong environment often produces the exact symptom “the UI is fine but the radio is wrong”.

Look at the serial log

Board-level implementations already produce useful failure clues such as:

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

If the radio appears completely dead, those messages are more valuable than screenshots.

It Can Receive, But It Cannot Transmit

Check transmit-related settings first

1. confirm that the current protocol path actually allows transmit
2. check whether power and region settings were changed into a bad combination
3. check whether the device is on the wrong channel or using the wrong key

Then check protocol boundaries

On MeshCore, the clearest stable path today is still text messaging. More complex app-data or control flows should not be assumed complete by default.

On the LXMF path, do not judge behavior using Meshtastic broadcast expectations. Reticulum and LXMF use announce, path, proof, link, and resource semantics that are not the same model.

If this is really a Team problem

Team traffic is not the same thing as ordinary broadcast traffic. Confirm:

1. that the device actually supports Team, and is not a target such as GAT562
2. that team formation really completed
3. that you are testing a Team path rather than an ordinary text path

GPS Is Abnormal Or Never Gets A Fix

Confirm that this target even enables GPS

Not every target does. Currently:

• T-Watch S3 has HAS_GPS=0
• GAT562, T-Deck, T-LoRa-Pager, and T-Deck Pro do have GPS paths

If the target does not include GPS, then “no fix” is not a fault inside the intended feature set.

Then confirm the environment

Indoor space, partial sky view, or too little time after power-up can all look like hardware failure. Move outdoors into an open area, then use GNSS Sky Plot to check:

1. whether satellites are visible
2. whether any satellites are contributing to a fix
3. whether a fix gradually forms

If initialization already fails in logs

Then stop investigating the map or chat pages. Treat it as a board-level GPS initialization problem first.

Map Problems

The map page opens, but the base map is empty

Check these in order:

1. is the SD card actually recognized
2. is the directory really /maps/base/{source}/{z}/{x}/{y}.{ext}
3. did the satellite folder accidentally use .png
4. does the selected layer actually have matching tiles

There is a position marker, but no base map

That usually means the GPS chain is fine and the resource directory is wrong.

Routes or tracks do not appear

1. KML belongs in /routes
2. track files belong in /trackers
3. if the folders are missing, the relevant pages simply stay empty

When to suspect format mismatch

If you prepared mbtiles, custom filenames, or a non-standard hierarchy, then you are outside the current device-side input format boundary already.

Touch, Trackball, Keyboard, Or Joystick Problems

First confirm your expectation of the board

Input models differ a lot:

• T-Deck: keyboard, touch, and trackball
• T-LoRa-Pager: knob, center key, and keyboard
• GAT562: 5-way joystick and two buttons
• T-Watch S3: mostly touch

Do not use one board’s interaction style to diagnose another board as “backward” or “wrong”.

GAT562 specifics

If the directional inputs work but center press does not, the board documentation already suggests suspecting pin mapping or hardware first. That board has had history around joystick-center mapping.

T-Deck specifics

Trail Mate maps the T-Deck trackball more like a directional or rotary navigation device than a general mouse cursor. That is normal.

Power, Sleep, Or Shutdown Behavior

The device will not power off

On T-LoRa-Pager, if USB is still connected, the project currently blocks normal power-off and displays:

Unplug USB to power off

That behavior is better understood as board power policy than as a page-level bug.

It seems like touch is dead, but it is really waking the screen

On some screen-sleep paths, the first touch wakes the display without passing that touch through to the page as a normal interaction. If this happens, try again before assuming the UI is frozen.

Battery life is unexpectedly poor

Start with configuration checks:

1. GPS update interval
2. screen brightness and timeout
3. whether BLE and high-frequency positioning remain enabled all the time

These issues are often more about settings than about the battery hardware itself.

Pages Or Features “Disappear”

Do not assume the build is incomplete immediately. Trail Mate hides pages according to capability and resource budget. Common cases include:

• GAT562 removing Team, HostLink, SD, and CJK
• T-Watch S3 currently lacking the GPS and SD route
• large-screen IDF targets still being in bring-up or staged rollout

If one feature is missing only on one device, treat it as a target-boundary question first.

When You Should Collect Logs

Logs are more important than screenshots when:

• the radio does not work at all
• GPS initialization fails
• SD initialization fails
• the target reboots abnormally at startup
• a feature disappears only on one hardware target

At minimum, record:

1. board model and radio variant
2. build target such as tdeck or tlora_pager_sx1262
3. active protocol: Meshtastic, MeshCore, or Reticulum; for Reticulum, report whether the configuration source is SD, Cached, or Defaults
4. whether region, preset, channel, PSK, or RNode carrier parameters were modified
5. Reticulum configuration source, status message, and a redacted SD config.json
6. whether an SD card is inserted and the directory structure is approximately correct
7. the earliest relevant serial-log error line

If You Still Cannot Isolate The Problem

If you have gone through the relevant branch here and are still stuck, avoid reporting only “does not work”. A more useful issue includes:

• the exact board and build target
• what operation you were performing
• what you expected
• what happened instead
• whether it reproduces reliably
• the most relevant log fragment

Most Trail Mate problems cannot be pinned down from one sentence such as “map is blank” or “message will not send”. The clearer the chain is described, the lower the maintenance cost becomes.