t-deckard/README.md

T-DeckARD: T-Deck Augmented Runtime Distribution

About

T-DeckARD is a curated, interconnected and integrated collection of Python 3 modules developed for CircuitPython 10.x on LilyGO T-Deck (but also mostly compatible with MicroPython and desktop CPython) aimed at turning the stock (Circuit)Python REPL into an easy to use operating environment.

T-DeckARD modules are divided into two categories: components, which are the building blocks anyone can use to easily create their own applications, and ready-made applets which can already be used as stand-alone applications, as well as included as components of other, more complicated ones. This repo also hosts the games section which is just a special kind of applets that implement various computer games.

Prerequisites for T-Deck (Plus)

On T-Deck (Plus), the following components must be installed:

• CircuitPython 10.x (tested on 10.0.3);
• Adafruit Library Bundles from the official CircuitPython page.

If you have circup installed, you can connect the device via USB and then run circup install -r requirements.txt from the project root.

The tdeck_repl distribution is already incorporated into the repo.

On other generic platforms, most modules which are not T-Deck-specific are set to work on both CPython and MicroPython.

Installation on T-Deck (Plus)

Current installation process doesn't involve any .mpy module compilation, so, after installing the prerequisites, you just need to copy the repl, deck and app directories, as well as the code.py and tdeckboot.py files, into the root of the CIRCUITPY removable volume.

Components (deck.*)

As of now, T-DeckARD implements the following component modules.

deck.runtime

A library for establishing runtime compatibility across various Python environments.

Exported functions:

• runcode(code_string): compile and execute a Python program expressed as a string. Used by REPL and some applets.

deck.input

A library for single-line and multi-line (ed-like) text input.

Exported functions:

• input(prompt=None): standard single-line Python input
• input_multi(prompt=None, terminator='.'): multi-line input, end with the terminator string on a separate line

deck.pager

A library for paged text output. In CPython, relies on the terminal dimensions provided by the host OS. In CircuitPython and MicroPython, it requires correct values to be provided inside TERM_COLS and TERM_ROWS environment variables. In case they are not provided, these values default to 53 columns and 19 rows (the actual value for T-Deck running tdeck_repl in CircuitPython).

Exported functions:

• term_size(): return the terminal dimensions tuple in the (rows, columns) format
• reflow(text): split text into a list of lines not exceeding terminal width
• print_paged(text): reflow and print the text in a paginated manner, prompting for Enter presses to move to the next page

deck.menu

A library for easy menu systems for T-DeckARD programs. Allows displaying up to 10 menu items with the ability to select them with a single digit or a key on the QWERTYUIOP keyboard row.

Exports the only function, menu(choices), which accepts a list of tuples, each in the format (id, label). The label field is what's displayed on the screen, the id field is the string that gets returned upon selection. If the user selects c, the operation is canceled and an empty id string is returned.

deck.time

A wrapper for standard Python date, time and datetime modules. Just run from deck.time import * to activate.

deck.chat

A generic chat UI helper library. Exports a single class called DeckChat with the following parameters:

chat_instance = DeckChat(start_state={}, chat_prefix='> ', command_prefix='/')

where the constructor parameters are:

• start_state: the state object to be modified by chat actions
• chat_prefix: the prefix to be displayed before each user's message input
• command_prefix: the prefix to be prepended to every registered chat command

Every chat instance exposes the following methods:

• command(command_name, handler): register a command under the command_name according to the handler specification (see below); e.g. if the prefix is / and the command name is list, the chat will react to the /list command and pass everything after it as the argument to the handler function
• start(): start the chat loop (keyboard interrupts, if any are supported, exit the loop)

The handler accepts two parameters: a message and a state object, and returns the response and the new state object. If the returned state object is None, then the chat loop exits. Non-command handler (i.e. what should be done on any user input that doesn't start with a registered command) is registered under the default command.

deck.xlat

Character translation helper library. For now, only supports base Cyrillic character set.

Exports the following functions:

• enc(s, mapname='CYR'): encode from the selected character set into Latin
• dec(s, mapname='CYR'): decode from Latin into the selected character set

deck.fs

FS helper librаry.

Exports the following functions:

• unlock_rootfs(): make the device root filesystem read-write (does nothing on desktop)
• lock_rootfs(): make the device root filesystem read-only (does nothing on desktop)
• stat(path) (aka du(path)): alias to os.stat but returning the stats as a dictionary
• statvfs(path) (aka df(path)): alias to os.statvfs but returning the stats as a dictionary
• mount_sd(path='/sd', readonly=False): mount the inserted microSD card (T-Deck only, must be FAT32)
• umount_sd(path='/sd'): unmount the inserted microSD card (T-Deck only)

The following deck.fs functions are direct aliases to the corresponding os call counterparts:

• sep = pathsep = os.sep
• cwd = pwd = os.getcwd
• ls = listdir = os.listdir
• md = mkdir = os.mkdir
• cd = chdir = os.chdir
• rd = rmdir = os.rmdir
• rm = remove = os.remove
• mv = rename = move = os.rename
• sync = os.sync (where supported)
• env = getenv = os.getenv
• rnd = urandom = os.urandom

deck.hwinfo

Various hardware information. May be expanded in the future.

Exports the following functions:

• board_id(): get the board ID (e.g. lilygo_tdeck for T-Deck/T-Deck Plus), or emulated if it's not run on a CircuitPython device
• battery_v(): (T-Deck-specific) get the current battery voltage (or 0 if running in an emulated environment)
• cpu_f(): CPU frequency in Hertz

Also, this module exposes the REAL_HW variable to detect whether the code is running on a real hardware in the CircuitPython environment.

deck.net

T-Deck/CircuitPython-specific library for Wi-Fi connection and returning requests and socket library instances.

Exported functions:

• wifi_scan(): scan available Wi-Fi networks and return the list of (ssid, rssi) tuples (sorted from the strongest signal to the weakest)
• wifi_connect(ssid=None, password=None): connect to a Wi-Fi SSID without waiting (default credentials are pulled from the /settings.toml file)
• wifi_connect_wait(ssid=None, password=None, tmout=15, retries=3): connect to a Wi-Fi SSID (with the same parameters as wifi_connect) and wait until the connection is established
• my_ip(): return the current local IPv4 (as a string)
• ssl_context(): get the default SSL context for wrapping in a raw socket
• init_socket(): return the active reference to the socket library
• init_requests(): return the active reference to the requests library
• init_ntp(tz=0): return an NTP time client instance (use the .datetime property of the instance to access current time and the tz parameter to specify the timezone offset)

A normal flow for instantiating a Requests library looks like this:

# init requests library in a platform-agnostic way
requests = None
try:
  from deck import net
  print('Waiting for online status...')
  status, stext, myip = net.wifi_connect_wait()
  if status:
    print("We're online, initing requests lib...")
    requests = net.init_requests()
except:
  import requests

deck.http

High-level HTTP client library.

Exports the following functions:

• http_set_ua(ua_str='Mozilla/5.0'): set a default HTTP user agent string
• http_fetch(url, useragent=None, hdrs={}): fetch text content from a URL into a string (returns (status_code, content) tuple)
• auth_header(username, password): get a dictionary fragment with the corresponding HTTP Basic Auth header according to the username and password
• url_escape(s): escape a string to be used as a part of URL parameters
• form_encode(params): encode a form body dictionary in the x-www-form-urlencoded format
• wget(url, filename='', useragent=None, hdrs={}): download a file into a local path (returns (status_code, filename) tuple)
• wput(url, file_path, field_name="file", method="POST", format="x-www-form-urlencoded", headers={}, useragent=None): upload a file from a local path in the x-www-form-urlencoded or JSON format (returns (status_code, content) tuple)

deck.otp

A library that provides HOTP and TOTP one-time password implementations.

Exports the following functions:

• hotp(key, counter, digits=6): generate a digits-long HOTP code from (bytes-only) key and counter value
• totp(key, time_step, digits=6): generate a digits-long TOTP code from (bytes-only) key, using time_step as the basis (30 seconds is default and the most common)
• get_epoch(): a helper platform-agnostic function to get the current Unix timestamp in seconds

deck.text

A library that implements a DeckText format parser. Exports a single class, DeckText, with the following methods:

• doc = DeckText(src=None) constructor: initialize a DeckText document object from the passed source
• doc.load(src): load DeckText source into the existing document object.

After the source is loaded, the document object exposes two properties: title and pages.

The title property is a normal string that represents the document's title (read from the <title> HTML tag).

The pages property contains a list of DeckText pages in the form of {content, links} dictionary, where content is the rendered (ready-to-display) page content and links is the list of links present on the page.

Each link is in the form of (url, label) tuple. The client using this class for DeckText page rendering is supposed to provide a UI to visit the links based on this list.

deck.llm

A helper library for interaction with remote LLM (large language model) endpoints that expose OpenAI-compatible API. As of now, it only exports a single class, LLMChat, to encapsulate all the interaction.

To initialize, this class requires a provider configuration object from a JSON file that looks like this:

{
  "temperature": 0.7,
  "system_prompt": "You are a concise, embedded assistant.",
  "active_provider": "openrouter",
  "providers": {
    "openrouter": {
      "base_url": "https://openrouter.ai/api/v1",
      "api_key": "...",
      "model": "xiaomi/mimo-v2-flash:free",
      "extra_headers": {}
    },
    "pollinations": {
      "base_url": "https://text.pollinations.ai/openai",
      "api_key": "",
      "model": "openai-fast",
      "extra_headers": {}
    }
  }
}

Then, we initialize it like this:

llm = LLMChat(config_file=CONFIG_FILE_PATH, message_limit=20)

The instance exposes the following methods (all returning a (status, result) tuple where applicable):

• load_config(config_file='llmcfg.json'): load configuration from a config file
• save_config(): save current configuration into the config file
• setup_provider(): load currently active provider settings
• reset_context(): clear the conversation history and re-add the system prompt
• get_completion(prompt): prompt the LLM and return the response message
• list_models(): list available model IDs from the current active provider
• get_last_response(): get the most recent assistant's response as a plain string
• add_file(fname): read a text file and add it to the context (within the message limit)
• export(): export the entire current conversation (within the message limit) as a plain string

Applets (app.*)

As of now, T-DeckARD implements the following applets.

app.ed

A simple line-oriented text editor and page-oriented text viewer for MicroPython/CircuitPython implementing a POSIX ed subset (feature-wise, it still is closer to EDLIN from DOS).

Exports the following functions:

• edit(filename): start an ed-like text editor on a file (see below)
• edbuf(bufstr=''): create an empty buffer, fill it with the input string (if any), run the editor interface on it and return the result as a string (without creating any files)
• edurl(url): download the URL contents via HTTP, run the editor interface on it and return the result as a string (without creating any files)
• view(filename, lno=False): start a more-like pager for viewing a text file (pass an additional parameter to view it with line numbers)
• viewbuf(text, lno=False): same as view but for string variables instead of files
• viewurl(url, lno=False): download the URL contents via HTTP and run viewbuf method on the result

Note: with edbuf and edurl methods, you can always save the file locally while inside the editor interface. Use the f command to specify the name (see below).

The editor mode supports the following subset of POSIX ed commands in the standard [range][command][param] syntax:

• p: print out the range
• n: print out the range with line numbers
• a: append new text to the end of the range
• i: insert new text to the start of the range
• c: replace the range with new text
• d: delete the range
• s/old/new: replace text in the range (doesn't support regex syntax from POSIX ed)
• f: set the current filename to write to
• w: save changes to the current filename
• x: interpret the range as Python code and execute it immediately
• q: quit (q! force-quits without prompting for saving changes)

app.llmchat

A simple interactive chat with remote LLMs. Configured via llmcfg.json (see the deck.llm module reference and the llmcfg.example.json file) placed into the storage root. Run with the single llmchat() method it exports.

Supported chat commands:

• /help: display a brief help
• /clear: clear the conversation context
• /system: display or set the system prompt
• /temp: display or set the model temperature
• /prov: display or set the current provider selection
• /model: display or set the current model selection
• /provlist: list provider IDs in the config
• /modellist: list model IDs available for current provider
• /add: add a (text) file to the context
• /saveconv: save the entire conversation log (within the current limits) into a file
• /savelast: save the most recent message into a file
• /savecode: extract code blocks from the most recent message and save them into a file
• /edcode: extract code blocks from the most recent message and open app.ed.edbuf() on the contents
• /exit or /quit: exit the chat applet

app.bro

An implementation of DeckBro, a simple text-only HTTP browser for DeckText and simple HTML documents.

Usage: from app.bro import bro, then bro(starting_url).

Available commands:

r)ef b)ack f)wd n)ext p)rev l)ink or pg#: q

• g [url]: go to a new URL
• r: refresh the current document
• b: go back in history
• f: go forward in history
• n: go to the next DeckText page of the document (this is the default action if you just press Enter)
• p: go to the previous DeckText page of the document
• [num]: jump to the page [num] if it exists
• l [num]: visit the link number [num] on the current page (if it exists)
• q: quit the browser

app.blog

A simple interface to any POST-based blog API that supports HTTP Basic Auth.

Requires the following environment variables to be configured (for T-Deck, use the /settings.toml file):

• BLOG_POST_ENDPOINT: the full URL to send POST requests to
• BLOG_POST_USER: the username to send the requests as
• BLOG_POST_PASS: the password for this username

Exports the following functions:

• blogpost(): wait for a (multiline) input and send the post
• bloged(): same as blogpost() but with a full-featured app.ed interface
• blogpost_str(content): post the content in a non-interactive manner

Games (game.*)

As of now, T-DeckARD implements the following games.

Scoundrel (game.scoundrel)

A port of the rogue-like card game Scoundrel to CircuitPython. Uses M to denote monsters, W to denote weapons, P to denote potions and D to denote weapon durability.

Implements the official ruleset of the game with no modifications.

Run: scoundrel() from the REPL itself, or use from game.scoundrel import scoundrel in other code.

Controls: enter a, b, c or d to interact with an item above this letter in the room, or r to run from the room in case it's possible. To quit the game before winning or losing, enter the q command at any time.

FAQ

Is this an OS shell?

No, but it provides comparable functionality to the on-device Python REPL. You can easily build a shell application from the T-DeckARD components.

Why doesn't it include a shell by default?

It may at some point, but the entire idea is to give you the foundation to easily create your own custom shells for any special purposes. The project carries the spirit of early personal computing days when the programming language REPL (BASIC, Forth, Lisp etc) was your primary operating environment. In this case, the on-device Python REPL is such an environment.

To get the hang of what the shell might look like, you can already access some of the common methods from the main core modules via T-DeckARD REPL. See the tdeckboot.py file for details.

Which platforms is T-DeckARD being tested on?

CircuitPython 10.x on a T-Deck Plus and MicroPython for modern x86_64 Linux. That's it.

So, can I use T-DeckARD outside CircuitPython or even MicroPython?

Yes, but don't expect some modules (like deck.net) to work at all. Wrap your code inside try-blocks to achieve maximum compatibility.

The virtcode.py could be used with bare tdeck_repl but can't be used here. Why so?

It has been renamed. Place your startup code into autoexec.py instead.

You can start it with from tdeckboot import * to give it the same extended capabilities as the interactive REPL.

So, what's the difference between tdeckboot.py and autoexec.py?

Everything that gets imported inside tdeckboot.py becomes automatically available in the T-DeckARD interactive REPL. This file is solely designed for passthrough import of modules into the REPL and nothing more.

Everything that gets imported inside autoexec.py stays in autoexec.py. This is just your usual startup script.

You can use tdeckboot.py for autoexecing but that's not recommended as this carries a heavy risk of REPL namespace pollution.

Is there any feature roadmap for core components?

The foundational module set is going to at least include high-level capabilities for:

• exposing low-level socket and HTTP APIs (done),
• high-level HTTP APIs (done),
• high-level LLM APIs (partially done),
• date and time informaion (done),
• file system manipulation (done),
• text viewing and editing (done),
• device information collection (done),
• chat UI creation (done).

After all this is implemented, future phases may also include device-specific features like GPS, graphics, sound and touchscreen input.

Is there any feature roadmap for applets?

No. All applets are created ad-hoc when the author needs them.

Credits

Created by Luxferre in 2025-2026, released into public domain with no warranties.

Special thanks to RetiredWizard for providing a wonderful tdeck_repl wrapper.