Initial delivery.

LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2020, Paul Koning
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1 +1,12 @@
-# lk201emu
+# Digital Equipment LK201 keyboard emulator
+
+This project allows a standard USB PC keyboard to be used as replacement for a DEC LK201 keyboard.  It consists of a small circuit built around an Adafruit Trinket M0 Arduino processor, and software for that to implement a USB host driver for the USB keyboard and the LK201 communication protocol. 
+
+Subdirectory `lk201` is the Arduino software.  You can build it using the standard Arduino SDK, or use the prebuilt binary.
+
+Subdirectory `kicad` is the circuit board design.  You can view it using the open source KiCAD package.
+
+Subdirectory `doc` contains several documentation files in MD format.  File `emulator.md` describes the features of the emulator; `kicad` describes the board design and assembly information, and `software` describes the software and the load procedure.  There are also two JPG files that show the circuit board.
+
+File `LICENSE` is the open source license under which this emulator is released.
+

doc/emulator.md

@@ -0,0 +1,59 @@
+# Digital Equipment LK201 keyboard emulator
+
+The emulator allows a standard PC-style USB keyboard to be used as a replacement for a DEC LK201 keyboard.  This is useful if you don't have one, or if all the ones you have stopped working, as happened to me.
+
+The emulator circuit has two connectors: a modular jack which accepts the LK201 keyboard cable, and a USB connector.  The USB connector on the Trinket board is a micro-B connector; your keyboard presumably needs an A jack.  There are various ways to convert from one to the other; [Adafruit](https://www.adafruit.com/product/1099 "Micro B to A cable") sells one.
+
+## Keyboard mapping
+
+For the most part, the keys on the PC keyboard correspond directly to the same keys on the LK201.  This applies to all the letters and digits as well as most punctuation.  Similarly, F1 through F12 are the same in both, as are the cursor keys and most of the numeric keypad keys.  Both shift keys are shift, but only the left control key is control.
+
+Some other keys are different on the two keyboards.  Sometimes similar key labels exist but the positions are different; in that case I have chosen to map the keys by their positions.
+
+| PC keyboard key | LK201 key |
+| --- | --- |
+| Left Windows | < > |
+| Left Alt | Compose |
+| Esc  | F11 |
+| Insert | Find |
+| Home | Insert Here |
+| PgUp | Remove |
+| Delete | Select |
+| End | Prev Screen |
+| PgDn | Next Screen  |
+| PrtScr | F14 |
+| Scroll Lock | Help (F15) |
+| Pause | Do (F16) |
+| Right Alt | F17 | 
+| Right Windows | F18 |
+| App Menu | F19 |
+| Right Control | F20 |
+| Num Lock | PF1 | 
+| Num keypad / | PF2 |
+| Num keypad * | PF3 |
+
+Note that the PF4 and F13 keys are not available, I ran out of places to put them.
+
+## Lights
+
+Standard PC keyboards have only three LEDs, while the LK201 has four.  The mappings are:
+
+| PC keyboard LED | LK201 keyboard LED |
+| --- | --- |
+| Scroll lock | Hold screen |
+| Caps lock | Lock |
+| Num lock | Compose |
+
+The WAIT light is not on the keyboard but is provided by the LED on the center of the Trinket board (the multi-color one), in green.
+
+## Trinket middle LED color coding
+
+When operating, the emulator uses the middle LED for the LK201 WAIT light, in green.  Other colors are used during initialization, to reflect the phases of the USB discovery.
+* Purple: settling.
+* Blue: waiting for device.  This is the code you will see when no keyboard is plugged in.
+* Yellow: attached, reset device.
+* Orange: wait for device reset complete.
+* Cyan (light blue): configuring device.  If the board stays in this state, the USB device is not compatible with this software.
+
+When the USB initialization completes, there is a brief bright green flash.
+

doc/kicad.md

@@ -0,0 +1,59 @@
+# Digital Equipment LK201 keyboard emulator
+
+The `kicad` subdirectory contains the design files for the emulator circuit board, which you can inspect or modify using the open source KiCAD package.
+
+## Creating the circuit board
+
+There are three ways to get a circuit board.
+1. From the (shared designs)[https://oshpark.com/shared_projects/zDjWDDDL "LK201 emulator"] section of the OSHPark PCB fabricator website.
+2. From any PCB fabricator that accepts KiCAD board files (such as OSHPark).
+3. From any PCB fabricator that doesn't, by generating the standard *Gerber* files.
+
+If you want to use a fabricator that needs Gerber files, open the `lk201.kicad_pcb` file using KiCAD (specifically the *Pcbnew* application) and use the File->Plot menu option to generate them.  You'll want to review the detailed instructions from the fabricator to confirm settings, file name rules, etc.
+
+## Schematic
+
+The board schematic is in `lk201.sch`.  You won't need this to create the board, but you can review this if you are interested, or if you want to modify the design.
+
+## Assembly
+
+The design is a simple circuit board with all through-hole components.  If you have experience building small electronic kits it should not create any problems.  If you do not, you may want to seek out some help since this is not a "Heathkit" style kit with detailed instructions or tutorials.
+
+## Parts list
+
+Here are all the parts in the design, with schematic reference (also on the board silk screen labeling), value or device type, description, along with manufacturer name and Digikey part number.  The Digikey numbers are just by way of illustration.  Capacitors and resistors are generic, you can replace them by similar devices from other suppliers so long as they fit in the available space.  The capacitors  are small ceramic devices with 0.1 in ch lead spacing; the resistors are standard 1/4 watt parts.  The transistor is a general purpose small NPN transistor, many other TO92 package transistors should work so long as the pinout matches.  Beware of the 2N2222, there are two variants with different pinouts!
+
+If you don't want the key click and beep (bell) features, omit LS1, Q1, R1 and R2.
+| Ref | Value | Description | Manufacturer | Digikey part # |
+| --- | ----- | ----------- | ------------ | -------------- |
+| C1 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| C2 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| C3 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| C4 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| C5 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| C6 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| C7 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| J1 | RJ22 | RJ connector, 4P4C (4 positions 4 connected), RJ9/RJ10/RJ22 | Assmann WSW | ​AE10381-ND |
+| LS1 | PS1420 | Crystal speaker/transducer | TDK Corporation | ​445-2526-1-ND |
+| Q1 | 2N3904 | 0.2A Ic, 40V Vce, Small Signal NPN Transistor, TO-92 | ON Semiconductor | 2N3904FS-ND |
+| R1 | 1k | Resistor, 1/4 W | Stackpole | CF14JT1K00CT-ND |
+| R2 | 3.3k | Resistor, 1/4 W | Stackpole | CF14JT3K30TR-ND |
+| U1 | L78L05 | Positive 100mA 30V Linear Regulator, Fixed Output 5V, TO-92 | ST Microelectronics | 497-13127-1-ND |
+| U2 | Trinket M0 | Adafruit Trinket M0 board (SAMD21) | Adafruit | 1528-2361-ND |
+| U3 | ICL3232CPZ | Dual RS232 driver/receiver, 5V supply, 120kb/s, 0C-70C | Renesas | ICL3232CPZ-ND​ |
+
+## Assembly suggestions
+
+I found that this order of installing the components works well:
+1. U3 (16 pin DIP)
+2. Resistors and capacitors
+3. U1 (voltage regular) and Q1 (transistor)
+4. LS1 (piezo beeper)
+5. U2 (Trinket M0).  The board comes with a set of pins.  Cut off two 5-pin sections and solder these to the board, then slip the Trinket onto the pins and solder it.
+6. J1 (RJ connector)
+
+Note the correct orientation of U1, U2, U3, and Q1.
+
+## Software load
+
+After the board is built you will need to load the software.  See the software.md file for instructions.

doc/software.md

@@ -0,0 +1,59 @@
+# Digital Equipment LK201 keyboard emulator
+
+The `kicad` subdirectory contains the design files for the emulator circuit board, which you can inspect or modify using the open source KiCAD package.
+
+## Creating the circuit board
+
+There are three ways to get a circuit board.
+1. From the [shared designs](https://oshpark.com/shared_projects/zDjWDDDL "LK201 emulator") section of the OSHPark PCB fabricator website.
+2. From any PCB fabricator that accepts KiCAD board files (such as OSHPark).
+3. From any PCB fabricator that doesn't, by generating the standard *Gerber* files.
+
+If you want to use a fabricator that needs Gerber files, open the `lk201.kicad_pcb` file using KiCAD (specifically the *Pcbnew* application) and use the File->Plot menu option to generate them.  You'll want to review the detailed instructions from the fabricator to confirm settings, file name rules, etc.
+
+## Schematic
+
+The board schematic is in `lk201.sch`.  You won't need this to create the board, but you can review this if you are interested, or if you want to modify the design.
+
+## Assembly
+
+The design is a simple circuit board with all through-hole components.  If you have experience building small electronic kits it should not create any problems.  If you do not, you may want to seek out some help since this is not a "Heathkit" style kit with detailed instructions or tutorials.
+
+## Parts list
+
+Here are all the parts in the design, with schematic reference (also on the board silk screen labeling), value or device type, description, along with manufacturer name and Digikey part number.  The Digikey numbers are just by way of illustration.  Capacitors and resistors are generic, you can replace them by similar devices from other suppliers so long as they fit in the available space.  The capacitors  are small ceramic devices with 0.1 in ch lead spacing; the resistors are standard 1/4 watt parts.  The transistor is a general purpose small NPN transistor, many other TO92 package transistors should work so long as the pinout matches.  Beware of the 2N2222, there are two variants with different pinouts!
+
+If you don't want the key click and beep (bell) features, omit LS1, Q1, R1 and R2.
+| Ref | Value | Description | Manufacturer | Digikey part # |
+| --- | ----- | ----------- | ------------ | -------------- |
+| C1 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| C2 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| C3 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| C4 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| C5 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| C6 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| C7 | 0.1uF | Unpolarized capacitor | Kemet | 399-14010-1-ND​ |
+| J1 | RJ22 | RJ connector, 4P4C (4 positions 4 connected), RJ9/RJ10/RJ22 | Assmann WSW | ​AE10381-ND |
+| LS1 | PS1420 | Crystal speaker/transducer | TDK Corporation | ​445-2526-1-ND |
+| Q1 | 2N3904 | 0.2A Ic, 40V Vce, Small Signal NPN Transistor, TO-92 | ON Semiconductor | 2N3904FS-ND |
+| R1 | 1k | Resistor, 1/4 W | Stackpole | CF14JT1K00CT-ND |
+| R2 | 3.3k | Resistor, 1/4 W | Stackpole | CF14JT3K30TR-ND |
+| U1 | L78L05 | Positive 100mA 30V Linear Regulator, Fixed Output 5V, TO-92 | ST Microelectronics | 497-13127-1-ND |
+| U2 | Trinket M0 | Adafruit Trinket M0 board (SAMD21) | Adafruit | 1528-2361-ND |
+| U3 | ICL3232CPZ | Dual RS232 driver/receiver, 5V supply, 120kb/s, 0C-70C | Renesas | ICL3232CPZ-ND​ |
+
+## Assembly suggestions
+
+I found that this order of installing the components works well:
+1. U3 (16 pin DIP)
+2. Resistors and capacitors
+3. U1 (voltage regular) and Q1 (transistor)
+4. LS1 (piezo beeper)
+5. U2 (Trinket M0).  The board comes with a set of pins.  Cut off two 5-pin sections and solder these to the board, then slip the Trinket onto the pins and solder it.
+6. J1 (RJ connector)
+
+Note the correct orientation of U1, U2, U3, and Q1.
+
+## Software load
+
+After the board is built you will need to load the software.  See the software.md file for instructions.