From 18f8bcb1782be8762b4f366fa445d8f1987e537d Mon Sep 17 00:00:00 2001
From: Dejvino <dejvino@gmail.com>
Date: Sun, 14 Mar 2021 12:54:25 +0100
Subject: [PATCH] Hardware build instructions

---
 Hardware.md                       | 82 +++++++++++++++++++++++++++++++
 README.md                         |  2 +-
 video-terminal/Display.h          |  4 +-
 video-terminal/video-terminal.ino | 15 ++++--
 4 files changed, 97 insertions(+), 6 deletions(-)
 create mode 100644 Hardware.md

diff --git a/Hardware.md b/Hardware.md
new file mode 100644
index 0000000..d4b0b7e
--- /dev/null
+++ b/Hardware.md
@@ -0,0 +1,82 @@
+# Video Terminal Hardware
+Build instructions for the video-terminal-revival project.
+
+## Bill of Materials
+- ESP32 development board
+    - USB cable (for development)
+    - 5V power source (may be a 12V step down converter)
+- Display with composite input (TV, monitor)
+    - RCA cable
+    - RCA socket
+    - resistors: 2x 1k ohm
+- LK201 keyboard
+    - RJ-11 socket
+    - MAX2323 TTL-RS232 conversion board
+    - 12V power source + connector socket
+
+## Build
+### Display
+Connect the TV via the RCA cable to the RCA socket, then through a voltage divider into the ESP32:
+
+```
+ESP32                             TV
+-------+
+   GND |-+------------------ Composite (-)
+       | |  ____ 1k ohm
+       | +-|____|-+           (RCA socket)
+       |    ____  |
+ pin25 |---|____|-+--------- Composite (+)
+-------+         1k ohm
+```
+
+### Keyboard
+Connect the keyboard into the RJ-11 socket, hook that into a 12V power source and the RS-232 converter, then to the ESP32's serial port:
+
+```
+      [GND][12V]
+  [1]   |    |   [2]
+   |    |    |    |
+  -------------------               MAX2323                ESP32
+ | "    "    "    "  |           +-----------+           +--------
+ | E    G    1    L  |      [1]--| <-      - |-----------| GND
+ | S    N    2    K  |      [2]--| ->      + |--[5V]     |
+ | P    D    V    -> |         x-| +      <- |-----------| pin17
+ | ->             E  |    [GND]--| -      -> |-----------| pin16
+ | L              S  |           +-----------+           +--------
+ | K              P  |
+  --               --
+    |             |
+     --         --
+       |       |
+        -------
+
+Looking into the RJ-11 Socket
+on the ESP32-side (i.e. DEC)
+
+```
+
+![LK201 connection](http://www.netbsd.org/docs/Hardware/Machines/DEC/LK201_connector.jpg)
+Source: [LK201 Interface](http://www.netbsd.org/docs/Hardware/Machines/DEC/lk201.html)
+
+### TTY
+This part depends on what serial port you are connecting to. Most SBCs (e.g. Orange Pi) provide pins for TTL serial port, alternatively you can use a USB-Serial dongle. Either way you can connect the ESP32 directly to this:
+
+```
+ESP32               Serial port
+-------+              +---
+   GND |--------------|GND
+ pin18 |--------------|TX
+ pin19 |--------------|RX
+-------+              +---
+```
+
+### CPU
+The ESP32 should now be connected to both the keyboard and the display, as well as the "mainframe" (serial port) it will be talking to.
+
+For development (or at least the first flashing), all that remains is to connect it over USB to a computer with the Arduino IDE.
+
+For production use, connect it to a 5V power source.
+
+### Finishing
+For bonus points, place everything on a PCB, solder it, put it into a cool enclosure and go impress your friends!
+
diff --git a/README.md b/README.md
index 4de52f5..8ba03a3 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@ Physical recreation of a video terminal device for connecting to a serial consol
  - [ESP32Lib](https://github.com/bitluni/ESP32Lib/tree/development) for composite video output
 
 ## Building
-1. Connect up the hardware (TODO).
+1. Connect up the hardware. See [Hardware.md](Hardware.md)
 2. Get the Arduino IDE, Install ESP32 board package, Install ESP32Lib library.
 3. Compile and upload the sketch in `video-terminal/video-terminal.ino`
 
diff --git a/video-terminal/Display.h b/video-terminal/Display.h
index 1cd9084..5b5d06c 100644
--- a/video-terminal/Display.h
+++ b/video-terminal/Display.h
@@ -33,6 +33,8 @@
     Custom ladders can be used by tweaking colorMinValue and colorMaxValue
 */
 
+#define COMPOSITE_VIDEO_PIN 25 // hardcoded, this pin has a HW DAC
+
 #include <ESP32Lib.h>
 #include <Ressources/Font6x8.h>
 #include <Ressources/CodePage437_8x8.h>
@@ -43,7 +45,7 @@
 #define FONT CodePage437_8x8
 
 //pin configuration for DAC
-const int outputPin = 25;
+const int outputPin = COMPOSITE_VIDEO_PIN;
 // A) B)
 CompositeGrayDAC videodisplay;
 // C) D)
diff --git a/video-terminal/video-terminal.ino b/video-terminal/video-terminal.ino
index 6d4c40e..aaa9ad7 100644
--- a/video-terminal/video-terminal.ino
+++ b/video-terminal/video-terminal.ino
@@ -9,6 +9,15 @@
  * and modified by Peter Scargill.
  */
 
+#define SERIAL_KBD_BAUDRATE   4800 // hardcoded LK201 baud rate
+#define SERIAL_KBD_RX_PIN     16 // hardcoded in Serial2
+#define SERIAL_KBD_TX_PIN     17 // hardcoded in Serial2
+
+#define SERIAL_TTY_BAUDRATE   9600 // configurable, depends on the TTY
+#define SERIAL_TTY_CONFIG     SERIAL_8N1 // configurable, depends on the TTY
+#define SERIAL_TTY_RX_PIN     18 // configurable
+#define SERIAL_TTY_TX_PIN     19 // configurable
+
 #include <SPI.h>
 
 #include <Adafruit_GFX.h>
@@ -110,14 +119,12 @@ void setup() {
   Serial.println("Running!");
 
   // TTY host
-  SerialTty.begin(9600, SERIAL_8N1, 18, 19, false, 100);
+  SerialTty.begin(SERIAL_TTY_BAUDRATE, SERIAL_TTY_CONFIG, SERIAL_TTY_RX_PIN, SERIAL_TTY_TX_PIN, false, 100);
 
   // LK201 keyboard connected to pins 16 and 17
-  SerialKbd.begin(4800);
+  SerialKbd.begin(SERIAL_KBD_BAUDRATE);
   
   display.setup();
-  //uint16_t tftID = tft.readID();
-  //tft.begin(tftID);
 
   input_init();