Using MSXPi Extension for openMSX ================================= MSXPi is a hardware and software solution that allows MSX computers to control and use Raspberry Pi resources. The interface exposes I/O ports for the MSX computer, which allows exchange of data with the Raspberry Pi using a custom protocol. Many resources are implemented, such as access to network drives, internet, disk images, and access to the Raspberry Pi itself to execute commands. The MSXPiDevice for openMSX implements the same functionality of the physical MSXPi without the need of a Raspberry Pi - instead, relies on a Python msxpi-server code running on the same computer where openMSX is hosted. For detailed information about the MSXPi project and the hardware interface, go to: https://github.com/costarc/MSXPi This README is for the openMSX extension that reproduces the behaviour of the physical interface. Architecture of the physical Interface: ┌────────────┐ ┌────────────────────────┐ ┌────────────────────┐ │ MSX │ <---> │ MSXPi Interface │ <---> │ msxpi-server │ │ (Z80 I/O) │ 0x56 │ (CPLD + SPI bridge) │ GPIO │ (Python GPIO API) │ │ │ 0x57 │ + 32KB EEPROM │ │ │ └────────────┘ 0x5A └────────────────────────┘ └────────────────────┘ Architecture of the MSXPi extension for openMSX: ┌────────────┐ ┌────────────────────────┐ ┌────────────────────┐ │ MSX │ <---> │ MSXPi Interface │ <---> │ msxpi-server │ │ (Z80 I/O) │ 0x56 │ (MSXPiDevice + socket │ Socket │(Python socket API) │ │ │ 0x57 │ + msxpibios.rom) │ │ │ └────────────┘ 0x5A └────────────────────────┘ └────────────────────┘ The emulated device reproduces the CPLD (firmware v1.6) at I/O-port level, so the same msxpibios.rom and the same MSX side commands that run on the physical interface run unchanged in openMSX. Port 0x57 returns the firmware version, which means software cannot tell the emulated interface from the real one. Now that you know everything you need (not really!) to start with MSXPi, prepare the environment. Quick setup on Windows ====================== If you are on Windows, one installer does everything below: it installs Python 3 and the modules the server needs, 7-Zip and mpv music player, the msxpi-server code, the MSXPi disk images, an openMSX build with MSXPi support, MSXPi.xml and msxpibios.rom, and a launcher that starts the server and openMSX together. Download msxpi-openmsx-install.bat from: https://github.com/costarc/MSXPi/tree/master/software/Server/Setup and double-click it. The .bat fetches msxpi-windows-setup.ps1 (the script that does the work) if it is not next to it, so that one file is enough. From a command line, with options: msxpi-openmsx-install.bat [-Network] [-Branch name] -Network also installs the OpenVPN TAP driver and sets up the MSX network (NAT), so the MSX TCP/IP commands work. This step asks for administrator rights; the rest of the install does not need any. Everything lands in C:\home\pi\msxpi - the path the server expects - with openMSX in C:\home\pi\msxpi\openMSX. You get a start-openmsx.bat launcher and an MSXPi icon on the desktop. Running the installer again is safe: it updates what is out of date and keeps your msxpi.ini and your disk images. Then start MSXPi from the desktop icon and go to step 8 below, where the MSXPi commands are tried out. The manual steps that follow are for other platforms, or if you would rather install the pieces yourself. To install the pieces by hand you will need Python3 installed in your computer. IDLE will work with MSXPi in Windows - it can be downloaded and installed from Microsoft App store. MSXPi will also work in other platforms - it works better on Linux, since it is the native environment it was designed for initially. At this time, some commands will work on Windows, many won't - but they are being ported and pushed to MSXPi repository, so I recommend to keep refreshing your local copy frequently. There are a lot of Python modules that are not standard in Python, and will require you to install before running MSXPi. When you run msxpi-server, it will complain about missing modules - use that information to install them. For example, to install module "fs": Go to Windows command line and type: python -m pip install fs Repeat for all modules that are not already installed. You will also have to download several files needed by MSXPi - follow the instructions below to get started. Manual setup, and trying MSXPi out ================================== 1. Install an openMSX version that has support for MSXPi extension. You can download binaries for all platforms (nightly builds from openMSX) in the releases section: https://github.com/costarc/openMSX/releases Always use the latest release. 2. Download msxpi-server.py from: https://github.com/costarc/MSXPi/tree/master/software/Server/Python/src Use a server from the same MSXPi version as the ROM in step 3: the socket transport that openMSX uses was introduced in MSXPi v1.6, older servers do not speak it. Note: the msxpi-server component has some commands that require elevation of privileges in the Raspberry Pi platform using "sudo". These commands apply only to Raspberry Pi and will return a message "Command not supported on this platform" for all non-raspberry pi hosts. Run from IDLE console, or from command line: python msxpi-server.py 3. Download msxpibios.rom from: https://github.com/costarc/MSXPi/tree/master/software/openMSX/share/systemroms/extensions Copy to you openMSX/share/systemroms/extensions/ folder. This file is required: openMSX does not ship ROM images, and the extension will not load without it. It is the content of the EEPROM on the physical board, and the emulated interface serves it in the same way, so it boots the MSXPi BIOS and MSX-DOS1 on its own. 4. The MSXPi.xml extension definition is part of openMSX, so there is nothing to copy for it. If you want to use a ROM newer than the openMSX release you installed, take the matching MSXPi.xml from: https://github.com/costarc/MSXPi/tree/master/software/openMSX/share/extensions and copy it into your personal openMSX folder (share/extensions/ under ~/.openMSX, or under Documents/openMSX on Windows), where it takes precedence over the one that comes with openMSX. 5. Use a DIR as DISK with openMSX to facilitate the tests. Create a directory named FloppyA Copy MSXDOS.SYS and COMMAND.COM to FloppyA Make sure openMSX can boot into MSX-DOS using this folder as a drive: openmsx -machine Panasonic_FS-A1WSX -diska FloppyA This is the easiest way to get the MSXPi commands onto a drive. You can also boot MSX-DOS1 from the interface itself, as the physical board does, and use the MSXPi drives instead of a floppy. 6. Download the MSXPi commands you want to test from: https://github.com/costarc/MSXPi/tree/master/software/target Some commands will not work (yet) with openMSX because they were originally developed to work on Raspberry Pi. In time, most (if not all) commands will be ported to abstract the platform and run everywhere. If you can develop in python, help port them (thanks). Three files give you the whole command set: p.com the MSXPi command, which takes the operation as its first argument: "p dir", "p run", "p chatgpt" and so on. It replaces the older one-command-per-operation files (pdir.com, prun.com, pcd.com and the rest), which are gone. pver.com versions of the interface, the ROM and the server pcopy.com copy files between the MSX drives and the MSXPi drives Copy all these commands to you FloppyA You will need an OpenAI key for "p chatgpt" - see step 9 for where it goes. 7. Start openMSX loading the MSXPi extension: openmsx -machine Panasonic_FS-A1WSX -diska FloppyA -ext MSXPi 8. Try some commands - type exactly as shown: p ver pver p cd p dir p set p run p date p chatgpt p music p showpage pcopy Note 1: Read the Users Guide to learn more about these commands. It can be downloaded here: https://github.com/costarc/MSXPi/tree/master/documents Note 2: As I mentioned before, some commands will not behave nicely because they were developed for Raspberry Pi (Linux). Some work is needed on the msxpi-server side to make those commands work on Python running in a host that is not Linux. 9. Create a local /home/pi/msxpi/msxpi.ini This file is used to persist some MSXPi configuration. Create the folder in your computer (under Windows the path is C:\home\pi\msxpi) and save this file inside it: https://github.com/costarc/MSXPi/tree/master/software/Server/Shell/msxpi.ini If you have an OpenAI key, update this file with it so you can use the "p chatgpt" command. The Windows installer creates this file for you, from the msxpi-JumperLeft template, and never overwrites an existing one. 10. Read the MSXPi documentation for more detailed information: https://github.com/costarc/MSXPi/tree/master/documents Settings ======== The extension adds three openMSX settings. Type "help set " in the openMSX console for the full description of each one. msxpirom_bank The bank jumper, as labelled on the PCB. BANK2 (the default) puts the lower half of the EEPROM, with MSX-DOS1, at 4000h; BANK1 puts the upper half, the BIOS only, there. Read at reset. msxpirom_sltsl The J3 SLTSL jumper. OFF disconnects the EEPROM while the interface ports keep working, which is how the board is used when the BIOS comes from somewhere else. ON is the default. Read at reset. msxpiserver_port TCP port used to reach msxpi-server on the host. The default, 5000, is the port msxpi-server listens on. Change it on both sides if that port is taken. Takes effect immediately: the interface reconnects. The first two mirror jumpers on the physical board, and like the jumpers they are sampled when the machine resets, so moving one while the MSX is running does not pull the ROM out from under the code that is executing. Savestates and the reverse feature (PgUp, the "reverse" commands) work with the extension: the state of the interface is part of the savestate. The connection to msxpi-server is not, and neither is the server's own state, so a command that was in the middle of a transfer when the state was saved can fail after a load. Save and load between commands.