Companion guide¶

This guide should help you configure a Meshcore "companion", which you need to communicate with other people on the mesh.

Companions must be able to talk with a repeater connected to the mesh to talk with other companions, unless companions are within range. If there's no repeater in your area, you should consider setting one up following the repeater guide!

Hardware¶

Pick a device in our hardware review notes or the Meshtastic hardware list¹.

It's cheap! Expect to pay 50$CAD for a starter kit or 100$CAD for a good companion.

Tip

If the device you picked comes with a removable antenna, make sure you connect the antenna before powering up the device. A radio that transmits without an antenna can damage itself!

Software¶

Now you own a LoRa transceiver, congratulations! The next step is to make sure it runs Meshcore by installing firmware on it, and that you can talk to the device, typically by installing an app on your phone.

Flash the firmware on the device¶

First you need to flash your device, which essentially means connecting to the following website.

https://flasher.meshcore.io

Tip

If you picked a standalone companion like the Lilygo T-Deck or T-Lora pager, or the Heltec v4 expansion kit, you might want to take a look at Wadamesh as well. The stock firmware GUI (Ripple) is hard to use and proprietary, while Wadamsh is free software, although coded with the Claude LLM.

Your web browser must support the Web Serial API, which includes Chrome (and derivatives) and Firefox 151 or later.

You may skip this step if it comes flashed with Meshcore already.

Connect your device to your computer using a USB cable. Note that for some USB-C cables, you might need to flip the cable over for the connection to work. A good hint is whether the device is charging or not from your laptop: if it isn't, it means it likely isn't connected correctly.

On many devices, you need to enter some special mode for flashing to work. Here are examples:

Heltec: hold the "program" (PRG) button while connecting the USB cable. For the Heltec v4, it will show up as a JTAG device. On the Heltec v3, it will show up as a CP2102 USB to UART Bridge Controller.
RAK: double-click the reset button will bring it in "DFU" mode, but the web flasher should also be able to do that automatically.

Important

You will have the option to flash a "Bluetooth" of "Serial" companion. You should typically choose "Bluetooth" unless you want to connect to the device over the USB cable. Those are exclusive: a Bluetooth device cannot be accessed over serial and vice-versa.

Proprietary software warning

While most Meshcore firmware is free software (the meshcore-dev/MeshCore repository, the T-Deck firmware is proprietary. Awesome MeshCore lists a few alternatives.

During first boot, the device will display the message:

Loading...

... for a solid minute, that is normal.

Backing up before flashing¶

If you're flashing an already configured device, you should backup before flashing it.

On the Meshcore you want to:

go into Settings (the "gear" icon)
go into Export Config
hit Select All
hit the check mark
save the file somewhere safe

Normally, flashing a Meshcore device with a newer version should be safe and your settings should be kept, but it's always good to backup your configuration anyways, and this can be used to copy your configuration to another device as well.

If you're flashing over a Meshtastic device, backups can be done by exporting the configuration in the Meshtastic app settings, or with the Meshtastic command line tool:

meshtastic --export-config > devicename.yaml

Install an app¶

Unless you picked a standalone device, now you'll need something to talk with people on the mesh. Unless you use a standalone device, this means installing software on your phone.

You can try that from your computer with a web browser by using Liam Cottle's web app. There are also iOS and Android versions and a pretty good Linux desktop app called Meshy.

Proprietary software warning

The official Meshcore app is proprietary software that do not publish their source code and require a subscription or a 10 second wait time for certain features.

You can work around some of those problems by installing the open app which requires going through Obtainium on Android or test flight. It's a little complicated, so don't venture there unless you get frustrated with the official apps. The open app also lacks a few features from the official one, namely:

Note that an active fork fixes many of those issues.

To connect your phone to the device, you need to find the right device in your list, which can be challenging if you are in an environment with lots of Bluetooth devices.

Pick the device name that looks like the alphanumeric identifier displayed at the top left of the display.

The Bluetooth PIN should also be displayed, bigger, and in the center, as a string of 6 digits. That is different from the device name, which will have letters in it, and is only used in pairing.

The device name on the top left, however, identifies the device over the airwaves, both on the Mesh and Bluetooth.

Configuration¶

The main configuration you need to do on the device is set the preset, but you should also pick a display name.

Radio settings: "recommended USA / Canada", see the frequencies question for details
Display name: your name, YUL-Area for a repeater, for example YUL-Villeray, YUL-Parc-Extension, etc
Region: do not set a region, as we currently do not use one, and it will interfere with routing
Path hash mode: pick 3-byte (2) or 2-byte (1), see this question in the FAQ and the tip below

Warning

Some Meshcore configurations exposes your location by default on devices which have a GPS device! To work around this problem, you can disable the GPS or reduce the coordinates precision, we recommend two digits (~1km) for clients and 3 digits (~100m) for repeaters.

Tip

We are now telling users to set multi-byte path routing even though upstream still doesn't recommend that. The upstream rationale is that multibyte messages just get dropped by older releases, but we have long passed that threshold. In fact, we believe the mesh cannot function correctly with single-byte repeaters, so every repeater must set a multibyte path hash mode.

Setting a multibyte path hash mode on your companion should improve the reliability of your direct messages (DMs). Because DMs are routed (as opposed to channel messages and adverts that are flooded), it is crucial that the right path is taken. In single-byte configuration, that single byte is ambiguous and can refer to multiple conflicting repeaters. So an advert you receive that might tell you to go through a specific set of repeaters might actually tell your companion to use a really bad route for a contact.

If you're having trouble with DMs, try setting multibyte path hash mode!

You made it! Say hi!¶

At this point, your companion should be properly configured.

Introduce yourself! Say "hi!" on the "Public" channel.

Explain what device did you setup, where's your general area, what's the weather like, etc. Be kind, reply to people, participate!

If no one answers, try the #bots channel and send ping or test. See also the channels list.

Meshtastic-supported device are often (but not always!) also working under Meshcore. ↩