This is a custom firmware for the T-Echo devices made by Lilygo.
With this firmware the T-Echo becomes a LoRa-APRS tracker. The LoRa transmissions are compatible with the popular LoRa-APRS-iGate firmware for some ESP32-based devices usually used as iGates.
One particular focus of this firmware is to use the low-power capabilites of the T-Echo. With the standard 800 mAh battery, it achieves more than 10 hours of active tracking, multiple days of lora reception and 1 to 4 months of standby (reachable via BLE; standby time depends on hardware configuration).
Please note: if you have questions regarding the usage of this firmware, check the FAQ section below before opening an issue.
See the documentation for details.
!DAO!
for improved latitude/longitude precision (see APRS 1.2 specification)Here are some screenshots of version 0.8+ from the display simulator I use to develop the display layout. The data shown is obviously fake, but the screen layout on the device is identical.
The startup screen:
GNSS and tracker status:
Screen shown when a packet is successfully received and decoded. It shows the course and distance to the other station:
Impressions from the menu system:
I provide this firmware in the hope that it will be useful. However I can not guarantee that it will work on your device.
It may even break your device if you have a different hardware version with a different pin assignment or power distribution network or other LoRa/GNSS/display modules. You are using this on your own risk.
Before you try this firmware, make sure that the pinout in config/pinout.h
matches your device!
This firmware should support T-Echos with the following components:
The device is operated using the two free buttons: the touch button on the top of the device and the push button on the bottom left. The top left button is the hardware reset button for the SoC.
In any state, the touch button enables the display backlight for three seconds and refreshes the display.
In normal state (the state entered after firmware boot), a short press on the lower-left push button switches to the next display state (i.e. tracker state, GNSS state, received and decoded messages). A long press on this button opens the menu.
The menu is operated as follows:
>
) or left (items starting with <<<
)Please note: pre-built binaries are also available and strongly recommended. Skip this section if you are using those.
To compile the firmware you need to set up the toolchain for Nordic
Semiconductor’s nRF5 SDK. See the SDK
documentation
for setup instructions. Only compilation via GCC is supported. If you can build
any example from the SDK (located in nrf5-sdk/examples/
) you should be good
to go.
To compile the firmware, simply run
make
This will give you firmware binaries (ELF and HEX files) that you can use to
directly flash a device via SWD and debug the firmware. All outputs are stored
in a new directory called _build
.
To generate UF2 files that can be used with the preinstalled bootloader the following commands are available.
make uf2_sd
This generates a complete installation image
(_build/nrf52840_xxaa_with_sd.uf2
) that can be used to flash devices
currently running a different firmware.
Alternatively, you can create a simple update image with
make uf2
The resulting image (_build/nrf52840_xxaa.uf2
) can only be used to upgrade
devices that run different versions of this LoRa-APRS firmware. However, it is
much smaller and therefore faster to download and flash.
Just for the sake of completeness: The pre-built binaries are generated with an
additional make
target that copies the UF2 images above to new names
including the version number (like t-echo-lora-aprs-v0.6.uf2
). Run it as
follows:
make release
This firmware is compatible with the T-Echo’s preinstalled bootloader, so you can simply install it like an regular firmware update (tested with the Meshtastic version, not sure about the SoftRF version).
Short reminder: to invoke the bootloader, double-press the reset button and
connect the T-Echo to your PC via USB-C. It should appear as a mass-storage
device called TECHOBOOT
.
Back up your current firmware before installing this firmware. To do so,
copy the CURRENT.UF2
from the T-Echo’s mass storage device TECHOBOOT
to
your PC.
When you first install the LoRa-APRS firmware, you must also install the
correct SoftDevice (Bluetooth stack). Therefore, download the latest
t-echo-lora-aprs-with-sd-vX.Y.uf2
from the Releases
page (or use the one you
built yourself) which contains both the SoftDevice and the regular firmware
build. Copy t-echo-lora-aprs-with-sd-vX.Y.uf2
to the TECHOBOOT
. When the
copy operation is complete, the device should disconnect, reset, and boot the
LoRa-APRS firmware.
After initial installation, you have to configure your call sign to be able to transmit LoRa packets (see Configuring the firmware below).
If the SoftDevice is unchanged, only the firmware part needs to be updated. To
do so, download or build
t-echo-lora-aprs-vX.Y.uf2
. Copy that file to TECHOBOOT
and you are done.
There are two ways to configure certain aspects of the firmware: via Bluetooth LE and via the on-screen menu.
The following aspects are configurable via the menu:
Via BLE you can set the following directly:
The source call sign must be set to be able to transmit APRS packets.
All other settings can be modified through a generic interface.
See the manual for details about the service and characteristic UUIDs and data formats.
A simple Python script based on the Bleak BLE library is available for configuring the device. It should work on any platform that Bleak works on, but I can only test it on Linux.
To use the script, first install the correct version of Bleak (consider using a Python Virtual Environment):
pip install -r tools/ble_client/requirements.txt
Then, run the script:
cd tools/ble_client/
./techo_client.py
The script provides a simple menu system with indexed entries. To select an entry, just type the corresponding index when prompted to do so.
When started, the script will first scan for T-Echos and list all that were found. You pick one and the script connects to it. You can then select from various actions, including listing and changing the current settings.
If you cannot use the Python script described above, you can try a generic BLE exploration/debugging app like nRF Connect for Mobile to write the available BLE characteristics.
If you tried to flash another firmware, but it does not boot after you had my
firmware installed, please flash your backup of CURRENT.UF2
first. That
reliably resets the flash contents to whatever was delivered with your T-Echo
and should always restore it to a working state.
If you don’t have the backup file, well, that’s a problem. You can try using the one I created from one of my devices (see this comment ), but I cannot guarantee anything.
If you still cannot get the T-Echo to boot again, you can try re-flashing the bootloader (see documentation by LilyGo). You need to connect an SWD programmer to do that.
Probably the BLE security keys are messed up. The T-Echo refuses any connection with a wrong or missing key. Try the following:
Please note that if you remove the keys from the T-Echo, any other device you used to connect before will no longer be able to connect. You have to remove the T-Echo connection from all other devices.
For license information, see COPYING.