Introduction
Meshtastic is a project that lets you pair your mobile phone with an inexpensive (~$30) GPS LoRa radio. This allows you to communicate over a mesh network where you don’t have reliable cell/mobile reception or wifi access. The Meshtastic Android app handles the communication and shows the location of everyone in your private group. You will also require a LoRa radio device, which works with this app to allow you to communicate.
Use this application if you are interested in trying the Meshtastic project. The radios are great for hiking, skiing, paragliding - essentially any hobby where you don’t have reliable internet access. Each member of your private mesh can always see the location and distance of all other members and any text messages sent to your group chat.
This is the user guide for the Meshtastic Android app. There is also a separate guide for the Meshtastic device. Currently (September 2020) there is no IOS app.
Getting Started
This will help you install and connect the app. There is also a useful getting started guide here that explains more about devices and batteries.
Installation
To install the Android app, just search in the Playstore for "Meshtastic".
image
The application will need access to your Location, and should be permitted as "Allow all the time", and to Notifications. These permissions are required as the application will "listen" for incoming messages from the radio device in the background.
image settings
The application may not be found if your phone/Android version are too old. The minimum Android version is 5.0 (Lollipop 2014, first BLE support). However Android 6, Marshmallow 2015, is recommended as the Bluetooth is more stable. See Android_version_history.
Note: In your phone Settings, Location Services should be enabled, and Bluetooth should be turned on.
Open the App and you should see a screen like this. You can move through the tabs but nothing much will be visible until you connect to a radio device.
Connecting
You will need a device with Meshtastic installed to go any further. See the Device User Guide, or the project documents on GitHub to get your device ready.
Open the Settings tab (last tab), and it should look similar to the screen below. It shows any Meshtastic devices that are found over Bluetooth.
- Select the Device by name, "Meshtastic_b615" in the example below. (You will see any active devices within range, so make sure to get the right one.)
- You will need to "pair" the device by entering a PIN shown on the device screen. This can alternatively be done in the phone Bluetooth settings. If the Device has no screen, but it's connected via USB, it may be displayed on a serial terminal (921600 Baud). For a development device, the PlatformIO terminal would come in handy.
- Edit the "Your name", e.g. to be "Mike Bird". This is the name that other people will see, so make it unique within your group.
- The initials e.g. "MB" should also be unique and will be used to identify you in the message history and on the device screens.
- This should start the communication with the Device. The cloud icon, on the status bar, will have a tick.
Also you can check the Debug Panel, via the menu (top-right), and you should see some messages as shown below.
If there is no Device shown, just the None (disable) as below, then the device may be off, or in a sleep mode. Try to reset, or press a button to wake it.
Common Tasks
Once you are connected to a Device the App will work, and you can test it by "sending" a message. However you will need to join or create a new mesh network so you have someone to communicate with. If you have been sent a QR code or link for Meshtastic, then skip ahead to Join a Channel, otherwise you will need to Setup a Channel.
Setup a Channel
To use Meshtastic you need to setup a Channel, and share the details with your group. The group is private and only those who have the details can join the group and see the messages. You will need to do this once initially, and then only when you want to change or make a new mesh network group. For a new device you will see there is a default setting, shown as #LongSlow-1, Very long range (but slow). It is OK to use this initially.
The Channel tab allow you to do this. This screen is initially locked, so that you don't change it accidentally. Press the lock symbol, and you will be able to edit. First, select the Channel options, as shown here, and chose the most appropriate option:
Here we selected Medium Range (but fast), and then make a Channel Name using the keyboard. This identifies your group, here Owl Team.
You will see a warning because changing the Channel will break communications with your group, i.e. if you change your settings without sharing the new details with the group.
The app will generate a new QR code on the screen, and this encodes the channel details and a random 256-bit key for sharing with the new group. You can share the QR code with other Meshtastic users, or use the Share button and share the link via chat message, SMS, email (the link is a very long code, for example: https://www.meshtastic.org/c/#GAEiIPBUiiLq74okyCaw3rq5vs4cTE3awoMUJ3P2ALrh-nhLKghPd2wgVGVhbQ== ).
Join a Channel
If another user shares a QR code, you should be able to scan it with your camera (phones with Android 9 or later will recognise QR codes).
- You will see a message like Tap here to go to "www.meshtastic.org" in your browser.
- Proceed and it will launch the Meshtastic app, and you should see a message like Do you want to switch to the 'Owl Team' channel?.
- Accept this, and the app will change to this new channel. You will lose any current channel setting!
If the channel is shared as a link via a message, or email, you can click on the link and follow similar steps.
You can test this with the QR code shown below.
Note: You must use a link or a QR Code to Join a Channel. Setting the Channel Settings to the same Name and Options will not work as there is also a shared key encoded in the link.
Note: your app must be connected to an active Meshtastic device for the link or QR Code to work.
Send a message
ToDo - confirm meaning of symbols; store & forward; time-out durations; does a router confirmation mean a tick?
The message window operates like any chat applications. Note that any messages sent go to the whole group, and there is no one-to-one message feature.
With LoRa (or any radio) there is some uncertainty that the messages has been received, so there is a confirmation built-in to the protocol. There are small cloud icons shown to the right of the messages you send:
- Cloud only: message has been sent via Bluetooth and transmitted via LoRa.
- Cloud with a check mark: message has been delivered to at least one node in the mesh and at least one node sent back a confirmation (successfully received by the initial sender).
- Cloud crossed out: message may have been delivered to at least one node in the mesh. If at least one node sent a confirmation back the initial sender did not receive the confirmation within a certain timeout.
Thus, in a group size of 3 and up, confirmations could be from any one device (not person), so it is good practice to respond, so the initial sender knows you have read their message.
There is no long-term store-and-forward of messages, so messages not received within a time-out (duration?) are lost.
View your Network
The network list shows all the users (devices) that have connected to the same Channel. For each entry, it shows the last time they were active, their distance, and their last known power status (battery & percentage, or external power). In the example below, Eddie is the local user, Mike is active and 29m away, and a third node has been inactive since 9:02pm.
This is a list of network nodes, rather than users, so where there is a named user connected to the device, you will see the user name, otherwise the node is shown as Unknown a3c9 (where a3c9 is the last 4 hex digits from the MAC address.)
View the map
ToDo - any map symbols other details?
The Map tab will show a local map with an icon for each active mesh node that has a known position. The users names are shown against the icon.
The map is not developed by the Meshtastic project, and the source of the maps is Mapbox (free-tier), and the map data is sourced from OpenStreetMap OSM. There is currently (January 2021) no off-line maps (phone needs mobile data), although this will be improved in the future. If you don't see the features that you'd expect on the map then head over to OpenStreetMap OSM where you can contribute new data to the map.
Advanced Tasks
Configure a Channel
ToDo - different modes and configuration, more technical details
Various data-rates are selectable when configuring a channel and are inversely proportional to the theoretical range of the devices:
| Channel setting | Data-rate |
|---|---|
| Short range (but fast) | 21.875 kbps |
| Medium range (but fast) | 5.469 kbps |
| Long range (but slower) | 0.275 kbps |
| Very long range (but slow) | 0.183 kbps (default) |
Troubleshooting
Debug Panel Todo
Multiple Users, multiple devices Todo - switching between devices, effect on message history, etc
Pairing Pairing To Do - device screen when pairing. No screen
Permissions The application will need access to your Location, and should be permitted as "Allow all the time", and to Notifications. These permissions are required as the application will "listen" for incoming messages from the radio device in the background.
Learn More
ToDo
- Point to the reference documentation.
- Point to the relevant parts of the community documentation.
- Mention support is only community, open source.
- Point to other resources.
If you'd like to take part in testing the latest software as it being developed, you can join this Google group and then go here to opt-in to alpha testing for the latest version of app.
Links
Meshtastic Project
- https://meshtastic.discourse.group/ Discussion group - get more info & ask questions here.
- https://github.com/meshtastic/Meshtastic-Android/wiki Github for this Android application.
- https://github.com/meshtastic/Meshtastic-device/wiki Github for the radio device application.
- https://github.com/meshtastic/Meshtastic-device/wiki/Hardware-Information Device and hardware reference
Technology
- LoRa on Wikipedia
- Mapbox Source of the mapping application.
- OpenStreetMap OSM Source of the map data.