Android Application Usage

Introduction

The Meshtastic Android app handles the communication and can show the location of everyone in your private group. Each member of your private mesh can see the location and distance of members and text messages sent to your group chat.

Open the app and you should see the Settings tab like the screen above. Notice the cloud with a slash through it in the upper right, showing no device connection. 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 getting started section for information on how to do this.

To find devices to connect via Bluetooth click the "+" button on the bottom right corner. Devices connected via Wi-Fi or Ethernet using the same network as your phone should be found automatically, or can be manually selected by entering its IP address. If you connect the device via USB OTG to your phone, it will be found automatically.

1. Select the device name, Meshtastic_769d in this example. (You will see devices within range, so make sure to get the right one.)
2. Before you can connect for the first time, you need to "pair" the devices to allow communication between them. Some devices are pinless, others require entering a PIN shown on the device screen.
   note

   If the device was flashed without a screen connected, it will automatically default to a pairing PIN of '123456'. If it was booted with a screen once, the config is set to random pin. If you remove the screen afterwards, it stays like this. Either set it to use the default pin manually, or factory reset it and it will revert to '123456' after the next boot.

3. This starts the communication with the device. The cloud icon on the status bar should change and show a check mark.

The cloud icon at the top right corner indicates if you are connected to a device. This currently has three states:

Cloud with a slash through it: No device connected to the application.

Cloud with a check in it: Device connected to the application.

Cloud with an up arrow in it: Device is connected, but currently sleeping or out of range.

Common tasks

Set your region

In order to start communicating with your mesh, you must select a region. This setting controls which frequency range your device uses and should be set according to your location. See Region Settings for a list of region codes and their meanings.

• Tap on the "Region" dropdown in the top-right corner and make the appropriate selection.

Change your name

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. Initials, or "short name", can be customized in the Radio configuration - User settings. The four characters displayed after your initials cannot be changed. These are the last four hex digits of the device MAC address. Devices with unset names will display these four characters as the device short name.

Setup a channel

If you have been sent a QR code or link for Meshtastic, then skip ahead to Join a Channel. Devices have a default channel preconfigured, shown as #LongFast-I (Long range / Fast). It is OK to use this channel if you want your node to be visible to all Meshtastic users (within range) who are using the default channel.

You can also create a new 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.

The Channel tab allows you to create a new private mesh. 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 Long Range / Fast, and then made 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. 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, or email. The link is a very long code, for example: https://www.meshtastic.org/d/#CgUYAyIBAQ

Join a channel

1. If another user shares a QR code, you will be able to scan it directly with your camera using the Scan button.

   

2. If the channel is shared from a file or link using the Share button, you can click on the file or link and you need to choose "Open with Meshtastic".

If a QR or URL opens a webpage instead of the APP or "Open with Meshtastic" is not an option:

1. Go to Android Settings > Apps > Default apps > Meshtastic > Opening links
2. Make sure you have in "links/web address": www.meshtastic.org
3. If you see the option "Open the supported links", make sure it is enabled.

Proceed 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!

note

Setting the same Name and Options directly doesn't work as there are other radio settings (like the unique pre-shared key) encoded in the QR code or link.

You can test changing channels with the QR code shown below.

Adjust a channel

You can change the following settings by tapping on the name of an existing channel:

1. MQTT Uplink
2. MQTT Downlink
3. Position enabled
4. Precise location (if position is enabled)
5. Position precision (if precise location is disabled)

Position Precision

The precision levels currently used in the app correspond the values in the table below. These can be thought of as the radius of a circle around a point (not your current location) which you are within.

Metric	Imperial
23.3 km	14.5 miles
11.7 km	7.3 miles
5.8 km	3.6 miles
2.9 km	1.8 miles
1.5 km	4787 feet
729 m	2392 feet
364 m	1194 feet
182 m	597 feet
91 m	299 feet
45 m	148 feet

Send a message

The message window operates like most messaging apps. Note that your primary channel i.e. LongFast contact is always shown and works as a group chat. Other contacts are for direct messaging, or private group chats.

• Long press contacts or messages for options, like delete.
• Press a node from the Nodes tab to send Direct Messages.

With LoRa (or any radio) there is some uncertainty that the message has been received, so there is a confirmation built-in to the protocol. There are small icons shown to the right of the messages you send:

Cloud with an up arrow: the message is queued in the app, waiting to be handed to the device.

• Cloud only: the device received the message from the app, and it has been sent and transmitted via LoRa.

• Cloud with a check mark: received at least one node's acknowledgement response. Confirmations could be from any one device.

• Person with a check mark - The intended recipient node of your direct message acknowledged the message.

• Cloud crossed out: the initial sender did not receive any confirmation within a certain timeout.

By default there is no long-term store-and-forward of messages, so messages not received during transmission 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 location and distance (when available), and their last known power status. In the example above, Monkey is the local user, Rabbit was last heard from 10 minutes ago and is 50m away, and Panda was last heard 11 minutes ago and 5m away.

• Tap on a node in the list to show more details about the node. A Show Details toggle is in the filter menu.
• Tap on a node's colored chip to start Direct Messaging, request a position update, request a traceroute or add it to your Ignore Incoming Array.
• Tap on a node's location coordinates to open in your maps application, long press to copy the coordinates to your clipboard.
• If you have an Admin Channel enabled on your devices, tapping on the node's colored chip will also display an option to remotely configure the node.

View the map

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 above the icon.

• Clicking the layers icon in the top-right will allow you to select the map type.

Offline maps

• Some map types allow downloading for offline use. If offline maps are available for your selected map type, a download icon will appear in the bottom-right corner of the map. Tap this icon and choose the option to Download Region, then select the area you wish to download.

Configuration options

Pressing the three vertical dots in the top right corner shows the configuration menu.

Debug Panel

The debug panel allows you to see all packets sent between the application and the device. This can be useful for debugging purposes.

Radio Configuration

Radio Configuration opens a list of all radio and module configuration settings.

• See Radio Config for radio settings.
• See Module Config for module settings.
• At the end of this list are buttons for Reboot, Shutdown, Factory reset, and NodeDB reset.

Export rangetest.csv

Allows you to save all your network's position data with GPS coordinates into a .csv (comma separated value) file on your phone. This file can be imported into the spreadsheet application of your choice for easy viewing. This feature is similar but independent from the device range test module, and results may differ.

To reset the values go to the Debug Panel and press the "Clear" button.

Theme

Allows you to change between light and dark themes, or to select the system default.

Language

Allows you to select a language for the application's user interface.

Show Introduction

Opens the introduction slideshow.

Quick chat options

Brings up an editor to create and edit quick response messages. These will appear as buttons in the chat window. Messages have the option to send instantly, or be appended to your message and sent manually.

About

Displays the current app version.