ЛУЧ (LUCH)

Terminal client for a MeshCore Companion radio, styled like a Soviet comms console. Connects over Bluetooth, USB or Wi-Fi, and logs every message to SQLite. An optional background logger keeps the radio connected and logging while the screen is closed.

[!TIP] American comrade? Press Ctrl+T. The screen is in Russian, and so is the label for the language switch (ПЕРЕВОД). Ctrl+T turns every heading, button and slogan into English ("Yankee mode"); press it again for Russian. LUCH remembers your choice, or start with --english. Messages are never translated.

Website: mojeska.github.io/luch, where Misha the cosmonaut explains everything (and the ПУСК button works).

Built on meshcore_py and Textual. Runs on macOS and Linux; see Tested hardware for what has actually been tried.

Screen text is Russian with English hints; Ctrl+T switches it all to English, see the tip above.

Tested hardware

LUCH has been used with these radios, on a Mac (macOS, Apple silicon):

Radio	Firmware	Bluetooth	Wi-Fi	USB	GPS
Heltec WiFi LoRa 32 V3 (ESP32-S3)	MeshCore Companion BLE 1.17.1, 1.18.0	✅	✅ (1.18.0)	not tried	no GPS on board
Seeed Wio Tracker L1 Pro (nRF52840)	MeshCore Companion BLE 1.17.1, 1.18.0	✅	not on this board	not tried	✅

What that covers: messages on channels and DMs, the background logger (over Bluetooth and over Wi-Fi), channels, favourites, renaming a node, the firmware check, GPS position and weather. Firmware was updated on both with the steps in Updating firmware.

Not tested yet:

• Other boards. LUCH talks to the radio through meshcore_py, the same protocol the MeshCore phone app uses, so any board running MeshCore Companion firmware should work. Repeater and room-server firmware won't. What a board offers (Wi-Fi, GPS, a screen, battery reporting) varies, and LUCH only shows what the radio reports.
• USB. The code is there (--port), but no USB Companion build has been tried. A board flashed with the BLE build does not answer over USB.
• Linux with a real radio. The automated tests run on Ubuntu, but Bluetooth, USB and the systemd logger haven't been used with hardware on Linux (Omarchy is next).
• Firmware before 1.17. /cli, Wi-Fi and /name need 1.18.

Tried LUCH on another radio? Please open an issue with the board, firmware version, and what worked, so it can go in this table.

Updating firmware

LUCH tells you when a newer Companion release is out (/firmware). The MeshCore web flasher is the easy way to update. What was done here, keeping contacts, channels and keys:

• ESP32 boards (Heltec V3): back up the whole flash with esptool read-flash 0 0x800000 backup.bin, then write only the app with esptool write-flash 0x10000 <board>_companion_radio_ble-<ver>.bin (not the -merged image). The Heltec's USB serial chip needed --baud 115200; faster speeds gave serial errors.
• nRF52 boards (Wio Tracker L1): double-press reset, and the board appears as a USB drive (TRACKER L1); copy the .uf2 onto it. Save CURRENT.UF2 from the drive first as a fallback.

Install

Python 3.11 or later.

git clone https://github.com/mojeska/luch.git && cd luch
python3 -m venv .venv && .venv/bin/pip install -e .

Run

Bluetooth, by BLE name (any part of it works).

.venv/bin/luch -d MeshCore-MyNode

USB, finding the port automatically (or give it, e.g. --port /dev/cu.usbserial-0001).

.venv/bin/luch --port auto

Wi-Fi (radio already on your network, TCP port 5000 by default).

.venv/bin/luch --tcp 192.168.1.50 --radio mynode

Browse the log without connecting.

.venv/bin/luch --offline

Linux (Arch / Omarchy)

Bluetooth and USB access, then install as above.

sudo pacman -S --needed python bluez bluez-utils
sudo systemctl enable --now bluetooth
sudo usermod -aG uucp $USER     # USB serial (/dev/ttyUSB*, /dev/ttyACM*); log out and back in

The radio has to be paired once, with the 6-digit PIN shown on its screen. Pass it with --pin on the first Bluetooth connect and LUCH answers the pairing request itself (Linux usually has no program to ask you for it):

.venv/bin/luch -d MeshCore-MyNode --pin 123456

After that it's paired and --pin isn't needed. luch service install -d MeshCore-MyNode --pin 123456 passes it to the logger too. On macOS, leave --pin off: the system asks for the PIN in a dialog.

Or pair by hand with bluetoothctl:

bluetoothctl
  scan on
  pair <radio address>
  trust <radio address>

On Debian / Ubuntu the serial group is dialout instead of uucp.

Windows

LUCH runs on Windows 10 and 11 in Windows Terminal, over Bluetooth, USB or Wi-Fi, with the background logger as a Task Scheduler task (see Background logger). Tested on Windows 11 over Wi-Fi, Bluetooth and USB.

git clone https://github.com/mojeska/luch.git; cd luch
py -m venv .venv; .venv\Scripts\pip install -e .
.venv\Scripts\luch --tcp 192.168.1.50      # or: --port auto (finds the COM port), or -d MeshCore-MyNode

This is the beginning of the README. Read the rest at the original. Read the full README ↗