GhostMesh: a Flipper Zero companion interface for offline Meshtastic field communications.
GhostMesh turns your Flipper Zero into a long-range, mesh-radio command terminal by pairing it with a Heltec ESP32 LoRa node running Meshtastic. No phone, no internet, no cell infrastructure required.
- Sends canned field messages over LoRa mesh — select from scrollable profiles, press OK
- Receives incoming mesh text messages with sender ID and RSSI displayed
- RX history screen (long-press Down) — last 16 messages with full signal data, scrollable
- Logs every received message to a dated CSV on the Flipper SD card with timestamp, node ID, RSSI, and SNR
- Three built-in profiles: Grid Down, Hiking / SAR, Red Team
- Custom profiles loaded from
profiles.yamlon the SD card - All text marquee-scrolls if it doesn't fit the display — nothing is cut off
tools/log_to_kml.pyconverts the SD card CSV to KML for Google Earth / QGIS
| Component | Details |
|---|---|
| Flipper Zero | With PINGEQUA or official prototype board |
| Heltec WiFi LoRa 32 V3 | ESP32-S3 + SX1262, Meshtastic firmware |
| 915 MHz antenna | Attached to Heltec before powering on |
| LiPo battery | For Heltec — independent of Flipper battery |
See docs/hardware.md for the full hardware reference and planned sensor expansion (GPS, BME280, tamper sensors, etc.).
Visit flasher.meshtastic.org, select Heltec WiFi LoRa 32 V3, and flash. Set your region in the Meshtastic app before proceeding.
See docs/meshtastic-setup.md for full setup and private channel configuration.
Flipper U_TX (pin 13) → Heltec GPIO44 (labeled "RX" on board)
Flipper U_RX (pin 14) → Heltec GPIO43 (labeled "TX" on board)
Flipper GND → Heltec GND
Do not connect power rails. Each device runs from its own battery. See docs/wiring.md.
pip install ufbt
cd flipper-app
ufbtCopy dist/ghostmesh.fap to SD:/apps/Tools/ on your Flipper, or run ufbt launch with the Flipper connected via USB.
See docs/flipper-setup.md for the full build guide.
Apps → Tools → GhostMesh
The title bar shows ... during the startup handshake (~3 seconds), then RDY. Select a profile, navigate the message list, press OK to send.
See docs/user-guide.md for a screen-by-screen walkthrough.
Create SD:/apps_data/ghostmesh/profiles.yaml:
name: My Profile
- CHECKIN OK
- IN POSITION
- ABORT
- EXFIL NOW
name: Another Profile
- MESSAGE ONE
- MESSAGE TWOUp to 5 custom profiles load alongside the 3 built-ins (8 total). See examples/profiles.yaml for the full documented template.
ghostmesh/
├── README.md
├── docs/
│ ├── user-guide.md Screen-by-screen user manual
│ ├── developer-guide.md Code architecture and contribution guide
│ ├── hardware.md Full hardware reference and BOM
│ ├── wiring.md Pinout, connections, sensor wiring
│ ├── meshtastic-setup.md Meshtastic config, private channels
│ ├── flipper-setup.md ufbt build and install
│ ├── opsec.md Encryption, stealth, nuke protocol
│ ├── serial-modes.md PROTO protocol field numbers
│ ├── roadmap.md Phased development plan (Phases 0–14)
│ └── red-team-lab-use-cases.md Authorized lab use cases
├── flipper-app/
│ ├── application.fam
│ ├── ghostmesh.c App entry point and main loop
│ ├── helpers/
│ │ ├── proto_mode.h/.c PROTO encoder/decoder, handshake
│ │ ├── profile_manager.h/.c Built-in profiles + YAML loader
│ │ ├── log_manager.h/.c SD card CSV logger
│ │ ├── uart_helper.h/.c USART1 init and async RX/TX
│ │ └── proto_notes.md Protocol implementation reference
│ └── views/
│ └── main_view.h/.c Three-screen UI
├── examples/
│ └── profiles.yaml Documented custom profile template
├── tests/
│ ├── uart-test-plan.md Manual hardware validation checklist
│ └── proto_send_test.py Python PROTO test script
└── tools/
└── log_to_kml.py Convert SD card CSV log to KML
GhostMesh connects to Meshtastic's PhoneAPI on UART0 (GPIO43/44) — the same interface used by the official phone app and Python library over USB. Packets use Meshtastic's binary PROTO framing (0x94 0xC3 magic bytes + protobuf payload). All protobuf field numbers are confirmed against meshtastic Python library v2.7.8.
See docs/serial-modes.md for the complete protocol reference.
GhostMesh on the default Meshtastic channel uses a public encryption key — traffic is visible to any Meshtastic node. For operational use, create a private channel with a random key before deployment.
See docs/opsec.md for the full encryption picture, private channel setup, and the planned nuke / stealth features.
Current version: v0.5 — PROTO mode full client, SD logging, RX history, marquee scroll.
Planned phases include GPS + wardriving, environmental telemetry, tamper detection, dead-drop surveillance, remote payload execution, and UART encryption. See docs/roadmap.md.
This project is for authorized security work, personal lab testing, grid-down comms experimentation, and open-source learning only.
No malware, unauthorized remote execution, credential theft, or destructive payloads are implemented or will be accepted. See docs/red-team-lab-use-cases.md.
MIT — see LICENSE.