https://github.com/dragongr/lora-sim
A reproducible LoRa network simulator for experimenting with radio behavior, gateway selection, collisions, retries, duty-cycle constraints, and confirmed uplinks.
https://github.com/dragongr/lora-sim
adr duty-cycle gateway lora lorawan network-simulator packet-simulation radio-network
Last synced: 2 months ago
JSON representation
A reproducible LoRa network simulator for experimenting with radio behavior, gateway selection, collisions, retries, duty-cycle constraints, and confirmed uplinks.
- Host: GitHub
- URL: https://github.com/dragongr/lora-sim
- Owner: dragonGR
- Created: 2025-07-08T19:08:13.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-03-20T17:58:00.000Z (3 months ago)
- Last Synced: 2026-03-21T09:10:39.442Z (3 months ago)
- Topics: adr, duty-cycle, gateway, lora, lorawan, network-simulator, packet-simulation, radio-network
- Language: Python
- Homepage:
- Size: 35.2 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# LoRa Simulation Toolkit
`lora-sim` is a deterministic LoRa network simulation toolkit for repeatable scenario runs, collision analysis, ADR behavior, and structured reporting. The original repository was a single demo script; it is now organized as a real package with a simulation engine, scenario files, results export, and automated tests.
## What it does
- Runs event-driven LoRa simulations with fixed seeds
- Models nodes, radios, channels, retries, airtime, and ADR behavior
- Supports multi-node scenarios and collision pressure
- Tracks per-node radio energy for transmit, receive, and idle phases
- Supports Monte Carlo runs for repeatable benchmark aggregates
- Supports multi-gateway reception and gateway-level accounting
- Models confirmed uplinks with RX1 ACK timing
- Adds RX2 fallback handling for confirmed traffic
- Applies duty-cycle and channel-guard scheduling constraints
- Produces structured JSON or CSV outputs for analysis pipelines
- Generates lightweight HTML reports for sharing run results
## Project layout
```text
src/lora_sim/
app/ CLI, runner, report rendering
domain/ packets, nodes, radios, metrics, channel model
io/ result writers
models/ propagation, ADR, corruption, interference, retry policy
simulation/ scenario loading, event queue, engine
scenarios/ example scenario definitions
tests/ regression and unit tests
```
## Quick start
```bash
python3 -m pip install -e .
lora-sim run scenarios/simple_link.json
```
Compatibility entrypoint:
```bash
python3 simulator.py run scenarios/simple_link.json
```
## Example commands
Run a scenario and print a text report:
```bash
lora-sim run scenarios/simple_link.json
```
Override the seed and save structured results:
```bash
lora-sim run scenarios/multi_node_collision.json --seed 99 --out results.json
```
Write a CSV packet log:
```bash
lora-sim run scenarios/multi_node_collision.json --out results.csv
```
Generate an HTML report during a run:
```bash
lora-sim run scenarios/simple_link.json --report report.html
```
Generate a report from saved results:
```bash
lora-sim report results.json --out report.html
```
Run a parameter sweep:
```bash
lora-sim sweep scenarios/simple_link.json --param nodes.gateway.x_m --range 500:3000:500
```
Compare two scenarios with the same seed:
```bash
lora-sim compare scenarios/simple_link.json scenarios/multi_node_collision.json --seed 42
```
Run a Monte Carlo batch:
```bash
lora-sim monte-carlo scenarios/multi_node_collision.json --iterations 20 --seed 100
```
Run a multi-gateway confirmed-uplink scenario:
```bash
lora-sim run scenarios/multi_gateway_ack.json
```
Run a duty-cycle constrained scenario with RX2 fallback:
```bash
lora-sim run scenarios/duty_cycle_rx2.json
```
## Scenario format
Scenario files are JSON documents that define:
- simulation metadata such as `name`, `duration_seconds`, and `seed`
- channel behavior such as `noise_floor_dbm`, `path_loss_exponent`, interference settings, and gateway demodulation capacity
- ACK behavior through `ack_model`, including RX1 delay and downlink interference probability
- channel-level MAC constraints through `duty_cycle_fraction` and `channel_guard_seconds`
- retry policy with `max_attempts` and `backoff_seconds`
- nodes with coordinates, role, radio settings, power profile, and optional traffic profiles
`traffic.confirmed_messages` controls whether a node waits for gateway ACKs before the uplink attempt is considered successful
See [simple_link.json](scenarios/simple_link.json) and [multi_node_collision.json](scenarios/multi_node_collision.json) for working examples.
Use [gateway_capacity.json](scenarios/gateway_capacity.json) to stress-test the gateway demodulation path limit with overlapping uplinks.
Use [multi_gateway_ack.json](scenarios/multi_gateway_ack.json) to exercise gateway diversity with confirmed uplinks and ACK timing.
Use [duty_cycle_rx2.json](scenarios/duty_cycle_rx2.json) to validate duty-cycle scheduling and RX2 ACK recovery.
## Development
Run the test suite:
```bash
python3 -m pytest
```