ZXpand Online Manual

charlierobson edited this page Dec 21, 2017 · 41 revisions

ZXpand+

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.

COMPATIBILITY

The ZXpand will work with all standard Sinclair ZX81 and TS/1000 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.

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.


WHAT DO I NEED

The ZXpand comes ready to switch on and go. However, you will need a standard SD card to be able to store files.


GETTING STARTED

Format an SD 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!


COMMAND REFERENCE

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
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.

Notes:

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 ""
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

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.

An experimental 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

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

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] 2400 < 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.
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 port.
CLO[SE] FIL[E] Closes the opened file.

Notes:

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.

Examples:

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

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.

FIRMWARE UPDATES

Interface firmware updates are performed via the SD card boot loader. The firmware binary image, ZXPANDFW.BIN, should be copied to a freshly FAT/FAT16 formatted 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 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.

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.


SOUND HARDWARE

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.


ROM FUNCTION ENTRY VECTORS

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 accordingly

    The 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 pointer

    Multiple 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.

  • 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

Notes:

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.


JOYSTICK/SERIAL EXPANSION CONNECTOR PINOUT

As well as joystick connections the expansion connection also exposes 5 & 3.3 voltses, and 5V TTL serial lines. 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!

Pin Function Pin Function
1 Up 2 Fire
3 Down 4 5V0
5 Left 6 GND
7 Right 8 RX
9 TX 10 3V3

Here is a graphic representation of the connector pinout and the numbering of a cable terminated with a 10 way IDC connector: zxp-io-conn


BASIC ERROR CODES

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.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.