vtterm internals

This page is for you if you’re changing vtterm or wondering why it’s built the way it is; using it is in the vtterm guide. vtterm is three small parts and two ways to join them to a Python prompt. It is pure Python, so the same package runs on every interpreter, and it draws with pygraphics, so it needs nothing from a display but blit_rect.

bytes from the REPL, a program, or another device
            |
            v
        Parser ----- answers (cursor position, device type) back to the sender
            |
            v
        Screen: characters, colors, styles, cursor; dirty rows marked
            |
            v
       Renderer: each dirty row composed in one strip, one blit_rect
            |
            v
         the display

The parser

Parser.feed is a byte-at-a-time state machine: ground, escape, CSI parameters, strings and the character-set and # prefixes. It keeps its state between calls, so a sequence split across two reads from a link finishes on the second. Printable ASCII goes to the screen in runs, not a byte at a time, which is most of what a REPL prints.

24-bit colors are kept as the nearest of the 256 ANSI colors, so every cell’s color fits in one byte. The palette needed for that is imported only when the first 24-bit color arrives.

A cell’s character is one byte too, and the fonts are ASCII. The line-drawing characters, from the DEC set or from UTF-8, are stored as the codes below 32, which no printable character uses, and the renderer draws those as lines itself. They meet at the middle of each cell’s edges, so a box joins up with any font.

The screen

Each row is four bytearrays the width of the screen: characters, foreground, background and style flags. A scroll moves rows in a list rather than copying bytes. A row that changes is marked dirty, and a whole-screen scroll is counted, so the renderer knows what to draw.

The cursor follows the VT100 when a character lands in the last column: it stays there with a wrap pending, and the next character starts the new row. This matches xterm and a real VT100, and it’s what the line editors in REPLs expect.

The renderer

The renderer keeps one strip buffer, a row high and the display wide, in RGB565. For each dirty row it fills each run of cells that share colors, draws their text with a pygraphics font, adds underline and the cursor, and sends the strip with one blit_rect. A display that scrolls in hardware (an SPI panel’s scroll registers, or the desktop window) moves the picture on a whole-screen scroll, and only the new rows are drawn.

The memory it needs is the screen, four bytes per cell, plus the strip, the display’s width times the font’s height times two bytes.

The two ways in

Console is a stream for os.dupterm. The REPL writes to it, and it reads the bytes you push, or the bytes a key source returns, when the REPL looks for input. While output streams it redraws at most every interval_ms, and everything left is drawn when the REPL next waits.

session.run is an asyncio loop for a link to another device: bytes from the link go to the parser, and key bytes and the parser’s answers go back down the link.

Ctrl-C from a timer

A keyboard read from a timer pushes Ctrl-C from inside the timer’s callback. Raised there, the interrupt would land in the callback, and a busy program wouldn’t see it until it next waited. Console.push schedules the notify with micropython.schedule instead, so the interrupt is raised in the running program once the callback returns, as it is for Ctrl-C over USB.

A soft reset with the console attached

On ESP32 firmware, a soft reset frees every object and then writes “soft reboot” to the dupterm streams, before it clears them. With a Python stream such as Console attached, that write runs on freed memory: the board prints an error from some unrelated object, or panics and restarts. OmniPython MP firmware clears the dupterm slots first, so a soft reset there is clean. On other ESP32 firmware, detach() the console before Ctrl-D.