MeshMesh

English · Русский · Українська · Español · Português · Français · Deutsch · Italiano · Polski · Türkçe · 中文 · 日本語 · 한국어 · العربية · Bahasa Indonesia

Website and one-click browser install: https://ikrasnodymov.github.io/meshmesh/

Off-grid messaging firmware for ESP32 and nRF52 LoRa devices. Messages hop by radio from device to device, with no internet, no cell network and no servers. The radio layer is MeshCore, so MeshMesh nodes talk to standard MeshCore nodes.

Features

• Chats — direct and public messages, ✓✓ delivery receipts, retries, route shown per message.
• Channels — up to 8 MeshCore channels: join by #hashtag, meshcore:// link or QR code, name and key; create a private one, invite contacts by direct message, find channels heard on air. docs/en/channels.md
• Regions — MeshCore flood scope: a default region and one per channel, a search of the regions nearby repeaters serve; repeaters set up with the region commands. docs/en/regions.md
• Network of your city — the frequency, bandwidth, SF and CR of a local MeshCore network from the community catalogue, written from the website (stock MeshCore boards too) or applied in the app with a test, Keep, Revert and a way back to the previous settings. docs/en/networks.md
• Offline maps — OpenStreetMap with relief and contour lines, kept on the phone (app) or the device SD card; nodes, direct links and GPS on the map, with any board.
• Wardriving — a coverage map of the mesh: packets heard and channel pings with the repeaters that pass them on, logged with a trusted GPS or phone position; Wi-Fi and Bluetooth too on ESP32; export to CSV, GeoJSON, KML and WiGLE. docs/en/wardrive.md
• Nearby nodes — signal, hops, distance and bearing; contacts, repeaters and rooms.
• Signal radar — Wi-Fi, Bluetooth and LoRa around you, with “warmer / colder” homing.
• Motion sensor — two boards detect a person walking between them (Wi-Fi CSI).
• Chess with your contacts over the mesh, and Klondike solitaire on the M9.
• Mesh pet — a Tamagotchi-like pixel creature on every board that feeds on radio traffic, grows up and can die of hunger or loneliness. docs/en/pet.md
• Dice — the DIC3R dice roller on every board: RPG pools and formulas (2d6+1, d20, d66, d%), a Warhammer grid with a success threshold and a character sheet of blocks (stats, tracks, marks, abilities that roll and spend) with D&D 5e and R.E.T. templates, built on the web page or in the app and sent to a contact over the mesh; the same on the screen, the web page and the app.

Boards

Board	Status
Elecrow ThinkNode M9 (keyboard, 320×240 screen)	tested on hardware
Heltec WiFi LoRa 32 V4 (OLED, one button)	tested on hardware
GAT562 30S Mesh Kit (nRF52840, OLED, joystick; no Wi-Fi)	tested on hardware (our unit has no GPS module fitted) — docs/en/gat562.md
Heltec Mesh Node T114 (nRF52840, 240×135 colour TFT, one button; no Wi-Fi)	tested on hardware — docs/en/t114.md
Heltec V4-R8, Heltec V3, Heltec Wireless Tracker, LilyGO T-Deck, T-Beam, T-Beam Supreme, T3-S3, T-LoRa V2.1-1.6, Seeed XIAO ESP32S3 + Wio-SX1262, B&Q Station G2, Elecrow ThinkNode M2, Heltec Vision Master E213, Heltec Mesh Node T096, fakeTec (ProMicro nRF52840)	builds only, not yet run on hardware — reports welcome

ESP32 boards have every feature. The GAT562 (nRF52840) has no Wi-Fi: no access point, Wi-Fi radar, motion sensor or internet client; the phone connects through the Android app over Bluetooth or USB. It adds an on-screen keyboard and chess on the OLED. Pins and details: docs/en/boards.md.

Install

Browser: open the website in Chrome or Edge on a computer, pick your board and the device language, press Install. Updating MeshMesh keeps your key, contacts, settings and history; tick “Erase device” only when coming from other firmware.

esptool: download the board's zip from the website and run

python -m esptool --chip esp32s3 --port PORT write-flash --flash-mode dio --flash-freq 80m --flash-size 16MB \
  0x0 bootloader.bin 0x8000 partitions.bin 0xe000 boot_app0.bin 0x10000 firmware.bin

(ESP32 boards: --chip esp32, bootloader at 0x1000, --flash-freq 40m; flash size per board.)

GAT562 (nRF52840): the same Install button on the website (serial DFU over Web Serial); a board with other firmware first needs RESET pressed twice. Or press RESET twice — a GAT562-BOOT drive appears — and copy firmware.uf2 from the website onto it. Later updates: python tools/nrf52.py flash PACKAGE (docs/en/gat562.md).

Default radio: 868.731 MHz, BW 62.5 kHz, SF8, CR4/6 — change it in Settings → Radio; all nodes of a network must match. Follow your country's radio regulations.

Build

python3 -m venv .venv
.venv/bin/pip install platformio esptool pyserial cryptography
.venv/bin/pio run -e m9            # or heltec_v4, tdeck, tbeam, ...
.venv/bin/python tools/package.py m9

Android app: cd android && ./gradlew testDebugUnitTest assembleRelease (docs/en/android.md). The screen UI can be rendered on a computer without a board: tools/ui_preview/build.sh m9 OUTDIR en.

Documentation

Detailed documentation in English: channels, regions, network of your city, MeshCore compatibility, boards, GAT562, Android, repeater and room modes, chess protocol, mesh pet, dice, map format, comparison with MeshCore, hardware verification. The Russian originals are in docs/, with the full guide to controls and features in README.ru.md.

Not verified yet: LoRa range, GPS accuracy under open sky, compass accuracy, relaying through a third repeater. Not implemented: voice, route planning, OTA updates.

License

MIT. Bundled MeshCore (lib/MeshCore) keeps its own MIT license. Map data © OpenStreetMap contributors. The radar idea follows the RSSI tracker and radar HUDs by Stevee87.

Release 0.4.0: event waits on every board and independent firmware/Android versions and publishing. Battery-life gains have not been measured.

Firmware 0.4.1 reduces history-export memory use and reports allocation failures explicitly; Android remains 0.4.0.

Firmware 0.26.0: the sheet's block builder on the M9 and T-Deck screens (E edits a block, A adds one); every board adds a ready D&D 5e and R.E.T. character once.

Firmware 0.25.0 and Android 0.18.0: the character sheet replaces the dice counters (they become its tracks); D&D 5e and R.E.T. templates, formulas between blocks, sending a sheet to a contact; the nRF52 libraries are built for size (-Os).

Firmware 0.8.1: switching off also writes the dice counters changed in the last two seconds.

Firmware and Android 0.8.0: switch the device off from the Settings menu on its screen, the web page, the app or the USB command poweroff; it saves its data, shows "Device is off" and how to turn it on, then enters deep sleep (ESP32), a soft off (nRF52: everything off, the CPU waits for the button) or is cut off by its PMU (T-Beam). Holding the button for about a second, RESET or the power switch turns it on, depending on the board (docs/en/power.md).

Firmware and Android 0.7.0: dice — the DIC3R roller (RPG pools and formulas, a Warhammer grid with a success threshold, counters, characters) on every board, the web page and the app; on the T114 and GAT562 chess, the pet and the dice are optional modules chosen when building (tools/nrf52.py package ENV --without …). Dice checked on the M9 by the owner; the module images not yet on a board.

Firmware and Android 0.6.0: reply to a chat message by swiping it from right to left, as in Telegram (double-click on a computer); a channel reply starts with the @[Name] mention, a direct one with a short > … quote. Checked in the Android emulator's Chrome with test data, not with a board.

Firmware 0.5.1: the Heltec V3 build uses the DIO flash driver, matching its image header (a user's V3 did not keep writes with the QIO driver libraries; not yet verified there); flashstatus names the driver mode and flashprobe also writes through the ROM functions, as esptool does.

Firmware 0.4.3: when the LittleFS partition does not keep writes (as on a user's Heltec V3), fsformat puts the storage into the free OTA slot; the USB commands flashstatus and flashprobe show the flash chip and where writes stop staying.

Firmware 0.4.2: messages recorded before the clock is set get their exact time once it is set; a spoofed GPS date earlier than the firmware build, or one contradicting the phone/NTP time, is rejected. Android 0.4.1 does not repeat message notifications after that.

Notifications, quick send, channel retention, periodic NTP and quick counter.