3. Installation & Flashing

Installation & Flashing

Language: English. Chinese version: 3. Installation & Flashing (中文)

This page is about how to put the firmware onto the device correctly and how to provide the resources the device actually expects afterward. Unlike [[1. Quick Start]], this page includes the fuller build routes, flashing commands, resource locations, and the most common failure points.

Two Things To Separate First

In Trail Mate, “the firmware flashed successfully” and “the map system is usable” are not the same thing.

Firmware is written to the device through PlatformIO or ESP-IDF depending on the target. Offline map tiles, KML routes, and track files live mainly on the SD card. The project does not currently package offline maps into the firmware image, and it does not use mbtiles as the device-side map source.

Many “maps do not show up” reports are not flashing failures at all. They are simply missing or mis-placed SD-card resources.

How To Obtain Firmware

Path 1: prebuilt firmware

If the repository’s Releases page provides an asset that exactly matches your hardware and radio variant, using the prebuilt image is the simplest route for a first trial.

Two conditions matter:

• the asset must match the real hardware target, including radio variant where relevant
• release asset naming and coverage may change, so this page does not hard-code one asset name as a permanent fact

Always verify against the actual release content that exists at the time you flash.

Path 2: build from source

If you want to pick a specific target, modify configuration, test the current branch, or there is no suitable release image, building from source is the safer route.

Today the repository has two active toolchain paths:

• PlatformIO for the Arduino-based ESP32 targets and the current nRF52 target
• ESP-IDF for the shared-shell large-screen line, currently centered on tab5 and t_display_p4

PlatformIO Path

Which targets this covers

Use this path for T-LoRa-Pager, T-Deck, T-Deck Pro, T-Watch S3, and GAT562 Mesh EVB Pro.

Common build commands

# mainline targets
platformio run -e tlora_pager_sx1262
platformio run -e tdeck

# resource-constrained / nRF52 target
platformio run -e gat562_mesh_evb_pro

# other integrated targets
platformio run -e tlora_pager_sx1280
platformio run -e tdeck_pro_a7682e
platformio run -e tdeck_pro_pcm512a
platformio run -e lilygo_twatch_s3

If you need more serial logging, the repository also includes debug environments such as:

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

Upload commands

The general form is:

platformio run -e <env> --target upload

If you need to specify the serial port explicitly:

platformio run -e tdeck --target upload --upload-port COM6

Practical notes on this path

• running platformio run from the repository root uses the default environment tlora_pager_sx1262, so do not omit -e unless that is really your board
• T-LoRa-Pager SX1262 and T-LoRa-Pager SX1280 are different environments and must match the real radio hardware
• GAT562 Mesh EVB Pro is resource-constrained, so treat heavy logging more carefully
• T-Watch S3 currently disables GPS and SD in its environment, which should not be misread as a flashing failure

ESP-IDF Path

Which targets this covers

Use this path for Tab5 and T-Display P4.

tab5 example

idf.py -B build.tab5 -DTRAIL_MATE_IDF_TARGET=tab5 reconfigure build
idf.py -B build.tab5 -DTRAIL_MATE_IDF_TARGET=tab5 -p COM6 flash
idf.py -B build.tab5 -DTRAIL_MATE_IDF_TARGET=tab5 monitor

t_display_p4 example

idf.py -B build.t_display_p4 -DTRAIL_MATE_IDF_TARGET=t_display_p4 reconfigure build
idf.py -B build.t_display_p4 -DTRAIL_MATE_IDF_TARGET=t_display_p4 build

Practical notes on this path

• sdkconfig now follows the build directory, such as build.tab5 or build.t_display_p4, rather than reusing one root-level configuration
• for Tab5, it is safer to run flash and monitor separately; the project README already notes that chaining them can leave ESP32-P4 in ROM download mode after reset
• if your goal is just to try Trail Mate, the IDF large-screen route is usually not the best first step

Where Resource Files Go

Map tiles

The device reads SD-card directory tiles. The baseline structure is:

/maps/base/osm/{z}/{x}/{y}.png
/maps/base/terrain/{z}/{x}/{y}.png
/maps/base/satellite/{z}/{x}/{y}.jpg
/maps/contour/major-500/{z}/{x}/{y}.png
/maps/contour/major-200/{z}/{x}/{y}.png
/maps/contour/major-100/{z}/{x}/{y}.png
/maps/contour/major-50/{z}/{x}/{y}.png
/maps/contour/major-25/{z}/{x}/{y}.png

Several mistakes are common here:

• mbtiles is not supported as the device-side map source
• the satellite layer expects .jpg, not .png
• empty folders are not enough; real tile files must exist

Routes and tracks

/routes/*.kml
/trackers/*.gpx / *.csv / *.bin

• routes is used for route-mode KML input
• trackers is used for track display and export-related paths

Which devices do not use this path

Not every target supports SD-based resources. GAT562 Mesh EVB Pro explicitly does not support SD. T-Watch S3 also currently has SD disabled in its environment. On those targets, map and track expectations should be adjusted accordingly.

First-Boot Initialization Behavior

On first run, Trail Mate generates configuration from built-in defaults. The important thing to understand is that those defaults only guarantee a bootable starting point, not a correct deployment for your region or scenario.

Current AppConfig defaults include things such as:

• default protocol Meshtastic
• BLE enabled by default
• contour overlay and track recording disabled by default
• default GPS update interval at 60000 ms

These are starting values. Region, channel, PSK, power, and any MeshCore or RNode carrier settings still need deliberate review after the first boot.

Common Reasons Flashing or Bring-Up Fails

Wrong environment

This is one of the most common Trail Mate problems. It is not only the board family that must match. In some cases the radio variant must match too, as with T-LoRa-Pager SX1262 versus SX1280.

Wrong or busy serial port

The PlatformIO path depends on the right upload port. When in doubt, use --upload-port COMx explicitly rather than relying on auto-detection.

Chaining flash and monitor on large-screen IDF targets

This is a known concern especially on Tab5. Use separate flash and monitor steps if behavior looks strange after programming.

Assuming “firmware is flashed” means “maps will display”

That is not a flashing problem. It is a resource problem. Maps, routes, and tracks must be placed on the SD card under the expected directory layout.

Common Problems That Are Not Trail Mate-Specific

Some failures are still generic serial-flashing problems rather than project-specific ones:

• the USB cable provides power only and no data
• drivers or serial permissions prevent the tool from seeing the device
• another serial monitor, IDE, or host tool is already holding the port

This page does not expand into a general driver tutorial, but those possibilities are still worth checking early.

What To Do Right After Flashing

After a successful flash, do not jump straight into the most complex features. Confirm things in this order:

1. the device boots reliably
2. screen and input behave normally
3. protocol, region, channel, and identity were checked manually
4. if the device supports SD, the card is inserted and a minimal map resource set is present
5. GPS can obtain a fix outdoors
6. at least one simple broadcast or text message can be sent

Once that works, moving on to Team, HostLink, or more complex multi-device flows becomes much easier.

Information Still Worth Expanding

This page does not yet include per-board illustrated flashing guides or OS-specific driver notes for Windows, macOS, and Linux. If those turn out to be the main user bottleneck, device-specific flashing pages would be the right next split.