A fully offline, end-to-end encrypted mesh communication system built on ESP32, managed via native iOS and macOS apps over secure Bluetooth Low Energy handshakes.
Important
Note on App Signing: The iOS and macOS apps provided in the Releases section are unsigned. They do not contain Apple Developer certificates.
- macOS: You may need to right-click the app and select "Open" to bypass Gatekeeper, or allow it in System Settings > Privacy & Security.
- iOS: These are provided as source code or
.ipafiles for side-loading (requires AltStore, Sideloadly, or Xcode).
MeshOS is a decentralised peer-to-peer communication platform with no cloud, no Wi-Fi router, and no internet required. ESP32 nodes form a self-healing multi-hop mesh using ESP-NOW and expose themselves to native Apple clients over BLE GATT.
┌────────────────┐ BLE GATT ┌──────────────────────────────────────┐
│ iOS / macOS App│ ←──────────────→ │ ESP32 Node A │
│ (SwiftUI) │ Secure Handshake│ ┌──────────────────────────────┐ │
└────────────────┘ (P-256 ECDH) │ │ ESP-NOW Mesh (encrypted) │ │
│ │ Node A ↔ Node B ↔ Node C │ │
│ └──────────────────────────────┘ │
└──────────────────────────────────────┘
| Feature | Detail |
|---|---|
| Self-healing mesh | Nodes build routing tables (AODV-lite) via heartbeat broadcasts |
| P-256 ECDH Security | Dynamic session keys negotiated via Elliptic Curve Diffie-Hellman on every connection |
| AES-128-GCM | Hardware-accelerated authenticated encryption for all mesh traffic |
| Dual-Platform Apps | Full-featured native SwiftUI apps for both iOS and macOS |
| Mesh Topology View | Real-time GPU-rendered (Metal) graph of the entire network structure |
| Reliable Delivery | End-to-end ACKs and delivery indicators for every message |
| Mesh Time Sync | Automatic time distribution across the mesh from the connected app |
| Node Telemetry | Monitor battery levels and uptime of every node in the network |
| OTA Updates | Wireless firmware updates directly from the iOS/macOS app over BLE |
esp32Mesh/
├── firmware/ # ESP32 C firmware (ESP-IDF 5.x / PlatformIO)
├── ios/ # iOS SwiftUI application (Xcode)
└── macos/ # macOS SwiftUI application (Xcode)
Prerequisites: PlatformIO CLI
cd firmware
# Build and flash to connected ESP32
pio run -t upload
# Monitor serial logs (115200 baud)
pio run -t monitor- macOS: Open
macos/MeshOS.xcodeprojin Xcode 15+, select theMeshOSscheme, and press⌘R. - iOS: Open
ios/MeshOSiOS.xcodeprojin Xcode, connect your iPhone, and deploy to the device.
Download the latest binaries from the Releases page. See the security note above regarding unsigned apps.
- Power on at least two ESP32 nodes running the MeshOS firmware.
- Open the App on your iPhone or Mac.
- Scan & Connect: Click the "Connect" button in the app. It will scan for nodes (named
MeshOS_XXXXXXXX). - Secure Handshake: The app will automatically perform a P-256 ECDH handshake to establish a secure session key.
- Chat: Once connected, you can send broadcasts (to everyone) or DMs (to specific nodes).
- Monitor: Switch to the Network tab to see a live visual map of your mesh topology.
- Service UUID:
DECAFBAD-CAFE-4BEE-B00B-000000000000 - Characteristics:
...0001(Status): Node ID, Uptime, Nickname....0002(Peers): Live neighbor topology data....0003(Chat): Encrypted message stream (Write/Notify)....0005(ECDH): Public key exchange....0006(OTA): Firmware update control.
- Transport: ESP-NOW (2.4GHz IEEE 802.11 Raw Frames).
- Routing: AODV-lite (Distance Vector).
- Max Hops: Default 7.
- Encryption: AES-128-GCM (mbedTLS hardware-accelerated).
- ESP32 Dev Board: ESP32-WROOM, ESP32-WROVER, or any standard ESP32 variant.
- Apple Device: iPhone (iOS 17+) or Mac (macOS 13+).
MIT
Built for secure, resilient, and independent communication.