https://github.com/danst0/fennek
🦊 Fennek — alternative open-source firmware for the LilyGO T-Deck Pro: music, audiobooks, eBooks & LoRa mesh chat (MeshCore). GPL-3.0+
https://github.com/danst0/fennek
alternative-firmware arduino e-ink epub-reader esp32 esp32-s3 firmware handheld lilygo lora mesh-networking meshcore mp3-player platformio t-deck-pro
Last synced: 7 days ago
JSON representation
🦊 Fennek — alternative open-source firmware for the LilyGO T-Deck Pro: music, audiobooks, eBooks & LoRa mesh chat (MeshCore). GPL-3.0+
- Host: GitHub
- URL: https://github.com/danst0/fennek
- Owner: danst0
- License: gpl-3.0
- Created: 2026-06-12T03:58:26.000Z (24 days ago)
- Default Branch: main
- Last Pushed: 2026-06-19T17:00:47.000Z (17 days ago)
- Last Synced: 2026-06-19T19:05:10.893Z (17 days ago)
- Topics: alternative-firmware, arduino, e-ink, epub-reader, esp32, esp32-s3, firmware, handheld, lilygo, lora, mesh-networking, meshcore, mp3-player, platformio, t-deck-pro
- Language: C++
- Homepage: https://fennek.dumke.me
- Size: 44.4 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🦊 Fennek
**An alternative open-source firmware for the LilyGO T-Deck Pro**
Music, audiobooks, eBooks and LoRa mesh chat — in one handheld.
🇬🇧 English · [🇩🇪 Deutsch](README.de.md) · [🇸🇪 Svenska](README.sv.md)
🌐 **[fennek.dumke.me](https://fennek.dumke.me)**
[](LICENSE)
[](https://github.com/danst0/fennek/releases/latest)
[](https://github.com/danst0/fennek/releases)
[](CHANGELOG.md)
[](https://www.espressif.com/en/products/socs/esp32-s3)
[](https://www.lilygo.cc/products/t-deck-pro)
[](https://platformio.org/)
---
**Fennek** turns the LilyGO T-Deck Pro (ESP32-S3, E-Ink, LoRa) into a real
handheld: listen to music, resume audiobooks, read eBooks and chat over the LoRa
mesh via **MeshCore** — with a homescreen launcher, touch + physical keyboard,
and background audio that keeps playing across app switches. Like the desert
fox: small, frugal, big ears.
It is a **standalone alternative** to the factory firmware — built around the
hardware's defining quirk, that E-Ink, the SD card and LoRa all share **one**
SPI bus, while still delivering stutter-free audio playback.
## 📸 Screenshots
Launcher (app picker)
Music – playback
Games – Tic-Tac-Toe
Settings (radio & system)
Standby (sleeping fennec)
Maps – offline SD tiles + GPS
Rendered pixel-accurately from the real drawing code (240×320 E-Ink) via
tools/screenshots.sh — see tools/.
## ✨ Apps
| App | Features |
|---|---|
| **🎵 Music** | MP3/AAC/FLAC/WAV from SD (`/music`), artist/album/playlist browser, ID3 tags (with SD cache), shuffle/repeat, sleep timer, resume after reboot |
| **🎧 Audiobook** | Books as folders under `/audiobooks`, chapters natural-sorted, per-book bookmark (NVS), ±30 s jumps, sleep timer |
| **📖 Reading** | `.txt` and `.epub` from `/books`, on-device EPUB conversion (ROM-tinfl), page-index cache, per-book reading position |
| **📡 Mesh** | Lean MeshCore client: public and hashtag channels (`#test` …), DMs with delivery status, contacts from adverts, message log on SD incl. history reload |
| **🎮 Games** | 2048, Minesweeper, Chess (Negamax AI) and Tic-Tac-Toe — logic host-tested |
| **📝 Notes** | One note per day under `/notes` (`YYYY-MM-DD.md`); "+ Today" opens or appends to today's note, the list shows every day newest-first with a first-line preview, append-style editor with delete confirmation |
| **🎙️ Podcast** | RSS subscriptions in `/podcasts/feeds.txt` (Freakshow preset), syncs the latest episode over Wi-Fi and keeps only that one — downloaded to SD, played via the audio queue with resume |
| **⚙️ Options** | Radio presets (EU Narrow = DE/NRW standard 869.618 MHz / 62.5 kHz / SF8), individual parameters, node name, battery info, firmware version |
Plus: a status line (battery, playback), standby/key-lock via the button, and a
serial debug console over USB (type `help` — `status`, `chan test hello`,
`meshlog`, `ls /books` …).
## 🔧 Hardware
LilyGO **T-Deck Pro V1.1**: ESP32-S3 (16 MB flash, 8 MB PSRAM), E-Ink
GDEQ031T10 240×320, CST328 touch (I2C), TCA8418 keyboard, PCM5102A DAC
(I2S, 3.5 mm jack), SX1262 LoRa, BQ27220 fuel gauge, microSD.
> **Defining quirk:** E-Ink, the SD card and LoRa share **one** SPI bus. The
> entire architecture revolves around audio never stuttering despite that, and
> inputs responding instantly — details in [`CLAUDE.md`](CLAUDE.md)
> (anti-stutter invariants).
## 🧭 Engineering around the hardware
The T-Deck Pro has four awkward constraints; Fennek is the story of working *with*
them. (Full design notes and anti-stutter invariants in [`CLAUDE.md`](CLAUDE.md).)
- **🕐 No real-time clock.** There is no battery-backed RTC. The canonical clock is
the ESP32 system time (it survives deep sleep, unlike a `millis()` clock), set in
priority order from **GPS → NTP → mesh adverts**; drift is learned and a
future-dated packet can't drag the clock forward unchecked.
- **🔋 Can't stay online.** Always-on networking isn't possible on this power budget —
and Wi-Fi and audio can't run at once (the Wi-Fi task on core 0 evicts the audio
task). So Fennek never holds a connection: scrobbles, note polishing and **podcast
downloads** are batched into a short Wi-Fi window before standby, and unused
peripherals (GPS, haptics) are powered down at boot.
- **🧩 Only two cores.** Two cores mean barely any true multitasking. Audio decoding
is pinned to core 0, the UI + mesh pump to core 1; SD library scans pause during
playback and the chess AI runs at low priority — so playback stays smooth and the
keyboard responsive.
- **🖋️ E-Ink screen.** E-Ink is beautiful but slow, and full refreshes flash the
panel. Fennek redraws only on a real change, paints progress/status as narrow
*region strips* instead of full repaints, and stretches the anti-ghosting full
refresh out to keep the screen calm.
## 🚀 Build & Flash
Prerequisite: [PlatformIO](https://platformio.org/). Connect the T-Deck Pro via
USB-C, then:
```bash
pio run -e fennek # build
pio run -e fennek -t upload # flash (USB-C)
pio device monitor -b 115200 # log + debug console
```
The firmware also runs **without an SD card** (apps then show a hint). Radio
parameters are configurable at runtime in the Options app; the default is the
**EU/UK Narrow** preset commonly used in Germany.
> ⚠️ Custom firmware replaces the factory software. You flash at your own risk —
> a way back to the original firmware is available via the
> [LilyGO resources](https://github.com/Xinyuan-LilyGO).
## 📁 Project layout
- `src/` — active firmware (`core/` drivers & framework, `services/` audio/
library/text, `apps/` the apps)
- `lib/meshcore/`, `lib/ed25519/` — vendored MeshCore stack (subset)
- `boards/t-deck_pro.json` — board definition (partition `default_16MB.csv`)
- `CHANGELOG.md` — release notes
- `CLAUDE.md` — architecture, invariants, verification status
- `LICENSE` — GPL-3.0-or-later
## 📜 License
Fennek is licensed under the **GNU General Public License v3.0 or later
(GPL-3.0-or-later)** — see [`LICENSE`](LICENSE).
Bundled components keep their own GPL-compatible licenses:
- **MeshCore** (`lib/meshcore/`) — MIT License, © Scott Powell / rippleradios.com
([original](https://github.com/ripplebiz/MeshCore), [`lib/meshcore/LICENSE`](lib/meshcore/LICENSE))
- **ed25519** (`lib/ed25519/`) — zlib License, © Orson Peters
([`lib/ed25519/license.txt`](lib/ed25519/license.txt))
## 🙏 Credits
Fennek started out inspired by the **Meck** fork
([pelgraine/Meck](https://github.com/pelgraine/Meck), a MeshCore companion for
the T-Deck), but was rebuilt from v1.0.0 as a standalone multi-app firmware and
has been its own project ever since. The mesh stack is based on
[MeshCore](https://github.com/ripplebiz/MeshCore) by Scott Powell. The earlier
Meck code (formerly under `archive_legacy/`) lives in the Git history and can be
restored from there at any time.