VBMesh Logo 
 ___      ___  ________   _____ ______    _______    ________   ___  ___        ________    _______   _________   
|\  \    /  /||\   __  \ |\   _ \  _   \ |\  ___ \  |\   ____\ |\  \|\  \      |\   ___  \ |\  ___ \ |\___   ___\ 
\ \  \  /  / /\ \  \|\ /_\ \  \\\__\ \  \\ \   __/| \ \  \___|_\ \  \\\  \     \ \  \\ \  \\ \   __/|\|___ \  \_| 
 \ \  \/  / /  \ \   __  \\ \  \\|__| \  \\ \  \_|/__\ \_____  \\ \   __  \     \ \  \\ \  \\ \  \_|/__   \ \  \  
  \ \    / /    \ \  \|\  \\ \  \    \ \  \\ \  \_|\ \\|____|\  \\ \  \ \  \  ___\ \  \\ \  \\ \  \_|\ \   \ \  \ 
   \ \__/ /      \ \_______\\ \__\    \ \__\\ \_______\ ____\_\  \\ \__\ \__\|\__\\ \__\\ \__\\ \_______\   \ \__\
    \|__|/        \|_______| \|__|     \|__| \|_______||\_________\\|__|\|__|\|__| \|__| \|__| \|_______|    \|__|
                                                       \|_________|

VBMesh.net

Tips

  • Because most meshtastic devices are low power, they can be a little slow. Be patient when applying settings.
  • Changing most settings will trigger a reboot of your device upon saving, wait for that to finish before moving to other steps.
  • It is best to reconnect your client after a reboot. When using the Web Client, wait for it to confirm saving the setting, then simply refresh the page and reconnect.
  • After reconnecting, double check the settings you just changed.

Step 1: Flashing A New Device

When setting up a brand new device, it is best to start by flashing the latest firmware and then factory resetting the device. When deciding what firmware version to pick, the latest beta will be the most stable. But, for recently released devices, you may need the latest alpha version to fully support your device. You can read through the full changelog for each version on Meshtastic's Firmware Github

To flash your device go to the Meshtastic Web Flasher, select your device,the firmware version and click "flash". A changelog dialog may pop up that you will need to scroll past to click "continue". Once on the flashing dialog, follow it's instructions. If your device supports "Full Erase and Install", it should be enabled to ensure any older settings for older firmware do not impact operation on the new firmware.

Once the device has been flashed it should reboot.

After reconnecting, if your device did not have a "Full Erase and Install" option, perform a "Factory Reset".

With your device connected to your computer over USB Serial, open the Meshtastic Web Client and start a Serial connection.

Navigate: Command Menu → Factory Reset

Step 2: Giving The Device a Name

Many guides start by setting the LoRa Region and Preset, and while this is the fastest way to get started, it isn't the most ideal set up. There are some settings that should be changed before your node announces itself to the world.

With your device connected to your computer over USB Serial, open the Meshtastic Web Client and start a Serial connection.

Navigate: Change Device Name

Long Name
The full name of your node.
Short Name
A short (max 4 character) name for your node.

Click: Save

Choose a name that uniquely identifies your device on the mesh. If you'd like to stay mostly anonymous on the mesh, leaving the default name is totally OK. Generic names like "My Client" or "Car Node" should be avoided unless you include a random extra set of characters to differentiate your node from anyone else who may also choose a simialr name. For extra fun, Long and Short Names support unicode emojis!

When choosing a name for an infrastructure node, please include something that can identify who maintains the node. That way if there are issues, the maintainer can be notified.

Step 3: Setting Up Bluetooth

Bluetooth is the most common low power way of connecting to a node.

Navigate: Config → Radio Config → Bluetooth

Enabled
On
Pairing Mode
Fixed Pin
PIN
A random 6 digit PIN.

Click: Save

Do not use an easy to guess PIN like 000000 or 123456.
Save your PIN in a password manager for safe keeping.

Step 4: Generating a New Private Key

It is important to ensure your node has a unique and securely generated private key. This is because your private/public keypair is how other clients know your node is owned by you.

Navigate: Config → Radio Config → Security

Click: Generate button

Click: Save

Never share your private key with someone.
Backup your private key by clicking the Backup Key button, or copy-pasting into a password manager. This is useful if you ever need to factory reset your device.

Setting up Remote Administration is a great way to maintain Infrastructure nodes that may not be easily accessible. To set this up, enter your primary client's PUBLIC key into one of the Admin Key settings.

At one point, device manufacturers has mistakenly pre-configured their devices with the same private key. This meant there were tons of devices with the same private key, breaking their security. This is partly why it is best to factory reset a new device and manually generate a new key.

Step 5: Joining The Mesh

It is finally time to enable your radio and join the mesh!

Be sure an antenna is connected to your device. Transmitting without an antenna attached can damage your radio.

Navigate: Config → Radio Config → LoRa

Region
US
Use Preset
On
Preset
Long Fast
Frequency Slot
0
Hop Limit
3, 4, or 5
Prefer a lower hop limit if you know there are lots of nodes near you.
Transmit Enabled
On
Transmit Power
30
Your device will adjust to it's max transmit capability.
Boosted RX Gain
On
OK to MQTT
On or Off
If you want your node to appear on the public maps, this needs to be On.

Click: Save

If you set a hop limit above 3, be prepared to eventually adjust it as the mesh grows and more congestion appears.

Step 6: MQTT / Showing Up on Public Maps

MQTT is a risky feature to enable, and misconfigured devices can flood their local LoRa mesh with messages. Even a minimal amount of MQTT traffic can severly impact other user's ability to use the mesh.

This step will present a number of options to safely configure your device for MQTT. For a given device, choose one option and follow it exactly. Do not mix-and-match settings from multiple options.

If your client is near an existing MQTT gateway, you do not need to directly connect your client to MQTT. If you are not near an MQTT gateway, you will need to set one up.

Navigate: Config → Radio Config → Lora

Ok to MQTT
On
This tells other MQTT gateways that your messages are OK to forward to MQTT.

Navigate: Config → Channel Config → Primary

Uplink
Off
Downlink
Off
Location
On
Precise Location
Off
Precision
700m or wider
Using a location precision smaller than 700m will prevent you from showing up on the public maps. This is a safety feature to protect your privacy.

An MQTT gateway is a device that forwards messages from it's local LoRA mesh to an MQTT broker. It listens for all OK-to-MQTT messages, and forwards them. This is an advanced option that is safe for most device roles.

Navigate: Config → Radio Config → Device

Role
any

Navigate: Config → Radio Config → Lora

Ok to MQTT
On

Navigate: Config → Module Config → MQTT

Enabled
On
Server Address
mqtt.vbmesh.net
Username
meshdev
Password
large4cats
Encryption Enabled
On
JSON Enaled
On or Off
TLS Enaled
Off
Root Topic
msh/US/VA/VBMesh
MQTT Client Proxy Enabled
On or Off
Enable this if your device's connection to the Internet is through your phone.
Map Reporting
On or Off
Only enable this if you want your MQTT gateway to appear on public maps.

Navigate: Config → Channel Config → Primary

Uplink
On
This is the key setting that allows your device to forward to the MQTT broker
Downlink
Off
This setting must be off. Check it multiple times.
Location
On or Off
Precise Location
Off
Precision
700m or wider
Using a location precision smaller than 700m will prevent you from showing up on the public maps. This is a safety feature to protect your privacy.

This is the most dangerous option, misconfiguration here can impact all devices on your local LoRa mesh.

In order to not only send, but also view MQTT traffic, you will need to enable MQTT downlink. This instructs your device to treat MQTT messages as routable, and if you are in a role other than CLIENT_MUTE, your device will route MQTT messages onto the LoRa mesh. This can create a ton of congestion and degrade the service for every device around you.

Navigate: Config → Radio Config → Device

Role
CLIENT_MUTE
This is the only safe role for a full MQTT client. Any other role will leak MQTT traffic onto LoRa.

Navigate: Config → Radio Config → Lora

Ok to MQTT
On

Navigate: Config → Module Config → MQTT

Enabled
On
Server Address
mqtt.vbmesh.net
Username
meshdev
Password
large4cats
Encryption Enabled
On
JSON Enaled
On or Off
TLS Enaled
Off
Root Topic
msh/US/VA/VBMesh
MQTT Client Proxy Enabled
On or Off
Enable this if your device's connection to the Internet is through your phone.
Map Reporting
On or Off
Only enable this if you want your MQTT gateway to appear on public maps.

Navigate: Config → Channel Config → Primary

Uplink
On
Downlink
On
Be sure your device role is CLIENT_MUTE. Check it multiple times.
Location
On or Off
Precise Location
Off
Precision
700m or wider
Using a location precision smaller than 700m will prevent you from showing up on the public maps. This is a safety feature to protect your privacy.