GitHub iob.dev
Hardware and Wiring

VIOS targets one board: the Olimex Agon Light 2. It runs on the board as shipped. You need no soldering and no extra chips, and the normal setup needs no wires either. Two optional jumper wires give the Mac a debug and recovery path into the eZ80. They are described at the end of this chapter.

The board

Part Details What VIOS does with it
Main CPU Zilog eZ80F92, 24-bit ADL mode, 18.432 MHz crystal Runs the resident Forth.
CPU memory 512 KB external SRAM (0x040000..0x0BFFFF), 128 KB on-chip flash, 8 KB on-chip SRAM The resident lives in external RAM. The flash holds Agon MOS, which VIOS leaves alone.
Coprocessor ESP32-PICO-D4, dual-core, 4 MB flash, 8 MB PSRAM Runs the VIOS VDP firmware: display, keyboard, audio, USB link, boot and recovery.
Video VGA (resistor DAC driven by the ESP32) 640×480 at 16 colours for the GUI.
Audio 3.5 mm jack and an on-board buzzer Three-voice synthesizer on the ESP32.
Keyboard USB-A-shaped socket carrying PS/2 signals Keyboard input.
Storage microSD slot on the eZ80's SPI bus MOS boot files, VIOS modules, boot bundles and your files (FAT32).
Host link USB-C through a CH340 USB-serial chip to the ESP32's UART0 Power, plus the 115200-baud framed link to the Mac.
Expansion 34-pin GPIO header, 10-pin UEXT, 4-pin ACCESS.bus, 6-pin ZDI header Only the GPIO and ZDI headers are used, by the optional recovery wires.
Power 5 V from USB-C, optional LiPo battery with charger

The eZ80 has no video hardware of its own. Every pixel and every sound comes from the ESP32, which receives drawing commands from the eZ80 over an internal UART (1,152,000 baud with hardware flow control). The USB socket does not connect to the eZ80 at all. Everything the Mac says reaches the eZ80 through the ESP32.

What you need

  • An Agon Light 2. Olimex's Rev. B is the first public revision, and the ZDI pinout below is for Rev. B. Check the revision printed on your board.
  • A microSD card, formatted FAT32 with an MBR partition table. Up to 32 GB is the conservative choice. The card holds MOS's boot file and the VIOS boot stub (see Installing).
  • A VGA monitor that accepts 640×480 at 60 Hz, and a VGA cable.
  • A PS/2 keyboard. The keyboard socket is shaped like USB-A but speaks PS/2. A keyboard with a USB-A plug works only if it also supports PS/2 signalling. Keyboards sold as "USB and PS/2" (often shipped with a small purple or green adapter) plug straight into the socket; you do not use the adapter. A USB-only keyboard does not work, because the board has no USB host controller.
  • A USB-C cable to power the board. A data cable to a Mac is needed for installing firmware and for the host harness, but not for everyday use.
  • Optional: headphones or a powered speaker on the audio jack. The buzzer sounds only when the BUZ_EN1 jumper is closed.
  • Optional: four female-to-male jumper wires and a small breadboard for the ZDI recovery links.

Mouse: the VIOS firmware does not enable the PS/2 mouse. The GUI is driven entirely from the keyboard. The mouse's default pins (ESP32 GPIO26 and GPIO27) are the same pins the ZDI recovery link uses, so firmware with ZDI recovery cannot also drive a mouse on them.

Jumpers

Jumper Setting for VIOS Why
UART_DIS1 (UART_D) Open Open connects the eZ80 to the ESP32. Closed cuts the link and nothing works.
BUZ_EN1 Your choice Closed enables the on-board buzzer.
ESP_PROG1 Leave as shipped It controls ESP32 bootloader entry. Firmware updates over USB do not need it.

Connecting it up

  1. Insert the prepared microSD card (see Installing).
  2. Connect the VGA monitor and the PS/2 keyboard.
  3. Optionally, plug headphones or a speaker into the audio jack.
  4. Connect USB-C, to your Mac or to any 5 V USB supply. The board powers up and boots at once.

The board shows up on the Mac as a CH340 serial device, /dev/cu.usbserial-<suffix>, for example /dev/cu.usbserial-210. The suffix depends on the USB socket or hub, so list the devices before you use any tool. Opening this serial port resets the board. Treat starting the harness, esptool or any other serial tool as a reboot.

ZDI is the eZ80's on-chip debug interface. With two jumper wires from the GPIO header to the ZDI header, the ESP32 can halt the eZ80, read and write its registers and memory, and load VIOS straight into RAM ("dev boot"). This works whatever is on the SD card or in the eZ80 flash. The Mac can then use the harness's debug tools (debug_registers, memory_read, memory_write, resume, deploy), and a wedged eZ80 can always be reset from the Mac.

Without the wires the board boots untethered from the SD card (see Architecture). Fit the wires if you are developing VIOS itself or need deep recovery. Otherwise leave them off.

Board GPIO header Signal ZDI header
Pin 9 ESP32 GPIO26, ZDI clock Pin 4 (ZCL)
Pin 8 ESP32 GPIO27, ZDI data Pin 6 (ZDA)

For reference, the Rev. B ZDI header is 1 = 3.3 V, 2 = reset, 3 = GND, 4 = ZCL, 5 = GND, 6 = ZDA. Only pins 4 and 6 are connected. Both ends are on the same board, so no extra ground or power wire is needed.

Making the links with four female-to-male wires and a breadboard:

  1. Unplug USB-C and disconnect any battery first. Never change wires on a powered board.
  2. Make sure UART_DIS1 is open.
  3. Find pin 1 on each header from the board's silkscreen and the Olimex schematic for your revision. Do not rely on a photo or memory: Rev. B changed the ZDI pinout.
  4. Plug one wire onto GPIO header pin 9 and one onto ZDI pin 4. Put their male ends in the same numbered breadboard strip, for example A1 and B1.
  5. Plug one wire onto GPIO header pin 8 and one onto ZDI pin 6. Put their male ends in another strip, for example A3 and B3.
  6. Check that each strip holds exactly one GPIO lead and one ZDI lead. Never join the two GPIO leads to each other, and never join the two ZDI leads to each other. That would short the clock to the data line.
  7. Reconnect USB-C. The boot events now say BOOT VIOS v0.8 ... and BOOT VIOS VDP 1.04 ... followed by NATIVE RAM ... DONE A5 and VIOREADY ... instead of BOOT user mode.

Safety notes:

  • All header signals are 3.3 V logic. Never connect them to 5 V.
  • The ESP drives the ZDI clock as an output. Do not connect anything else to GPIO26 or GPIO27 while the links are fitted.
  • To boot untethered again, power off and remove both wires. The ESP probes ZDI at every power-on and picks the mode by itself.
  • The wires are also required by tools/vios_ez80_flash.py, which can rewrite the eZ80 flash. A normal VIOS install never needs that tool (see Installing).