Configuring MeshCore¶

What to Deploy¶

If you're new to ChiMesh and not sure what to set up, the ideal starting deployment is:

• A repeater on your roof (or as high as you can get it) to maximize line of sight coverage
• A companion node for day to day messaging indoors and outdoors

Line of sight is king in LoRa mesh networking. Walls, floors, and buildings dramatically reduce range. A rooftop repeater gets you above the obstructions and provides a strong signal path to your companion indoors, as well as connecting you to the broader mesh. This matters especially in dense urban environments where buildings block signals that would otherwise reach you more easily in the suburbs.

Companion vs. Repeater/Room Server¶

How you configure your node depends heavily on its role:

• Companion nodes are configured entirely through the MeshCore companion app over Bluetooth. There is no USB configuration step, and there is no CLI available during normal use. Most of the settings below apply only to repeaters and room servers.
• Repeater and Room Server nodes are typically configured via USB serial connection using the MeshCore Configuration Tool, especially for initial setup. CLI commands are available through the Remote Management interface.

If you're setting up a companion, skip the USB and CLI sections below.

Initial Configuration¶

1. Power on your device after flashing
2. Visit the MeshCore Configuration Tool in your web browser
3. Connect to your device using one of the available methods:
   • USB serial connection (recommended for initial setup of repeaters/room servers)
   • Bluetooth pairing (if using BLE companion firmware)
4. Configure basic settings through the web interface:
   • Set your node name (consider adding "ChiMesh.org" to help identify our community)
   • Location (optional)
   • Change the admin password
   • Go to "Radio Settings" and set "Preset" to "USA/Canada (Recommended)"

Radio Settings¶

Configure your device using the USA/Canada (Recommended) preset, which includes the following settings:

Required Commands¶

Companion Node¶

A companion node travels with you and does not repeat traffic. Companions are configured through the companion app UI, the CLI commands used for repeaters are not available on companion nodes during normal use.

For companions, path hash mode is found under the Experimental Settings menu in the app, and there are no periodic advertisement intervals to configure.

Repeater Node¶

An infrastructure or well placed node repeats traffic to extend network coverage.

set path.hash.mode 2

set repeat on

set advert.interval 240

set flood.advert.interval 72

reboot

Channels¶

MeshCore supports named channels that allow you to communicate with specific groups of users. Channels use a shared secret key for encryption. Anyone with the same key can send and receive messages in that channel.

How Channel Keys Work¶

There are two types of channels:

Hash channels (names beginning with #): When you create or join a channel by name, MeshCore automatically derives a secret key from that name using a cryptographic hash function. This means:

• The channel name is run through a one-way algorithm that always produces the same fixed-length key for a given name
• Anyone who enters the same channel name on their device gets the identical secret key, no manual key sharing required
• #chicago will always generate c1c289b131e5222370cbc2048445844b, on every device, every time
• You cannot reverse the key back to the channel name

This is why sharing a hash channel name is equivalent to sharing access, the name is the key, just in human-readable form.

Private channels: You can also create a truly private channel, which generates a random secret key that is not derived from the name. This key must be shared manually between users (e.g., via QR code or direct copy). Private channels cannot be joined by name alone.

Adding a Channel¶

1. Open the MeshCore app menu
2. Navigate to Add Channel → Scan QR Code (or enter the secret key manually)
3. Enter the channel name or paste the secret key
4. Tap Add, your device will derive or store the key and join the channel

Popular Community Channels¶

The following channels are commonly used in the MeshCore community. Hash channels can be added by entering the channel name (MeshCore will derive the key automatically) or by entering the secret key directly.