ZXpand Online Manual
The ZXpand+ is an all-in-one expansion solution for Sinclair ZX81 computers and some clones. It provides the following features:
- 32K of static RAM with software configurable mapping.
- SD/MMC card storage with transparent LOAD/SAVE integration.
- New support commands in an overlay ROM for instant availability.
- Support for common software based high resolution (HRG) systems.
- A reset button to save wear on the power jack connection.
- AY/YM sound chip.
- Joystick and serial I/O via extension connector.
- Firmware update via SD card.
The ZXpand will work with all standard Sinclair ZX81 and TS1000/1500 Computers.
The plus is backwards compatible at a software level with the classic ZXpand.
-
Some hi-resolution programs require additional modifications to the ZX81 in order to work. These will usually be identified as requiring ‘CHR$128’ or ‘UDG’ add-ons. These schemes need additional hardware due to the way the ZX81 video generation works.
-
The TS1500 has a different port arrangement and the ZXpand will obscure the video and tape jacks. There are a number of work-arounds for this such as using a port extender or adding a video 'flying lead' when you do the composite video mod.
This manual aims to be correct but may contain out of date information as the firmware is under constant development. If in doubt make sure that the firmware on your device is up-to-date, listed features may only be available in the latest firmware release.
The ZXpand comes ready to switch on and go. However, you will need a standard SD card to be able to store files.
Most cards come pre-formatted. In the rare case this isn't true or you want a fresh start then you can format the card. You can use any of the standard FAT format types: 12, 16 and 32 are supported. Windows based PCs can generally format cards directly. Mac users should download the SD Association formatter.
Once formatted, you can save some ZX81 programs to your card. These are widely available around the internet. They typically have the extension ‘.P’. If you come across files with the .81 extension, these should be renamed to have a 'P' extension – the formats are identical.
Long filenames are not supported. Filenames should use a maximum of 8 characters followed by the extension, the DOS short name standard.
You may want to organise your files on the card by creating directories, again using a maximum of 8 characters maximum in the name, and putting a few files in each. This should make finding the file you want much easier.
Connect the ZXpand to your computer, insert the SD card and switch on.
To load (for example) the program called 'MAZOGS.P' enter the command:
LOAD “MAZOGS”
It is not normally necessary to add the .P extension, it is generally assumed.
Once you have explored the joy of the 3D Monster Maze or the fields of the Fungaloids then kindly proceed to the command reference to see what else there is to play with!
The built-in commands relating to the ZX printer have been replaced with those required to usefully operate the ZXpand interface. For example the CAT command replaces COPY - therefore to get CAT, you press the Z key in K mode.
If your program needs access to one of the original commands then you will need to disable the ZXpand's overlay ROM at LOAD time or by using the appropriate configuration option. More on that later.
CONFIG
CONFIG "x"
CONFIG "x=y"
Press shift-G in K mode – replaces ‘LLIST’ command
The CONFIG command is used to configure the ZXpand interface and how the ZX81 works with it. As the working of some programs and commands is affected by how the interface is set up, this will be dealt with first.
Parameters to the command and their effects are:
| Parameter | Function |
|---|---|
| "V" | Displays the interface's firmware version string |
| "R=nnnnn" | Sets RAMTOP to the specified decimal value nnnnn and executes NEW. |
| “M=L” | Sets the 'Low' RAM mapping, 8-40K. See notes below. |
| “M=H” | Sets the 'High' RAM mapping, 16-48K. See notes below. |
| "M" | Displays the RAM mapping configuration, one of 8-40K or 16-48K. |
| "X" | Disables the overlay ROM until next reset. |
| "C=xx" | Sets the configuration byte's value, where xx is a 2 digit hexadecimal value, See notes below. |
| "C" | Displays the configuration byte's value as a 2 digit hexadecimal value. See notes below. |
| "J=udlrf" | Controls which keys are to be emulated by the joystick when using INKEY$. See notes below. |
Issue 5.2 of ZXpand maps an 8K block of RAM into two areas of the memory map simultaneously. A shadow of the block at 8-16K also appears at 40-48K. There is no need to use the CONFIG "M=.." command to move the block around. This should make things simpler for personal use. If you're developing a program that you intend to distribute however, you'll need to still use the CONFIG command for compatibility with previous issues of ZXpand. If you have some exotic hardware that requires a particular memory map incompatible with this arrangement then it is possible to restore the previous functionality by flashing a new configuration to the CPLD chip. See 'firmware updates'
The RAM address mapping set by CONFIG-M is preserved in the interface's EEPROM until it is next changed or a factory reset is performed. Some hi-res programs expect RAM in the 8-16K area. These are usually identified as using the ‘WRX’ scheme. Most 32K programs expect a continuous memory block from 16-48K.
Configuration bits are used to specify certain operating modes of the ZX81. The bits are combined into the configuration byte.
Bit 7 controls whether shift enables or disables auto-booting of a program called MENU.P. When the bit is set then shift is required. This is default behaviour. Clearing bit 7 will auto-boot unless shift is held. This mode can be very useful for exhibitions or power station control type applications.
If MENU.P is not found, error 9 will be issued.
Bit 6 controls the behaviour of space/break during program execution. With bit 6 set, behaviour is as normal. With bit 6 clear, you must press shift & space in order to break into the running BASIC code.
INKEY$ can be used to detect the 4 ordinal directions of an attached joystick. No diagonals are usable at this time. The default joystick codes are 6, 7, 5, 8 and 0 which map to the cursor directions.
CAT
CAT ""
CAT "directory"
CAT ">directory"
CAT "+directory"
Press Z in K mode - replaces ‘COPY’ command
It is sometimes useful to know what files are available on the card. The CAT command will do this. It can also be used for directory navigation.
The CAT command without a parameter or an empty string will list the content of the current working directory (CWD). To list the content of directories relative to this then you must specify the path as you might for a DOS based system.
Directories are identified by a following forward slash.
For example:
CAT ""
... might display:
GAMES/
UTILITY/
MYPROG.P 11K
Subsequently typing:
CAT "GAMES"
... might then display:
../
MAZOGS.P 15K
3DMONST.P 13K
To change the CWD you prefix the directory name with ‘>’. This implies ‘going to’ the directory.
CAT “>GAMES”
Having changed working directory then issuing one of the following commands:
CAT
CAT ""
... might show:
../
MAZOGS.P
3DMONST.P
... and from there:
CAT "../UTILITY"
... would show the content of the folder but not change to it.
There is support for wildcards when CATting files. Wildcard operators are similar to those used in DOS.
‘*’ will match with any sequence of characters
‘?’ will match with a single character.
CAT “ST*”
... will show all files beginning with ‘ST’.
CAT “S?T*”
... will show all files having S & T as the 1st and 3rd characters.
Wild cards may be used in conjunction with directory specifications.
CAT “../GAMES/S/STAR*”
... will show all the star-based games in the sub-folder specified.
To create a folder in the CWD you would issue the command:
CAT “+dirname”
Many filing systems automatically add folders for internal housekeeping and these may have combinations of naming and flags which produces seemingly corrupt output. It is safe to ignore these, e.g:
/TRASH-?1
LOAD "filename"
LOAD "filename;X"
LOAD "filename;address"
LOAD "filename:argument"
LOAD "$"
LOAD ""
LOAD will take data from the file with the specified name on the card and place it in memory. The basic LOAD command will work just as you expect. Specifying an empty name will invoke the tape loader as normal to allow you to load a program from cassette.
Some programs may require access to the printer routines (including commands such as LPRINT) or character table in ROM. These are unavailable when ZXpand is operating, so its overlay ROM must be temporarily disabled. Use the following command in this case:
LOAD "filename;X"
Once the program is loaded full access to the internal system ROM is given. The overlay ROM remains disabled until the current session is ended with a hard reset (press and hold) or power cycle.
To put data into specific locations in memory you can use the following form:
LOAD "filename;nnnnn"
... where nnnnn represents a decimal number specifying the target address.
Folders other than the CWD can be specified.
LOAD "../GAMES/MAZOGS"
A special form of the LOAD command will, with the aid of a special server program and suitable serial cable, allow loading of a program via the serial port. This is especially useful for rapid development cycles, and the excellent ZX-IDE can be configured to automatically invoke the server upon successful compilation. Refer to the 'LOAD "$" guide here.
A feature exists which allows a sort-of argument to be specified when typing LOAD. The ZXpand+ firmware will split any supplied filename when it encounters a colon. The text following the colon is stored away and may be retrieved by a program at some later time.
LOAD "ZXWORD:MYNOVEL"
The program ZXWORD (for example) will be loaded as normal, and the 'argument' MYNOVEL stored. See the ZXPAND command description dealing with the noun 'PARM' for further information.
To prevent a program from auto-running append the keyword STOP (shift-A) to the end of the filename. E.g:
LOAD "MAZOGS STOP "
SAVE "filename"
SAVE "filename;sssss,llll"
SAVE "+filename"
SAVE ">filename"
SAVE writes data to the specified file on the card. As with the LOAD command, the basic SAVE invocation will do as you expect. You will not be able to SAVE to cassette tape, unless you have explicitly disabled the overlay ROM with a CONFIG “X” command or used the LOAD "filename;X" form to load your program.
An alternate form of the command is used to save a specific memory location to the card, with a start address specified by ssss, and a length of llll bytes. All numbers are specified in decimal.
SAVE "filename;0,8192"
This would, for example, save the content of the overlay ROM to the desired file.
Options exist to control how existing files are treated when SAVEing. Similar to the CAT command, the characters ‘>’ and ‘+’ modify the SAVE behaviour.
SAVE “+filespec”
Prefixing any valid SAVE specification with ‘+’ will rename any existing file with the same name with a .BAK extension. If the backup file already exists, however, then an error will be generated.
SAVE “>filespec”
The ‘>’ prefix will unconditionally overwrite any existing file with the same name.
ZXPAND "verb"
ZXPAND "verb arg arg ..."
ZXPAND "verb noun"
ZXPAND "verb noun arg arg ..."
Press shift-S in K mode – replaces ‘LPRINT’ command
This command is intended to provide a more expressive way of interacting with ZXpand+. It is very early in the development of this command and so changes will occur.
The arguments are typically a combination of verb, noun and argument. Verbs and nouns are identified by at least 3 characters and may be abbreviated as such. Typically the verb describes a desired action, and the noun specifies the target of the action. Verbs are:
- OPE[N]
- PUT
- GET
- CLO[SE]
- DEL[ETE]
- REN[AME]
| Verb | Noun | Args | Note |
|---|---|---|---|
| DEL[ETE] | path | See extended note below. | |
| REN[AME] | path1 path2 | See extended note below. | |
| OPE[N] | SER[IAL] | 1200 <= baud rate <= 38400 | Opens the serial device at baud,8,n,1. |
| OPE[N] | MID[I] | Opens the serial port at midi data rate. | |
| OPE[N] | CAT | path | Opens a directory listing of the specified directory path. |
| OPE[N] | FIL[E] | path | Opens the specified file ready for use by streaming functions. |
| PUT | SER[IAL] | text | Puts the supplied text to the serial port. |
| PUT | SER[IAL] | *nnnnn lll | Puts lll bytes of data from memory address nnnnn to the serial port. |
| PUT | MID[I] | *nnnnn lll | Puts lll bytes of data from memory address nnnnn to the serial port. |
| GET | SER[IAL] | *nnnnn | Copies the content of the serial buffer to the specified address. |
| GET | CAT | *nnnnn | Gets the next catalogue entry, either in the IO buffer or at the specified address. |
| GET | PAR[M] | *nnnnn | Gets the argument that may have been specified by the last LOAD command, either in the IO buffer or at the specified address. |
| CLO[SE] | SER[IAL] | Closes the serial/midi port. | |
| CLO[SE] | FIL[E] | Closes the opened file. |
Unlike LOAD and SAVE, the .P extension is not assumed for DELete or RENaming. This is by design and is intended to provide a small amount of extra security.
The 'IO Buffer' is at 16449.
Write the data in A$ to the serial port:
10 INPUT A$
20 ZXPAND "OPE SER"
30 ZXPAND "PUT SER " + A$
40 ZXPAND "CLO SER"
Write 100 bytes of data from memory to the serial port:
10 LOAD "MYDATA;30000"
20 ZXPAND "OPE SER"
30 ZXPAND "PUT SER *30000 100"
40 ZXPAND "CLO SER"
The reset button has different effects depending upon how it is pressed. The three available reset types are:
- SOFT RESET A short tap will reset the ZX81 only. The green LED will flash.
- HARD RESET A longer press, approximately 1.5 seconds, will reset the ZX81 and the interface controller. The green and yellow LEDs will flash.
- FACTORY RESET A 5+ second press of the button will restore the content of the EEPROM to its factory default. The yellow LED will blink.
Interface firmware updates are performed via the SD card boot loader. The firmware binary image, ZXPANDFW.BIN, should be copied to your SD card. This is then inserted and the interface rebooted by executing a hard reset or power cycle. The yellow LED will come on and the green will flash. When the firmware has updated then the ZX81 will be reset.
The firmware revision is displayed at power-on.
The ZXpand+ contains some programmable logic in the form of a CPLD and this can also be updated in-place. Should the need arise then a file called zxpplus.xvf should placed on the SD card and the device rebooted. Because the main firmware is in charge of this process, rather than the space-limited bootloader, then the restrictions outlined above are not relevant. CPLD firmware images are found here.
To determine which revision of overlay ROM you have, type
PRINT PEEK 7679 / 10
This will yield a version something like ‘7.1’. Although not planned at this time it may become necessary to update the ROM. This should be easier than with the classic ZXpand as the code is stored in an EEPROM. It is not possible to update the code in place, however, as the chip does not support this. An external programmer is required but no eraser is necessary. If an update is desired then the chip can be returned to base for reprogramming or a new chip supplied for a minimum cost.
The on-board AY/YM chip is addressed using the same port number pairs as the de-facto standard ZON-X interface, namely $CF & $0F or $DF & $1F. Unlike ZON-X, however, these port addresses are fully decoded.
$CF/$DF are the register number latches.
$0F/$1F are the data latches.
Reading of the chip's registers and IO port is via port $CF or $DF.
Turbo-AY is possible with the addition of an inexpensive circuit board and additional AY/YM chip.
Information relating to the programming of this chip is beyond the scope of this document. Many online resources are available however, not least the ZON-X manual which contains much relevant information.
In order to maintain compatibility across version revisions a number of fixed address 'entry vectors' exist in the ROM. The vectors are primarily to insulate programmers from the nasty matter of calling code from the ROM, allowing updates and innovations to occur without breaking programs in the future.
These API functions represent a small subset of ZXpand functionality, and were designed to provide a clean way to manage some of the auxiliary matters of interfacing, such as waiting for commands to finish or transferring buffers of data. The actual mechanics of executing commands is left to the programmer as there would have been too many API calls if every feature were to be wrapped. The essential mechanisms of command execution will not change as they are dictated by hardware, and therefore are safe to code directly. Where breaking changes might occur care will be taken to maintain backward compatibility.
ZXpand often uses the high-bit terminated (HBT) string format where the string's end is marked by a byte having its top bit set. This was adopted because the BASIC integration made it a convenient choice. Some strings however may be better represented by storing a length along with the data. This is most likely the case when it comes to transferring serial data where a string may be arbitrary bytes rather than alphanumeric characters. These length-prefixed buffers (LPB) may be used in the streaming APIs.
In general ZXpand functions return a success error code of $40. ANDing the result with $3F will yield the same code as the BASIC error codes, or 0 which indicates success.
-
API_ZXPANDCMD
8178, $1ff2
This is the handler routine for the ZXPAND command. Anything it can do, you can do here. On entry: DE -> HBT command string. See ZXPAND command description. On return: All went well. Otherwise program will quit with error. -
API_STREAMREAD
8180, $1ff4
Perform composite streaming read operations on blocks of up to 256 bytes. Usable from BASIC.
On entry: Streaming parameter block (SPB) is set up appropriately
On return: result code in SPB is set accordinglyThe printer buffer at 16444 is designated as the SPB. Its structure is as follows:
16444 = (byte, in) operation/mode
16445 = (byte, out) result
16446 = (byte, in) xfer length (0 = 256)
16447 = (word, in) data pointerMultiple operations may be combined into one call. Each bit in the operation code designates a possible action. Operations are open, read, wait and store. These are represented by bits 0..3 inclusive, respectively. Open must be performed separately while read, wait, store may be used in any combination.
-
API_RESPONSE
8182, $1ff6
Waits until a previously executed command has finished.
On return: A = error code -
API_FILEOP
8184, $1ff8
Performs a file operation.
On entry: DE -> HBT filename string, A = mode ($00 = load, $7F = delete, $FF = save) On return: A = error code -
API_SENDSTRING
8186, $1ffa
Writes a string to ZXpand.
On entry: DE -> HBT terminated string, or 0 to send an empty string -
API_XFER
8188, $1ffc
Transfer data to/from ZXpand.
On entry: DE -> memory buffer, L = byte count, A = mode ($00 = read from ZXpand, $01 = write to ZXpand) -
API_RDJOY
8190, $1ffe
Reads the joystick. Usable from basic. See notes below. On return: A, BC = joystick data
One way to read the joystick data from BASIC is by using the following code:
LET J = USR(8190)
Each bit in the variable J, as used in the example above, represents a direction or button.
| Bit | Meaning |
|---|---|
| 7 | up/forward |
| 6 | down/back |
| 5 | left |
| 4 | right |
| 3 | fire |
Unfortunately ZX81 BASIC lacks bitwise operators, so decoding this value may be tedious. A better way to get joystick input in BASIC is to use the INKEY$ integration. Refer back to the CONFIG-J command.
The joystick interface is different depending on whether you have an issue 5.1 or 5.2 ZXpand+. Both interfaces offer a 5V TTL serial port as well as the joystick functionality. Prior to issue 5.2 the rectangular connector offers both 5 & 3.3 voltses for use by the intrepid experimentor. From issue 5.2 onward the 3.3v line is not present. It's easier to produce 3.3v from a 5v source than it is the other way around.
The joystick lines are general purpose TTL IO and can potentially be used for directly interfacing with other 5V digital signals.
ZXpand uses 5V TTL signalling levels on its serial port. Be sure that whatever you connect to your device will neither damage your ZXpand nor be damaged by it!
The pinout is thus:
| Pin | Function | Pin | Function |
|---|---|---|---|
| 1 | Up | 2 | Fire |
| 3 | Down | 4 | 5V0 |
| 5 | Left | 6 | GND |
| 7 | Right | 8 | RX |
| 9 | TX | 10* | 3V3 |
- only on boards prior to issue 5.2.
Here is a graphic representation of the connector pinout for boards prior to issue 5.2, and the numbering of a cable terminated with a 10 way IDC connector:
The interface can report the following errors. They are shown in inverse video to distinguish them from standard system report codes.
| Code | Meaning | Explanation |
|---|---|---|
| 1 | Fatal disk error | The card is unreadable due to a hardware problem or unformatted card. |
| 2 | Internal error | The card file system structures are inconsistent. Reset should fix this. |
| 3 | Not ready | The card is not responding or no card is present. |
| 4 | Not found | No such file exists. |
| 5 | No path | No such directory exists. |
| 6 | Invalid name | The specified name contains illegal characters. |
| 7 | Write protect | An attempt has been made to open a read-only file for writing. |
| 8 | Exists | An attempt was made to open a file for writing but the name is already used. |
| 9 | Boot error | Menu.p not found on the card root directory. |
| D | No FS | Card is not formatted or is damaged. |
| F | Timeout | A timed operation took too long to complete. |
This is usually a problem with the SD card. While ZXpand is compatible with most cards there will be some that will refuse to work even though they are fine in your computer. If possible try a different card. Newer and faster/bigger are not always better. Check the format of the card. If it's convenient you can try reformatting it. See the guide in the 'getting started' section.
This is most likely a power issue. The supply being used is not able to deliver enough current or the internal regulator has degraded over the years. The original sinclair power supplies produce 9-12v at ~700mA. I recommend a new power supply that is able to produce 7.5V at 1A+. This will ensure there is enough current, keep the zeddy cooler while working and reduce the wear on its internal regulator. Something like this:
The details here are:
- 7.5V is selectable or the unit's fixed output.
- 1000mA+ though less might be OK. 750mA is common and should work.
- 3.5mm TRS (tape/jack plug) connector - They used to be common but now are not.
- Straight adapters - Most are right-angled now. They might work but I can't say.
ZXpand is set to auto-boot but there is no 'menu.p' file in the root directory of the sd card. See section on the CONFIG command.
The firmware is probably corrupted and you need to re-flash it. Follow the update instructions.
You should re-flash the CPLD bitfile, Follow the update instructions.
Clean the zeddy's edge connector. Use a 'magic eraser' type sponge, pencil rubber or fiberglass pencil. Avoid sandpaper. It can just about be done with the motherboard in place but you may have to open the case. Be careful though! The keyboard ribbon will probably break. I don't recommend people open their zeddys any more.
- Some programs access the ROM directly. The ROM changes for the ZXpand overlay/driver mean code has been moved or deleted. This usually leads to a crash. Use the LOAD "PROGRAM;X" command to automatically disable the ZXpand overlay ROM after LOADing to allow a program to run. The overlay will be re-enabled by a reset.
- Some hires programs access the character set in ROM, they will show up with corrupted text. ZXpand uses the character set area of ROM for code. You just need to disable the overlay as above.
- 1K programs may have difficulty running on an expanded memory machine. Mostly this is because of the display file. Use CONFIG "R=17408" to set RAMTOP to the same value that a 1K machine would have then LOAD your program as normal.