NullSec LoRa Mesh
Zero-leakage, high-speed compressed mesh communications framework for Flipper One and LoRa-enabled devices.
Overview
NullSec LoRa Mesh is a protocol framework for building secure, resilient mesh networks over LoRa radio. Designed for the Flipper One and compatible LoRa hardware, it provides:
- Zero-leakage encryption — ChaCha20-Poly1305 with ephemeral key exchange
- High-speed compression — LZ4/Zstandard adaptive compression for maximum throughput
- Mesh routing — Dynamic multi-hop routing with AODV-inspired protocol
- Forward Error Correction — Reed-Solomon FEC for reliable delivery over noisy channels
- Anti-replay protection — Monotonic counters and sliding window verification
- Minimal overhead — Designed for LoRa's low bandwidth (0.3 - 50 kbps)
Architecture
┌─────────────────────────────────────────────────────┐
│ APPLICATION │
│ Chat │ File Transfer │ Telemetry │
├─────────────────────────────────────────────────────┤
│ TRANSPORT │
│ Fragmentation │ Reassembly │ Flow Control │
├─────────────────────────────────────────────────────┤
│ SECURITY │
│ ChaCha20-Poly1305 │ X25519 ECDH │ Anti-Replay │
├─────────────────────────────────────────────────────┤
│ COMPRESSION │
│ LZ4 (fast) │ Zstd (ratio) │ Adaptive │
├─────────────────────────────────────────────────────┤
│ MESH ROUTING │
│ AODV │ Flooding │ Gossip │ Route Maintenance │
├─────────────────────────────────────────────────────┤
│ LINK LAYER │
│ FEC (Reed-Solomon) │ CRC32 │ Duty Cycle Mgmt │
├─────────────────────────────────────────────────────┤
│ PHYSICAL │
│ LoRa SX1262/SX1276 │ SubGHz │ Flipper One │
└─────────────────────────────────────────────────────┘
Protocol Design
Frame Format
┌──────┬──────┬──────┬────────┬──────────┬──────────┬─────┐
│ Sync │ Ver │ Type │ Src ID │ Dst ID │ Seq/Frag │ Len │
│ 2B │ 1B │ 1B │ 4B │ 4B │ 4B │ 2B │
├──────┴──────┴──────┴────────┴──────────┴──────────┴─────┤
│ Payload (encrypted) │
│ 0 - 222 bytes │
├─────────────────────────────────────────────────────────┤
│ Auth Tag (16B) │
├─────────────────────────────────────────────────────────┤
│ FEC Parity (variable) │
└─────────────────────────────────────────────────────────┘
Total overhead: 18B header + 16B auth + FEC = ~40B minimum
Max payload per frame: 222 bytes (LoRa max 255B - overhead)
Message Types
| Type | ID | Description |
|---|---|---|
| DATA | 0x01 | Encrypted data payload |
| ACK | 0x02 | Acknowledgment |
| RREQ | 0x03 | Route Request (broadcast) |
| RREP | 0x04 | Route Reply (unicast) |
| RERR | 0x05 | Route Error |
| HELLO | 0x06 | Neighbor discovery beacon |
| KEXCH | 0x07 | Key exchange (X25519) |
| FRAG | 0x08 | Fragment of larger message |
| PING | 0x09 | Keepalive / latency test |
| CTRL | 0x0A | Control / management |
Compression Strategy
| Mode | Algorithm | Ratio | Speed | Use Case |
|---|---|---|---|---|
| Fast | LZ4 | ~2:1 | 780 MB/s | Real-time chat, telemetry |
| Balanced | Zstd L3 | ~3:1 | 350 MB/s | General data |
| Maximum | Zstd L19 | ~5:1 | 15 MB/s | File transfer (pre-compress) |
| None | Passthrough | 1:1 | ∞ | Already compressed / encrypted data |
Adaptive mode auto-selects based on payload size and channel conditions.
Security Model
- Key Exchange: X25519 ECDH with ephemeral keys per session
- Encryption: ChaCha20-Poly1305 AEAD (authenticated encryption)
- Anti-Replay: 64-bit monotonic counter + sliding window (128 entries)
- Key Rotation: Automatic rekeying every 1000 messages or 1 hour
- Forward Secrecy: Ephemeral keys destroyed after session
- Zero Metadata Leakage: Encrypted headers after initial handshake
Installation
pip install nullsec-lora-mesh
Hardware Requirements
- Flipper One with LoRa module
- SX1262 or SX1276 LoRa transceiver
- Any LoRa HAT for Raspberry Pi (for gateway nodes)
Quick Start
from nullsec_lora import MeshNode, LoRaConfig
# Configure LoRa radio
config = LoRaConfig(
frequency=915.0, # MHz (US ISM band)
bandwidth=125000, # Hz
spreading_factor=7, # SF7-SF12
coding_rate=5, # 4/5
tx_power=14, # dBm
)
# Create a mesh node
node = MeshNode(
node_id=0x00000001,
config=config,
compression="adaptive",
encryption=True,
)
# Start the node
node.start()
# Send a message
node.send(
dest=0x00000002,
data=b"Hello from the mesh!",
reliable=True, # Request ACK
)
# Receive messages
for msg in node.receive():
print(f"From {msg.src}: {msg.data}")
Project Structure
nullsec-lora-mesh/
├── README.md
├── LICENSE
├── pyproject.toml
├── protocol/
│ ├── __init__.py
│ ├── frame.py # Frame encoding/decoding
│ ├── compression.py # LZ4/Zstd adaptive compression
│ ├── crypto.py # ChaCha20-Poly1305 + X25519
│ ├── fec.py # Reed-Solomon forward error correction
│ └── routing.py # AODV mesh routing
├── transport/
│ ├── __init__.py
│ ├── fragment.py # Message fragmentation
│ ├── reassembly.py # Fragment reassembly
│ └── flow.py # Flow control / congestion
├── radio/
│ ├── __init__.py
│ ├── lora.py # LoRa radio abstraction
│ ├── sx1262.py # SX1262 driver
│ └── flipper.py # Flipper One integration
├── node/
│ ├── __init__.py
│ ├── mesh.py # MeshNode main class
│ ├── neighbor.py # Neighbor table management
│ └── config.py # Node configuration
├── apps/
│ ├── chat.py # Mesh chat application
│ ├── file_transfer.py # Compressed file transfer
│ └── telemetry.py # Sensor telemetry relay
└── tests/
├── test_frame.py
├── test_compression.py
├── test_crypto.py
└── test_routing.py
Roadmap
- Protocol specification
- Frame encoding/decoding
- Compression layer (LZ4/Zstd)
- Encryption layer (ChaCha20-Poly1305)
- FEC (Reed-Solomon)
- AODV routing implementation
- Flipper One radio driver
- File transfer application
- Mesh chat application
- Performance benchmarks
- Hardware testing with SX1262
License
MIT License - see LICENSE for details.
Author
NullSec (bad-antics) — badxantics@gmail.com
Metadata
Release files for nullsec-lora-mesh 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nullsec_lora_mesh-0.1.0.tar.gz | 52.4 kB | Without provenance | Details for nullsec_lora_mesh-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nullsec_lora_mesh-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for nullsec_lora_mesh-0.1.0-py3-none-any.whl |
Total release size: 99.0 kB
Release files / nullsec_lora_mesh-0.1.0.tar.gz
| Download URL | nullsec_lora_mesh-0.1.0.tar.gz |
|---|---|
| Size | 52.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7f1ba266a4a9e8b9707b34408787c6349953c728281effc4b5d744063af28a66
|
|
BLAKE2b-256 checksum How to use checksums |
72b34b35af1ad58976832b09a6eb9b9227e49c4e70d8fe59a57d1cceaf3faf29
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Release files / nullsec_lora_mesh-0.1.0-py3-none-any.whl
| Download URL | nullsec_lora_mesh-0.1.0-py3-none-any.whl |
|---|---|
| Size | 46.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c92a53df13783d9a3af442ddd6f78c2c6d518a32c3147739843fe38e98158342
|
|
BLAKE2b-256 checksum How to use checksums |
100543d743332dd5e7de327116e8440afe43739ccca3ef5b3569cb8960cb5710
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Security for nullsec-lora-mesh 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.