{"id":51254971,"url":"https://github.com/danst0/fennek","last_synced_at":"2026-06-29T09:32:08.975Z","repository":{"id":364215721,"uuid":"1266907380","full_name":"danst0/fennek","owner":"danst0","description":"🦊 Fennek — alternative open-source firmware for the LilyGO T-Deck Pro: music, audiobooks, eBooks \u0026 LoRa mesh chat (MeshCore). GPL-3.0+","archived":false,"fork":false,"pushed_at":"2026-06-19T17:00:47.000Z","size":46586,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T19:05:10.893Z","etag":null,"topics":["alternative-firmware","arduino","e-ink","epub-reader","esp32","esp32-s3","firmware","handheld","lilygo","lora","mesh-networking","meshcore","mp3-player","platformio","t-deck-pro"],"latest_commit_sha":null,"homepage":"https://fennek.dumke.me","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danst0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-12T03:58:26.000Z","updated_at":"2026-06-19T17:00:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/danst0/fennek","commit_stats":null,"previous_names":["danst0/fennek"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/danst0/fennek","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danst0%2Ffennek","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danst0%2Ffennek/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danst0%2Ffennek/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danst0%2Ffennek/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danst0","download_url":"https://codeload.github.com/danst0/fennek/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danst0%2Ffennek/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34921804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alternative-firmware","arduino","e-ink","epub-reader","esp32","esp32-s3","firmware","handheld","lilygo","lora","mesh-networking","meshcore","mp3-player","platformio","t-deck-pro"],"created_at":"2026-06-29T09:32:05.096Z","updated_at":"2026-06-29T09:32:08.961Z","avatar_url":"https://github.com/danst0.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🦊 Fennek\n\n**An alternative open-source firmware for the LilyGO T-Deck Pro**\n\nMusic, audiobooks, eBooks and LoRa mesh chat — in one handheld.\n\n🇬🇧 English · [🇩🇪 Deutsch](README.de.md) · [🇸🇪 Svenska](README.sv.md)\n\n🌐 **[fennek.dumke.me](https://fennek.dumke.me)**\n\n[![License: GPL v3+](https://img.shields.io/badge/License-GPLv3+-blue.svg)](LICENSE)\n[![Latest release](https://img.shields.io/github/v/release/danst0/fennek?sort=semver\u0026color=success)](https://github.com/danst0/fennek/releases/latest)\n[![Release date](https://img.shields.io/github/release-date/danst0/fennek)](https://github.com/danst0/fennek/releases)\n[![Changelog](https://img.shields.io/badge/changelog-md-informational)](CHANGELOG.md)\n[![Platform: ESP32-S3](https://img.shields.io/badge/Platform-ESP32--S3-orange.svg)](https://www.espressif.com/en/products/socs/esp32-s3)\n[![Board: T-Deck Pro](https://img.shields.io/badge/Board-LilyGO%20T--Deck%20Pro-green.svg)](https://www.lilygo.cc/products/t-deck-pro)\n[![Build: PlatformIO](https://img.shields.io/badge/Build-PlatformIO-blueviolet.svg)](https://platformio.org/)\n\n\u003c/div\u003e\n\n---\n\n**Fennek** turns the LilyGO T-Deck Pro (ESP32-S3, E-Ink, LoRa) into a real\nhandheld: listen to music, resume audiobooks, read eBooks and chat over the LoRa\nmesh via **MeshCore** — with a homescreen launcher, touch + physical keyboard,\nand background audio that keeps playing across app switches. Like the desert\nfox: small, frugal, big ears.\n\nIt is a **standalone alternative** to the factory firmware — built around the\nhardware's defining quirk, that E-Ink, the SD card and LoRa all share **one**\nSPI bus, while still delivering stutter-free audio playback.\n\n## 📸 Screenshots\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/screenshots/en/launcher.png\" width=\"240\" alt=\"Launcher\"\u003e\u003cbr\u003e\u003csub\u003eLauncher (app picker)\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/screenshots/en/music.png\" width=\"240\" alt=\"Music player\"\u003e\u003cbr\u003e\u003csub\u003eMusic – playback\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/screenshots/en/games-ttt.png\" width=\"240\" alt=\"Tic-Tac-Toe\"\u003e\u003cbr\u003e\u003csub\u003eGames – Tic-Tac-Toe\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/screenshots/en/settings.png\" width=\"240\" alt=\"Settings\"\u003e\u003cbr\u003e\u003csub\u003eSettings (radio \u0026amp; system)\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/screenshots/en/sleep.png\" width=\"240\" alt=\"Standby\"\u003e\u003cbr\u003e\u003csub\u003eStandby (sleeping fennec)\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/screenshots/en/maps.png\" width=\"240\" alt=\"Maps\"\u003e\u003cbr\u003e\u003csub\u003eMaps – offline SD tiles + GPS\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003csub\u003eRendered pixel-accurately from the real drawing code (240×320 E-Ink) via\n\u003ccode\u003etools/screenshots.sh\u003c/code\u003e — see \u003ca href=\"tools/README.md\"\u003etools/\u003c/a\u003e.\u003c/sub\u003e\n\n## ✨ Apps\n\n| App | Features |\n|---|---|\n| **🎵 Music** | MP3/AAC/FLAC/WAV from SD (`/music`), artist/album/playlist browser, ID3 tags (with SD cache), shuffle/repeat, sleep timer, resume after reboot |\n| **🎧 Audiobook** | Books as folders under `/audiobooks`, chapters natural-sorted, per-book bookmark (NVS), ±30 s jumps, sleep timer |\n| **📖 Reading** | `.txt` and `.epub` from `/books`, on-device EPUB conversion (ROM-tinfl), page-index cache, per-book reading position |\n| **📡 Mesh** | Lean MeshCore client: public and hashtag channels (`#test` …), DMs with delivery status, contacts from adverts, message log on SD incl. history reload |\n| **🎮 Games** | 2048, Minesweeper, Chess (Negamax AI) and Tic-Tac-Toe — logic host-tested |\n| **📝 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 |\n| **🎙️ 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 |\n| **⚙️ Options** | Radio presets (EU Narrow = DE/NRW standard 869.618 MHz / 62.5 kHz / SF8), individual parameters, node name, battery info, firmware version |\n\nPlus: a status line (battery, playback), standby/key-lock via the button, and a\nserial debug console over USB (type `help` — `status`, `chan test hello`,\n`meshlog`, `ls /books` …).\n\n## 🔧 Hardware\n\nLilyGO **T-Deck Pro V1.1**: ESP32-S3 (16 MB flash, 8 MB PSRAM), E-Ink\nGDEQ031T10 240×320, CST328 touch (I2C), TCA8418 keyboard, PCM5102A DAC\n(I2S, 3.5 mm jack), SX1262 LoRa, BQ27220 fuel gauge, microSD.\n\n\u003e **Defining quirk:** E-Ink, the SD card and LoRa share **one** SPI bus. The\n\u003e entire architecture revolves around audio never stuttering despite that, and\n\u003e inputs responding instantly — details in [`CLAUDE.md`](CLAUDE.md)\n\u003e (anti-stutter invariants).\n\n## 🧭 Engineering around the hardware\n\nThe T-Deck Pro has four awkward constraints; Fennek is the story of working *with*\nthem. (Full design notes and anti-stutter invariants in [`CLAUDE.md`](CLAUDE.md).)\n\n- **🕐 No real-time clock.** There is no battery-backed RTC. The canonical clock is\n  the ESP32 system time (it survives deep sleep, unlike a `millis()` clock), set in\n  priority order from **GPS → NTP → mesh adverts**; drift is learned and a\n  future-dated packet can't drag the clock forward unchecked.\n- **🔋 Can't stay online.** Always-on networking isn't possible on this power budget —\n  and Wi-Fi and audio can't run at once (the Wi-Fi task on core 0 evicts the audio\n  task). So Fennek never holds a connection: scrobbles, note polishing and **podcast\n  downloads** are batched into a short Wi-Fi window before standby, and unused\n  peripherals (GPS, haptics) are powered down at boot.\n- **🧩 Only two cores.** Two cores mean barely any true multitasking. Audio decoding\n  is pinned to core 0, the UI + mesh pump to core 1; SD library scans pause during\n  playback and the chess AI runs at low priority — so playback stays smooth and the\n  keyboard responsive.\n- **🖋️ E-Ink screen.** E-Ink is beautiful but slow, and full refreshes flash the\n  panel. Fennek redraws only on a real change, paints progress/status as narrow\n  *region strips* instead of full repaints, and stretches the anti-ghosting full\n  refresh out to keep the screen calm.\n\n## 🚀 Build \u0026 Flash\n\nPrerequisite: [PlatformIO](https://platformio.org/). Connect the T-Deck Pro via\nUSB-C, then:\n\n```bash\npio run -e fennek              # build\npio run -e fennek -t upload    # flash (USB-C)\npio device monitor -b 115200   # log + debug console\n```\n\nThe firmware also runs **without an SD card** (apps then show a hint). Radio\nparameters are configurable at runtime in the Options app; the default is the\n**EU/UK Narrow** preset commonly used in Germany.\n\n\u003e ⚠️ Custom firmware replaces the factory software. You flash at your own risk —\n\u003e a way back to the original firmware is available via the\n\u003e [LilyGO resources](https://github.com/Xinyuan-LilyGO).\n\n## 📁 Project layout\n\n- `src/` — active firmware (`core/` drivers \u0026 framework, `services/` audio/\n  library/text, `apps/` the apps)\n- `lib/meshcore/`, `lib/ed25519/` — vendored MeshCore stack (subset)\n- `boards/t-deck_pro.json` — board definition (partition `default_16MB.csv`)\n- `CHANGELOG.md` — release notes\n- `CLAUDE.md` — architecture, invariants, verification status\n- `LICENSE` — GPL-3.0-or-later\n\n## 📜 License\n\nFennek is licensed under the **GNU General Public License v3.0 or later\n(GPL-3.0-or-later)** — see [`LICENSE`](LICENSE).\n\nBundled components keep their own GPL-compatible licenses:\n\n- **MeshCore** (`lib/meshcore/`) — MIT License, © Scott Powell / rippleradios.com\n  ([original](https://github.com/ripplebiz/MeshCore), [`lib/meshcore/LICENSE`](lib/meshcore/LICENSE))\n- **ed25519** (`lib/ed25519/`) — zlib License, © Orson Peters\n  ([`lib/ed25519/license.txt`](lib/ed25519/license.txt))\n\n## 🙏 Credits\n\nFennek started out inspired by the **Meck** fork\n([pelgraine/Meck](https://github.com/pelgraine/Meck), a MeshCore companion for\nthe T-Deck), but was rebuilt from v1.0.0 as a standalone multi-app firmware and\nhas been its own project ever since. The mesh stack is based on\n[MeshCore](https://github.com/ripplebiz/MeshCore) by Scott Powell. The earlier\nMeck code (formerly under `archive_legacy/`) lives in the Git history and can be\nrestored from there at any time.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanst0%2Ffennek","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanst0%2Ffennek","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanst0%2Ffennek/lists"}