Added documentation on the VMPH and adapter

README.md

@@ -22,4 +22,4 @@ The VideoMacPacHack (like the original Video Mac Pac) requires its associated co
 
 The Video Mac Pac was created by Computer Care Inc. in 1991, apparently based on the Lapis DisplayServer.
 
-The VideoMacPacHack was designed by [Andrew McPherson](https://github.com/apmcpherson) and [Tom Stepleton](https://github.com/stepleton). In the interest of historical preservation it is released into the public domain, with no warranty of any sort.
+The VideoMacPacHack was designed by [Andrew McPherson](https://github.com/apmcpherson) with encouragement from [Tom Stepleton](https://github.com/stepleton) based on hardware in his collection. In the interest of historical preservation it is released into the public domain, with no warranty of any sort.

documentation/clone.md

@@ -0,0 +1,58 @@
+# VideoMacPacHack
+
+The following are implementation notes on cloning the Video Mac Pac PDS expansion card. The schematic and board layout can be found in the `hardware/VideoMacPac/` directory in this respository.
+
+## Schematic
+
+The schematic of the VideoMacPacHack conforms as closely as possible to the original VMP, with a few exceptions:
+
+### Address decoder
+
+On the VMP, a `GAL16V8` implements a relatively straightforward address decoder with 10 inputs (9 address lines plus an active sense signal) and 1 output (to the CPLD `WRT` pin). To avoid the need to recreate this custom IC, standard logic can be used instead. The basis of the current design is a `74F521` 8-bit address decoder. In addition to its 8 logic inputs, it has a 9th `OE/` input which can be used for one additional bit of decoding. 
+
+However, one further bit is still required to replicate the functionality of the GAL. Because board space does not allow another DIP IC, a single-gate SMT IC is used instead: `74AHCT1G00`, a single 2-input NAND gate.
+
+### Power switch
+
+Miniature relays have been supplanted by analog power switch ICs. This design uses a `TPS2030` IC to achieve the same effect as the original relay. A DIP package is used in the VMPH design. However, SMT versions of the part appear to be more widely available and can be used with a DIP-SMT adapter.
+
+### 74F244
+
+This is a place where the original design should not be changed.
+
+Initial experiments exchanged the `74F244` buffer IC for a nearly-equivalent `74HC244`. However, we found that the longer and more variable propagation delay on the `74HC244` caused vertical edges to show colour tints, as the edges on the three video channels were no longer aligned (the R, G and B lines have separate logic signals from the CPLD). The original 74F244 does not exhibit this problem.
+
+## PCB Layout
+
+The mechanical layout of the PCB follows the original VideoMacPac design, which is in turn based on Apple’s specifications in the Guide to the Macintosh Family Hardware. The component layout is broadly similar to the original.
+
+The PCB is a 4-layer design, like the original VMP. The trace routing is electrically identical but does not follow the same geometry as the original. The original VideoMacPac design largely avoids vias, with traces crossing layers at existing through-hole pads. The VMPH alternative routing was done relatively quickly and has not sought to optimise the layout in this way.
+
+The VMPH design attempts to use through-hole parts wherever possible. It was necessary to make a single exception for space reasons: U3 (`74AHCT1G00`), a single NAND gate which is used to provide one extra input to the address decoder in U2.
+
+On the other hand, the video adapter dongle is made with SMT ICs and passives for compactness.
+
+## Notes on Bill of Materials 
+
+The VideoMacPacHack requires the following historical parts, which can sometimes be found as new old stock:
+
+* 1x `XC2018-100-PC84` (84-pin PLCC): Xilinx CPLD
+* 4x `MT42C4064Z-12` (24-pin ZIP): VRAM
+* 5V 4-pin oscillator cans: 36MHz, 50.35MHz, 57.2832MHz (see below)
+
+### CPLD
+
+A `XC2018-70` was used in place of the `XC2018-100` with no adverse effects.
+
+### VRAM and resistor networks
+
+A `MT42C4064Z-10` was used in place of the `MT42C4064Z-12` in prototypes with no adverse effects.
+
+The VRAM connects to the PDS data lines, but most signals go to the CPLD by way of 47 ohm resistors. On the VMP, 4 SIP resistor networks are used: two with 4 elements, two with 3 elements. If 3-element resistor networks are hard to find, 4-element versions can be used in those slots with the two pins on the end cut off.
+
+### Oscillators
+
+5V DIP oscillator cans are no longer available in as many frequencies as they once were. New old stock may need to be found for these frequencies. In most cases, similar but non-identical frequencies can be used with the effect of changing the refresh rate of the resolution. Driving a modern LCD monitor this would likely not be a problem. 
+
+There appear to be limits to how far the frequencies can be stretched: for example, putting a 50MHz crystal in place of the 36MHz crystal produces no output at the affected resolutions.
+

documentation/hardware.md

@@ -37,7 +37,7 @@ For comparison, the Lapis DisplayServer-SE is also based on the XC2018. The SE-D
 
 ## VRAM
 
-The VMP uses four Micron `MT42C4064Z-10` 64kx4 VRAM ICs. These are in a 24-pin ZIP package (i.e. SIP with staggered leads). Each VRAM chip handles 4 bits of a 16-bit data word. 
+The VMP uses four Micron `MT42C4064Z-12` 64kx4 VRAM ICs. These are in a 24-pin ZIP package (i.e. SIP with staggered leads). Each VRAM chip handles 4 bits of a 16-bit data word. 
 
 The CPLD maps the VRAM to the memory address space from `$720000` to `$73FFFF` (128k bytes in total).
 

documentation/video_adapter.md

@@ -0,0 +1,47 @@
+# Video Adapter Dongle
+
+An adapter board is necessary to connect from the DB25 male on the back of the Portable to the monitor. The original dongle for the Video Mac Pac was lost, so this reconstruction is based on its apparent principles of operation and almost certain differs substantially from the original.
+
+See the `hardware/VGA_adapter/` directory in this repository for the schematic and board layout of the adapter. 
+
+## Detection Circuit
+
+Connecting pins 14 and 15 on the DB25 (pins 2 and 4 on the 20-pin IDC) holds the sense line high and signals the presence of the dongle. 
+
+In the schematic, a 100 ohm resistor is used between these as a precaution in case of incorrect insertion of the dongle, but this could probably be replaced with a simple short.
+
+## Oscillator Power
+
+Connecting pins 1 and 14 on the DB25 (pins 1 and 2 on the 20-pin IDC) provides +5V power to the oscillators which are needed to generate the video pixel clock.
+
+## Buffering and Level Shifting
+
+All signals from the card are 5V TTL. VGA signals need to be 0.7V or 1.0V maximum, depending on the standard. Level shifting is therefore required for the video signals. 
+
+The sync signals remain at TTL levels and are passed through unchanged to the VGA connector.
+
+### 3.3V regulator
+
+While a simple voltage divider could reduce the 5V TTL video signal to the correct level, we find that the 5V line on the Portable fluctuates under load, which results in brightness variations and sometimes noise on the picture.
+
+Instead, a 3.3V regulator is used to generate a stable reference voltage for the video signals. Each of the three video signals is buffered by a `74LVC245` level shifter, which produces 3.3V outputs. These are in turn divided down by a resistive voltage divider to meet VGA level and impedance requirements.
+
+### Impedance
+
+VGA expects a signal of up to 0.7V (1.0V in some variations), and an impedance of 75 ohms. The `74LVC245` has a rated output impedance of 15 ohms per buffer. We therefore use 133 ohms in series (closest available value to 135 ohms) and 150 ohms in parallel to produce a raw (unloaded) output of 3.3V/2 = 1.65V, with a source impedance of 150/2 = 75 ohms. When the monitor is connected, the 75 ohm load impedance reduces the video signal to 1.65V/2 = .825V.
+
+For comparison: examining the video adapters for the Lapis DisplayServer cards shows that they used 150 ohms in series and 150 ohms in parallel from a 5V source to generate the video signal.
+
+### Alternative approach
+
+Three separate logic signals are used for the R, G, and B lines, which ultimately derive from three different pins on the CPLD. Slight timing shifts between the pins result in messy vertical edges in the image, with colour tints to the left or right of the line. 
+
+In our later investigations, we found that the `74HC244` had too long and too variable a propagation delay and created noticeable clarity problems. The `74F244`, used on the original VideoMacPac design, does not show this problem. However, since the image is monochrome anyway, a relatively foolproof alternative is to drive all three buffers on the 74LVC245 with the same video signal.
+
+## PCB Design
+
+A 2-layer PCB was used with surface mount ICs and resistors for compactness. The DB25 and VGA connectors are on opposite ends of the board. 
+
+The board could be enclosed in a plastic housing, or a version could be developed that goes directly from the 20-pin IDC to a VGA port. If this adapter were connected all the time, a switch could be used to toggle the sensing function that activates the card.
+
+