Build Locally With uv¶

This repo uses uv for Python tooling and runs PlatformIO through uv run.

This page is for building from source. If you just want firmware to flash, start with Download and Flash Releases instead.

Setup¶

From the repo root:

uv sync

Useful Commands¶

List build targets:

bash build.sh list

Plain PlatformIO build for a single target:

uv run pio run -e heltec_v4_repeater_mqtt
uv run pio run -e heltec_v4_companion_radio_wifi

Flash a target:

uv run pio run -e heltec_v4_repeater_mqtt -t upload --upload-port /dev/tty.usbmodemXXXX

Serial monitor:

uv run pio device monitor --port /dev/tty.usbmodemXXXX --baud 115200

Release-Style Local Builds¶

If you want the same version metadata used by the release workflows, export the version variables first.

Companion WiFi:

export FIRMWARE_VERSION=v1.14.1
bash build.sh build-firmware heltec_v4_companion_radio_wifi

Repeater MQTT:

export FIRMWARE_VERSION=v1.14.1
export EASTMESH_VERSION=v1.0.1
bash build.sh build-firmware heltec_v4_repeater_mqtt

This produces versioned artifacts in out/.

Supported `repeater_mqtt` Boards¶

These are the full PlatformIO env names used for local source builds and release artifact naming.

Generic_E22_sx1262_repeater_mqtt
Generic_E22_sx1268_repeater_mqtt
Heltec_E213_repeater_mqtt
Heltec_E290_repeater_mqtt
Heltec_T190_repeater_mqtt
heltec_tracker_v2_repeater_mqtt
Heltec_v2_repeater_mqtt
Heltec_v3_repeater_mqtt
heltec_v4_repeater_mqtt
heltec_v4_tft_repeater_mqtt
Heltec_Wireless_Paper_repeater_mqtt
Heltec_Wireless_Tracker_repeater_mqtt
Heltec_WSL3_repeater_mqtt
LilyGo_T3S3_sx1262_repeater_mqtt
LilyGo_T3S3_sx1276_repeater_mqtt
LilyGo_TBeam_1W_repeater_mqtt
LilyGo_TDeck_repeater_mqtt
LilyGo_Tlora_C6_repeater_mqtt
M5Stack_Unit_C6L_repeater_mqtt
Meshadventurer_sx1262_repeater_mqtt
Meshadventurer_sx1268_repeater_mqtt
Meshimi_repeater_mqtt
nibble_screen_connect_repeater_mqtt
RAK_3112_repeater_mqtt
Station_G2_logging_repeater_mqtt
Station_G2_repeater_mqtt
T_Beam_S3_Supreme_SX1262_repeater_mqtt
Tbeam_SX1262_repeater_mqtt
Tbeam_SX1276_repeater_mqtt
WHY2025_badge_repeater_mqtt
Xiao_C6_repeater_mqtt
Xiao_S3_WIO_repeater_mqtt

Supported `companion_radio_wifi` Boards¶

These are the full PlatformIO env names used for local source builds and release artifact naming.

heltec_tracker_v2_companion_radio_wifi
Heltec_v2_companion_radio_wifi
Heltec_v3_companion_radio_wifi
heltec_v4_companion_radio_wifi
heltec_v4_tft_companion_radio_wifi
Heltec_WSL3_companion_radio_wifi
LilyGo_TBeam_1W_companion_radio_wifi
LilyGo_TLora_V2_1_1_6_companion_radio_wifi
nibble_screen_connect_companion_radio_wifi
RAK_3112_companion_radio_wifi
Station_G2_companion_radio_wifi
T_Beam_S3_Supreme_SX1262_companion_radio_wifi
ThinkNode_M2_companion_radio_wifi
ThinkNode_M5_companion_radio_wifi
Xiao_S3_WIO_companion_radio_wifi

Companion WiFi CLI¶

Current companion WiFi builds support persisted WiFi rescue commands:

open a serial monitor at 115200 baud
reboot the device
long-press the user button within the first 8 seconds after boot to enter CLI Rescue
wait for ========= CLI Rescue =========
then run the WiFi rescue commands below from the serial monitor

get wifi.status
get wifi.ssid
get wifi.powersaving
set wifi.ssid <ssid>
set wifi.pwd <password>
set wifi.powersaving none|min|max