Friday, September 10, 2021

Game Controller - SNES MAX - Software Resource

Just like the 4Play joystick card, I have setup this software resource page to keep together a list of supported SNES MAX software titles. I'll add more to this list as they become available.

Program(s) SNES MAX adaptation/conversion by SNES MAX port usage Comment Links
Attack of the PETSCII Robots David Murray / Ian Brumby 1
Robotron 2084 Nick Westgate / Lukazi 1
Mario Bros Lukazi 1 & 2 Two player co-op.

Friday, June 25, 2021

Game Controller - SNES MAX - SNES Controller to Apple II Serial Interface Card

The SNES MAX Cable and the SNES MAX Socket.

What is it?

The SNES MAX is a serial interface card that allows an Apple II to communicate with SNES Controllers. It allows a slotted Apple II to read the maximum number of the SNES controller pushbuttons ie all twelve of them. The game "Attack of the PETSCII Robots", developed by David (the 8bit guy) makes use of all twelve buttons. It allows you to do cool stuff like move in one direction and fire in another (which you want to do when being chased by a pesky robot). This game only supports keyboard or SNES MAX control. Ian led the Apple II conversion effort of the PETSCII Robots game and commissioned me to make an SNES adapter, similar to what was done for the Commodore version.

The PETSCII Robots game conversion overlapped the development of the SNES MAX. It's unfortunate that the SNES MAX was not able to be completed in time for the game release. While putting the first batch of production cards together I also converted a two player game, Mario Bros, to test and make use of SNES MAX's dual controller ability, These are the only software titles currently providing support for the card but we hope other developers come on board and help add more titles. There are a few games I have on my radar which I hope to convert some day. Other great candidates include the recent work to convert the "Game Boy" Tetris to Apple II conversion. By using an SNES controller you can closely resemble the "Game Boy" controls and capture more closely that specific controller feeling. Another great game, Roborton 2084, could use a controller upgrade. Its Apple II version resulted in a gameplay downgrade. The arcade version uses two joysticks, one for movement and one for the shooting direction. Much like the PETSCII Robots game, it could really benefit from having these independent actions. There are many other keyboard based Apple II games where the joystick control was not implemented or was cumbersome to use.

Let's be clear. The SNES MAX is not an Apple II joystick replacement. It does not operate via the Game Port. The SNES MAX uses the SNES controller protocol which reads the controllers serially just like how it's done on an SNES Console.

The SNES MAX comes in two different board layouts (the cable version and the socket version). Both boards are electrically identical. The difference lies in the connection options. The cable version of the board would suit users that predominantly would use wired SNES controllers and the socket version would suit those who plan to use a wireless solution. Either board can be used with wired or wireless controllers. The sockets allow for a cheaper solution but it means that if you are using wired controllers then the plugs will not fit through the back Apple II case slots (unless used on the early Apple II models where the back slots are open) and you will need to keep your hood open.

Things to note:
1 The wireless receivers may consume a lot of power eg the 8BitDo receivers consume about 100mA on the 5V rail. When using multiple receivers or if your system is already highly loaded you may experience power issues. Make sure you use the SNES MAX appropriately based on your power supply and existing card setup.
2. The SNES MAX Socket version results in a tight fit between slots if you have the following Apple II slot populated. Wireless receivers which are larger in physical size than the 8BitDo option may cause issues.
3. The 8BitDo receiver tends to have a very tight plug fit with the SNES sockets. I'm told this is also the case when using the 8BitDo receiver on an original SNES console.
4. The SNES MAX only works with digital signals. Even though some wireless controllers may have analog thumb sticks, the analgue signals are not used. For example the 8BitDo wireless receive converts the thumb stick 1 into the digital direction buttons while thumb stick 2 is not used.
5. Other SNES devices such as guns and multitaps are not supported. Mice may work.

The SNES MAX has been tested using an Apple IIe and a IIGS. Various different revisions of the wired controller and 8BitDo's SNES wireless receivers have been tested. Also all controllers have been tested with a lengthy extension cable.

How it works.

Early 8bit game consoles like the Atari 2600 use joysticks where each button or direction is wired directly to the game console ie parallel communications. With the advent of faster consoles and the requirement for more pushbuttons on the controller, multiplexing was selected over more signal lines (needing bigger plugs and thicker cables). This resulted in the transfer of more signal data over fewer lines ie serial communications. Some controllers try to be backwards compatible with the Atari standard like the Amiga CD32 which is half parallel and half serial and the SEGA Genesis / Mega Drive Controller which is both parallel and serial depending on a selected mode. The following generation (6 button) SEGA Genesis / Mega Drive Controller is backwards compatible and so the controller became an overly complicated solution. Alternately Nintendo's solution for its original game system, the NES, only uses serial communications which results in a very simple and elegant design. For its following generation, the SNES controller, is just an extension of this which is also nice and simple. The SNES controllers are one of the simplest of serial controllers to work with. Hence their preference over alternate controllers.

The way in which an SNES controller works is by using simple latch chips ie 2x4021, 2xW545 or 1xV520B (the NES controller only used one 4021 chip). Only three signal lines are needed between the host and the controller. A latch signal is sent from the host to the SNES controller to tell it to take a snapshot of all its pushbuttons. Then the data line is read by the host to determine if a button is on or off. Clock signals are sent from the host to the controller to tell it to send the next button press status. This results in being able to read up to sixteen digital button signals. However, the controller is physically constricted to only using the first twelve of these signals. There may be third party controllers which make use of the extra four spare buttons.

On the host side (in this case the Apple II) software needs to be written to read the SNES controller data serially. This routine takes about 500 microseconds (for two controllers ie twelve pushbuttons read from each controller) which is much quicker than the roughly 3000 microseconds it takes to read one of the Apple II analog joystick axis. You then have code on top of that which processes the data but you have to do that anyway regardless of which type of interface you have. Example software for the serial import routine can be found in the attached file at the end of this blog post.

Designing the solution.

The first decision was to select which type of interface this project was going to take. The options were

1. Remove the existing cabling out of a SNES controller and wire the twelve pushbuttons directly to a parallel input card (such as the 4Play card). The problem with this solution is that it requires the destruction of the original controller.

2. Build a buffer in between the SNES Controller and a parallel input card (such as the 4Play card). A microcontroller could be used to buffer the pushbutton signals and push these in parallel to the host. This option requires more hardware but simpler software on the Apple II side. The problem with this option is you would need two devices, the adapter and a parallel interface card. These days using a microcontroller to do the buffering is the cheapest option however back in the day this was not the case. The December 1993 copy of Popular Electronics (, starting at page 34, contains a great article on how this was achieved back in the day.

3. The serial ports on an Apple II (directly from the IIc/IIGS ports or via a serial card) use a different type of serial communication compared to that of the SNES Controller, both in electrical terms and in the terms of the protocol. A microcontroller could be build inbetween to buffer the signals and then serially send them to the host. This would involve a considerable amount of work on the hardware side and the software side.

4. Talk serially directly from the host to the SNES controller. This requires very simple hardware and relatively simple software. Hence this option was chosen for the project. There is always a trade off between designs and in this case, when comparing this solution to the parallel interface option we are sacrificing the speed of reading the data (500 microseconds instead of 40 microseconds) and in doing so make the hardware side much, much simpler. This was deemed an acceptable trade off and fits in well with the ethos of how the Apple II was designed ie optimise the hardware and let the programmer deal with what they get.

Once the type of interface was selected there were two main ways in which this could be implemented. One was to use the 16pin Game Port interface (not the 9pin Game Port because it needs to support output as well as input signals) and the other was to use the slot based interface.

I love the 16pin Game Port as a quick and easy way to do hobby experiments. However, for a durable professional solution I believe that using the Apple II slots is a much better option. I find the 16pin Game Port fiddley and difficult at times to connect in to. It's not something I would want to be plugging to and unplugging from all the time. The SNES controller adapter which uses this interface has been around for decades ( however one must take care in its design because other circuits use this socket too (shift key mod, open and close apple buttons / joystick PB0 and PB1) meaning if diode protection is not added one can easy cause a short circuit which would not be good for the motherboard. Being such a simple build I did put it together just for laughs. It does work however it does have its issues ie CMOS - TTL theoretical incompatibility, problematic when used with certain controllers (due to region locking) and control-resetting the Apple II due to the open/close apple button tie ins.

Just a few of the official SNES Controller boards. Here are several of the SNES MAX boards used for testing.

For a durable solution, using the slot interface is definitely the way to go. I figured that being such a simple design that I could knock the project over in a day or two. Here we are a few months down the track and I'm finally getting the production boards ready for sale. It's annoying to think how much work there was for such a simple circuit. Most of the delays have come from having to wait for parts and PCBs. I have managed to get every prototype board working however they have not worked in all conditions.

I've never owned an SNES console, therefore, I've never had an SNES controller. Acquiring one was my first step in testing the first prototype. The testing went fine until I found out that Nintendo had not only region locked specific sections of their console but also region locked the controllers. It surprised me to find out how many variations there are of just the official SNES controller circuit boards. For proper testing I needed to source the other types of controllers which I did. The difference in electronics between the US/JAPAN controller and the PAL controller was not very much (pull up resistors on the latch and clock lines) but it was enough to cause issues with the first prototype. Being a tri-state design with pull-ups/pull-downs caused issues because of the region locking differences. Running the controllers via extension cables or when using two controllers at the same time exacerbated the issue. Swapping both the chips to their inverted equivalents meant keeping the same design but having an extra inverter to replace the pull-down latch circuit. This worked but the design was changed anyway to remove the need for tri-state outputs altogether and resulted in a more stable solution.

Measured resistance between 5V and the following lines
US/JAPAN, Model SHVC-005, Design 1990, Clock = 7.3k ohm, Latch = not connected.
US/JAPAN, Model SHVC-005, Design 1992, Clock = 12.8k ohm, Latch = 12.9k ohm.
PAL, Model SNSP-005, Design 1990, Clock = 1.0k ohm, Latch = 3.6k ohm.
PAL, Model SNSP-005, Design 1992, Clock = 1.1k ohm, Latch = 2.4k ohm.
8BitDo Bluetooth Wireless Receiver, Clock = 153.9k ohm, Latch = 153.2k ohm.

This design worked on my ROM1 IIGS and IIe machines but did not work on Ian's ROM3 IIGS. The wired SNES controllers would work but the wireless controllers would not. I tried to setup my IIGS as close as possible to Ian's and even tried his wireless controllers but I could not reproduce the problem. Luckily Ian had a logic analyser and hence was able to provide me with details as to what was going on. We tried a number of changes but to no avail. Having to do remote testing is never easy.

At this stage I started looking more closely at the chip design. The SNES controller is CMOS based and I had been using TTL logic to match the Apple II slots. Signals going from CMOS to TTL are not an issue but going from TTL to CMOS requires greater care. Technically the signals are not compatible and the adapter was only working for me because my TTL chips were manufactured to better tolerances than what the TTL requirement specifies. The right move was to change over to using 74HCT chips instead of the 74LS ones. With this comes extra care since CMOS chips are more prone to static damage. It was decided to include some protection circuitry. No so much to reduce electrical noise or to improve static immunity but mostly to protect the adapter from issues caused by hot plugging of the controllers.

I went back over the Apple II circuit diagrams using several different publications and I came across the signal descriptions that show that during a data output pulse video garbage can be super imposed into the first part of the pulse. I kicked myself for not knowing this. Normally this would not have been a problem since latching circuitry only looks at the pulse during the low to high Apple II clock transition and does not take the rest of the pulse into account. In our case there was no latching circuitry (the latch and clock pulses are being generated by the Apple II system clock and not by any latching chips). I find it strange that I could not reproduce these issues on any of my machines. The adapter design was changed from using the data bus to the address bus for control and this fixed the issue.

Could this design be optimised even further? Definitely. Daniel put forward some great alternative designs including a single chip version and designs where the address bus control was not required ie the clock and the data read actions could be joined together into one action. These designs do work, however, because of the tri-state design it had stability issues just like my first prototypes. Tuning could have been performed but at the expense of other factors such as a larger current draw. The issue with joining the clock and data read actions resulted in the Apple II latching the button read data on the same pulse transition as the change between buttons. It was deemed to risky to use a design that's working on the very edge of what is possible.

Just as I was putting together the first run of boards and performing unit testing, I found that a specific combination of controllers would not work together. Each controller was fine on it's own but since the clock and latch signals are shared between two controllers, a controller can affect the signals going to the other controller. The region locking issue had come back to haunt me. This time thanks to the addition of the protection circuitry. Luckily the fix did not required a PCB board change. However, I had to purchase extra controllers to perform more thorough testing and this just delayed the project even further.

I'm happy to be finally releasing the product.

Availability and distribution.

I've only just received the production boards and have put a few together to get some photos for this blog entry. I've started putting together the first run of boards as the component parts arrive. The boards will be available shortly from the USA using ReactiveMicro and from Australia using my "Lukazi's Loot" website.

Future work.

I'm working with Nick to include 4Play/SNES MAX support into the AppleWin emulator. This will save me a lot of time when it comes to adding software support for these hardware projects. It will also help games such as the PETSCII Robots be more playable in the emulator.

The Bluetooth version of the 4Play card is in development (using an ESP32 chip solution so hopefully WiFi can be added in as there well). Maybe this can even be worked into a Game Port equivalent version at a later stage. The only reason that I'm mentioning this here is because I know that some people have expressed interest in getting the 4Play card at the same time as getting their SNES MAX. Not that the 4Play card will be discontinued but if you are a wireless junkie then you may wish to wait for the new card.


I just want to thank all the people involved in the "Attack of the PETSCII Robots" project. Thank-you Ian for approaching me for the build and collaborating on the project. Thank-you to Kevin, Dean and Michael for your expert opinions on some of the technical details and making sure I was heading in the right direction. Thank-you to Daniel for keeping me on my toes and making sure I had double checked all the design decisions. Thank-you to the many people who helped with marketing and distribution of the product. Lastly thank-you to everyone else for your support and I wish you many years of enjoyable gaming.

Order your copy of "Attack of the PETSCII Robots" from here

Update: 17th July, 2021.

Thanks to Nick's great disassembly notes, the conversion of Robotron 2084 to use the SNES MAX, was much easier than what I was expecting. The game can be found along side other goodies in the attached file below.
SNES MAX example code, schematics, etc

Update: 20th August, 2021.

The SNES MAX is now avialable from ReActiveMicro or Lukazi's Loot.

The 4Play and SNES MAX cards have been emulated in AppleWin. However, currently the configuration is limited and most things are still hard coded. Tom is helping out in getting the user interface part enhanced and getting the code integrated into the live AppleWin release.

I have tested an NES controller (NES-004) with the SNES MAX and it works well. Since the NES controller contains fewer buttons it can only be used with games like Mario Bros where fewer buttons are required. It's like having a SNES controller but where the upper protocol buttons (A, X, Front Left and Front Right) are contstantly pressed down. I'm not going to keep the cables for these in stock but I can make these up as a special order.

Friday, October 16, 2020

Total 4play - Leveraging Total Replay's amazing infrastructure

Total 4play is a hard drive based collection of arcade style games which have been modified to support digital joystick gameplay, specifically via the 4play card. This compilation has only been made possible due to an amazing bit of infrastructure, called Total Replay, which is what Total 4play is based upon.

Total Replay can be described as a menu selection system and compilation of Apple II games. Compilation sets of Apple II games have been done before but nothing comes close to having the features of Total Replay. To obtain valuable disk space other game compilations have, in the past, resorted to removing parts of the game such as the title screen to cram games together. In contrast, Total Replay aims to preserve all the original content. It uses relatively modern compression techniques and relentless byte saving optimisations to make up for the extra disk storage space needed. The software contains game help pages, original title pages, game demos, an intelligent game title text search engine, original box art where possible, a configurable cheat mode, Control-Reset feature that gets you back to the main menu, a quick loader and bug/compatibility fixes for certain storage media, memory and sound cards. These are just a few of its amazing features. In many ways this software is more than just a game compilation, it's a way to immerse one's self in retro gaming nostalgia but without all the annoyances of the era, such as compatibility issues and relatively slow loading times.

Version 1.0 of Total 4play has be released with twenty converted games. The majority of these games have already been converted to support the 4play. However, these conversions have been done on floppy disk images. There are several advantages to using the Total Replay infrastructure instead of using disk images. These advantages include :-

1. Better grouping of games in one easy usable format. Faster loading and switching between games. Seeing title screens and demos before starting the games.

2. Being able to use any slot of the Apple II for the 4play card. This was more difficult to achieve with individual floppy disk conversions.

3. Having information in the help page that describes which input format (keyboard, Apple II Joystick, Joyport or Gizmo) has been overwritten. Saving the need to look this information up from another source.

4. The second stage of the conversion process (the storage of the changes) is much simpler. In Total 4play this involves applying the changes to the game during the start up sequence where as with the individual floppy disk conversion this meant finding the right places on the disk to modify the code. Having code go across sectors or code that was duplicated multiple times on the disk or code that was compressed made the conversion difficult to perform.

You would have thought that after twenty or so conversions that the conversion process would get simpler due to reoccurring code. However, this has not been the case so far. Apart from the games that were sequels, the code has been different in every one of my conversions. It amazes me how many different ways something can be written in assembly language that performs the same function.

This project will be ongoing. The first round was to work out the infrastructure and get some experience in putting together the games where "stage one" of the conversion process had already been done. Therefore, these first twenty games might not be the best examples of where digital joystick gameplay shines. I missed including some games like "Boulder Dash II", "SuperPuckman" and "Super Taxman 2" because these games were not included in the Total Replay list. The next round of conversions is to work out how to include these into the infrastructure then work on games which make the most sense and the ones which I can still play with for hours on end ie "Snakebyte", "Mr Do.", "Hard Hat Mack", "Pooyan" etc.

Digital gameplay is not not for everyone. It does take away from that nostalgic Apple II experience but does bring that arcade experience closer to the home computer environment. Some people prefer playing games using game controllers over joysticks but my preference is for the arcade joystick, which in my opinion, adds another layer to the experience. For now my original Apple II joysticks have been put away and I'm happy to let other users play with the digital ones. These are much easier to replace.

A big thanks to everyone who made Total Replay possible and for your help in getting me started on my variant. I suspect that Total 4play is not going to be the last offshoot of this wonderful bit of infrastructure. It has the potential to transform many other gaming genres. Think "Total Adventure" or "Total Education". 

Total Replay:


Total 4play V1.0 (20 games):


Sunday, August 23, 2020

Modern Monitor Solutions - Display Lag

Early home computers were built around the concept of using televisions for a source of display. As monitors became more affordable, monochrome and then colour monitors became the norm. These solutions rely on CRT technology but as time goes on it becomes harder and harder to support, in terms of replacement or in terms of repair. Numerous creative solutions have been designed and built to cater for an ever-increasing demand of CRT screen replacements. A lot of these conversions have focused on getting an image that is as close as possible to the CRT looking display. However, is this being done at the expense of other factors such as the display lag? Do you find it difficult to match that high score you got as a teenager on your favourite game? If so, then maybe it's not due to old age. It may be due to your monitor solution. I compared the display lag on several of today's solutions and I found mixed results.

For those enthusiasts using retro computers for word processing, programming, communications and hardware hacking, the display lag will hardly matter but for the retro gamer it’s an important factor to consider. Everyone will have a different perspective on how authentic they wish their retro experience to be. To some, having to replace their CRT display with an LCD solution would seem unthinkable while to others playing a game on an emulator is nostalgic enough. It will all depend on your time, resources, budget and your level of the "Obsessive Compulsive Disorder". Which is more authentic, playing on a cycle accurate emulator or a physical computer with a modern-day monitor? This is what I wanted to find out.

Frame strip showing a three frame (60ms) delay.

It's generally considered that a lag of 30ms on a display is not going to be noticeable. When you consider one screen refresh will take 20ms when displaying at 50Hz or 16.67ms when displaying at 60Hz then you hope your monitor is not going to have a lag of more than a frame or two. Even 30ms sounds quite a long time to me, considering today's LCD gaming monitors tend to advertise lag to be under 15ms. If you are sitting in front of a computer with just one monitor, then you're probably not going to notice any lag. I first noticed it when developing the A2 Video Streamer which sends video signals over USB to display on a modern-day computer. I wasn't surprised to find that sending video data over a USB feed was going to cause a delay but what I do find surprising is seeing large delays in some modern-day monitor solutions, especially on those that I assumed to have no buffering. Every monitor is going to have lag. Even a CRT monitor. However, the lag on a CRT monitor is going to be in the nanosecond range. For now, I just wanted to test the display lag using tools I had at my disposal. What I wanted to do was to compare a CRT monitor with other video solutions to see how much difference there was. I figured I could do this with a bit of programming and a device to record the video of two monitors side by side.

I started off by writing a simple program that displays a two-digit number at the start of each text line. The number is updated by one and rewritten to the buffer page every time a vertical blank happens. That way the number represents each display frame. Vertical blanking is a pain to write on the Apple II because it is done differently for each of these groups of models 1.Apple II/II+, 2.Apple IIe, 3.Apple IIc/IIc+, 4.Apple IIGS. Since the II/II+ code either requires a hardware modification, extra hardware or substantial amount of programming (specifically lookup tables), I left the code supported only by the computers I had on hand. That is all but the II/II+. Once the program was written, tested and running, all I had to do was to setup each of my computers (IIc, IIe and IIGS) with two monitors at a time and video the results. To do this I used an iPhone and two apps, ProMovie and MoviePro. These apps allowed me to use a predefined frame rate (~50fps and ~200fps for 50Hz). The iPhone seemed like a reasonable option for the accuracy that I was after.

The selected recording frame rate, using the iPhone, was not exact nor was it an exact match to the Apple II's output frame rate, but this did not turn out to be an issue. When looking at the video frame by frame, it allows you to see a scan line coming down the page very slowly. The scan line differences from both monitors can then be compared. Watching the recording of a CRT monitor shows the frame numbers changing over the scan line. However, the recordings of the LCD monitors are not as clear. The change is more gradual, and I suspect this is because filtering is being done to merge the video frames. This makes the comparison process more difficult.

Due to the slight difference in scanning rates between the IIGS and the Video Overlay Card (VOC) we get to see some interesting line updates.

The results are as follows. I will update this list as more test data becomes available.

Model Video 1 Video 2 Lag (Frames)
IIe Composite -> IIc Monitor (Composite) AIIE 80COL64K MEMORY EXPANSION AND VIDEO -> Sony PVM-9045QM Monitor (Composite) 0
IIe Composite -> IIc Monitor (Composite) AIIE 80COL64K MEMORY EXPANSION AND VIDEO -> Sony Portable CD/DVD Player DVP-FX720 (Composite) 0.5
IIe Composite -> IIc Monitor (Composite) AIIE 80COL64K MEMORY EXPANSION AND VIDEO -> Dell U2410 Monitor (Composite) 3
IIc Composite -> IIc Monitor (Composite) Apple IIc Video Expansion -> PAL Modulator Adapter -> Sony PVM-9045QM Monitor (Composite) 0
IIc Composite -> IIc Monitor (Composite) Apple IIc Video Expansion -> BeagleBoneBlackHDMI -> Dell U2410 Monitor (HDMI) 2
IIc Composite -> IIc Monitor (Composite) Apple IIc Video Expansion -> A2 Video Streamer -> PC Laptop Inbuilt Monitor (USB) 2.5
IIGS Composite -> IIc Monitor (Composite) Video Overlay Card -> Sony PVM-9045QM Monitor (RGB) -0.5 to 0
IIGS Composite -> IIc Monitor (Composite) Video Overlay Card -> Sony PVM-9045QM Monitor (Composite) -0.5 to 0
IIGS Composite -> IIc Monitor (Composite) IIGS RGB -> IIGS Monitor (Analog RGB) 0
IIGS Composite -> IIc Monitor (Composite) VidHD -> DELL P2719H Monitor (HDMI) 1
IIGS Composite -> IIc Monitor (Composite) VidHD -> HP P242va Monitor (HDMI) 1
IIGS Composite -> IIc Monitor (Composite) IIGS RGB -> GBS-8200 -> Samsung SyncMaster 740N (VGA) 1
IIGS Composite -> IIc Monitor (Composite) VidHD -> DELL 2407WFPb Monitor (HDMI) 1.5
IIGS Composite -> IIc Monitor (Composite) VidHD -> Dell U2410 Monitor (HDMI) 1.5
IIGS Composite -> IIc Monitor (Composite) IIGS RGB -> GBS-8200 -> Dell U2410 Monitor (VGA) 2.5
IIGS Composite -> IIc Monitor (Composite) IIGS RGB -> GBS-8200 -> VGA to HDMI transcoder -> Dell U2410 Monitor (HDMI) 2.5
IIGS Composite -> IIc Monitor (Composite) IIGS RGB -> Dell U2410 Monitor (Component) 3

The frame counter disk image can be found here.

Friday, August 14, 2020

Game Controller - H.A.L. Labs Gizmo - Cloning the Cloner

In 1981 H.A.L. Labs released Taxman, a direct Pac-Man clone on the Apple II. Atari was not happy since they held the rights to Pac-Man so they asked H.A.L. Labs to stop selling the software. Atari took Taxman, changed the title and then went on to release the game as their own official Pac-Man for the Apple II platform. Not to be outdone, Taxman's developers re-created the game but this time they made sure that there were enough differences to keep it away from Atari's clutches. It was called Super Taxman 2 and in terms of game play, it was a big improvement. The ghost characters no longer looked like ghosts. The maze layouts were different. However, the running speed and the ghost artificial intelligence made it feel more like a real Pac-Man game.

In their pursuit of performance, the developers became frustrated with the slow speed of the Apple II's analog joystick. In response they created their own joystick solution. They built the Gizmo, which is an adaptor that allows you to use digital joysticks on the Apple II so long as the software is coded to detect the special hardware. In Super Taxman 2 there is no support to play using the Apple II Joystick. It's either the keyboard or the Gizmo. Some levels are so fast it's barely controllable. Try level 88 and you'll wonder if you are playing on a standard Apple II or if you're running via an accelerator.

It was the Gizmo adaptor which interested me the most. This adaptor allows a single digital joystick to be connected to the Apple II and be able to control specific software titles. I could only find two titles which have been adapted to use the Gizmo, Super Taxman 2 and Vindicator (a Robotron clone) also released by H.A.L. Labs. I was unable to locate any information on the construction of the Gizmo so I headed in the only direction I had available to me and that was to reverse engineer the hardware from the software. My investigation led me to conclude that the Gizmo works in a similar way to the Atari Joyport ( which is also an adaptor that allows digital joysticks to be used with the Apple II. However instead of multiplexing the Apple II game port's annunciator output onto three of the push button lines the Gizmo multiplexes the game port's three annunciator outputs onto a single push button line.

To test my assumptions, I put together a board and luckily it worked first go. Here is the schematic for the Gizmo and the truth table used by the software. I'm sure that H.A.L. Labs being in the business of cloning (not all their software titles mind you) are not going to pursue me for recreating their hardware. If the hardware had taken off then doing this back in the day may have been a different story.

If you fancy getting that high speed digital joystick experience without having to go through the pain of creating an adaptor for just two software titles then you will find that I have modified the games to work with the 4play card ( Since the Gizmo only supports one trigger button it's a pain to play the game Vindicator. This game contains two fire actions (one for shooting and one for the screen bomb). Having to use the keyboard to access the screen bomb annoyed me greatly so in the 4play conversion the screen bomb is mapped to the second trigger button. This makes playing the game much more enjoyable.

Tuesday, August 21, 2018

Apple II 4joy - Serial interfacing through the game port

The Apple II 4Joy is an adapter that lets you connect four digital joysticks to the Apple II via the game port.

In my last blog I looked at running a digital joystick interface via the IIc's serial port. Technically I wasn't correct in saying that the serial interface is the only available option for communication on the IIc. Obviously there are other options such as the floppy disk interface, the keyboard interface and the game port interface but these are most likely already being used for dedicated functions. The game port however can be used for general communications but it's only unidirectional. In our case this is enough to get by on. I evaluated a few methods of communicating using this interface.

Method 1: The first method I looked into involved transferring a byte of information by generating a resistive circuit that mimics an Apple II paddle / joystick axis. This could be done by outputting eight digital lines from the microcontroller and switching parts of a resistive ladder to form the zero to 150k ohm resistance range needed by the Apple II. Alternately an extra chip such as the AD5206 could be used to generate the resistance. This method would require multitasking to put through four digital joystick status bytes over the IIc's only two paddle lines and each Apple II would need to be tuned because the game port's analog circuit contains discrete components that vary slightly from one machine to another. The other factor is that reading analog values via the Apple IIs games port is very slow. Even if the format is modified to be limited to a low analog value I estimate it would still take about 2000 microseconds to read, process and store the four joystick status values. This method is not preferred for serial data communications.

Method 2: This method involves running digital signals though the analog paddle lines. Each analog port would be reduced to a value of zero ("False") and non-zero ("True"). Reading an analog value from the paddle port takes about 4 microseconds if the value is zero all the way up to about 3000 microseconds if the value is 255. If the data is digital then we can read the port after 4 microseconds and get an answer straight away. This translates into a transfer rate of about 200 microseconds per byte instead of up to 3000. Most Apple IIs have four paddle lines (PDL0, PLD1, PDL2 and PLD3) so we could send though a nibble of data at a time (this is not as great as it sounds because you still need to read each bit at a time). The push button lines could be used to handle the synchronisation. The software would require some overheads in putting the two nibbles and the format back together but this would be straight forward. The hardware would require something like a 4066 chip to switch each analog port from 0k resistance to about 1.5k or greater. This should result in enough time to read all four analog ports and determine if each is "True" or "False". The IIc however does not have PDL2 and PLC3 lines. These were removed to make way for the mouse interface. Instead these lines are TTL compatible digital input lines (XDIR and YDIR). We don't need to change our method by much because we are already dealing with digital signals. The only change needed would be to add a toggle switch which allows the microcontroller to connect to XDIR and YDIR directly on the IIc or to the 4066 chip for non-IIc Apples. The result of all this would be to have all four joystick status bytes sent over in about 1000 microseconds. This is not a bad solution but can we do better? 

Method 3: The last method I looked at was to send a serial stream of bits though the game port's push button lines. One push button would be used for data and the other would be used for synchronisation. It's unlikely that the microcontroller's clock rate will be a direct multiple of the Apple II's clock rate so synchronisation needs to happen quite often, possible once every byte. A byte could be sent through in under 100 microseconds. The software would be relatively simple (simpler than the above methods). The routine to do the synchronisation, data transfer, processing and storage would not be as compact as running data through the serial port but should result in a much faster transfer rate. With this setup the hardware becomes simple too. Only the microcontroller is needed and a few discrete components. The result of all this is being able to transfer the four joystick status bytes in around 500 microseconds.

Once I looked at method three it was clear that this was going to be the best option to tackle. A good amount of the work was already done in the serial port project so I reused as much as I could. In terms of hardware the TTL to RS232 converter was removed and in its place I added a small breadboard with the DE9 pin plug, some discrete components and some headers for testing. This project was all about getting the software right which meant timing was critical and counting cycles on the Apple II as well as the microcontroller was needed.

Showing microcontroller output is too fast and then after delays have been added.

The first step was to write the fastest read loop on the Apple II. After obtaining a few pointers from Michael's NadaNet project, I was able to nut this out. This was going to be the bottle neck since the microcontroller was capable of outputting data much quicker than the Apple II could read it. The microcontroller code was written to stream a sync signal followed by an eight bit byte for each joystick. The dilemma now was how to view what the microcontroller was outputting and compare that to when the Apple II was expecting a read. The timing was sub-microsecond critical and the Apple II was reading (inputting) signals and not outputting them. The easiest thing to do was to move the development from the Apple IIc over to the Apple IIe. What this allowed me to do was to take a copy of the code, change the read instructions into write instructions but at the same time keep the cycle timing the same. These write instructions were then sent to the IIe's 16pin game port output (annunciator) pin. By adding this output to the logic analyser I was able so see exactly when the Apple II was going to be performing a read operation. I could then tune the microcontroller outputs to match the requirements of the Apple II.

Since the joystick number was going to be extracted from the data (just like in the serial port version) there was no need to synchronise starting at a specific byte. So long as four bytes were read in a row it did not matter which joystick status byte was read first.

In tuning the interface there were several critical points to get right:

1. Apple II read pulse length.

To get the microcontroller to match the Apple II, read pulse lengths measurements from the logic analyser were used and delays were added in the appropriate places. The faster the microcontroller can be run the more resolution is available to match the Apple II. Since one speed is not a subset of the other then the best we can ever do is an approximation.

2. Sync pulse length.

The Apple II code that checks for the sync pulse is seven cycles long. Therefore the sync pulse length needs to be at least seven cycles long but less than twice that.

3. Time between bytes.

Once the Apple II has read a byte of data the microcontroller needs to pause for while until the Apple II catches up with processing and storing that data. For this project that amount was roughly forty five microseconds.

We can see from the above screen shot that if the sync pulse is too short or if the delay between bytes is too short then a gap is generated between the joystick status bytes. This condition would be too short to affect any game play but it is undesirable and easy to eliminate by performing more tuning.

4. Time between the start of sync and the start of first read.

These screen shots show how much the time between the start of the sync pulse and the start of the read pulse can vary.

The last critical point was to fine tune the time between the start of the sync pulse and the start of the first read. This is where all the fun began. This start time variance is determined by the length of the sync check.

The sync check takes seven cycles to execute and looks like this

LOOP CPX $C061 - 4 cycles
   BCS LOOP - 3 cycles on jump

however the initial read loop takes six cycles and looks like this

   CPX $C062 - 4 cycles
   ROL - 2 cycles

Therefore the read pulse is going to be shorter than the variance of the start time. In other words this is not going to work. The read pulse needed to be extended. The longer the read pulse is, the less significant the start time variance becomes but also at the same time this slows down communications. By adding just one extra delay into the read loop it takes the cycle count to eight which is larger than the sync check.

Even though the sync check pulse is now less than the read pulse when you take into account that the microprocessor timings are not directly linked to the Apple II clock, this becomes our border line condition. I can get communications working at this speed but it's not stable. It can be tuned to a given computer but the aim is to have the device working on any Apple II computer. This translates into a communication rate of around 80kbps. This includes reading the data, processing the data (extracting the joystick number) and storing the data.

Testing for stability was quite easy to do. The microcontroller was setup to transmit a specific byte. The Apple II side was setup to read this byte and if it was different from what was expected then a counter was incremented. As the timing was adjusted on the microcontroller you could see the rate at which the counter was ticking over slowed down until it stopped counting. It had reached stability.

To make the interface stable I ended up expanding the read loop, not by adding an extra NOP instruction but by making the read routine into a loop (instead of just having the same read code duplicated for every bit). This resulted in a read pulse of eleven cycles but it makes the code a lot shorter. A good compromise in my book. This translates into a communication rate of around 60kbps which is still six times faster than reading analog data or several times faster than what I was able to achieve through the serial port. For processing joystick data it is still an overkill.

At first I thought that running communications over the two game port push button lines would be the perfect solution especially in making a device that would work on all models of the Apple II. Well it didn't turn out as straight forward as I had hoped. These were the issues:-

1. Apple added filtering capacitors to the Apple IIe platinum model so I suspect the 4Joy in its current setup will not work on this machine. Without removing the filtering capacitors the only option would be to slow down the communication rate. I don't have one of these models to test on.

2. I've had mixed results trying to get these high speed communications going over the push button lines on the Apple IIc. Sometimes it works but then other times it does not. I suspect this is to do with the resistor pack on the IIc's game port interface. I tried replacing the general signal diodes with ones that have a lower breakdown voltage however this made the timings worse. On the IIc I found that diverting the communications from the PB0/PB1 pins over to the XDIR/YDIR pins bypasses the resistor pack and makes the interface work very well (similar to my tests on a IIe and a IIgs). The other option would be to slow down the communication speed.

3. The game port push button pins (PB0 and PB1) on some Apple II models are tied into the reboot function and the self-diagnostic function. Since the sync pulse on time is much less then the data on time I swapped my PB0 with PB1 signals so that the probability of starting the self-diagnostic function on a control-reset is very low. It does happen occasionally but I get around this by doing a second control-reset. However this means that the probability of getting a reboot from doing a control-reset is quite high. I prefer it to be this way around than the reverse.

The next phase will be to add USB support and combine it with the "Bluetooth Game Port Receiver". With a flick of a switch it should be possible to swap from being a single USB/Bluetooth analog joystick receiver to a multi USB/Bluetooth digital joystick solution.

All the project files are contained here.

Wednesday, July 4, 2018

Apple II 4serjoy - Gaming through the serial port

The 4Serjoy is a device that allows you to connect four digital joysticks to an Apple II computer using a serial port.

With the release of the 4Play card, the Apple II models now have a great option for multiplayer gaming using digital joysticks. But what about the poor ole Apple IIc, the slotless Apple II? Having a slotless Apple II is like having your arms and legs chopped off. It really limits the expandability of the machine. Any interaction with external devices is reduced to what you can put through the serial ports. Some IIc motherboard revisions allow special expansion cards but I'm talking about compatibility on all IIc systems. Not only did the IIc have to contend with not having any of the standard Apple II expansion slots but existing functionality, that a hacker would come to expect, was removed in the name of compactness. This includes the 16pin game port (which was more than just a dual analog joystick port) and the second joystick port which made way for the mouse interface.

So what options could there be for multiplayer joystick control on the IIc? Well, like I said, the interface is limited to the serial ports. I wondered how well games would perform if having the joystick control flow through this interface. Would it even be feasible to begin with? I did some rough calculations. The maximum time for the Apple II's analog paddle read to reach stability is just under three milliseconds and all the paddle/joystick reads are in parallel so that's still three milliseconds. Now for the serial port solution. At 9600 baud in a typical N81 setup, 8 data bits, 1 start bit and 1 stop bit results in a transfer rate of about 960 bytes per second or one byte every millisecond. Four joystick bytes should work out to four milliseconds. A baud rate of 19200 should yield a time of about two milliseconds for four joysticks bytes. The serial times seem like they are on par with the analog circuits. Therefore if the overheads are small I figured that this was certainly possible. That was enough for me to proceeded with the challenge. 

The hardware comprises of an ATmega1284P microcontroller, a breakout board and a "Serial TTL to Serial RS232" converter. For the software I started off by using an existing 4Play modified multiplayer game. Using an already converted 4Play game saved me time because the analog joystick/ keyboard handler to digital control was already done. I didn't have any four player games so the closest I could find was Mario Bros which is a two player game. The microcontroller can handle reading four joysticks but only two are currently hooked up. I threw together a simple assembly program to test the serial stream.

The way this device works is that it uses the microcontroller to read the digital signals from four joysticks (four direction positions and two fire buttons per joystick). This information is encoded into four bytes that is similar to the 4Play protocol. The four least significant bits are kept the same (direction signals), the two most significant bits are kept the same (two fire buttons) and the remaining two bits now encode the joystick number instead of the 4Play card identifier (bits 00: joystick 1, 01: joystick 2, 10: joystick 3 and 11:joystick 4). These four joystick status bytes are continually streamed to the Apple II via the serial port. Software running on the Apple II reads these values and replaces the existing direction commands that came from the game port / keyboard with the new digital signals.

The biggest issue with this setup is the need to modify the original software. The software needs to be modified to read the serial port instead of the game port or keyboard. This is a lot more work than modifying software to handle the 4Play card. Unlike the 4Play card which uses up less code then the original software (when hard coding the card's slot location ie not using the 4Play identification bits) the 4Serjoy needs to find space for 1. Serial port initiation (roughly 15 bytes), 2. Routine to read the serial port and store the joystick status bytes (roughly 25 bytes), 3. Storage of the joystick status bytes (4 bytes), 4. Call to the serial processing routine (roughly 20 bytes because there are multiple calls per loop) and then 5. As per the 4Play card you need to change the existing joystick/keyboard handler to use digital signals.

Apart form the usual great tools that I use to put together a project like this, having Hex Ray (a part of Nick's Virtu Apple II emulator) was a life saver. It allowed me to work out which parts of the Apple II memory were free to add in all the extra code that I needed for this game. Mario Bros is a resource hungry game so it wasn't easy to find available space.

Within the Mario Bros game there is a loop in which the joystick/keyboard handler gets called. When adding in the new call for the "check serial port" routine I found that every now and again the trigger button would not register. This seemed reasonable because there are four joystick status bytes to transport and checking one byte each loop means that a single joystick will only be read once every four loops. I added a second call to the loop however this did nothing to fix the trigger button issue. The problem was that the calls were too close to each other. By placing multiple calls within the loop and placing them further apart made all the difference. This means that joysticks 1 and 2 are being read every odd time through the loop and joysticks 3 and 4 every even time. This produced the game play that I was expecting.

My first lot of testing was using the default baud rate of 9600 but I wanted to know how the buad rate affected signal lag so I setup the system with baud rates 19200, 9600, 4800, 2400, 1200, 600 and 300. I had a preconceived idea that the game would not work below 9600 but I found that having baud rates between 19200 and 1200 did not change the game play enough for me to notice a difference. Maybe on a different game the lag would be more noticeable at the lower rates. Mario Bros is more of your "get the timing right" then a "test your reflexes" type of game. However the lag was obvious once 600 baud was used and 300 baud was even worse. What surprised me the most was that the lag was pretty bad at 300 baud but the game was still relatively playable. Using this baud rate I still managed to complete the first five levels without a problem. I could have continued playing the game further but the lag was annoying the crap out of me. This shows that the positioning of the code to read the serial port within the game loop is far more critical then the baud rate.

I built this device to full-fill the problem for the IIc but it will work just as well on an Apple II/II+/IIe (with a serial card) and the IIgs.

There are a few small changes I would need to make if I was to get this product up and running. These includes adding in the resistors to make it compatible with the Sega Genesis (Maga Drive) / Amiga CD32 type controllers and turning off the JTAG fuse on the microcontroller to free up port C which would then allow the connection with four joysticks instead of two.

Even though I don't see much of a demand for this device it answered a few of my questions and with surprising results. However on the rare chance that a landslide of multiplayer games becomes available for the Apple II then I know I'll be ready to go.

All the project files are contained here.