
  The HPUSB firmware for the HP21xx USB disk adapter
  ==================================================
  Version 0.41 - November 23, 2010


This program provides the logic needed to connect a vintage HP minicomputer
(or any other machine that provides the necessary control signals) to a
VDRIVE USB disk adapter for reading and writing files. Files can be opened
and closed using a manual switch / LCD interface, using a serial terminal,
or by sending commands from the HP minicomputer. A single read file and a
single write file can be open at the same time. 1K byte buffers are used to
avoid excessive access of the VDRIVE. When the read buffer is empty the next
block is loaded from the read file. When a read file is open, the pointer
is set to the beginning of the file. Each read request returns the next
byte from the file. When a write file is opened an empty write buffer is
set up, each write adds to the buffer. When the write buffer is full or if
about one second goes by with no activity, the data in the buffer is
appended to the write file. To overwrite a file the existing file must
be deleted first using a VDRIVE command. Full access to the VDRIVE module
is provided to permit implementing more complex disk commands.


Hardware details
----------------

The HPUSB software is designed for a PIC18F2525 processor connected as
shown in the schematic diagrams...

usbadapter3_processor.jpg - the PIC, switches, LED's and VDRIVE interface
usbadapter3_inputoutput.jpg - interfacing to the HP's main and punch ports
2-wire_lcd.jpg - Myke Predko's 2-wire LCD interface, redrawn with notes

Electronics skill is required to source the parts and successfully wire
the adapter, this is not a "turn-key" project as presented. HP machines
vary so the circuitry (and possibly the firmware) may need tweaking to be
compatible. The SPI buss runs at 8mhz and requires about 20nS timing
accuracy to avoid errors, be careful wiring those lines - avoid wiring
parallel with other data lines and keep the lines as short as possible.
I used perfboard and lots of solid-core "telephone" wire...

usbadapter_parts.jpg - top side
usbadapter_wiring.jpg - wiring side 

There are a few differences between the prototype and the schematics,
I used a total of 6 resistor packs rather than the 5 shown, some sections
were not used but permitted placing a resistor pack next to each ULN2003
chip to simplify the wiring. The arrangement of the ULN2003 sections is
different in the prototype - the first two chips were used for output
bits 15-2 with bits 0 and 1 and both flag outs on the third chip.
220 ohm resistors were used in series with the SEL SDO SDI and SCK lines
rather than the 150 ohm resistors shown in the schematic but I recommend
using 150 ohms - I went higher to test for margin and 150 ohms should be
enough to limit voltage difference currents and protect the IC pins if
the PIC is misprogrammed. I used 470 ohms in series with the RST line but
that's unnecessary. I used 180 ohms in series with the VDRIVE data out line,
but the 150 ohm resistor shown on the schematic is probably better.

Here's the pinouts I'm using for the connectors...

Wiring side, or looking at the holes in the mating connectors
G = ground  C = HP command out  F = HP flag in

PUNCH connector...        MAIN connector...

         from HP outs      ----to HP ins----     ---from HP outs--
 G   F       7 5 3 1       0 2 4 6 8 101214F G    151311 9 7 5 3 1
 O O O O O O O O O O       O O O O O O O O O O   O O O O O O O O O
 O O O O O O O O O O       O O O O O O O O O O O O O O O O O O O O
 G G C       6 4 2 0       1 3 5 7 9 111315  G G C141210 8 6 4 2 0

"+16B DUP REG" HP 12554 12V interface connector pinout, looking at
the back of the machine or the wiring side of the connector...

 ------------- inputs ----------------------------------------------
 0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15                    F  G
 O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O
 O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O
 0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15                    C  G
 ------------- outputs ---------------------------------------------

The "microcircuit" 5 volt HP 12566 interface is different...

 ------------- inputs ----------------------------------------------
 0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15                 C  F  G
 O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O
 O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O  O
 0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15                 C  F  G
 ------------- outputs ---------------------------------------------

Refer to the 12554 and 12566 docs for more info, the 12554 doc is available
at the HP Computer Museum (search for it) the 12566 doc is on BitSavers in
the pdf/hp/21xx/interfaces directory.

My 12 volt HP 12597 "+8B" punch board has a pinout similar to the 12554 board
except there are only 8 inputs and outputs, and has extra pins for functions
probably related to status. For punching I only connected the 8 HP outputs,
command and flag. HP input bit 5 is used to indicate out-of-tape, must be
logically low - for a ground-true board like mine leave disconnected.
For a ground-false board probably need to ground all 8 HP inputs.


Firmware usage
--------------

On startup or exit from the bootloader, the firmware quickly cycles the data 
LED's once to indicate correct operation of the SPI buss. If a serial terminal 
is connected (9600 baud) and the debug menu is enabled in the stored setup, a 
debug menu is displayed that can be used to test various hardware functions...

Debug menu
==========

Main polarity: inverted         Punch polarity: normal
Main control:  cmd/flag flipped Punch control:  same polarity
Main command:  clear            Punch command:  clear
Main data in:  1111111111111111 Punch data in:  00000000
A) VDRIVE prompt
B) Clock and redisplay
C) Flip main polarity
D) Flip punch polarity
E) Save polarity setup
F) Set main port output
G) Set data LEDs
H) Change main control setup
I) Change punch control setup
Esc) resume startup
Select: 

Initial polarity setup can be performed using this menu, or done using the
LCD setup screens. The debug menu provides the option to change the setup
temporarily without saving to eeprom.

Before use, the adapter must be set to match the HP adapter card being
used, for both the main port and the punch port, the adapter firmware needs
to know if the data from and to the card needs to be inverted, and if the
command and/or flag lines are inverted with respect to the data lines.

Note - for the main port both the input and output data must be the same
polarity, there is no provision to invert input or output separately (as far
as I know there is no need to but if such a case is discovered let me know).
Also note that the main/punch polarity selection inverts the control lines
too, the control settings specify if the control polarities are different
with respect to the data polarity.

Note - if not using the punch port, it needs to be set to normal polarity
with normal control lines.

For my "+16B DUP REG" board I need to select inverted polarity with normal
control. For my "microcircuit" board I need inverted polarity with control and
flag lines both inverted (i.e. data is inverted but control signals are not).

After exiting the debug menu or on startup if the debug menu is disabled, the 
firmware version and the text "D for setup" appear on the LCD for about 1 
second, to enter setup mode press switch D quickly and hold it until "Setup 
polarity" appears on the LCD. Setup options are main port polarity, punch port 
polarity, data LED functions, enable/disable debug menu, main control lines,
punch control lines, command delay and flag speed. For each setup option,
press the A switch to change the data, press the B switch to confirm and
continue to the next item.

The LED setup determines if data LED's respond to commands, read data and/or
write data, all 8 combinations can be cycled by pressing the A switch. 

The command delay setup option inserts a delay in the main loop before
checking for the next command. This may be needed for line settling, and
is required for compatibility with older versions VDOS and UDOS, especially
if using with IRQ's enabled. Versions of VDOS before 11/17/10 have a bug
that causes issues with more than about 100 files in a directory, upgrade or
use the patch presently at: http://newton.freehostia.com/hp/fixvdos.ipl.txt

The flag speed setting may be needed under some conditions, the long setting
pulses for about 1.2uS, the long setting pulses for about 1.7uS. Both settings
work OK on my machine. If needed the controller code can be modified to adjust
the delay factors.

Setup can also be entered by pressing the D switch  if it gets hung up
waiting for the HP command lines to clear.

After exiting the setup, or on startup if D wasn't pressed, the firmware 
checks the states of the main and punch command lines. If either line is 
logically true then the LCD displays "Waiting on HP", usually this means one 
of the port polarities is incorrect, or the HP is not turned on with an 
inverted interface. If the HP is on while displaying the waiting message, 
press Preset button on the HP, if that doesn't do it then press D to reenter 
setup and correct the polarity.

When the command lines are logically clear the unit should briefly display 
"Syncing VDRIVE" then display "SF HPBOOT" as it checks the disk in the VDRIVE 
for a file named "HPBOOT", if found it is attached as the read file, otherwise 
the unit starts up with no files attached and the "error" LED lit  The HPBOOT 
file should be an ABS-format binary containing the default boot system, after 
a normal startup the HP's bootloader can be operated to load the file - on a 
HP2113 this is accomplished by selecting the S register, setting bits 11-6 to 
the disk adapter interface slot address, then pressing Store then Preset IBL 
Preset Run. LED's should flicker while loading, after a successful load the 
LED's on the HP for bits 0-5 should be all lit to indicate a successful load. 
Select the P register, Clear and set bit 1 for address 2, then press Store 
Preset Run to run the application. The exact details vary somewhat for other 
HP21xx minicomputers, refer to the documentation for the standard papertape 
load proceedure. Core machines such as the HP2114 use a memory-resident 
bootloader with a hard-coded slot address, which must match the slot for the 
I/O card connected to the disk adapter.

Important - some configurations require resetting the adapter after
turning on the HP if the adapter is already powered, especially boards with
active-high command lines.

Once set up and with no serial terminal attached, the above steps all execute 
in a couple of seconds after powerup or a reset with no interaction required, 
then the unit enters normal run mode. The LCD displays the current file 
attachments following the "RF:" (read file) and "WF:" (write file) labels. 
Normal "errors" such as EOF or a file wasn't found are shown as numbers in the 
last column. These include 2 for command failed (usually file not found), 5 
for disk full, 6 for input file not open, 7 for output file not open, 8 for 
end of file and 9 for zero size (usually an attempt to open a directory as a 
file). More serious errors preempt the normal LCD display and are spelled out, 
these are "No disk" (code 1), "Bad filename" (code 2, invalid characters in a 
filename), "IntFile open" (code 3, an internal file is open on the VDRIVE, 
should never happen unless something abnormal occurs like resetting the unit 
while writing data), and "Unknown error" (code 255, something went wrong that 
I didn't bother parsing in the firmware or the firmware couldn't make sense 
of). The fast way to clear an error condition blocking the display is to press 
the reset button.

The status LED's are assigned as follows...

Port C bit 0 - "Ready" - lights when the unit is waiting for a disk command
Port C bit 1 - "Busy" - lights when not monitoring for disk commands
Port B bit 0 - "Serial" - lights when the serial port is active
Port B bit 1 - "Read open" - lights when a read file is open
Port B bit 2 - "Write open" - lights when a write file is open
Port B bit 3 - "Processing" - lights when processing a disk command
Port B bit 4 - "Error" - lights if the global error variable isn't zero

In run mode (when Ready is lit), the switches operate as follows...

Switch A - manual attach mode with the read file cleared
Switch B - manual attach mode with the write file cleared
Switch C - refresh the LCD to show an error condition
Switch D - run a serial file menu if a serial terminal is attached

In manual attach mode, press the A and B switches to select single-letter 
files, or none. Press switch C to confirm the selection and open/close the 
files if the filenames have been changed. Press switch D to abandon the 
changes and return to run mode with the previous file setup. If a newly 
selected write file exists after confirming the selection, the LCD prints 
"File x exists" "C to overwrite" where x = the letter file selected. Press the 
C switch to delete the file to write new data, or any other with to append to 
the file (which does not alter the file unless data is actually written). If
a write file is closed immediately after confirming overwrite, it is removed.

When selecting files using manual attach mode, upon confirming whatever is on 
the main input buss is recorded as an "ignore" value so papertape mode will 
work correctly even if previous software set the lines to something besides 
clear. File open commands and the sync command are never ignored. Any data 
remaining in the write buffer is written to disk upon selecting manual mode, 
and automatically written after about a second in normal run mode, so it's not 
vital to close a file after write operations. 

The serial file menu permits attaching named files...

Serial file menu
================

Read file:    HPBOOT
Write file:   [not open]
Global error: 0
A) VDRIVE prompt
B) Open read file
C) Open write file
D) Close write file
E) Clear globalerror
Esc) Resume operation
Select:  

Mostly self-explanitory. At the filename prompts press escape to abandon 
without changing (such as after a typo, there is no backspace editing in the 
current version, trying will result in error 3). Press just enter to clear the 
filename, effectively closing the file. Filenames are restricted to 8.3 "dos" 
format. Prompts to overwrite existing write files, if confirmed then deletes
the file before opening, otherwise new data is appended to the end of the file.
If no data is written before closing the file then nothing is written,
removing a file if an overwrite is confirmed. Read files are opened in
papertape mode, ignoring whatever bits are presently on the HP output lines
unless certain commands (sync and opens).

The VDRIVE prompt is useful for checking the directory, deleting files, 
changing to a new directory, making and deleting directories, and listing text 
files, among things. Avoid using the file rename option as it does not affect 
the long filename, a PC will continue to see the original name which can lead 
to PC oddities like multiple files with the same name, best to unplug the 
thumbdrive (but not while being accessed!) and use a PC if a file has to be 
renamed. Common VDRIVE commands include...

FWV - print VDRIVE firmware version (need at least 3.66 for reliable operation)
DIR - list a disk directory
CD dirname - change to a directory one level lower
CD .. - go up one directory level
CD / - change to the root directory
DLF filename - delete a file
MKD dirname - make a new directory
DLD dirname - delete a directory (must be empty)
RD filename - list a file to the terminal - best used with text files

A reminder of the commands is printed when the prompt is started...

Select: E

VDRIVE prompt - send Esc at prompt to exit
Useful commands: FWV, DIR, RD file, DLF file, MKD dir, DLD dir, CD dir|..|/
D:\>
[ready]

Note - There is no line editing at all in prompt mode, each byte is sent to
the VDRIVE as it is received, so type carefully. Sometimes the "Bad Command"
error may not be displayed with short incorrect entries until CR is pressed
again. for example DI[cr] produces no output, then fails at the next entry.
If D:\> or an error message is not printed then the VDRIVE got confused.

Caution - do not attempt to use raw open and file read/write commands in
interactive mode unless you know exactly what you are doing, some VDRIVE
commands require binary parameters which cannot be sent by a regular terminal.
See the Vinculum Firmware manual for the exact send and response sequences.

Other notes...

The VDRIVE dos prompt converts line ends to CRLF whether CR, LF or CRLF.
This prevents using a PC program to remotely access files using binary
VDRIVE commands, other effects must also be considered like when there
is no data to send or the input buffer is full. Code is in place for a
"raw mode" which theoretically would make it possible to access via a PC
but this code has not been tested and the protocols are subject to change.
Practically this is an unnecessary feature since the storage media is a
plain USB disk, attach it directly to a PC for transferring files.

The VDRIVE supports the FAT32 disk format but filenames are restricted
to 8.3 and the LFN field is totally ignored, avoid renaming files using
the VDRIVE since a PC will see the old name, possibly resulting in odd
situations like apparent duplicate files. Use a PC to rename files.

Warning - always properly unmount the USB disk from the PC when using
a PC to copy files to it, never just yank the thumbdrive!!! Under Windows
that opion is often hidden in the tray and causes major problems when it
is not used. Also note that PC disk utilities will complain that the FATs
are out of sync, the VDRIVE uses just the first FAT. Ignore this error or
reformat the USB disk so that it uses a single FAT.

This combination of hardware and software supports the full command set used 
by the VDOS and UDOS operating systems, in addition to being a full-featured 
papertape reader/punch emulator. Care needs to be taken when mixing VDOS and 
papertape operations, in particular something needs to be done to tell the 
adapter that further accesses are to be treated as papertape reads unless a 
new command is sent. This can be done by sending the papertape read command 
(octal 132000) to the adapter from the HP software, or simply clearing the 
output lines by executing CLA then OTA portaddress. This would be required to 
say use HP-IPL/OS to semi-automate the running of vintage compiler tools.
Under HP-IPL/OS with VDOS this can be done by making a PTRMODE word...

CREATE PTRMODE
      LDA PINST        get output instruction
      AND M77          mask off low 6 bits
      IOR 357          OR with PTR slot
      STA PINST        patch output instruction to PTR/USB slot
      CLA              set bits to 0
PINST OTA 0            write bits to PTR/USB interface
      JMP ZNXT,I       exit
M77   OCT 177700       low bits clear
END

This is from "vintage.ipl", automatically configures itself to the PTR port.
Run this before using papertape software that reads files opened using VDOS.
Otherwise, restrict papertape reads to booting and manually selecting files 
A-Z, which automatically sets up papertape mode. UDOS is not affected by
this since it sends the papertape read command when attaching files.


Firmware disk commands
----------------------

120000 = 1010000000000000   read from VDRIVE
121bbb = 10100010bbbbbbbb   write to VDRIVE, byte in low 8 bits of command
122000 = 1010010000000000   sync VDRIVE (call before starting operations)
123000 = 1010011000000000   clear VDRIVE response buffer
130000 = 1011000000000000   open read file, follow by filename[cr]
131000 = 1011001000000000   read the next byte from an open read file
132000 = 1011010000000000   switches to paper-tape emulator mode
134000 = 1011100000000000   open write file, follow by filename[cr]
135bbb = 10111010bbbbbbbb   write to file, byte in low 8 bits of command
136000 = 1011110000000000   close write file (write remaining buffered bytes)
137000 = 1011111000000000   get usb_error value

In the firmware source code this is expressed as...

'disk commands
#define command_readVD        b'10100000'
#define command_writeVD       b'10100010'
#define command_syncVD        b'10100100'
#define command_clearVD       b'10100110'
#define command_openreadfile  b'10110000'
#define command_readfromfile  b'10110010'
#define command_readasPTR     b'10110100'
#define command_openwritefile b'10111000'
#define command_writetofile   b'10111010'
#define command_closefile     b'10111100'
#define command_geterror      b'10111110'

Most of the commands are single-cycle, if the command returns data, it
will be on the buss when the flag signal is asserted. The open file commands
expect the filename will be sent as separate command/flag transfers, ending
with a CR (byte 13). If more than 12 characters are sent the extra characters
will not be added to the filename but the firmware will not continue until
a CR is received. The readasPTR command doesn't return data itself, rather
it tells the interface to act as a papertape reader emulator, ignoring the
command that is presently on the HP outputs (in this case readasPTR) and
instead returning the next byte from an open file for subsequent commands.
A command of 0 is always treated as a papertape read.

The geterror command returns the following error codes...

'error codes
#define error_nodisk          1
#define error_commandfailed   2
#define error_invalidfilename 3
#define error_fileopen        4
#define error_diskfull        5
#define error_inputnotopen    6
#define error_outputnotopen   7
#define error_eof             8
#define error_zerosize        9
#define error_other         255

If a read is attempted and a read file isn't open, the firmware returns 0
and sets error code 6. Likewise, if a write is attempted and a write file
isn't open, the byte is sent to the bitbucket and the error code is set to 7.
If a read is attempted past the end of a file, 0 is returned and the error
code is set to 8. Error code 2 occurs if a file doesn't exist, useful for
prompting to overwrite a file or detecting a failed open request. Error 3
occurs when the filename contains illegal characters. Error code 4 should
never happen, if it does cycle the interface power to clear the VDRIVE.
Error code 9 is set if attempting to open a directory or an empty file.
Error code 255 is set when the firmware doesn't know what went wrong.


PIC pin assignments
-------------------

MCLR - reset switch (active low)
Port A bit 0 - main flag output
Port A bit 1 - punch flag output
Port A bit 2 - main command input
Port A bit 3 - punch command input
Port A bit 4 - switch A input (active low)
Port A bit 5 - switch B input (active low)
Port A bit 6 - switch D input (active low)
Port A bit 7 - switch C input (active low)
Port B bit 0 - serial active LED output 
Port B bit 1 - read file open LED output
Port B bit 2 - write file open LED output
Port B bit 3 - command in progress LED output
Port B bit 4 - error LED output
Port B bit 5 - LCD interface clock output (*)
Port B bit 6 - LCD interface data output (*)
Port B bit 7 - I/O enable output (active low)
Port C bit 0 - ready LED output 
Port C bit 1 - busy LED output
Port C bit 2 - VDRIVE enable output (active high)
Port C bit 3 - SPI clock output (to I/O and VDRIVE)
Port C bit 4 - SPI data input (from I/O and VDRIVE)
Port C bit 5 - SPI data output (to I/O and VDRIVE)
Port C bit 6 - Serial data output (**)
Port C bit 7 - Serial data input (**)

(*) - for Myke Predko's 74LS174 shift register circuit or equivalent.

(**) - serial port does not use an inverting interface, rather is connected
to the serial lines via series resistors (18K for input, 1K for output).
A 100K pullup resistor keeps the input line high when not being used.


Known issues
------------

The source code won't compile with stock GCBASIC prior to Nov.2010, use
the modified compiler or otherwise fix relative branch code generation.

Some configurations require reseting the adapter after powering on the HP,
particularly with ground-true data and/or ground false control lines.
Doesn't smoothly detect power on, all the data LED's light up, no error is
detected but the HP's papertape loader won't work. After a reset it works.
As a matter of procedure, always reset the adapter after powering the HP.

This firmware version pushes the speed somewhat, if timing issues occur
then try increasing the CLEAR_MS and/or CLEAR_VDOS constants and recompile.
CLEAR_MS should be ok, stock value is double what is known to work, but
have not done margin testing on the CLEAR_VDOS setting.

The code and hardware is new, and not all aspects have been fully tested
under all conditions. There likely are other glitches to discover.


Web links
---------

http://www.ftdichip.com/Products/Modules/ApplicationModules.htm
Information about the VDRIVE module, links to the manual.

http://www.rentron.com/Myke1.htm
http://sites.google.com/site/zoranrilak/drive-an-hd44780-lcd-with-just-two-wires
Myke Predko's 2-wire LCD circuit.

http://newton.freehostia.com/hp/ideusb.html
VDRIVE modification for the 8052-based disk interface, VDOS

http://newton.freehostia.com/hp/udos.zip - a simple HP operating system.

http://newton.freehostia.com/hp/index.html
My HP Minicomputer Projects page.

http://www.infionline.net/~wtnewton/oldcomp/hp2100/
http://newton.freehostia.com/net/oldcomp/hp2100/ (mirror)
Main HP-IPL/OS page.

http://newton.freehostia.com/hpiplos_main_testing.zip
Latest HP-IPL/OS archive.

http://newton.freehostia.com/hp/usbadapter.html
Project page for this project.

http://gcbasic.sourceforge.net/
Great Cow Basic - the language used to implement this project.

http://gputils.sourceforge.net/
GPUTILS - includes gpasm, a very nice assembler for PIC code.

http://www.microchip.com/
The Microchip web site - source for PIC development tools/software.

http://www.microchip.com/wwwproducts/Devices.aspx?dDocName=en010278
PIC18F2525 page.

http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en023805&part=DV164120
DV164120 Pickit 2 page, downloads for software etc.
DM164120-3 is the 28 pin adapter board.

http://www.digikey.com/
Source for all of the parts used to make this thing.


License
-------

' The source code for the program is written by Terry Newton, it is provided
' as-is and without warranty of any kind. Under no circumstances shall the
' author be held liable for damages resulting from the use of the software.
' The source code itself is public domain and may be used for any purpose.
' The hex file that results from compiling this program includes libraries
' from the Great Cow Basic compiler that are Copyright Hugh Considine and
' Stefano Bonomi under the terms of the Lesser GNU Public License v2.1 or
' later. Source code is available from: http://gcbasic.sourceforge.net/

----------------------------------------------------------------------------
Terry Newton (wtn90125@yahoo.com)
Last modified November 23, 2010.
