MSXPi

MSXPi is a hardware interface and software solution that lets MSX computers control and use Raspberry Pi resources. The interface exposes I/O ports that the MSX reads and writes, and the data appears on the Raspberry Pi side, where a Python program (the msxpi-server) acts on it. Through it the MSX can reach network drives, the internet, disk images, ROM archives, ChatGPT, an IRC server, TCP/IP (via UNAPI) and the Raspberry Pi itself. A Raspberry Pi Zero W or Zero 2 W is the recommended companion board.

MSXPi also exists as a virtual device for openMSX: the emulated MSX gets the same commands and the same server, with no hardware at all. See Quick Start 2 - openMSX.

📖 The Book

The complete design and implementation of MSXPi is documented in a book:

Anatomy of an Interface: MSXPi, a Case Study in Hardware/Software Co-Design

It follows one real system, from the cartridge bus and the programmable logic to the Python server on the Raspberry Pi and the applications on the MSX, and shows how each layer was designed, built and tested. No MSX knowledge is assumed, and you do not need the board: the whole system runs in the openMSX emulator on a PC.

The book covers:

• Design decisions and trade-offs
• Hardware architecture
• CPLD design (VHDL) and the Z80 bus interface
• Software implementation: Z80 assembly on the MSX, Python on the Raspberry Pi
• The LINK2 protocol and interface specifications
• Testing on real hardware and in openMSX
• Engineering lessons learned during development

👉 Get the book on Amazon

_{As an Amazon Associate, the author earns from qualifying purchases. Buying through this link supports the MSXPi project at no extra cost to you.}

Caution

Version 1.7.0 breaks compatibility with every earlier MSXPi ROM. Every MSXPi EEPROM must be rewritten with the 1.7.0 ROM (software/target/msxpi32k.rom, written with at28c256, see Step 2) before it is used with this release. Upgrade the whole set together: the ROM, the msxpi-server and the client commands (.COM files). Version 1.7.0 moves every transfer between the MSX and the Pi to LINK2, a new protocol with CRC-16 checked blocks; the new .COM files do not work with an older server. The CPLD firmware is unchanged (v1.6). To stay on an older ROM, use the server from the matching release/vX.Y branch.

Version 1.7.0 is the current release. What changed is in Release_Notes; how to use everything is in the documents folder.

Notice: online gaming is in alpha testing. The online games (PLAYNET and MCHAT game invitations, for example Konami's Soccer over the Internet) are experimental and not ready for end users yet. They have only been tested between emulators, expect bugs and missing pieces, and the files, commands and protocols may still change. Try them if you want to help test, but do not rely on them.

MCHAT plays through the MSXPi when there is one, and over TCP/IP UNAPI (InterNestor Lite on the MSXPi's Ethernet, or a hardware stack such as GR8NET) when there is not. MCHAT /T forces TCP/IP even with an MSXPi. TCP/IP play needs a memory mapper (MSR or Nextor); see the users' guide section "Online games" for the requirements.

CPLD firmware. Version 1.7.0 uses the v1.6 CPLD firmware; a board already on v1.6 needs no CPLD change. On older CPLD firmware the 1.7.0 ROM still works, using the slower polled transfers.

About the DOS. MSXPi's own ROM contains MSX-DOS 1 (1.03) only. It does not contain Nextor or MSX-DOS 2. MSXPi coexists with them: Nextor or MSX-DOS 2 come from another disk interface in the same MSX (for example a MegaFlashROM SCC+ SD), and MSXPi's commands, BASIC extension and UNAPI work alongside them. The EEPROM holds two ROMs, picked with the bank jumper: MSX-DOS 1 (BANK2) or the BIOS only - CALL MSXPI and the Ethernet UNAPI in ROM, no disk system (BANK1) - for use next to Nextor / MSX-DOS 2. With the MSX-DOS 1 ROM the Ethernet UNAPI driver is loaded from disk (ETHUNAPI.COM).

Contents

1. How the pieces fit together
2. Quick Start 1 - Real hardware
3. Quick Start 2 - openMSX
4. Using MSXPi: the p commands
5. Bugs and known limitations
6. Repository structure

How the pieces fit together

Real hardware:
MSX  <-- I/O ports $56 $57 $5A -->  MSXPi interface  <-- GPIO -->  Raspberry Pi
(p.com, pcopy, msxarch,             (CPLD + EEPROM with            (msxpi-server.py,
 BASIC CALL MSXPI, ROM BIOS)         the MSXPi ROM)                 Python 3)

openMSX:
MSX  <-- I/O ports $56 $57 $5A -->  MSXPiDevice      <-- TCP :5000 --> msxpi-server.py
                                    (emulated CPLD)                    (on your PC)

• MSX side - the ROMs in the interface's 32 KB EEPROM and the .COM programs that you copy to your MSX disk or SD card. The EEPROM image, msxpi32k.rom, holds two 16 KB ROMs:
  • msxpibios.rom - MSXPi BIOS, MSX-DOS 1 disk driver, CALL MSXPI for BASIC (the Ethernet UNAPI driver no longer fits here: load ETHUNAPI.COM for TCP/IP);
  • msxpibas.rom - the BIOS without the disk system: CALL MSXPI and the Ethernet UNAPI.
• Interface - a CPLD decodes ports $56/$57/$5A and shifts bytes to and from the Pi; since v1.6 it also holds the Z80 /WAIT line while a byte is in flight, so the MSX can move data with INIR/OTIR.
• The link - since 1.7.0 every transfer uses LINK2: framed blocks with a CRC-16 (CCITT-FALSE), acknowledged one by one and resent when damaged (documents/LINK2-DESIGN.md).
• Server side - msxpi-server.py, which runs on the Pi (GPIO link) or on your PC next to openMSX (TCP socket link). Everything it needs lives in one folder, the MSXPi home directory: /home/pi/msxpi.

Quick Start 1 - Real hardware (MSXPi interface + Raspberry Pi)

You will need:

• An MSXPi interface (built from hardware/; assembly notes in documents/MSXPi Assembly Instructions.txt) with an AT28C256 EEPROM.
• A Raspberry Pi Zero W / Zero 2 W (not a Pico - it cannot run Linux), with the 40-pin header on the side that matches your PCB, a micro SD card of 8 GB or more, and a PC to prepare it.
• An MSX with a disk or SD interface running MSX-DOS 1, MSX-DOS 2 or Nextor (MSXPi itself only has MSX-DOS 1 in its ROM; MSX-DOS 2 / Nextor must come from that other interface), and a way to copy files from your PC onto that disk. A second disk interface (Nextor / MSX-DOS 2) next to MSXPi is the best way to use it.
• Only if the CPLD is not programmed yet: an Altera USB-Blaster and Quartus 13.0 SP1 on Windows.

Do the steps in order. Each ends with a check, so you know where a problem is.

Step 1 - Program the CPLD (skip if it is already programmed)

1. Connect the USB-Blaster to the JTAG connector of the interface. The interface must be in the MSX slot and the MSX switched on.

2. In Quartus: Tools -> Programmer, mode JTAG, Add File, pick the .pof for your board, tick Program/Configure and Verify, Start.

   Board	File (in hardware/CPLD_Project)
   V1.3 Rev.1 (and boards built for v1.3 to v1.5)	MSXPi_v1.6.pof
   V1.1 Rev.1, V1.2.1b	v1.1/MSXPi_v1.6_wait.pof
   v0.8.2 / v1.0 (PCB v0.7 Rev.7)	v0.8.2/MSXPi_v1.6_polled.pof

3. Check: in MSX BASIC, PRINT INP(&H57) must not print 254 or 255 (that means no CPLD answered); p ver shows the same build ID in readable form later. Older boards need a few extra settings - see hardware/CPLD_Project/LEGACY_BOARDS.md and documents/Legacy Support.odt.

Step 2 - Write the ROM to the EEPROM with AT28C256.COM

The EEPROM (32 KB) holds msxpi32k.rom: two 16 KB ROMs, one per bank. It is written from the MSX itself, so you need a working MSX with a disk drive and the interface plugged in. The Raspberry Pi does not need to be attached yet.

Bank jumper (as on the PCB)	EEPROM half	ROM	The MSX gets
BANK2 (EEPROM A14 = CPU A15)	lower	msxpibios.rom	MSX-DOS 1 from the Pi, CALL MSXPI (Ethernet UNAPI from ETHUNAPI.COM)
BANK1 (EEPROM A14 = CPU A14)	upper	msxpibas.rom	CALL MSXPI and Ethernet UNAPI, no disk system and no extra drives

1. Copy software/target/at28c256.com and software/target/msxpi32k.rom to your MSX disk or SD card. (Both are also on the MSXPi boot disk.)

2. Set the bank jumper to BANK2. The EEPROM can only be programmed in that position: the chip's write-protection commands only reach the right addresses when its A14 follows CPU A15.

3. Boot MSX-DOS (from your disk interface) and list the ROMs the tool can see:

    at28c256 /i
   

   If the interface already holds a bootable ROM, remove its enable jumper (SLTSL, CS12 on some boards) first, otherwise the MSX finds it, boots from it and the tool cannot write. Note the slot number of the interface.

4. Write the ROM (2 is the slot number here; use yours):

    at28c256 /s 2 msxpi32k.rom
   

   Always write the whole 32 KB file in one go: the tool erases the entire chip before writing, so writing one 16 KB ROM on its own wipes the other bank. The tool write-protects the EEPROM (software data protection) when it is done. If your chip fails to program, repeat with /r, which writes slowly.

5. Switch the MSX off and set the jumpers for how you will use it:

   • Booting MSX-DOS 1 from a disk image on the Pi: close SLTSL, bank jumper on BANK2. The Pi must finish booting first, so the first cold boot takes a few minutes. Press ESC during boot to go straight to BASIC.
   • With another disk interface (recommended): close SLTSL, bank jumper on BANK1, and put MSXPi in a higher slot than the disk interface. The MSX boots Nextor / MSX-DOS 2 from the other interface; MSXPi adds no drives and uses almost no memory, and CALL MSXPI in BASIC and the Ethernet UNAPI (in this ROM) are available.
   • MSXPi ROM off: remove SLTSL. MSXPi then works only through the .COM commands - no CALL MSXPI; for TCP/IP load ETHUNAPI.COM.

   The EEPROM answers in every page of its slot, so the bank that is not selected appears at 8000h. The two ROMs are built to tolerate each other there; always write them together, from the same msxpi32k.rom.

6. Check: in BASIC, CALL MSXPIVER prints the ROM version; with BANK1 it ends in "(no DOS)".

Step 3 - Prepare the Raspberry Pi

Install a fresh Raspberry Pi OS Lite and run the MSXPi setup script. (The old ready-made SD card image is no longer offered.)

1. Write Raspberry Pi OS Lite (32-bit) to the SD card with Raspberry Pi Imager (https://www.raspberrypi.com/software). In its settings choose user name pi, enable SSH and enter your WiFi details.

2. Boot the Pi, log in (SSH, or keyboard and HDMI) and run:

    wget https://tinyurl.com/MSXPi-Setup
    chmod 755 MSXPi-Setup
    bash ./MSXPi-Setup
   

   The script checks the Pi, the network and the clock, installs everything below, starts the server, checks that it runs, and reboots (a few minutes). It asks which board you have; to skip the question add --board v1.3, --board v1.1 or --board old (see the table below). --help lists the other options (WiFi, --no-reboot, ...). It is safe to run again: it updates the server and repairs what is missing, and never overwrites msxpi.ini.

What the setup gives you (check it, or do it by hand):

• Python 3 with the modules requests, fs and RPi.GPIO. fs needs pkg_resources, so a setuptools older than version 81 must be present (python3 -m pip install fs "setuptools<81" --break-system-packages if you do it by hand). The packages unar, lhasa, unzip, mpv, alsa-utils and smbclient are for unpacking archives, playing audio and reading network shares; iptables gives the MSX its network; gcc builds the native GPIO engine. PChess also needs the Python package chess (requirements-pchess.txt); the rest of the server works without it.

• The MSXPi home directory /home/pi/msxpi, owned by user pi. The path is built into the server (the environment variable MSXPI_HOME overrides it). It holds:

  File	Purpose
  msxpi-server.py and the msxpi_*.py modules (msxpi_cmd_*.py, msxpi_transport.py, msxpi_settings.py, ...), mapper_detect.py	the server and its modules
  native/	the native GPIO library libmsxpi_gpio.so, built on the Pi (without it the server falls back to slower Python GPIO and says so in its log)
  msxpi.ini	your settings, see below
  disks/msxpiboot.dsk, disks/tools.dsk	drives A: and B: for the MSX-DOS 1 boot mode
  msxpi-monitor, msxpi-tcpip-setup.sh, update.sh	helpers

• A systemd service (msxpi-monitor) that starts the server at boot. To watch it work, run it by hand: cd /home/pi/msxpi && python3 msxpi-server.py.

• msxpi.ini, copied from the template that matches your PCB (software/Server/Python/src):

  Board	Template
  V1.3 (and later)	msxpi-JumperRight.ini
  V1.1 Rev.0	msxpi-JumperRight_PCBV1.1Rev.0.ini
  Older boards	msxpi-JumperLeft.ini

  A board without the shutdown push-button needs var RPI_SHUTDOWN=none. Optional keys: OPENAIKEY and OPENAIMODEL (ChatGPT), RAPIDAPIKEY, FINNHUBKEY, TWELVEDATAKEY, ALPHAVANTAGEKEY (stock quotes), WIFISSID, WIFIPWD, WIFICOUNTRY. From the MSX you can change any of them with p set NAME value.

Insert the SD card, plug the Pi into the interface with its component side facing you, and switch the MSX on. The interface LED lights when the server is running.

Step 4 - Copy the MSX-side programs

Copy the contents of software/target (at least p.com, pcopy.com, msxarch.com, msxarch.ini, LOADROM.COM, ETHUNAPI.COM, INL.CFG and the .BAS programs) to your MSX disk or SD card. They must all come from the same release as the ROM and the server.

Check: at the MSX-DOS prompt type

    p ver

It prints the board (build ID, CPLD, /WAIT yes or no) and the server version. "Connection error" means the Pi is still booting (the first boot may take three minutes), the interface is not seated, or the ROM and server versions do not match. Press CTRL+ESC, wait five seconds, and try again. A "protocol error" means the server is older than 1.7.0 and cannot speak LINK2: update the server.

Step 5 - Connect to WiFi and the network

    p set WIFISSID Your Wifi Name
    p set WIFIPWD YourWifiPassword
    p wifi set
    p reboot

p wifi alone lists the interfaces and addresses. For TCP/IP programs (UNAPI: InterNestor Lite, telnet, HGET) the MSX needs the MSXPi Ethernet UNAPI driver, and the Pi builds the network behind it with msxpi-tcpip-setup.sh when the server starts. If the Pi had no default route at boot, run p netreset. Then, depending on how the MSX was started:

ROM bank / DOS	Type, in this order
BANK2, MSX-DOS 1 booted from MSXPi	MSR I, ETHUNAPI, INL I
BANK1, MSX-DOS 1 from another interface	MSR I, INL I
BANK1, Nextor or MSX-DOS 2	RAMHELPR I, INL I

then HOST GOOGLE.COM. With BANK1 the driver is in the ROM and ETHUNAPI refuses to load. Under MSX-DOS 1 never run RAMHELPR: MSR installs the RAM helper itself and fails if one is already there.

HOST printing an address means the whole path works. p wlanreset resets the Pi's WiFi. Details: software/UNAPI/README.md.

Step 6 - Try it

    p dir /home/pi/msxpi
    p run uname -a
    pcopy m:p.com
    msxarch                     (browse and start ROM games from the network)
    LOADROM game.rom /N
    p chatgpt Tell me a fun fact about MSX

Updating

• MSX disk (the .COM files): run msxpiupd.bat (network required).

• To update from another git branch (client files, ROMs and server), give its name: msxpiupd feature/name. Without a name it is master. Files that exist only in the branch are not copied.

• Server: run the setup script again, from the Pi or from the MSX:

    p run wget https://tinyurl.com/MSXPi-Setup
    p run chmod 755 MSXPi-Setup
    p run sudo ./MSXPi-Setup
  

• ROM: the updater downloads it but never writes it - repeat Step 2.

Update all three together: the ROM, the server and the clients (.COM files, including playnet.com, playnet.ovl and mchat.com) come from the same build, so a server update also means flashing msxpibios.rom again. Run p shut before you switch the MSX off: the Pi is powered by the MSX, and an SD card can be corrupted by a sudden power cut.

More detail with pictures: documents/Quick Start.odt and the "Hard Way" tutorial (installing Raspberry Pi OS from scratch; Portuguese version available) in the documents folder.

Quick Start 2 - openMSX (no hardware needed)

The MSXPi device for openMSX emulates the interface, including the CPLD /WAIT flow control, and talks over a local TCP socket to the same msxpi-server.py that runs on the Pi. The p commands, BASIC, msxarch, ChatGPT and UNAPI networking all work as on real hardware, and what you write under openMSX runs unchanged on the real interface.

Windows: install everything in one step

1. Download msxpi-openmsx-install.bat (right-click the link, Save link as) and double-click it. It needs no administrator rights, and downloads everything from this repository and from the MSXPi build of openMSX.
2. It installs Python 3 and the packages the server uses, 7-Zip, Stockfish and mpv (with winget), then:
   • C:\home\pi\msxpi - the server, msxpi.ini and the disks folder
   • C:\home\pi\msxpi\openMSX - openMSX with the MSXPi device, the MSXPi.xml extension and msxpibios.rom
   • C:\home\pi\msxpi\start-openmsx.bat and an MSXPi desktop shortcut
3. Double-click the MSXPi shortcut. It starts the server in its own window, then openMSX as a Panasonic FS-A1WSX with the MSXPi and 4 MB RAM extensions. The MSX boots MSX-DOS from the MSXPi boot disk (disks\msxpiboot.dsk); no floppy image is needed.
4. Go on with Step 4 - Try it.

Notes:

• Machine ROMs. openMSX ships only the free C-BIOS ROMs. The FS-A1WSX needs its own system ROMs: put them in %USERPROFILE%\Documents\openMSX\share\systemroms (or in C:\home\pi\msxpi\openMSX\share\systemroms).
• Internet on the MSX. Run the installer with -Network (from a command prompt: msxpi-openmsx-install.bat -Network). It also installs the TAP driver, which asks for administrator rights once, and the launcher then sets up the MSX network when needed. See Internet from the MSX in openMSX.
• Updating. Run the installer again. It refreshes the server, the ROM and the extension, and replaces openMSX when a newer MSXPi build is required. It keeps msxpi.ini and the disk images.

Steps 1 to 3 below are the manual installation, for Linux and macOS or to set things up by hand on Windows.

Step 1 - Install openMSX with the MSXPi device

The official openMSX lives at https://github.com/openMSX/openMSX (binaries and documentation at https://openmsx.org). The MSXPi device is not in the official build yet, so download openMSX from the MSXPi fork instead:

• https://github.com/costarc/openMSX/releases - take the newest release for your operating system; the notes of each release say what it contains. Unpack it anywhere. It includes the MSXPi extension (MSXPi.xml) and the matching msxpibios.rom.
• Use the fork release, the msxpibios.rom, and the server from the same MSXPi version - the device, ROM and server share one protocol.
• If you keep your own openMSX, the two data files are also in this repository: software/openMSX/share/extensions/MSXPi.xml goes to openMSX's share/extensions, and software/target/msxpibios.rom goes to share/systemroms (the XML checks its sha1). The MSXPiDevice itself is only in builds of the fork.
• Two more extensions come from the same build (software/build, openMSX stage): MSXPiBasic - the BIOS-only ROM (msxpibas.rom), as on a board with the jumper on BANK1 - and MSXPi32K, the whole 32 KB EEPROM with the board's jumpers as openMSX settings, read at reset: set msxpirom_bank BANK2|BANK1 (default BANK2) and set msxpirom_sltsl ON|OFF (default ON). MSXPi32K needs a fork build with EEPROM support in MSXPiDevice (branch feature/msxpi-eeprom-jumpers).

Step 2 - Python and the MSXPi home directory

• Python 3 (3.9 or newer; on Windows from python.org or the Microsoft Store, with Add to PATH).
• Python modules: python -m pip install requests is all the server needs to start. Some commands need more: certifi and chess for pchess, Pillow and playwright (then python -m playwright install chromium) for renderpage.
• 7-Zip (7z.exe on the PATH) for zip, lzh, pma and 7z archives, used by msxarch and pcopy /z. On Linux/macOS install p7zip, lhasa and unar.
• The MSXPi home directory. The server has /home/pi/msxpi built in (set MSXPI_HOME to use another folder). On Linux and macOS create that folder. On Windows the path resolves on the current drive, so create C:\home\pi\msxpi and start the server from drive C:. Put in it: msxpi-server.py, mapper_detect.py and every msxpi_*.py module (all from software/Server/Python/src; the server imports them from its own folder), msxpi.ini (copy msxpi-JumperLeft.ini and rename it), and a disks folder with msxpiboot.dsk and tools.dsk from software/target/disks.
• Add the keys you need to msxpi.ini (for example OPENAIKEY for ChatGPT). Commands that only make sense on a Pi (wifi, reboot, shut, play) answer "Command not supported on this platform".

Step 3 - Start the server, then openMSX

    cd C:\home\pi\msxpi           (Linux/macOS: cd /home/pi/msxpi)
    python msxpi-server.py

The server listens on TCP port 5000. Now prepare a folder that openMSX uses as disk A:. Call it FloppyA, copy MSXDOS.SYS and COMMAND.COM from software/target/disks into it, and add the MSXPi commands from software/target. Then start openMSX with the extension:

    openmsx -machine Panasonic_FS-A1WSX -ext MSXPi -diska FloppyA

Any MSX2 with 64 KB RAM will do, and Nextor on an SD/IDE image works too. The fork also has an MSXPiNoROM extension (the ports without the ROM), for trying BLOAD"MSXPIEXT.BIN",R the way an interface without an EEPROM is used.

Optional: a different port. The device takes the TCP port from the openMSX setting msxpiserver_port (default 5000). Change it in the openMSX console (F10) and the device reconnects at once:

    set msxpiserver_port 5001

Make the server listen on the same port with the environment variable MSXPI_PORT (for example set MSXPI_PORT=5001 on Windows before starting it). Use this when port 5000 is taken, or to run two emulators with two servers.

Step 4 - Try it

At the MSX-DOS prompt:

    p ver
    p dir /
    p set
    msxarch
    p chatgpt Tell me a funny fact about MSX

p ver reports /WAIT: yes (burst) when the device emulates the wait flow control. "Connection error" means the server is not running, the ports differ, or the ROM and server versions do not match. Read the log window of the server: it prints every command it receives.

Internet from the MSX in openMSX (Windows)

The MSXPi extension carries real network traffic, so InterNestor Lite, telnet, HGET and the other UNAPI clients work in the emulator exactly as they do on hardware. The emulated MSX gets its own subnet (192.168.99.0/24) and Windows NATs it out through whichever interface carries your default route - the same arrangement the Raspberry Pi uses, and for the same reason: bridging cannot work over WiFi, because an access point will not forward frames whose source MAC is not the associated station's.

This works best with an openMSX whose MSXPi device implements the v1.6 hardware /WAIT flow control (openMSX/openMSX#2194). An older build still works: the ROM probes for wait mode, does not find it, and falls back to the polled transport - the same path MSXPi has always used under emulation. What you lose is the v1.6 speedup, not the connection.

With the Windows installer, run it with -Network instead of steps 1 and 2: it installs the TAP driver, and the MSXPi desktop shortcut sets up the network (asking for administrator rights) whenever it is missing, including after a reboot. Then go on with step 3.

Step 1: Install the OpenVPN TAP driver

Install OpenVPN (https://openvpn.net/community-downloads/) and keep the "TAP Virtual Ethernet Adapter" component, or install the standalone tap-windows6 driver on its own. Afterwards an adapter named "OpenVPN TAP-Windows6" appears in Network Connections - nothing else about OpenVPN is used or needs configuring.

Step 2: Run the setup once, as Administrator

From an elevated PowerShell:

      powershell -ExecutionPolicy Bypass -File software/Server/Setup/msxpi-tcpip-setup.ps1

It reports what it did:

      adapter: OpenVPN TAP-Windows6  [TAP-Windows Adapter V9]
      uplink: Wi-Fi
      OpenVPN TAP-Windows6 up: 192.168.99.1/24 mtu 576
      NAT: 192.168.99.0/24 -> Wi-Fi
      dns: 192.168.1.254

and prints the InterNestor Lite settings to match. Note the "dns:" line - that is the resolver the MSX should use.

This is NOT persistent across reboots; re-run it after a restart. To undo it and give the adapter back to OpenVPN, add "-Down".

Windows generally allows only one NAT instance, and Docker Desktop, Hyper-V and WSL each take one. If something already holds it the script names it and stops rather than half-configuring.

Step 3: Start the server

      python msxpi-server.py

No administrator rights are needed for this part. It should print:

      eth: TAP device OpenVPN TAP-Windows6 up

If it says "TAP unavailable ... falling back to MockLink", something else has the adapter open - a running OpenVPN session will do that. MockLink answers every UNAPI call correctly and carries no traffic at all, so the MSX will look configured and reach nothing.

Step 4: On the MSX

Start openMSX with the MSXPi extension, then:

      MSR I              (MSX-DOS 1 only - see below)
      ETHUNAPI
      INL I
      HOST GOOGLE.COM

HOST printing an address means the whole path works. The extension maps the EEPROM the way the board shows it with the BANK2 jumper, so the MSX boots the MSX-DOS 1 ROM, which has no Ethernet driver since 1.7.0: ETHUNAPI.COM loads it into a mapped RAM segment. (With the BIOS-only ROM the driver is in the ROM and ETHUNAPI refuses to load.)

Under MSX-DOS 1, do not run RAMHELPR I. It installs the UNAPI RAM helper on its own, and MSR.COM installs the mapper support routines AND a helper - so MSR then finds a helper already present and aborts, leaving INL to fail with "No mapper support routines found". A cold boot clears it. Under Nextor or MSX-DOS 2, skip MSR and run RAMHELPR I instead: the mapper routines are already there.

If HOST answers "8: DNS not found" but the link is otherwise up, the resolver is the problem rather than the network - INL.CFG ships with 1.1.1.1, and some networks block public resolvers. Use the address the setup script printed:

      INL IP P 192.168.1.254

Using MSXPi: the p commands

Type p with no arguments (or p /help) to list them. All work under MSX-DOS 1, MSX-DOS 2 and Nextor. Paths can be on the Pi, on the network (http, https, ftp, smb) or on one of the virtual drives set with p set: m: (your local server), r1: and r2: (MSX1 and MSX2 ROMs on msxarchive.nl).

Command	What it does
p ver	board, CPLD build and /WAIT support, then the server version
p cd, p dir	change and list the current path
p run <cmd>	run a command on the Pi; use :: for a pipe
p date	set the MSX date and time from the Pi
p set [NAME value]	show or change MSXPi variables (saved in msxpi.ini)
p wifi, p wifi set	list interfaces / apply WIFISSID and WIFIPWD
p wlanreset [secs], p netreset [secs]	reset the Pi's WiFi / rebuild its TCP/IP setup for UNAPI
p music, p play, p vol	audio playback and volume on the Pi
p reload A: (or B:)	reload a drive's disk image
p reboot, p shut, p restart	reboot / shut down the Pi, restart the server
p chatgpt <question>	ask ChatGPT (needs OPENAIKEY)
p showpage [/4|/6|/8] <url>	render a web page on the MSX screen
pchess	chess on an MSX2 (128 KB VRAM), local or over IRC (see software/Client/src/PCHESS.md)
nitros	on-demand NitrOS-9 console on the Pi with the MSXPi interface, or in openMSX on Windows/Linux, with file exchange; see setup
ssh user@host [port]	interactive SSH terminal through the MSXPi Raspberry Pi; prompts and passwords appear on the MSX
pcopy	copy Pi/network file to the MSX drive (/z unpacks archives) or an MSX file to the Pi
msxarch	browse ROM repositories (listed in MSXARCH.INI) and start a game
LOADROM name /N	load a plain ROM or MegaROM from the network
at28c256	write the interface EEPROM
msxpiupd.bat [branch]	update the MSX-side files (and the server) from master or a git branch

From BASIC use CALL MSXPI("1,C000,dir /home/pi/msxpi") (see target/API.BAS). The full reference, with examples, is in documents/MSXPi Users and Developers Guide.odt.

Bugs and known limitations

• Upgrade as a set. The 1.7.0 ROM, server and .COM files are meant to be used together; every EEPROM must be rewritten with the 1.7.0 ROM. A 1.7.0 .COM file against an older server stops with a protocol error (RC_PROTOERR, "server does not speak LINK2"); other mixes usually show up as "Connection error".
• /WAIT bursts need a v1.6 CPLD image and a board that wires /WAIT. Boards built for v0.8.2 and v1.0 (PCB v0.7 Rev.7) have no /WAIT connection and run the polled transfers only. Disk reads and writes both burst where /WAIT is available.
• LINK2 on real hardware. The BIOS half was soak-tested on hardware; the MSX-DOS 1 driver and the .COM tools on LINK2 were tested in openMSX, and their hardware checklist (documents/LINK2-TEST-PLAN.md, T6.7) is still open.
• Older boards need settings: RPI_SHUTDOWN=none without the push-button, and GPIO_CS_SETUP_NS=1000 on the v0.8.2 board. On that board the EPROM /OE jumper must be on CS1, never CS12, or programs that call EXTBIO (p, pcopy) hang the MSX. See hardware/CPLD_Project/LEGACY_BOARDS.md.
• MSXPi only carries MSX-DOS 1. Nextor and MSX-DOS 2 are not in the MSXPi ROM; they run from another disk interface that MSXPi coexists with.
• Booting MSX-DOS 1 from the Pi is slow and fragile. It needs the Pi to finish booting first and depends on the disk images; use another interface with Nextor or MSX-DOS 2 for daily work. Do not delete files on drive A: in that mode.
• A stuck transfer needs CTRL+ESC. Hold CTRL and press ESC to abort, wait about five seconds while the server resynchronises, and retry. ESC alone is an ordinary key and never aborts a transfer. If commands keep failing, restart the server (p restart) or reboot the Pi.
• msxarch and MegaROMs. Mappers detected: plain, Konami, Konami SCC, ASCII8 and ASCII16. Other mappers, ROMs that need more RAM than the MSX has, and some titles that rewrite their own bank switching are rejected with a reason or may not run. Bank-switch writes are patched by the server, so what runs is not byte-for-byte the original ROM.
• UNAPI/TCP/IP. With the MSX-DOS 1 ROM (BANK2) load ETHUNAPI after MSR I and before INL I; the driver is no longer in that ROM. Do not run RAMHELPR before MSR under MSX-DOS 1 (INL then fails with "No mapper support routines found"; a cold boot clears it). Run only one Ethernet driver: ETHUNAPI next to the BIOS-only ROM's driver is refused, and if it were forced the two would switch the server's Ethernet protocol back and forth. If HOST answers "8: DNS not found" the resolver, not the link, is the problem: use INL IP P <address>. Under openMSX on Windows the TAP setup script must be run again after every reboot, only one Windows NAT instance can exist (Docker Desktop, Hyper-V and WSL each take one), and if the server prints "falling back to MockLink" the MSX looks configured but reaches nothing.
• The server on Windows and macOS runs the commands that make sense there; wifi, reboot, shut, play/music and vol are Raspberry Pi only.
• Hardware compatibility. Some MSX models have unusual slot or bus implementations and may not work; MSX-DOS needs 64 KB RAM. The Pi header must face the correct way for your PCB (a Zero WH has its header on the wrong side for the standard PCB).
• ChatGPT and stock commands need your own API keys in msxpi.ini; no key ships with MSXPi.
• Tests. Server unit tests are in software/Server/Python/tests; the UNAPI harness is in software/UNAPI/harness.
• The PDF copies of the documents in documents may be older than the .odt files.

Report problems at https://github.com/costarc/MSXPi/issues.

Repository structure

Branches:

master          the most recent code; may change within minutes - expect bugs,
                and fixes just as fast
release/vX.Y    one branch per release (v0.8.2, v1.0, v1.1, v1.2.1b, v1.3,
                v1.5); use these for a known-good state
feature/*, fix/*, docs_*
                short-lived working branches; they appear and disappear, and
                I recommend you do not use them

Directories:

MSXPi
|-- software
|   |-- asm-common
|   |   |-- include          BIOS routines for assembly (msxpi_bios.asm, include.asm, ...)
|   |   `-- transport        generators: the LINK2 code for C, the /WAIT burst code
|   |-- C-common
|   |   |-- header           msxpi.h - the C BIOS API
|   |   `-- lib              msxpi-bios.c
|   |-- ROM/src
|   |   |-- BIOS             BIOS-only ROM bank (msxpibios.asm); BASIC extension (msxpiext.asm)
|   |   `-- MSX-DOS          disk driver and MSX-DOS 1 kernel sources
|   |-- Client/src           p, pcopy, msxarch, pchess, showpage, templates, at28c256
|   |   `-- loadrom          the LOADROM.COM network patch
|   |-- ROM-Patcher          ROM patch profiles used by msxarch
|   |-- Server
|   |   |-- Python/src       msxpi-server.py and its msxpi_*.py modules, mapper_detect.py,
|   |   |                    ini templates, native GPIO engine (native/)
|   |   |-- Python/tests     server unit tests
|   |   `-- Setup            setup scripts (Pi and Windows), update.sh, msxpi-monitor
|   |                        and its systemd unit
|   |-- UNAPI                Ethernet UNAPI: sources, tools, INL, test harness, documentation
|   |-- openMSX              MSXPiDevice source, extension XML, build files
|   |-- target               everything you copy to the MSX (.COM, .BAS, ROM, disks)
|   |-- docs                 mapper, ROM and PChess IRC design notes
|   `-- make.bat, make.sh    build scripts for the MSX-side programs
|-- hardware
|   |-- CPLD_Project         VHDL, Quartus project, .pof images for every board
|   `-- Schematic            KiCad schematic and PCB, Fabrication, BOM
`-- documents                Users and Developers Guide, C BIOS Developers Guide,
                             Quick Start, Legacy Support, tutorials