vtOS: A Terminal-Based Hobby Firmware

vtOS is a hobbyist firmware designed to transform the LilyGO T-Deck into a pocket-sized, hackable terminal computer. Developed primarily in MicroPython, it moves away from traditional GUI-heavy interfaces in favor of a text-based environment that feels both retro and modern. It provides a comprehensive suite of networking tools, local productivity apps, and communication utilities, all accessible through a built-in shell.

A Swiss Army Knife for the Handheld Terminal

At the heart of vtOS is its custom shell, which serves as the primary interface for the device. Unlike a standard REPL, this shell is stocked with a variety of built-in commands and clients. Users can browse the modern web via Gemini and Gopher protocols, connect to classic communication channels via IRC and Telnet, or manage remote servers using SSH and FTP clients.

For local tasks, vtOS includes a TUI (Text User Interface) file manager and a text editor based on vi (specifically a port of neatvi). The editor is highly configurable with support for multiple themes, making it a viable tool for on-the-go coding or configuration tweaks. The system also supports offline content consumption, featuring a Wikipedia reader that can handle a 170MB database from an SD card and an EPUB reader for e-books.

Hardware Integration and Customization

The firmware is highly optimized for the LilyGO T-Deck hardware. It includes specific drivers and mappings for:

• Display: SPI-based 2.8” ST7789 LCD (320x240) with full color support.
• Input: Full mapping for the I2C keyboard and the GPIO-based trackball, where the trackball handles terminal and command history navigation.
• Communication: Integrated support for the SX1262 LoRa radio and BLE, allowing for flood-mesh chat rooms that don’t require a Wi-Fi connection.
• Audio: I2S support for MP3, WAV, and Codec 2 playback and recording.

One of the most powerful features for power users is the .shellrc startup script. Much like a traditional Linux environment, users can automate their workflow by placing a script in /flash/ or /sd/. This allows for automatic Wi-Fi connection, setting default fonts, or launching specific applications immediately upon boot.

Server Capabilities

While vtOS is an excellent client, it also functions as a portable server. It can host SSH, FTP, Telnet, and VNC servers simultaneously. This allows users to access the T-Deck’s shell or filesystem from another machine, or even view the device’s screen remotely via VNC. For web-based access, it includes webvncd, a faster, web-friendly alternative to standard VNC.

Technical Architecture

vtOS is built on top of MicroPython v1.28.0 and ESP-IDF v5.5.1. By utilizing the ESP-IDF component system, it integrates several high-level libraries including Radiolib for LoRa communication, wolfSSH for secure shell access, and Codec 2 for digital voice encoding.

Because the system is “MicroPython all the way down,” it remains incredibly accessible for developers. The entire shell and its associated applications are open for inspection and modification directly on the device. For those looking to build the firmware from scratch, the project provides a robust Makefile and Docker-based build system, ensuring a consistent environment for cross-compilation for the ESP32-S3 platform.