AquariusPlus User Guide: An Overview - fvdhoef/aquarius-plus GitHub Wiki

When a new tool or technology is introduced, a user must be shown how to use it if they are expected to be proficient. A tool that lacks a training guide quickly gathers dust (or rust) in favor of the older, more familiar one, even if work efficiency can be improved with a new one.

In the late 1970s, when personal home computers were introduced, became affordable to own, and simple to use, it was customary to include a printed introductory "User Guide" with them. These manuals were usually concisely organized, written, and illustrated so that all levels of users could learn how to operate this new portal of fun and productivity. Examples of processes, commands, and programs were listed in easy-to-read (and easy-to-type) text, and accompanying narrative explanations gave new users the confidence to experiment without the fear of breaking something.

While not (currently) delivered in printed form with the Aquarius⁺ computer, this manual, the Aquarius⁺ User Guide, is intended to serve those same purposes.

In late 1981, Radofin Electronics in partnership with ASTEC designed a family of Z80-based computers targeted at the growing home computer market. Their entry-level proof of concept, nicknamed CHECKERS, featured an inexpensive chicklet keyboard, 2k of RAM, character-based color graphics, and the ability to add hardware and software via an expansion port. A more advanced model, CHESS, had similar features, but sported a mechanical keyboard and built-in Extended BASIC. While CHESS was originally designed to have additional features such as higher quality RGB video out, programmable graphics, and more RAM, those features were never implemented. There were also plans for a more advanced third prototype system (no boardgame-based nickname), but it was never developed.

At the time, Radofin was the primary manufacturer of the popular Intellivision video game system by Mattel Electronics (with components sourced from ASTEC). They also manufactured rebranded versions of the Intellivision for Sears and Radio Shack. After a very productive quarterly sales & manufacturing meeting with Mattel after the 1981 holiday season, Radofin took the opportunity to present the CHECKERS and CHESS concepts to the toymaker. Mattel had considered entering the home computer market for years, even revealing a flashy "Home Computer" add-on for the Intellivision in 1980 that was never released, but which became a point of frustration for both consumers and the Federal Trade Commission.

Mattel and Radofin entered into an agreement to develop and release CHECKERS as the Mattel Electronics Aquarius Home Computer System. The system was engineered and prepped for manufacturing in 1982. Units were teased at the International Toy Fair in early 1983, with a full announcement and roll-out on June 5, 1983 at CES (Consumer Electronics Show) in Chicago. Most of the system hardware components announced at CES were available to consumers by July of that year, along with a dozen software titles on cartridge.

Here were the system features:

• Zilog Z80 processor running at ~3.8Mhz
• 4k of onboard RAM: 1k of Character RAM + 1k of Color RAM + 2k of Program RAM
• Expansion bus for ROMs and additional RAM
• RF Modulator for video out
• Chicklet-style keyboard with 50 rubber keys
• Printer and Data Recorder ports
• Custom PLA1 and PLA2 chips for system management
• TEA1002 video chip
• 8k SYSTEM ROM

The first signs of trouble were reports from retailers in early August 1983 of weak sales. It was still over a month before holiday sales would kick into high gear, but Radofin executives were summoned to Mattel Electronics headquarters in Hawthorne, California to discuss options. That same week, a wave of layoffs at Mattel Electronics had been announced, and as the Radofin team waited in the lobby, they witnessed employee after employee escorted from the building, each carrying a box of personal items.

Mattel Electronics was decimated by the home video game crash of 1983. Parent company Mattel was advised by their accountants to "Either get out of the electronics business, or get out of business". The result was a $394 million loss to the company, most of it from lost revenue in unsold Intellivision hardware and cartridges, but also in the Aquarius. The rights to the Aquarius system were transferred to Radofin, as well as a contract settlement payout and ownership of all remaining inventory.

Radofin rebranded and bundled the remaining Aquarius inventory so that discount retailers could more easily sell product. They released CHESS under the Radofin brand as the Aquarius II. As it was only released in Europe and the UK, the computer is quite rare and fetches thousands of dollars among collectors. Radofin themselves went out of business in 1990, and with their closure, ownership of the Aquarius trademark and intellectual property passed into the public domain, as the purchaser of their assets was interested primarily in acquiring their manufacturing equipment and real estate.

Decades later, Frank van den Hoef and Sean Harrington developed the Aquarius⁺, an update to the Mattel Aquarius, designed to overcome the limitations of the original platform. It featured:

• Zilog Z80 processor running at ~3.8Mhz or ~7.6Mhz Turbo mode
• 512kb of paged RAM, accessible across four 16k banks, plus 2k of Character RAM and 2k of Color RAM
• Legacy expansion bus, controller, printer, and cassette ports
• VGA output with sprites, bitmaps, tiles, & 80 column mode
• USB port for keyboard + mouse input
• SD card for high-speed data storage and retrieval
• Spartan 6 FPGA for system devices (sound, IO, etc.)
• ESP32 S3 with WiFi and Bluetooth connectivity
• OTA system updates delivered wirelessly

Prototypes were manufactured in early 2023, and the project was opened to users on June 5, 2023, the 40th anniversary of the release of the original Aquarius computer. In August 2023, Curtis F Kaylor joined the development team to work on a revised S3 SYSROM/Kernel and plusBASIC, detailed below.

In explaining how a system like the Aquarius⁺ works, it's easy to get lost in technical jargon. As new users are the target audience of this Aquarius⁺ User Guide, we'll describe things in a relatable manner. Don't worry! There are plenty of detailed technical documents elsewhere in this Wiki, and we'll link to a few later, but for now, let's take a look under the hood...

To keep manufacturing costs as low as possible, the original Mattel Aquarius was a VERY simple system (see the specifications above), particularly when compared to modern devices like smartphones. The main processor, a Zilog Z80, did all the work of getting information, manipulating it, and putting the finished information where it belonged, very much like a factory. We also use a Z80 in the Aquarius⁺, partly because it is so efficient at doing this work, but also because there are already hundreds (thousands?) of programs written that the Z80 understands. Why reinvent the wheel? This "Z80 Factory" expects the information and instructions coming into it to be organized and submitted in a particular way.

Other parts of the system follow this process and wait their turn for the Z80 to handle their tasks. The SYSROM (SYStem Read-Only Memory) is a master set of instructions that are stored permanently in a chip on the motherboard. When the Aquarius⁺ is turned on, the SYSROM immediately sends the first instruction to the Z80, it is processed, the results are stored, and then the next instruction is sent. The results of the Z80 are commonly sent to RAM (Random Access Memory), a "warehouse" with hundreds of thousands of "cubbies" into which information can be placed. The Z80 can also retrieve information OR instructions from RAM.

The difference between RAM and the SYSROM is that within RAM, information in each of the "cubbies" can be changed, where in the SYSROM it cannot. When power is turned off or interrupted, all of the information in each of the "cubbies" can become erased or damaged, so RAM starts off as a big, empty (or scrambled) "warehouse" when the system first turns on. Interestingly, the Z80 can be reset without turning the power off and on, meaning that all of the "cubbies" in RAM don't get erased or damaged. This reset tells the Z80 to forget where it was and start again at the first instruction in the SYSROM.

But the SYSROM and RAM are not the only locations where information can be retrieved (or sent). The Z80 also communicates with I/O devices (Input/Output devices) like the keyboard, screen, data recorder, printer, and joysticks or sound generators. To do this, a slightly different set of instructions are sent to the Z80, and these I/O devices must be configured to "speak the language" of the Z80. On the Mattel Aquarius, two specialized PLA (Programmable Logic Array) chips were used to control the interaction of devices on the system along with other circuitry to do things like display video, play sounds, and read the keyboard input.

In creating the Aquarius⁺ as a successor to the original, a couple of problems existed...

First, most of the chips on the Mattel Aquarius motherboard are no longer manufactured:

• Zilog ceased manufacture of the Z80 in June 2024 after 48 years.
• The AY-3-8910 PSG (Programmable Sound Generator) from General Instruments used in the Aquarius Mini Expander is available only on on eBay and at computer swap meets.
• The PLA chips from Hitachi and Ferranti used exclusively in the Mattel Aquarius are only available by harvesting them from old motherboards.

Next, in interfacing the Aquarius⁺ with newer input devices (USB keyboards & mice, WiFi networking, Bluetooth controllers, SD card storage), a faster, more complex management chip needs to be used.

Finally, to add new features (bitmap graphics, digital audio, sprites, tilemaps), a more modern and flexible PLA-like device needs to be used within which these features can be built.

The Aquarius⁺ overcomes these issues with a modern system architecture:

• ESP32 "Governor Chip" - The ESP32 is an inexpensive SOC (System On a Chip) that has its own microprocessor, memory, and storage, along with dedicated I/O device "ports" for common modern devices. The ESP32 is more than powerful enough to run the programs at many times the speed of the Z80, but that is not it's job here...
  • At start-up, the ESP32 sends a core (virtual hardware definition of the Aquarius⁺) to the Spartan 6 FPGA (Field Programmable Gate Array), a modern re-writable version of the original PLA chips with exponentially greater capabilities. This communication is done through a high-speed connection called a SPI (Serial Peripheral Interface) bus.
  • The ESP32 also handles I/O for Wifi networking, Bluetooth, and SD Card storage.
• FPGA "System Scaffolding" - The Spartan 6 FPGA has virtual versions of the PSGs, video system, and the legacy components from the Mattel Aquarius PLA chips. It also has connections to the keyboard/mouse, RAM, and legacy ports.
• Z80 CPU "Factory" - The Z80 processor can either exist as a physical chip on the motherboard OR as a virtual chip within the FPGA using the T80/TV80 core and holding the on-board Z80 (if one exists) in RESET. Regardless of its implementation, the Z80 still executes all of the Aquarius code, but runs a modified version of the original SYSROM that has been expanded to include new features and functions.
• RAM "Warehouse" - The original Mattel Aquarius only shipped with 4kb of RAM, and could only make use of about 36kb. For the Aquarius⁺, RAM has been increased to 512kb, so additional logic within the FPGA manages the increased room for programs, sounds, and graphics on the system.
• Power "The Juice" - The power management of the Aquarius⁺ is much more advanced than the original which had a large "wall wart" power supply permanently attached to the computer. The system is powered via USB micro power input at 5v, but many of the other chips run at a lower 3.3v or 1.8v. To change between these different voltages shift registers are used.

As promised, here are links to more detailed explanations of the Aquarius⁺ hardware for those who are curious:

• plusBASIC Programmer's Reference Guide
• Technical Reference Manual

In many personal home computer systems like the original Mattel Aquarius, the default language for interacting with and programming is BASIC. Developed in 1963 by John Kemeney and Thomas Kurtz as a "Beginner's All-purpose Symbolic Instruction Code", BASIC was originally designed as an interactive mainframe timesharing language. It's commands are English-like, and the simplicity of the loops and branching elements are easy for new programmers to grasp.

The Aquarius⁺ uses an expansion of the original Aquarius BASIC called plusBASIC, a collection of commands and functions from various sources, including Aquarius/MS BASIC, Extended BASIC, USB and MX BASIC, and others. The first goal was to establish consistency across keywords, syntax, and objects so that familiarity in one area of development will lend itself naturally to learning another. The second goal was to allow programs written for the original Aquarius to run, as-is, so that the legacy software will continue to function. MX BASIC was developed by Curtis F. Kaylor beginning in July 2022 in response to the need to update the original USB BASIC 1.1 port (from the Aquarius Micro Expander / MX) to something that could intelligently use the new hardware features.

Kaylor's previously-completed annotated disassembly of the Aquarius S1 and S2 SYSROMs, as well as his work on MX BASIC made him the ideal candidate to expand the BASIC language to access the new system features added of the Aquarius⁺. These enhancements also necessitated that Kaylor create the S3 SYSROM, a Kernel-based revision to the S2 SYSROM that allowed more flexibility in where core routines can be accessed and stored. The S3 SYSROM can also be used in an original Aquarius, but significant hardware modifications must be made to incorporate the ROM. While the S3 SYSROM is effectively complete, the plusBASIC language is still in active development, with new features added regularly.

Writing programs for the Aquarius⁺ is not limited to plusBASIC. Thanks to the 48-year tenure of the Z80 processor that serves as the heart of the system, there are many development environments available to programmers. While it is beyond the scope of the AquariusPlus User Guide to cover these in detail, below is a short list of options.

• AQDS (C♭) - The AQuarius Development Studio features C♭ (C flat), a lightweight, C-style language designed specifically to run on the Aquarius⁺. It includes a file manager, editor, assembler, and compiler. When used within the Aquarius⁺ emulator for troubleshooting and monitoring, it is a full-featured, on-system development environment.
• C - The C programming language, developed in 1972 by Dennis Ritchie while at Bell Labs, is a general-purpose programming language that uses the imperative procedural structure and methodology. Like plusBASIC it uses an English-like language to define data structures and functions. However, unlike the language parser in plusBASIC, C utilizes a compiler program to process the code into a set of instructions the Z80 processor in the Aquarius⁺ can understand and run. While there are many Z80-based compilers out there, the Aquarius⁺ project team supports the free SDCC compiler. To structure the process of building and linking code for the Aquarius⁺, SDCC uses makefiles, a set of instructions on how to make the program. Below are links to platform-specific setup for SDCC:
  • SDCC for macOS
  • SDCC for Windows
• CP/M - CP/M (Control Program / Monitor) is not a development environment but rather an operating system for which a large library of tools have been written, including programming languages. The Aquarius⁺ comes with a CP/M v2.2 environment within which compilers such as Turbo Pascal or Fortran can be run.
• Z80 Assembly - Like the C language described above, Z80 Assembly Language uses a compiler to create Aquarius⁺ programs. However, assembly language is not at all English-like. It does however offer the ability to achieve the most efficient results, as it works with the same instruction set as the Z80 itself. The Aquarius⁺ development team has standardized on the zmac compiler, in fact plusBASIC and the SYSROM S3 kernel are written using zmac.

In this Overview we introduced you to this Aquarius⁺ User Guide, discussing its purpose. We went on to cover the history of both the Mattel Aquarius and the Aquarius⁺, including events and details that brought the platform to its current state. We established analogies to compare the differences in system architecture between the two systems. And finally, we introduced plusBASIC and other languages that can be used to write programs for the Aquarius⁺.

In the next section, we'll discuss how to set up your Aquarius⁺ environment.

If you want to go to another section, visit the Table of Contents.