Tactility Enhanced for T-Deck

Full hardware support for LilyGO T-Deck with enhanced features

Current Version: v0.2.5.0-WebServer-PSRAM-QoL-Enhancements

Overview

Tactility Enhanced is a custom distribution of Tactility OS specifically optimized for the LilyGO T-Deck, unlocking hardware features not available in the stock firmware.

What Makes This Different?

This build enables full T-Deck hardware utilization that stock Tactility doesn't provide:

✅ Working Features:

• USB Serial JTAG - Bidirectional relay support (Rx + Tx)
• UART Relay App - Monitor and control serial devices with USB/SD logging
• Firmware exports - Extended symbol table for advanced app development
• GPS (GNSS) - Built-in receiver supported
• I2C - Stock I2C bus support
• Keyboard backlight control - Brightness, timeout & wake-on-keypress
• Trackball navigation - Full UI navigation with visual focus indicators & wake-on-use
• WebServer - Built-in HTTP server with file browser and REST API
• App Hub - Download and install apps from CDN
• System Logging - Comprehensive logging to flash with rotation & SD archiving
• Settings Sync - Auto-backup/restore settings to SD card (survives firmware flashes)
• PSRAM Optimized - Aggressive PSRAM usage for stability (150KB+ internal RAM free)

🚧 In Development:

• Web-based serial terminal - Access UART over WiFi
• 4G LTE support - Cellular connectivity
• LoRa transceiver - Long-range communication

Key Applications

UartRelay - Flagship app for this distribution

• Bidirectional UART relay (device ↔ USB/WiFi)
• SD card logging with timestamps
• Real-time serial monitoring
• Configurable baud rates and protocols
• Future: GPS-tagged logs, remote access via 4G

Why This Fork Exists

The LilyGO T-Deck is packed with features (WiFi, 4G, GPS, LoRa, trackball, backlit keyboard) that aren't fully utilized by existing firmware options. This project aims to:

1. Enable all hardware - Every feature should work
2. Professional tools - Advanced debugging and development capabilities
3. Field deployment - Reliable remote access and monitoring
4. Developer friendly - Extended API for custom apps

Hardware Support

Fully Supported:

• LilyGO T-Deck (all variants)
• ESP32-S3 with 8MB+ PSRAM

Tested On:

• LilyGO T-Deck v1.0

Installation

Prerequisites

• LilyGO T-Deck device
• USB-C cable
• SD card (recommended: 8GB+)
• For UartRelay: JST-PH 2.0mm 4-pin connector (HY2.0-4P) to access the onboard UART port for device monitoring

Quick Start

1. Download latest release

   • Firmware: Tactility-Enhanced-[version].bin
   • Apps: UartRelay.elf
   • Direct app ELF: https://raw.githubusercontent.com/cscott0108/tactility-enhanced-t-deck/main/Prebuilt/SDCard/app/one.tactiity.uartrelay/elf/esp32s3.elf
   • SD card layout folder: https://github.com/cscott0108/tactility-enhanced-t-deck/tree/main/Prebuilt/SDCard/app/one.tactiity.uartrelay
   • Releases: https://github.com/cscott0108/tactility-enhanced-t-deck/releases

2. Flash firmware (Windows/Linux/Mac)

esptool.py --port COM3 write_flash 0x0 Tactility-Enhanced.bin

3. Install apps

   • Copy .elf files to SD card: /sdcard/app/
   • Or use built-in App Hub

4. First boot

   • Configure WiFi in Settings
   • Launch UartRelay from app list
   • Adjust keyboard backlight & timeout: Settings > Keyboard
   • (Optional) Change idle settings reload interval: Settings > Development
   • Test wake: let display/backlight timeout, press any key → both wake

Building from Source

See BUILDING.md for detailed instructions.

# Clone repository
git clone https://github.com/cscott0108/tactility-enhanced-t-deck
cd tactility-enhanced-t-deck

# Build firmware
idf.py build

# Build apps
cd Apps/UartRelay
python3 tactility.py build esp32s3

Roadmap

Phase 1: Core Hardware ✅

• USB Serial JTAG bidirectional
• UART relay functionality
• SD card logging
• GPS (GNSS)
• Keyboard backlight (brightness + timeout + wake)
• Trackball navigation (encoder-based UI selection + wake)

Phase 2: WebServer & Connectivity ✅

• WiFi file server (built-in HTTP server)
• Web file browser interface
• REST API for file operations
• App Hub integration (CDN downloads)
• Settings sync to SD card

Phase 3: Stability & Logging ✅

• PSRAM aggressive optimization
• System logging with rotation
• Early boot log capture
• Manual SD card archiving
• Crash detection & safe mode

Phase 4: Future 🚧

• Web-based serial terminal
• 4G LTE module support
• LoRa transceiver

Phase 5: Integration 📋

• GPS-tagged UART logs
• Remote UART access (WiFi/4G)
• LoRa UART bridge
• Web dashboard
• MQTT integration

Contributing

Contributions are welcome! This project aims to make the T-Deck reach its full potential.

Areas where help is needed:

• Testing on different T-Deck variants
• Documentation improvements
• New app development
• Hardware feature implementation

Differences from Stock Tactility

Feature	Stock Tactility	This Fork
USB Bidirectional	❌	✅
Keyboard Backlight	❌	✅
Trackball Support	❌	✅
WebServer/File Browser	❌	✅
App Hub Downloads	✅	✅ (Fixed HTTPS)
System Logging	❌	✅
Settings SD Backup	❌	✅
PSRAM Optimized	❌	✅
Crash Detection	❌	✅
4G LTE	❌	📋
GPS	✅	✅
LoRa	❌	📋
Web Serial Terminal	❌	📋
UartRelay App	❌	✅
I2C	✅	✅

Legend: ✅ Working | 🚧 In Progress | 📋 Planned | ❌ Not Available

What's New in v0.2.5.0

🚀 Major Features

• WebServer with File Browser - Built-in HTTP server at port 80, browse/upload/download files via web interface
• App Hub Integration - Download and install apps from the Tactility CDN
• PSRAM Optimization - Aggressive PSRAM configuration, 150KB+ internal RAM free (was 30KB)
• System Logging - Comprehensive log capture to /data/Log/system.log with rotation (7 backups)
• Settings Sync - Auto-backup/restore settings to SD card, survives firmware flashes

🔧 Technical Improvements

• Dual Versioning - CDN compatibility (0.7.0) while tracking enhanced features (0.2.5.0)
• HTTPS/TLS Downloads - App Hub downloads work reliably with proper timeout handling
• Early Boot Logging - Capture logs from before FileLog service starts
• Manual SD Archiving - Archive logs to SD card via System Info button (SPI bus safe)
• Event-Driven Architecture - Reduced CPU/disk overhead with PubSub events

🛡️ Stability Fixes

• Boot Watchdog Fix - Deferred SD operations to prevent boot freezes
• SPI Bus Safety - LVGL lock during SD card operations
• Memory Management - WiFi/LWIP buffers in PSRAM, reduced internal RAM pressure
• Crash Detection - Automatic safe mode after 3 crashes in 60 seconds

Recent Enhancements

Unified Idle Management

• Display + keyboard backlight idle logic merged into one service (reduced polling overhead)
• Configurable settings reload interval (default 10s) via Settings > Development

Keyboard Backlight Improvements

• Settings > Keyboard: enable, brightness, timeout enable, timeout value (5s–10min)
• Timeout & preferences persisted (NVS)
• Wake-on-keypress immediately restores display + keyboard backlights

Stability & Boot Reliability

• Deferred I2C initialization (keyboard & trackball) resolves early heap corruption
• Encoder-based trackball navigation with LVGL focus indicators for visual feedback
• NTP time persisted/restored before SNTP sync

Developer Quality of Life

• Idle reload interval user-adjustable (prompts reboot when changed)
• Reduced duplicated timers by consolidating services

Troubleshooting

Symptom	Resolution
Keyboard press doesn't wake display	Ensure timeout feature enabled; try a non-modifier key
Timeout value not saved	Leave Keyboard settings screen to trigger save
Idle interval not applied	Reboot after changing in Development settings
Early boot panic	Update to latest build (includes deferred I2C init)

Upgrading

1. Flash new firmware
2. (Optional) Clear outdated /data/settings/ entries if behavior is inconsistent
3. Re-set keyboard timeout (Settings > Keyboard)
4. Adjust idle reload interval (Settings > Development) if needed

Credits

Based on Tactility by Ken Van Hoeylandt (ByteWelder)

This is a community-driven fork focused on T-Deck hardware support. We maintain compatibility with the Tactility app ecosystem while extending hardware capabilities.

License

GNU General Public License Version 3