1. Quick Start

Quick Start

Language: English. Chinese version: 1. Quick Start (中文)

This page validates the minimum loop of a decentralized-phone-like MCU terminal: without a phone or cloud dependency, the device starts, positions itself, reads offline maps, manages contacts, and sends messages. Full TAK/Team validation can follow after the basic path works.

Start With the Most Stable Route

If this is your first attempt, do not pick a random target. The best entry points are still:

• tlora_pager_sx1262
• tdeck

These two paths currently cover Trail Mate’s most complete map, chat, and sharing UI loop. gat562_mesh_evb_pro is important too, but it is a deliberately resource-constrained target with Team, HostLink, SD, and CJK support removed, so it is not the best first impression if your goal is to see the full system.

What You Need

Hardware

• a well-supported device, preferably LILYGO T-LoRa-Pager (SX1262) or LILYGO T-Deck
• a USB cable that actually carries data
• an SD card, because maps, routes, and tracks live on SD rather than inside the firmware image
• ideally a second compatible device, or an existing nearby Meshtastic, MeshCore, or Reticulum/LXMF node for testing

Firmware

There are two sensible firmware paths:

• if the repository has a prebuilt release that exactly matches your hardware and radio variant, use that
• if there is no matching asset, or you are unsure whether it fits your board, build from source instead

Release assets, naming, and coverage can change over time. This page does not assume that a specific release file will always exist.

Map Resources

If you want a real map on day one, prepare SD-card tiles in advance. The device reads directory tiles, not mbtiles. The minimum structure looks like this:

/maps/base/osm/{z}/{x}/{y}.png
/maps/base/terrain/{z}/{x}/{y}.png
/maps/base/satellite/{z}/{x}/{y}.jpg

Contour layers and route files can come later.

The Shortest Working Flow

1. Confirm the correct target

Match your physical device to the correct environment before flashing:

• T-LoRa-Pager SX1262 -> tlora_pager_sx1262
• T-LoRa-Pager SX1280 -> tlora_pager_sx1280
• T-Deck -> tdeck

Do not guess here. When the board family has multiple radio variants, the wrong environment often leads to “the system boots, but radio behavior is wrong”.

2. Flash the firmware

For the PlatformIO path, the shortest commands look like this:

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

or:

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

COM6 is only an example. Use the actual port your machine exposes.

3. Prepare the SD card

At minimum, put one small base-map area on the card. For first validation, you do not need an entire region. A small local z=12 tile block is enough to prove that loading works. If you have no map tiles yet, you can still validate radio and GPS first, but the map page will not invent online data for you.

4. Change the first settings only

On first boot, do not wander through every menu. Confirm these first:

• User Name and Short Name, so the device has a recognizable identity
• the communication protocol, because the runtime activates one protocol role only
• region or carrier settings that match your path
• whether BLE is needed for your use case
• the map layer you actually prepared on SD

The protocol selector contains Meshtastic, MeshCore, and Reticulum. LXMF is the messaging layer inside Reticulum mode, not another protocol choice.

The wireless settings mean different things depending on the protocol:

• Meshtastic is mostly about Region, Channel, and PSK
• MeshCore is more about region preset or manual frequency, bandwidth, spread factor, and coding rate
• Reticulum LoRa uses carrier settings such as BW, SF, CR, TX Power, and Override Freq; Reticulum can also use configured Wi-Fi TCP Client and AutoInterface carriers

One especially important point: the built-in defaults are only bootable defaults. They are not automatically the right settings for your region, legal constraints, or existing team network.

Reticulum interfaces are not entered field-by-field in Settings. Create /trailmate/reticulum/config.json on the SD card, then start or reload Reticulum. See 4.1 Reticulum, LXMF and RNode Bridge#Reticulum network configuration comes from the SD card for the complete format, limits, and example.

5. Confirm the device is healthy

Before testing more complex workflows, confirm the basics:

• the screen and input method respond normally
• the LoRa hardware does not show an obvious init failure
• GPS-capable devices can gradually acquire satellites outdoors
• SD-capable devices can see their map layer or route directory

If you are validating GPS, GNSS Sky Plot is usually a better first check than the map itself because it tells you whether the receiver is actually seeing satellites and building a fix.

6. Validate the simplest possible message path

Do not begin with Team or more complex app-data flows. First prove that the basic link is alive:

1. make sure both sides use the same protocol role
2. make sure the relevant wireless parameters actually match
3. test the simplest text path available for that protocol

For Meshtastic, Trail Mate already supports the common text-messaging path. For MeshCore, treat text messaging as the clearest stable loop unless you are explicitly testing deeper protocol behavior.

If you are using Reticulum, first validate announces, peer discovery, and basic LXMF text delivery before moving to deeper path, link, or resource behavior. In Contacts, press S or / to search and A to enter an LXMF address manually. The more reliable workflow is to select an already discovered peer under Nearby and choose Add from its action menu. See the 4.1 Reticulum, LXMF and RNode Bridge#Contacts, Chat, and Network operations for full instructions.

If you explicitly enabled the external-host RNode/KISS HostLink runtime, validate that the host recognizes the USB modem. This is not a RNode Bridge protocol in Settings and is outside the normal Reticulum quick start.

7. Validate position and map

Go outdoors into an open area, wait for a valid fix, then open the map page. Confirm two things:

• your own position marker appears
• the selected base layer actually loads instead of reporting missing tiles

If GPS looks healthy but the map is still empty, treat it as a map-resource problem first, not as a GPS problem.

A Good First-Day Validation Order

If you want the smallest practical validation loop, do it in this order:

1. choose tdeck or tlora_pager_sx1262
2. flash firmware and boot
3. set name, protocol, region, and channel or carrier parameters
4. use GNSS Sky Plot to confirm GPS
5. place a small OSM tile set on SD
6. open the map and confirm both position and tile loading
7. send one simple broadcast or text message to another device or node

At that point you have already verified the three most important chains in Trail Mate: device UI, offline map and GPS, and LoRa text communication.

If You Hit Problems On Day One

The most common next steps are:

• if flashing fails, go to [[3. Installation & Flashing]]
• if the device boots but the radio does not work, see [[4. Protocols & Data]] and [[14. Troubleshooting]]
• if maps do not render, see [[5. Offline Maps]]
• if the device state is unclear, keep the serial log and then see [[14. Troubleshooting]]

Information Still To Expand

This page does not pin a fixed release workflow, exact release asset naming, or image-by-image board-specific flashing guides because those details may change and are not guaranteed uniformly in-repo yet. If the release workflow becomes stable enough, a separate “flash from release asset” section would make sense later.