Skip to content

getting-started.md

Latest commit

 

History

History
137 lines (90 loc) · 3.64 KB

getting-started.md

File metadata and controls

137 lines (90 loc) · 3.64 KB
Raw

Getting Started

Source: README.md, FAQ

Minimum Requirements

You only need one device to get started — a single MeshCore node can already send and receive messages within LoRa range. Multiple nodes extend the network range through multi-hop routing.

Option 1: Flash Pre-Built Firmware (Recommended)

The easiest way to get started is the MeshCore Flasher:

  1. Visit https://meshcore.io/flasher
  2. Connect your supported LoRa device via USB
  3. Select your board and firmware type
  4. Click Flash

No development environment required.

Option 2: Build from Source (PlatformIO)

For custom development or unsupported boards.

Prerequisites

Steps

# Clone the repository
git clone https://github.com/meshcore-dev/meshcore.git
cd meshcore

# Open in VS Code
code .

In PlatformIO, select the environment matching your board from platformio.ini and click Upload.

Local Documentation Build

pip install mkdocs mkdocs-material
mkdocs serve   # Development server with live reload
mkdocs build   # Build static site

Firmware Types

Choose the firmware type that fits your use case:

Firmware Connection Use Case
Companion Radio BLE, USB Serial, WiFi Connect external chat apps (mobile, web)
KISS Modem USB Serial Bridge for host applications
Simple Repeater No UI Extend network coverage
Simple Room Server No UI BBS-style shared message board
Simple Secure Chat USB Serial (terminal) Encrypted terminal-based messaging
Simple Sensor No UI Remote telemetry and alerting

See applications.md for detailed descriptions.

Initial Configuration

After flashing, configure your device via the CLI (serial connection at 115200 baud) or the companion app:

# Set node name (max 24–32 bytes depending on board)
set name MyNode

# Set radio frequency (MHz)
set freq 868.0

# Set GPS location (optional)
set lat 48.1351
set lon 11.5820

# Send initial advertisement
advert

Default credentials:

  • Admin password: password
  • Guest password: hello

Important: Change the admin password after first setup.

password

(Enter the command, then you will be prompted for the new password)

Client Applications

Once your Companion Radio firmware is running, connect with any of these clients:

Platform Client Link
Web MeshCore Web App https://app.meshcore.nz
Android MeshCore Android Google Play Store
iOS MeshCore iOS Apple App Store
Node.js meshcore.js by Liam Cottle https://github.com/liamcottle/meshcore.js
Python meshcore-cli https://github.com/fdlamotte/meshcore-cli

See clients.md for details.

OTA Updates

ESP32 Devices

OTA updates are supported via the companion app or web interface.

nRF52 Devices

OTA firmware updates are performed via DFU mode. Instructions are available in the FAQ.

Troubleshooting

  • Bluetooth not connecting: Try restarting both the device and the app. Check the FAQ for platform-specific steps.
  • Device in boot loop: Erase the device and reflash. See the FAQ for recovery procedures.
  • Serial not connecting: Verify baud rate is 115200, 8N1, no flow control.