# mattermesh-os **Repository Path**: Rockbase-iot/mattermesh-os ## Basic Information - **Project Name**: mattermesh-os - **Description**: No description available - **Primary Language**: Unknown - **License**: GPL-3.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-28 - **Last Updated**: 2026-11-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # MatterMesh OS An alternative firmware for the LilyGO **T-Deck Plus**, **T-Deck Max** and RockBase **NM-EPD-420-BW**, built on [MeshCore](https://github.com/meshcore-dev/MeshCore): off-grid LoRa chat, designed for use in the field. **Website and browser installer: [mattermeshos.com](https://mattermeshos.com)** — install it on your T-Deck from Chrome or Edge, no tools needed.

T-Deck Plus · lock screen	T-Deck Max · lock screen	NM-EPD-420 · lock screen
Chat in two languages (Plus)	Chat in two languages (Max)

This repository holds the source of the **Free edition**, released under the GNU General Public License v3.0. | Folder | Device | Display | |---|---|---| | [`tdeck-plus/`](tdeck-plus) | T-Deck Plus (ESP32-S3, SX1262) | 320×240 colour LCD, touch | | [`tdeck-max/`](tdeck-max) | T-Deck Max (ESP32-S3, SX1262) | 240×320 e-paper, touch | | [`nm-epd-420/`](nm-epd-420) | RockBase NM-EPD-420-BW (ESP32-S3, SX1262) | 400×300 monochrome e-paper, two buttons | Each device has an independent firmware directory. The NM firmware is derived from the Max application, with its board drivers, two-button input and landscape layouts isolated in `nm-epd-420/`. All devices use the MeshCore companion protocol, so they work with the MeshCore apps and with every other MeshCore node. ## What's in the Free edition - Channel and direct chats, contacts, emoji, mentions and quick replies; themes and lock screens (Plus), wallpapers (Max) - **Keyboard languages**: Italian, English, German, French, Spanish, Portuguese, Russian and Ukrainian (Settings → Keyboard languages, with search). Alt + Space switches between the enabled languages and the one in use shows in the status bar; the accent key, tapped before a letter, types the letters without a key of their own - MeshCore companion over Bluetooth, USB and Wi-Fi - Apps: **Maps** (OpenStreetMap tiles with GPS), **Weather** (Open-Meteo; on the Plus also radar and storm alerts), **Files**, **CLI** - On the Max: offline Italian dictation (the speech model is loaded from the SD card and is distributed separately) ## Build Requirements: [PlatformIO Core](https://platformio.org/install/cli), git, a C++17 host compiler for the tests. ```sh bash scripts/fetch-deps.sh # MeshCore companion-v1.18.0 and the LilyGO T-Deck-MAX libraries, pinned and patched cd tdeck-plus && pio run -e tdeck-plus-free # T-Deck Plus cd tdeck-max && pio run -e mattermesh-free # T-Deck Max cd nm-epd-420 && pio run -e nm-epd-420-bw-free # RockBase NM-EPD-420-BW ``` ### More about NM-EPD-420 Flash the app-only image at `0x10000` (for example `esptool.py write-flash 0x10000 .pio/build//firmware.bin`). For a complete NM-EPD-420 installation, flash `nm-epd-420-bw-free-merged-0x0.bin` at `0x0`; it contains the bootloader, partition table, OTA data and application. Or flash from the [web flasher](https://flash.rockbaseiot.com). To reduce NM-EPD-420 power consumption, the ES8311 codec (GPIO44), amplifier (GPIO41) and AHT20 (GPIO40) are all driven LOW to remove power; audio initialization is disabled. LoRa, microSD and the e-paper panel remain enabled. The NM-EPD-420 panel uses native partial refresh for changed regions, with periodic full-refresh maintenance. NM-EPD-420 defaults to External Antenna. Its reference board has no software-controlled RF selection pin, so the antenna choice is a persisted UI/configuration preference rather than an XL9555 hardware switch. Battery voltage is sampled from GPIO3 through the 2:1 divider; GPIO43 is enabled only during sampling. The serial command `battery status` reports `mv`, `percent`, raw `adc` and `pin_mv` for hardware verification. On NM-EPD-420, locking the screen suspends idle Wi-Fi without changing the saved preference; an active TCP Companion link or an NTP, weather or OTA request keeps a temporary Wi-Fi lease. Idle BLE advertising stops immediately and BLE is deinitialized after 60 seconds, then restored on unlock. With both radios asleep, NM enters Light Sleep for up to 100 ms per pass while the SX1262 remains in continuous RX. DIO1, either button or the service timer wakes the CPU; an attached USB host prevents Light Sleep to keep diagnostics and Companion links stable. The serial commands `sleep status`, `wifi status` and the `WIFI_STANDBY` / `BLE_STANDBY` logs expose sleep counters and radio state. On the first NM-EPD-420 boot, **Connect to Wi-Fi** starts a temporary WPA2 setup hotspot instead of requiring password entry with two buttons. **Settings → Wi-Fi** opens the same hotspot for later reconfiguration. Join the `MatterMesh-Setup-XXXX` network using the fixed password `12345678`, then open `http://192.168.4.1`. The phone form configures the Wi-Fi SSID/password, 868/900 MHz band, country/network preset, time zone, Companion Name and 1–3 byte Path hash size. Saving opens a **Ready** page: hold USER on the device to stop the hotspot and reconnect Wi-Fi immediately, or hold BOOT to restart. Hold USER before saving to cancel the hotspot and return to the previous screen. NM-EPD-420 controls: - Navigation: BOOT moves down/next, USER moves up/previous; hold BOOT to confirm and hold USER to go back. Hold USER on Home to lock. On Maps, short presses zoom out/in. - Text editing: BOOT/USER cycle a provisional character forwards/backwards. Hold BOOT to keep that character; with no provisional character, hold BOOT again to confirm the field or send. Hold USER deletes the provisional character or backspaces; on an empty field it exits. - Lock screen: BOOT/USER browse older/newer messages, hold BOOT to unlock, and hold USER to open Quick Reply. Host tests: `bash tools/test_release.sh` in either LilyGO folder. The Plus folder also contains a PC emulator (`emu/`, see its README). The emoji fonts live once in `shared/fonts/` and are symlinked into the device trees; they are only needed to regenerate the emoji bitmaps (`tools/make_color_emoji.py`, `tools/build_emoji_assets.py`), not to build. On Windows clone with `git clone -c core.symlinks=true` (or build on Linux/macOS). Builds made from this repository have no update server configured: over-the-air updates are only offered by the official images. ## Support MatterMesh OS is free and has no ads. If you find it useful, you can support it with a donation of any amount at [ko-fi.com/mattermeshos](https://ko-fi.com/mattermeshos) — on the device: Settings → Donate / Unlock. ## Download Ready-to-flash **Free** image for the **T-Deck Plus**, always the latest release: **[mattermesh-os.bin](https://mattermeshos.com/firmware/plus/mattermesh-os.bin)** — copy it to the SD card and install it from [bmorcelli's Launcher](https://github.com/bmorcelli/Launcher), or flash it at `0x10000` with esptool. Tested with Launcher 2.9.1 on the T-Deck Plus (install from the SD card, signed updates saved to the SD card and installed from the Launcher). MatterMesh OS has no agreement or affiliation with the Launcher project: it has only been tested with it. A first install without the Launcher needs the bootloader and partition table too: the easiest way is the browser installer at [mattermeshos.com](https://mattermeshos.com), which writes everything (Chrome or Edge, USB-C data cable). Later updates arrive signed over Wi-Fi: Settings → OTA update. ## License MatterMesh OS Free edition — GNU General Public License v3.0, see [LICENSE](LICENSE). Third-party components keep their own licenses: see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). MatterMesh OS is an independent project, not affiliated with LilyGO or the MeshCore project.