MeshCore sim v2

Option 1: Local Install

System dependencies (Debian/Ubuntu)

  sudo apt install build-essential cmake libssl-dev liblua5.4-dev python3 python3-venv

Clone and build

git clone --recursive https://github.com/stachuman/meshcore_simv2.git
cd meshcore_simv2
cmake -S . -B build && cmake --build build

Python env (needed for visualization and topology tools)

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

Run a simulation with visualization:

source venv/bin/activate
./tools/run_sim.sh test/t06_msg_stats.json

This opens two browser tabs — a swim-lane event timeline and a geographic map view. Note this visualization is a simplified version of webapp, therefore it is recommended to use webapp for visual working and scripts - for processing large amount of simulations.

Start the web app (optional):

cd webapp
pip install -r requirements.txt
uvicorn server.main:app --port 8000

Open http://localhost:8000 — create topologies from live MeshCore network data, edit configs visually, run simulations, and view results in the browser.

Option 2: Docker

Requires a Linux x86_64 machine with Docker.

Build the image (on your dev machine):

git clone --recursive https://github.com/stachuman/meshcore_simv2.git
cd meshcore_simv2

(--recursive - that will enable pulling also MeshCore firmware - which is required to build simulator)

Build the optimized orchestrator binary

sudo apt install build-essential cmake libssl-dev liblua5.4-dev
cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release
cmake --build build-release --target orchestrator -j$(nproc)

Build the Docker image

cd webapp && docker compose build

Run locally:

docker compose up -d

Deploy to another machine (VPS, etc.):

On build machine — export image

docker save meshcore-sim:latest | gzip > meshcore-sim.tar.gz
scp meshcore-sim.tar.gz user@target-ip:/path/

On target machine — load and run

docker load < meshcore-sim.tar.gz
docker run -d --name meshcore-sim \
      -p 8000:8000 \
      -v meshcore-data:/app/data \
      --restart unless-stopped \
      meshcore-sim:latest

Where meshcore-data needs to point for the local storage

Open http://target-ip:8000. Simulation data persists in the meshcore-data volume.

A high-fidelity, single-process network simulator for MeshCore mesh radio networks. Built to model real-world LoRa deployments with physically accurate radio propagation — without needing real hardware.

This simulator:

Uses real MeshCore firmware (simple repeater, companion radio)
From the beginning was built with intention to simulate real behavior of hardware and radio propagation
Is built with speed in mind (in non interactive run)
Allows enter interactive mode during simulation
Allows writing scripts to test new features before applying changes to firmware
Comes with rich GUI through webapp

Key Features

Multi-node orchestration — Simulate entire networks of repeaters and companions in a single process, with per-node virtual clocks and staggered timers for realistic behavior. All running as native code — fast!
Realistic radio physics model — Half-duplex constraints, Listen-Before-Talk (LBT), collision detection with timing-dependent capture effect, SNR-based link quality, correlated Ornstein-Uhlenbeck fading, and stochastic packet loss.
Hot-start initialization — Collision-free advert exchange with automatic quiescence-based settling, so nodes discover each other naturally — just like real hardware boot-up, but fast. Simulates a stable network state.
Adversarial testing — Per-node drop, corrupt, and replay attack modes to stress-test protocol resilience.
Message fate tracking — Follow every packet from source to destination through the relay chain.
Lua scripting — Drive simulations programmatically with Lua scripts, define custom scenarios, react to events in real time, and collect structured statistics.
Web UI — Browser-based scenario editor, simulation runner with SSE progress, swim-lane visualization, and topology map view.
Real topology import — Convert real-world MeshCore network data into simulation configs.