ILI9341TTY
USB serial TTY for the Arduino Uno with ILI9341 LCD screen shield
Install / Use
/learn @michaelerule/ILI9341TTYREADME
ILI9341TTY
USB serial TTY for the Arduino Uno with ILI9341 LCD screen shield
<p align="center"> <img src="https://user-images.githubusercontent.com/687425/138597953-d5aba9b8-e358-4952-8c00-fc15979596ab.png"> </br> </br> <a href="https://vimeo.com/625432715">[video]</a> </br> <a href="https://vimeo.com/625432715"><img src="https://user-images.githubusercontent.com/687425/136545726-7201accb-b339-4181-a5ac-83aaa7b98b43.gif"></a></br> </p>Semigraphics, ANSI, unicode, and an Arduino LCD-screen terminal
I've been playing with retro-styled interfaces terminal lately. The unicode box and block drawing characters are wonderful for this, especially "symbols for legacy computing". These include characters from classic computers of the twentieth century, and the block-diagonal teletext characters. These can be combined with ANSI escape codes for styled and colored text. Here's an example of a plot rendering in Gnome terminal using the teletext block-diagonal characters and ANSI color codes:
<p align="center"> <img src="./writeup/ploteg.png"> </p>How hard would it be to support these features on an Arduino terminal display? This question led me down a rabbit-hole of vt100 terminal emulators on the arduino.
Getting a basic Arduino terminal monitor is straigtforward, if building upon a graphics library that supports text rendering. Bodmer has a nice demo for the Arduino using the Adagruit GFX graphics libraries, and Philippe Lucidarme has a short-and-sweet demo for the Seeduino (video). Both of these use the ILI9341 touch-screen display, which is commonly available as an Arduino shield.
However, getting good performance with the Arduino is hard. Scrolling requires re-drawing large areas, and is slow. One work-around is to use the ILI9341's built-in vertical scrolling feature. Among the most feature-complete is Nick Matantsev's TinTTY VT100 emulator for Arduino+ILI9341. This includes fast vertical scrolling and a touchscreen keyboard. Nick cites as inspiration this VT100 emulator for the ILI9340 screen with Arduino, by Martin K. Schröder. Bodmer's vertical-scrolling terminal for Arduino+ILI9341 notes that performance can be improved further by optimizing the graphics drivers to write directly to the 8-bit PORTB/C/D registers on the Arduino Uno.
In the broader universe of DIY terminals, Fabrizio Di Vittorio has a full-featured graphics library for the ESP32, which includes an ANSI/VT terminal. James Moxham has explored Arduino terminals with a wide variety of LCD and LED displays. Scargill's tech blog has a VT-100-esque vertical terminal using a ILI9340 display for the ESP8266 (video). Matthew Sarnoff also has this beautiful VT100 implementation using an oscilliscope as a display. I was especially charmed by ht-deko's implementation of ANSI color and style codes for the STM32F103, which builds upon the work of cbm80amiga.
Can we get an Arduino terminal that supports enough semigraphics charactes? Let's implement a virtual terminal monitor for the Arduino Uno and the ILI9341 LCD display with the following objectives:
- Fast enough to be a reasonable output device
- Support ANSI escape codes for color and style
- Interpret incoming data as utf-8 encoded unicode
- Support the box, block, and legacy computing chracters
- Optimize the drawing commands
- Squeeze as much unicode onto the Arduino as possible
(sorry for the poor photo quality, digital camera interacts poorly with the screen's narrow view angle; contrast is better in person)
Version 0.2
Version 0.2 includes some additional unicode characters, including Armenian, Georgian, and Katakana/Hiragana. There was an aborted, incomplete attempt to support devanagari (prefix diacritics would require a bit of extra code to handle). Supported unicode characters are given in v0.2/test_terminal/v0p2supported.txt
How to test it
Download the sketch and upload it onto the Arduino Uno with an Adafruit-style ILI9341 LCD shield.
Python:
BAUDRATE = MYBAUDRATE
ARDUINO_PORT_FILE_NAME = "/dev/MYARDUINOSERIALPORT"
import serial
arduino = serial.Serial(port=ARDUINO_PORT_FILE_NAME, baudrate=BAUDRATE, timeout=.1)
time.sleep(3)
def print_arduino(s=''):
arduino.write(s.encode('utf-8'))
reset = '\x1bc'
print_arduino(reset+'Hello world!')
Bash:
> stty -F /dev/MYARDUINOSERIALPORT MYBAUDRATE cr3 ff1 nl1 bs1
> # (wait for arduino to reset)
> echo -e "\x1bcHello World!" >> /dev/MYARDUINOSERIALPORT
(The flags cr3 ff1 nl1 bs1 will be explained later)
Copy the output of a command with unbuffer
> # (Apt install `expect` to get the `unbuffer` command.)
> unbuffer ls -w1 --color=auto | tee /dev/MYARDUINOSERIALPORT
Send keystrokes with screen or picocom
> screen /dev/MYARDUINOSERIALPORT MYBAUDRATE
This will open a blank window. Try typing to see if text shows up on the Arduino. To exit, press Ctrl-A and release, then press k to kill the screen session, then press y to confirm. Screen sends Carriage Return (CR;\r) instead of Line Feed (LF; \n aka newline). There's no way to change this, but if you install picocom it will play nicely with newlines:
picocom /dev/MYARDUINOSERIALPORT --baud YOURBAUDRATE --omap crcrlf --echo
# (press Control+a Control+x to exit)
How mirror terminal output on the Arduino TTY
First, configure the serial device
> stty -F /dev/MYARDUINOSERIALPORT BAUDRATE ixon cr3 ff1 nl1 bs1
You can the output from a command to the Arduino TTY by redirecting standard output:
ls --color=yes > /dev/MYARDUINOSERIALPORT
We can also use tee to echo the output back to the curent terminal. The echoed output will appear on the main computer immediately, but the command will wait until serial data is finished drawing on the Arduino before exiting.
ls --color=yes | tee /dev/MYARDUINOSERIALPORT
Some commands behave differently when piped through tee, however. The command unbuffer (apt install expect) can trick them into behaving normally:
unbuffer ls --color=yes | tee /dev/MYARDUINOSERIALPORT
You can list the settings of a tty device using stty:
stty -F /dev/MYARDUINOSERIALPORT -a
stty can set the number rows and columns on a tty, but this won't work:
> stty -F /dev/MYARDUINOSERIALPORT MYBAUDRATE rows 20 cols 53
> stty -F /dev/MYARDUINOSERIALPORT -a
speed MYBAUDRATE baud; rows 0; columns 0; ...
What does work is setting the rows and columns on the current virtual terminal in linux. Note that this size will be reset by any window resize events:
stty cols 53 rows 20
Note how the output of ls is correctly wrapped after applying this command:
# (before applying stty cols 53 rows 20)
> unbuffer ls --color=yes | tee /dev/MYARDUINOSERIALPORT
prepare_fonts self_contained_Uno9341TFT_TTY_horizontal_v14 test_terminal writeup
> stty cols 53 rows 20
> unbuffer ls --color=yes | tee /dev/MYARDUINOSERIALPORT
prepare_fonts
self_contained_Uno9341TFT_TTY_horizontal_v14
test_terminal
writeup
You can pipe all output from the shell to the screen by starting a new instance of bash and using tee to send a copy of stdout to the Arduino:
> stty -F /dev/MYARDUINOSERIALPORT MYBAUDRATE ixon cr3 ff1 nl1 bs1
> stty cols 53 rows 20
> bash | tee /dev/MYARDUINOSERIALPORT
> # (all output will now be copied to the Arduino TTY )
Dealing with serial buffer overflow
If bytes arrive faster than the Arduino can react, the serial buffer will overflow. This leads to dropped bytes. To address this, one can
- Lower the baud rate
- Increase the serial buffer size [1,2,3]
- Ensure that the host machine limits the rate at which it sends data
- Implement software control flow, which sends
XOFF(19) to pause andXON(17) to resume. <s>These can be enabled on linux by providing theixonargument to stty when configuring the serial connection.</s> (Edit: this ma
