BoneNet Firmware

Custom mesh networking firmware for LoRa devices. Simple, hackable, and fully functional.

Features

✅ BoneNet Protocol - Custom efficient mesh protocol
✅ Multi-hop Routing - Automatic mesh relay with deduplication
✅ OLED Display - 4 screens (Status, Signal, Messages, Routes)
✅ GPS Integration - Via phone WiFi bridge
✅ WiFi Connectivity - MQTT and GPS bridge support
✅ Network Observer - Read-only monitoring of other mesh protocols
✅ Serial Commands - Interactive control

Hardware Support

• ✅ Heltec WiFi LoRa 32 V3 (ESP32-S3 + SX1262)
• 🔄 More devices coming soon

Quick Start

Prerequisites

pip install platformio

Build & Flash

cd bonenetwork
python -m platformio run --target upload
python -m platformio device monitor

Configuration

Edit src/main.cpp:

const char* WIFI_SSID = "YourWiFiName";
const char* WIFI_PASS = "YourPassword";
const char* GPS_BRIDGE = "http://192.168.43.1:8080/gps";
const char* MQTT_BRIDGE = "http://192.168.43.1:8081/report";

Usage

Serial Commands

• Type text to broadcast message
• /routes - Show routing table
• /beacon - Send beacon
• /wifi - Connect to WiFi

Button

• Press button (GPIO 0) to cycle through display screens

Display Screens

1. Status - Node ID, routes, uptime
2. Signal - RSSI, SNR, signal strength
3. Messages - Last received message
4. Routes - Active routing table

Architecture

bonenetwork/
├── src/
│   ├── main.cpp              # Main firmware logic
│   ├── hal/
│   │   ├── display.h         # Display abstraction
│   │   └── display.cpp
│   ├── core/
│   │   ├── mesh_router.h     # Routing logic
│   │   ├── message_handler.h # Message processing
│   │   └── gps_handler.h     # GPS bridge client
│   └── protocols/
│       ├── bonenet_protocol.h      # Packet structures
│       └── meshtastic_observer.h   # Observer mode
├── docs/
│   ├── FIRMWARE.md           # Detailed firmware docs
│   ├── PROTOCOL.md           # Protocol specification
│   ├── COMPLETE.md           # Implementation status
│   
├── platformio.ini            # Build configuration
└── README.md                 # This file

Protocol

Packet Structure

[Header: 16 bytes][Payload: 0-240 bytes]

Header:
- Magic: 0xB0E1 (2 bytes)
- Version: 0x01 (1 byte)
- Type: MSG_BEACON/TEXT/POSITION/TELEMETRY (1 byte)
- From: Node ID (4 bytes)
- To: Destination (4 bytes, 0xFFFFFFFF = broadcast)
- Hop Count: TTL (1 byte)
- Flags: Reserved (1 byte)
- Payload Length: (2 bytes)

Message Types

• MSG_BEACON (0x01) - Node announcement
• MSG_TEXT (0x02) - Text message
• MSG_POSITION (0x03) - GPS location
• MSG_TELEMETRY (0x04) - Node status

Radio Configuration

Frequency: 868.0 MHz (EU)
Spreading Factor: 7
Bandwidth: 125 kHz
Coding Rate: 5
Output Power: 14 dBm (EU legal limit)

Pin Configuration (Heltec V3)

LoRa:
  CS    = 8
  DIO1  = 14
  RST   = 12
  BUSY  = 13
  SCK   = 9
  MISO  = 11
  MOSI  = 10

OLED:
  SDA   = 17
  SCL   = 18
  RST   = 21
  Vext  = 36 (power control)

Button: GPIO 0

Integration

GPS Bridge

Fetch GPS from phone via HTTP:

node gps-bridge.js  # Serves GPS at :8080/gps

MQTT Bridge

Report node stats to web:

node mqtt-bridge.js  # Accepts reports at :8081/report

Performance

• Boot time: ~3 seconds
• Message latency: <500ms (single hop)
• GPS update rate: 10 seconds
• Display refresh: 5 seconds
• Beacon interval: 2 minutes
• Max range: ~10km (SF7, 14dBm, line of sight)

Documentation

• FIRMWARE.md - Complete firmware documentation
• PROTOCOL.md - Protocol specification
• COMPLETE.md - Implementation status

Roadmap

Completed ✅

• BoneNet protocol implementation
• Multi-hop mesh routing
• OLED display with 4 screens
• GPS integration via phone bridge
• WiFi connectivity
• MQTT reporting
• Network observer mode
• Serial commands
• Web dashboard with OSM and Google Maps support

Planned 🔄

• AES-256 encryption
• BLE connectivity
• OTA updates
• More hardware support (T-Beam, RAK)
• Mobile app
• Battery optimization

Contributing

All contributions welcome! This is an open, welcoming project with no gatekeeping.

1. Fork the repository
2. Create your feature branch
3. Make your changes
4. Submit a pull request

No complex process, no politics - just building cool stuff together.

License

GPL v3 License - see LICENSE file for details.

This project is licensed under the GNU General Public License v3.0, which means:

• ✅ Free to use, modify, and distribute
• ✅ Must remain open source
• ✅ Modifications must use the same license
• ❌ Cannot be used in proprietary/commercial closed-source products

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

• Built with RadioLib
• OLED library by ThingPulse

---