Frequently Asked Question

VT320 MeshCore Terminal
Last Updated about a month ago

Skunkworks: MeshCore VT320 Terminal Build

Purpose

This project documents a retro MeshCore terminal build using a DEC VT320 serial terminal, an IBM AT keyboard, a Raspberry Pi, and a Heltec WiFi LoRa 32 V4 board running MeshCore firmware.

The goal is to create a dedicated text-mode MeshCore messaging appliance that feels like a 1980s packet radio or BBS terminal, while using modern LoRa mesh networking underneath.

Design Concept

IBM AT Keyboard
      |
      | AT-to-USB active converter
      |
Raspberry Pi
      |
      | USB-to-RS232 serial adapter
      |
DEC VT320 Terminal
      |
      | USB / BLE / serial / TCP, depending on MeshCore support
      |
Heltec WiFi LoRa 32 V4
      |
LoRa MeshCore Network

In this design, the Raspberry Pi is the host computer. The VT320 is used primarily as the display terminal over RS-232. The IBM AT keyboard is connected directly to the Raspberry Pi using an active AT-to-USB converter. This avoids the need to translate IBM AT keyboard protocol into the DEC LK201/LK401 keyboard protocol used by the VT320 keyboard port.

Important Design Decision

Do not attempt to passively adapt the IBM AT keyboard to the VT320 keyboard jack. The VT320 keyboard connector is not IBM AT, PS/2, or USB. It uses DEC’s own keyboard protocol. A passive adapter will not work.

The cost-conscious and technically simpler approach is:

  • Use the IBM AT keyboard as a USB keyboard connected to the Raspberry Pi.
  • Use the VT320 as a serial display connected to the Raspberry Pi.
  • Use the Heltec V4 as the MeshCore radio device.

Bill of Materials

Item Purpose Notes
DEC VT320 terminal Serial display terminal Uses RS-232 serial via DB25 or other DEC serial connector depending on model/options.
IBM AT keyboard Keyboard input Large 5-pin DIN AT keyboard preferred if already available.
Active AT-to-USB keyboard converter Connects IBM AT keyboard to Raspberry Pi Must be active. Passive adapters are not sufficient.
Raspberry Pi Zero 2 W, Pi 3, Pi 4, or similar Linux SBC Terminal host and application controller Runs the MeshCore terminal application.
MicroSD card Raspberry Pi operating system storage 16 GB or larger recommended.
USB-to-RS232 serial adapter Connects Raspberry Pi to VT320 FTDI or Silicon Labs chipset preferred.
DB9-to-DB25 serial adapter or cable Adapts USB-RS232 adapter to VT320 serial port Needed if USB-RS232 adapter has DB9 and VT320 has DB25.
Null modem adapter or cable Corrects serial transmit/receive wiring if needed Required depending on cable and adapter wiring.
Heltec WiFi LoRa 32 V4 MeshCore radio Runs MeshCore companion/radio firmware.
USB cable for Heltec Power/data between Pi and Heltec Use a data-capable USB cable, not charge-only.
5 V power supply Power for Raspberry Pi Use adequate current for Pi, USB adapters, and attached devices.
Project enclosure Optional packaging Can hold Pi, adapters, strain relief, and power distribution.

Hardware Layout

Recommended Cabling

IBM AT Keyboard
  -> Active AT-to-USB Converter
  -> Raspberry Pi USB Port

Raspberry Pi USB Port
  -> USB-to-RS232 Adapter
  -> DB9-to-DB25 Adapter or Serial Cable
  -> VT320 Serial Port

Raspberry Pi USB Port
  -> Heltec V4 USB-C Port

Do Not Use

  • USB-to-parallel DB25 printer cable. This is not RS-232 serial.
  • Passive AT-to-PS/2-to-USB adapters unless the keyboard explicitly supports it.
  • Direct GPIO wiring from the Raspberry Pi or Heltec to the VT320 RS-232 port without a proper RS-232 level converter.
  • Direct IBM AT keyboard wiring to the VT320 keyboard port.

VT320 Serial Notes

The VT320 serial port uses RS-232 signaling. RS-232 is not the same as TTL serial. If using GPIO UART from a microcontroller or Raspberry Pi header, a level shifter such as a MAX3232 would be required.

For this build, a USB-to-RS232 adapter is preferred because it is simpler and easier to troubleshoot.

Common DB25 RS-232 Pinout

DB25 Pin Signal Description
2 TXD Transmit Data
3 RXD Receive Data
7 GND Signal Ground
4 RTS Request To Send
5 CTS Clear To Send
6 DSR Data Set Ready
20 DTR Data Terminal Ready

For basic operation, TXD, RXD, and GND are the most important signals. Hardware flow control may require RTS/CTS or DTR/DSR depending on terminal settings and cabling.

Initial VT320 Serial Settings

Setting Recommended Initial Value
Baud rate 9600 or 19200
Data bits 8
Parity None
Stop bits 1
Flow control None to start; XON/XOFF or hardware flow control only if needed
Emulation VT320 / VT100-compatible
Local echo Off

Keyboard Notes

The IBM AT keyboard should connect to the Raspberry Pi, not to the VT320 keyboard jack.

Reason

The VT320 keyboard jack uses DEC’s LK201/LK401 keyboard protocol. The IBM AT keyboard uses IBM AT keyboard protocol. These are not electrically or logically compatible.

Recommended Keyboard Path

IBM AT Keyboard
  -> Active AT-to-USB Converter
  -> Raspberry Pi

The Raspberry Pi application will read keyboard input locally and send display output to the VT320 over the serial port.

Software Stack

Raspberry Pi

  • Raspberry Pi OS Lite
  • Python 3
  • pyserial
  • curses, blessed, prompt_toolkit, or another terminal UI library
  • SQLite for message history
  • systemd service for auto-launching the terminal application

Heltec V4

  • MeshCore firmware appropriate for the Heltec WiFi LoRa 32 V4
  • Connection method to be confirmed: USB serial, BLE, Wi-Fi, TCP, or other supported interface

Application Role

The Raspberry Pi application should act as the user interface and message controller. The Heltec board should act as the radio transport. 

VT320 display output  <- Raspberry Pi application
IBM AT keyboard input -> Raspberry Pi application
MeshCore messages     <-> Heltec V4

Initial Configuration Procedure

1. Test the VT320 Serial Connection

  1. Connect the USB-to-RS232 adapter to the Raspberry Pi.
  2. Connect the adapter to the VT320 using the correct DB9/DB25/null modem cabling.
  3. Set the VT320 to 9600 baud, 8N1, local echo off.
  4. On the Pi, identify the serial adapter:
ls /dev/ttyUSB*

Common device names:

/dev/ttyUSB0
/dev/ttyACM0

Install a terminal test tool:

sudo apt update
sudo apt install screen minicom

Test with:

screen /dev/ttyUSB0 9600

2. Test Keyboard Input

  1. Connect the IBM AT keyboard to the active AT-to-USB converter.
  2. Connect the converter to the Raspberry Pi.
  3. Confirm the keyboard works on the Pi console.

3. Install Python Dependencies

sudo apt update
sudo apt install python3 python3-pip python3-venv
python3 -m venv ~/meshterm-venv
source ~/meshterm-venv/bin/activate
pip install pyserial

Additional libraries may be added once the terminal UI approach is selected.

4. Test Python Output to VT320

import serial
import time

ser = serial.Serial('/dev/ttyUSB0', 9600, timeout=1)
ser.write(b'\x1b[2J')       # Clear screen
ser.write(b'\x1b[H')        # Cursor home
ser.write(b'MeshCore VT320 Terminal\r\n')
ser.write(b'Keyboard input handled by Raspberry Pi.\r\n')
time.sleep(1)
ser.close()

5. Connect the Heltec V4

  1. Flash MeshCore firmware to the Heltec V4.
  2. Confirm the board appears on the Raspberry Pi over USB, BLE, Wi-Fi, or other supported interface.
  3. Determine which MeshCore API/interface is available for sending and receiving messages.
  4. Write a small test script that sends and receives one message before building the full terminal UI.

Terminal Application Design

Planned User Interface

The application should boot into a full-screen text-mode interface on the VT320. 

MeshCore Terminal v0.1

Node: KK4TJH-T1
Status: Connected
Peers: 18

------------------------------------------------
Conversations

> Broadcast
  TF8 Command
  Durham EOC
  Chatham Ops
  Direct Messages
------------------------------------------------

F1 Compose   F2 Contacts   F3 Nodes   F4 Status

Core Features

  • Full-screen terminal interface
  • Inbox view
  • Compose message view
  • Broadcast message support
  • Direct message support if supported by MeshCore interface
  • Node list / heard list
  • Message history stored locally on the Raspberry Pi
  • Status screen for radio connection, node name, and network state
  • Keyboard shortcuts using function keys or control-key sequences

Future Features

  • Address book
  • Message search
  • Unread indicators
  • RSSI/SNR display if available
  • GPS/location display if available
  • Simple bulletin board mode
  • Operator login profiles
  • Export message logs
  • ICS-style message form templates

Development Needed

Component Development Task Status
VT320 serial display Write terminal drawing functions using ANSI/VT escape codes. Needed
Keyboard input Map IBM AT keyboard input through Linux to application shortcuts. Needed
MeshCore interface Determine available API for Heltec V4 MeshCore communication. Needed
Message storage Create SQLite database for sent/received messages. Needed
User interface Build inbox, compose, contacts, nodes, and status screens. Needed
Startup behavior Create systemd service to launch application on boot. Needed
Packaging Mount Pi, adapters, and cabling in a clean enclosure. Optional

Suggested Development Phases

Phase 1: Hardware Bring-Up

  • Confirm VT320 powers on and displays correctly.
  • Confirm Raspberry Pi can write text to VT320 over RS-232.
  • Confirm IBM AT keyboard works through active AT-to-USB converter.
  • Confirm Heltec V4 is flashed and reachable from the Pi.

Phase 2: Minimal Terminal App

  • Clear screen and draw header.
  • Display node/radio status.
  • Accept keyboard input.
  • Send a test message through MeshCore.
  • Display received messages.

Phase 3: Usable Messaging Interface

  • Add inbox and compose screens.
  • Add local message history.
  • Add simple contact/node list.
  • Add key bindings for navigation.

Phase 4: Appliance Mode

  • Configure Raspberry Pi for headless boot.
  • Auto-launch MeshCore terminal application with systemd.
  • Hide Linux console details from normal use.
  • Package hardware in a durable enclosure.

Potential Problems and Mitigations

Problem Mitigation
Wrong DB25 cable purchased Use USB-to-RS232 serial, not USB-to-parallel printer cable.
VT320 does not display output Check baud rate, null modem wiring, local echo, and flow control.
IBM AT keyboard does not work Use an active AT-to-USB converter, not a passive adapter.
Heltec V4 does not expose usable serial API Use whichever MeshCore-supported interface is available: BLE, Wi-Fi, TCP, or serial.
Terminal UI draws incorrectly Start with basic ANSI/VT100 escape sequences before using advanced VT320 features.

Long-Term Vision

The finished build should operate like a dedicated field messaging appliance:

  • Power on the Raspberry Pi and VT320.
  • Pi boots automatically.
  • MeshCore terminal application launches.
  • Operator uses the IBM AT keyboard to compose and read MeshCore messages.
  • VT320 displays a full-screen retro terminal interface.

The result should feel like a purpose-built 1980s emergency communications terminal connected to a modern LoRa mesh network.

Open Questions

  • Which exact VT320 serial connector and cable combination is present on this unit?
  • Which active AT-to-USB converter works reliably with the specific IBM keyboard?
  • What MeshCore interface is available and stable on the Heltec V4?
  • Should the first software version use curses, blessed, prompt_toolkit, or direct ANSI escape sequences?
  • Should message logs be exportable for incident documentation?
  • Should the interface support ICS-213-style message formatting?

Please Wait!

Please wait... it will take a second!