lqml/examples/meshtastic/readme.md

Info

An APK (android) can be found here: meshtastic.apk

This simple app can either send direct messages between the radios, or broadcast messages (received by all radios).

It's basically meant to be used in an emergency situation, where internet is not available, in order to communicate with short text messages. This kind of mesh network is limited to about 70 nodes/radios/users to remain reliable.

Technical notes

You'll probably need to rebuild the lqml library, this app requires the latest version.

The app uses both BLE (bluetooth low energy) and the protobufs serialization library version 3.

For BLE you need to build the plugin in cpp/ first (written in Qt5/Qt6).

The cl-protobufs library is included here because the official version doesn't work without the C++ plugin installed (which we don't need here). So I made some small adaptions and included all generated proto Lisp files in order to be independent.

Unfortunately the generated and C compiled meshtastic proto files load very slowly on mobile. To improve load time, meshtastic proto files are simply loaded as *.lisp source files, which doesn't seem to impact performance at runtime (in this use case).

An hourglass animation is shown while loading the app. For this to work, the app is loaded in the background (that is, in a separate thread).

You will see a json output of all data sent/received. It simply uses the print-json convenience function from cl-protobufs.

The message db uses sqlite, but in a lispy manner, storing basically just a plist for every message.

The reason I chose Qt qsqlite over cl-sqlite is mobile: Qt comes with its own version, which is pulled in automatically, so one doesn't need to care about OS limitations or indirect requirements.

Tested

Tested on Linux, macOS, Windows 10+, android, iOS, SailfishOS.

The macOS version must be built with Qt6 (Qt5 has a buggy BLE implementation), and compiled first (see build/). So, you'll need to rebuild lqml using Qt6, and replace qml/ with ../meshtastic-qt6/qml/.

The iOS version also runs on older devices, like the 'iPod touch', as long as they are 64 bit and run at least iOS 12.

How to use cl-meshtastic

Bluetooth

The most universal connection type is BLE (Bluetooth Low Energy), which should work everywhere.

Your radio needs to be turned on and bluetooth needs to be enabled before you start the app.

On android coarse location permission is required for BLE to work.

Except for Windows, pairing of your LoRa radios is generally not needed beforehand, the app will ask for pairing/PIN during BLE ini. If your device doesn't have a display, use 123456 as your PIN.

On Windows it didn't work for me if not paired previously.

It may occur that your radio device is sometimes not found; some suggestions:

• try to disable the radio in any other app that used it previously
• try to unpair your radio from current device
• reboot your radio (turn off/on)
• press-and-hold on the radio icon to restart device discovery

A generic bluetooth app like nRF Connect may help in order to see if the devices themselves work and are able to connect.

USB

If you have your radio connected to your PC via USB, you can also choose 'USB' as connection type from the main menu (see 'Radios' icon). This works on Linux, macOS, (Windows not tested yet) and android. RAK devices won't need any additional driver, just permission to e.g. /dev/ttyACM0 (Linux). Other radios (ESP32 based) require addtional serial drivers to be installed, see official Meshtastic website.

Notes for android: tested with RAK and T-Beam. The app will launch as soon as a radio is attached to USB. You need to confirm a dialog, which will also grant USB permission.

WiFi

If you have a radio with intgrated WiFi (like LILYGO T-Beam, Heltec v3), you can setup your WiFi connection using the Python CLI:

meshtastic \
--set network.wifi_enabled true \
--set network.wifi_ssid "<name>" \
--set network.wifi_psk "<password>"

You should now be able to see the IP of your WiFi connected radio on it's small display (use the user button to switch to the WiFi page). The app will ask for the IP if not entered yet, or if it has changed.

See also readme-usage.

Emojis (Linux/SailfishOS)

See emojis-howto.

Build

Please apply hacks before trying to build.

On iOS see also note in upload-download.lisp regarding function read-sequence, which needs to be replaced in the Quicklisp zip library.

Run

lqml run.lisp

Optionally pass -slime to start a Swank server, and connect from Emacs with M-x slime-connect.

During development you can pass -auto, which will reload all QML files after you made a change to any of them and saved it. For re-initialization after reloading, file lisp/qml-reload/on-reloaded will be loaded.

Closing the window quits the app. If you try to kill it with ctrl-c, you need an additional ctrl-d to exit from ECL. To quit from Slime, do (qq) which is short for (qquit).

Hardware example

See radio for a simple radio example and some basics you should know about antennas.