mshfck Firmware

Current Version: 1.0.0 | Build: 3 | Released: 2025-12-10

⚠️ Early Development — This is a mesh networking system currently in early development. Features may be incomplete, APIs may change, and bugs are expected. Use at your own risk.

Multi-platform mesh repeater firmware for ESP32 and nRF52.

Supported Hardware

Board	Platform	Transports	Features	Status
Heltec WiFi LoRa 32 V3	ESP32-S3	BLE + ESP-NOW + LoRa	OLED, Battery	✅ Stable
Heltec WiFi LoRa 32 V4	ESP32-S3	BLE + ESP-NOW + LoRa	OLED, Battery, 27dBm TX	✅ Stable
ESP32 / ESP32-S3	ESP32	BLE + ESP-NOW	-	✅ Stable
RAK4631	nRF52840	BLE + LoRa	Battery	🚧 WIP
Seeed T1000-E	nRF52840	BLE + LoRa	Battery, GPS	🚧 WIP

⚠️ nRF52 boards (RAK4631, T1000-E) are experimental and may not work correctly yet. ESP32-based boards are recommended.

Installation

PlatformIO (recommended)

# Install PlatformIO CLI or use VSCode extension

# Heltec V3
pio run -e heltec_v3 -t upload

# Heltec V4 (27dBm)
pio run -e heltec_v4 -t upload

# ESP32
pio run -e esp32 -t upload

# RAK4631 (WIP)
pio run -e rak4631 -t upload

# T1000-E (WIP)
pio run -e t1000e -t upload

Arduino IDE

1. Install board support:

   • ESP32: Add https://dl.espressif.com/dl/package_esp32_index.json to Board Manager
   • nRF52: Add https://adafruit.github.io/arduino-board-index/package_adafruit_index.json

2. Install libraries:

   • RadioLib (LoRa)
   • U8g2 (OLED, ESP32 only)

3. Select board and upload

Project Structure

firmware/
├── platformio.ini      # Build configuration
├── src/
│   ├── main.cpp        # Main firmware
│   ├── protocol.h      # Shared protocol definitions
│   ├── Transport.h     # Transport interface
│   ├── LoRaTransport.h # LoRa implementation
│   └── LoRaTransport.cpp
└── variants/
    ├── heltec_v3/      # Heltec WiFi LoRa 32 V3
    ├── heltec_v4/      # Heltec WiFi LoRa 32 V4 (27dBm)
    ├── esp32/          # Generic ESP32
    ├── rak4631/        # RAK4631
    └── t1000e/         # Seeed T1000-E

Configuration

Repeaters are automatically discovered by the mshfck iOS app. Configuration (name, interval, transports) can be changed via the app.

Protocol

• Version: 0x01
• BLE Service: FACEB00B-DEAD-BEEF-CAFE-BADA55042069
• LoRa: 869.222 MHz, SF8, BW 62.5 kHz

See protocol.h for details.

---

Changelog

v1.0.0 Build 3 (2025-12-11)

• LoRa: TCXO/DIO2/RX boost config, SNR-based forwarding, Listen-Before-Talk with CAD
• LoRa: Noise floor calibration, AGC reset, airtime-based TX queue
• Display: Device counter, optimized layout
• Power: Light sleep framework, LED heartbeat auto-off, 20min advertise interval
• Smaller improvements and fixes

---

© 2025 Joshua Hoffmann