DOCSEARCHbyAlgolia
Submit Docs

MeshCore Documentation

repository·main·Indexed 23 days ago

https://github.com/meshcore-dev/meshcore

A lightweight, portable C++ library for multi-hop packet routing in embedded projects using LoRa and other packet radios. Designed for decentralized, resilient, and low-power wireless mesh networks for IoT, emergency, or off-grid applications. Includes documentation on firmware flashing, client integration, CLI commands for node management, and integrated tools like uf2conv for firmware conversion and littlefs for fail-safe embedded filesystem management.

Tokens
36.3K
Snippets
68
Records
197
Agent score
36%

What's inside MeshCore

  1. Overview of littlefs

    main

    littlefs is a fail-safe filesystem designed for embedded systems with the following characteristics:

    • Bounded RAM/ROM: Designed for limited memory environments. It avoids recursion and limits dynamic memory usage to configurable buffers that can be provided statically.
    • Power-loss resilience: Uses strong copy-on-write guarantees to ensure storage remains in a valid state even during random power failures.
    • Wear leveling: Provides dynamic wear leveling for erodible flash memories, making it suitable for systems that cannot accommodate a full flash translation layer.

  2. Understand Channel Types and Security

    main

    MeshCore supports three types of channels with different security models:

    1. Public Channel:

      • Uses a publicly known 16-byte key: 8b3387e9c5cdea6ac9e5edbaa115cd72.
      • Anyone can join; messages are considered public.

    2. Hashtag Channels:

      • Uses a secret key derived from the channel name (the first 16 bytes of sha256("#name")).
      • Traffic is encrypted on air, but anyone who knows the hashtag can derive the key. Not suitable for private communication.

    3. Private Channels:

      • Uses a randomly generated 16-byte secret key.
      • Messages are secure between those who know the secret.

  3. Understand MeshCore Payload Types

    main

    MeshCore packets contain a payload identified by a type in the packet header. Common payload types include:

    • Node advertisement: Notifies receivers of a node's existence.
    • Acknowledgment: Confirms message receipt.
    • Returned path: Describes the route a packet took.
    • Request: Contains destination/source hashes and MAC.
    • Response: Reply to a REQ or ANON_REQ.
    • Plain text message: Standard unencrypted or signed text.
    • Anonymous request: Requests made without a standard encrypted wrapper.
    • Group messages: Unverified group text or datagrams.
    • Control/Multi-part/Custom: Specialized packets for system control or raw bytes.

    Note: All 16 and 32-bit integer fields use Little Endian byte order.

  4. Build MeshCore firmware from source

    main

    To build MeshCore firmware, follow these steps based on your OS:

    1. Install Dependencies

    Linux / Windows (via WSL):

    sudo apt update
sudo apt install libpython3-dev
sudo apt install python3-venv

    Mac: python3 should be pre-installed.

    2. Environment Setup & Build

    Run these commands on all platforms:

    python3 -m venv meshcore
cd meshcore && source bin/activate
pip install -U platformio
git clone https://github.com/ripplebiz/MeshCore.git
cd MeshCore

    3. Configuration & Compilation

    1. Open platformio.ini.
    2. In the [arduino_base] section, edit LORA_FREQ=867.5.
    3. Save and run the build command (example for RAK 4631):
    pio run -e RAK_4631_Repeater

    The resulting firmware will be located in .pio/build/RAK_4631_Repeater/firmware.zip.

    python3 -m venv meshcore
cd meshcore && source bin/activate
pip install -U platformio
git clone https://github.com/ripplebiz/MeshCore.git
cd MeshCore
pio run -e RAK_4631_Repeater

  5. Manage USB serial devices via picocom

    main

    To manage a repeater or room server connected to a Raspberry Pi via USB serial, install and use picocom:

    1. Install: sudo apt install picocom
    2. Connect: picocom -b 115200 /dev/ttyUSB0 --imap lfcrlf

    Once connected, you can use the MeshCore CLI commands.

    sudo apt install picocom
picocom -b 115200 /dev/ttyUSB0 --imap lfcrlf

  6. Optimize LoRa transmission parameters (BW, SF, CR)

    main

    When configuring LoRa transmissions, you can balance speed and noise resistance using these parameters:

    • BW (Bandwidth): The width of the frequency spectrum. Increasing BW (e.g., from BW125 to BW250) allows sending 2x more bytes in the same time.
    • SF (Spreading Factor): Controls how much communication spreads in time. Lowering SF (e.g., from SF10 to SF9) allows 2x more bytes in the same time but makes the receiver more sensitive to noise.
    • CR (Coding Rate): Forward Error Correction (FEC) that adds redundant bits to restore corrupted data.

    Recommendation:

    • Default to CR 5 for stable links.
    • If the link is intermittent or unstable, increase CR to 7 or 8.

  8. Build and view MeshCore documentation locally

    main
    To build and view the MeshCore documentation on your local machine, you need to install mkdocs and the mkdocs-material theme using pip. Once installed, you can either start a live-reloading server for development or build a static documentation site.

  9. Add a MeshCore Channel via QR Code URL

    main

    You can share MeshCore channels using a specific URI scheme. This format is supported by the MeshCore mobile app for quickly adding channels to a user's device.

    URL Format: meshcore://channel/add?name=<name>&secret=<secret>&region_scope=<region_scope>

    Parameters:

    • name: The channel name (must be URL-encoded).
    • secret: The 16-byte secret, represented as 32 hex characters.
    • region_scope: (Optional) The region scope (must be URL-encoded if provided). Supported by MeshCore App v1.47.0+.
    meshcore://channel/add?name=Public&secret=8b3387e9c5cdea6ac9e5edbaa115cd72

  10. Update ESP32-based devices (e.g. Heltec V3) via OTA

    main

    ESP32-based devices use a Wi-Fi hotspot method for Over-the-Air updates.

    Steps:

    1. Download the non-merged version of the firmware (e.g., Heltec_v3_repeater-v1.6.2-4449fd3.bin — ensure it does not contain the word merged) from https://flasher.meshcore.io.
    2. In the MeshCore app, log in remotely to the repeater with admin privileges.
    3. In the Command Line tab, run: start ota.
    4. Once you see OK, the device will start a Wi-Fi hotspot named MeshCore OTA.
    5. Connect your phone or computer to the MeshCore OTA hotspot.
    6. Open a browser and navigate to http://192.168.4.1/update.
    7. Upload the non-merged .bin file to complete the update.
    start ota

  11. Configure a repeater or room server

    main

    When flashing MeshCore onto a LoRa device for the first time, you must set the server's frequency to comply with local regulations. You can administer a repeater or room server using one of these methods:

    1. Web UI: Connect to the device via USB serial at https://config.meshcore.io to set the name, frequency, location, and passwords.
    2. Flasher Console: Connect the device via USB to a computer running Chrome and use the console feature at https://flasher.meshcore.io.
    3. Smartphone Client: Use a MeshCore smartphone client to administer servers remotely via LoRa.
    4. T-Deck: Use a T-Deck running unlocked/registered MeshCore firmware (requires registration with Ripple Radios).

  12. Request device statistics using CMD_GET_STATS

    main

    To retrieve statistics from a MeshCore device, send the CMD_GET_STATS command (code 56). The command requires a 2-byte frame where the first byte is the command code and the second byte is the requested sub-type.

    Stats Sub-Types:

    • STATS_TYPE_CORE (0): Core device statistics
    • STATS_TYPE_RADIO (1): Radio statistics
    • STATS_TYPE_PACKETS (2): Packet statistics
    # Send command to get core stats
def send_get_stats_core(serial_interface):
    cmd = bytes([56, 0])  # CMD_GET_STATS (56) + STATS_TYPE_CORE (0)
    serial_interface.write(cmd)

# Send command to get radio stats
def send_get_stats_radio(serial_interface):
    cmd = bytes([56, 1])  # CMD_GET_STATS (56) + STATS_TYPE_RADIO (1)
    serial_interface.write(cmd)

# Send command to get packet stats
def send_get_stats_packets(serial_interface):
    cmd = bytes([56, 2])  # CMD_GET_STATS (56) + STATS_TYPE_PACKETS (2)
    serial_interface.write(cmd)