Suffix

Getting Started with Meshtastic

A simple off-grid two-node setup from the command line.

A Heltec v3 board with antenna showing the Meshtastic node info on its display

Meshtastic offers a glimpse into off-grid communication, and the Heltec V3 boards are a popular entry point. While there are fancier devices like the LilyGO T-Deck or Muzi.works, we’ll start with the basics. I picked up two Heltec V3 boards for €22 each (check TinyTronics, hamparts.shop or Nettigo for some European stores).

First, I attached the included stubby antennas. Always connect antennas first with devices that transmit, or you might damage them. Then, using the Meshtastic web flasher, I flashed the first board with the latest firmware. The flasher worked flawlessly with Chromium on Linux (Firefox does not support WebUSB).

The Phone Node

Meshtastic offers multiple configuration options: a mobile app, a web UI, and a Python CLI (more on that later). For this first device, we’ll use the mobile app over Bluetooth, which is likely the most common approach. We’ll refer to this first board as the phone node.

Powered by a LiPo battery (a USB power bank or adaptor would also work), the phone node was ready for configuration. Connecting via Bluetooth using the Meshtastic app is straightforward. The device’s name is displayed on its screen and shows a pairing code when connecting through the Meshtastic mobile app. After pairing, I set the device’s region and saved the configuration, triggering a reboot. We’ll leave other settings at their defaults.

The Computer Node

Next, we’ll flash the second board, designated the computer node, using the same web flasher. However, we’ll configure this node via the Meshtastic CLI. Since the device is already connected via USB for flashing, it’s convenient to configure it immediately.

First, let’s verify connectivity (the --port parameter might be optional). This will print the node’s configuration.

meshtastic --port /dev/ttyUSB0 --info

If successful, we’ll proceed with configuration. Note that the following settings are specific to my location in Belgium (EU_868 and CEST). Adjust them as needed for your region.

meshtastic \
--set lora.region EU_868 \
--set device.tzdef CET-1CEST,M3.5.0,M10.5.0/3 \
--set-time $(date +%s) \ # Current UNIX timestamp, will be forgotten on reset
--set device.led_heartbeat_disabled true # The blinking light annoyed me
↑ While these commands should theoretically run in a single execution, I needed to run them individually.

Both nodes now operates entirely offline, without Wi-Fi connectivity.

Sending Messages

Upon reboot, the computer node might be detected by the phone node, triggering a notification on your phone. The nodes can see each other!

To test message relay, we’ll use the --reply command on the computer node. This will listen to incoming messages and reply automatically.

meshtastic --reply

On your phone, ensure you’re subscribed to the phone node via BLE and open the "Primary channel" in the messages section. I went all out and texted an extremely creative "hi." After a brief "waiting for acknowledgment" period, the computer node should receive and reply to the message, which will then appear on your phone.

Now, don’t be rude and answer your phone from the computer node with the command line client:

meshtastic --no-nodes --no-time --sendtext "Hi me, got your message! Cheers, other me."

Bravo, you are now living the off-grid life and can send messages, without the need for any intermediary, completely self-reliant to… yourself.

Private Channels

While I didn’t detect other Meshtastic nodes in range, the "Primary channel" means that any nearby node would receive the message as well, it’s public.

For private communication, we can create a new channel on any of the nodes and share its encryption key. On the computer node:

meshtastic --ch-add "MyPrivateChannel" --ch-set psk random
meshtastic --info # Verify the new channel
mesttattic --qr-all

Scanning the generated QR code with your phone adds the private channel with the correct password, ensuring encrypted communication.

Direct Messaging

Direct messaging is also possible:

meshtastic --sendtext "Hi there" --dest '!a01bc234'
↑ The !a01bc234 is an example destination, use the ID of your phone node.

While the message was received by my phone (indicated by a push notification and a red counter on the speech bubble icon), it didn’t appear in the message list. This highlights the beta nature of Meshtastic, with its occasional quirks.

Internet Bridging

Meshtastic's true potential as a mesh network is realized when multiple nodes are within range, allowing messages to hop from one node to the next and extending the network's reach. However, we can further expand this connectivity by connecting to the internet through MQTT, enabling communication between nodes across the continent.

By enabling internet connectivity, we can bridge the gap between local Meshtastic networks. While this clearly deviates from the fully off-grid concept, it provides a fallback when nearby nodes are scarce. Let's configure the computer node for internet connectivity and MQTT:

meshtastic \
--set network.wifi_enabled true \
--set network.wifi_ssid MyWiFiNetwork \
--set network.wifi_psk MyWifiPa$$w0rd

After executing this command, the device’s display will show a new screen indicating its WiFi connection status. This alone is not enough to send and receive messages via the internet, we also have to enable MQTT:

meshtastic \
--set mqtt.enabled true \
--set lora.ignore_mqtt false \
--set lora.config_ok_to_mqtt true \
--ch-index 0 \
--ch-set uplink_enabled true \
--ch-set downlink_enabled true

This setup allows the phone node, still without an internet connection, remember, to communicate with distant nodes. Messages are relayed through the computer node to the MQTT server, which then forwards them to internet-connected nodes. The phone node needs “Ok to MQTT” (under the LoRa config) enabled for this to work.

Nodes on a Map

To make your node visible on a map, ensure WiFi is enabled as described above. Although the Heltec lacks GPS functionality, we can assign a fixed position for it to show up on the map. By default, the node sends MQTT updates every 15 minutes, but this interval can be adjusted.

meshtastic
--set mqtt.enabled true \
--set mqtt.map_reporting_enabled true \
--set position.fixed_position true \
--setlat 50.8449861 \
--setlon 4.3499932

Range Test

I was intrigued by the range of these little Heltec devices. I placed one node in the attic and took the other with me on a short walk, sending occasional messages along the way. The solid green lines indicate messages that were successfully received by my attic node, while the red dashed lines represent those that failed to go through. It’s worth noting that this informal test was in a dense urban area with some elevation changes; take it for what it’s worth.

A graph featuring red and green lines labeled with distance measurements from a central node, with a maximum successful distance of 500 meters indicated.