From b3551659e766f2de54a1c7d6b443dd33a38a3072 Mon Sep 17 00:00:00 2001
From: Nicholas Giori <11759504+najorin@users.noreply.github.com>
Date: Thu, 21 Apr 2022 07:36:49 -0400
Subject: [PATCH] Add Linux FTDI Flashing Instructions to xh_hk4401.md (#716)

Co-authored-by: Nicholas Giori <me@nicholasgiori.com>
---
 docs/v3.md        |   1 +
 docs/xh_hk4401.md | 140 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 141 insertions(+)

diff --git a/docs/v3.md b/docs/v3.md
index d5e08262..ec9011b0 100644
--- a/docs/v3.md
+++ b/docs/v3.md
@@ -30,6 +30,7 @@ If you have a kit without a metal case, you can use our free 3D printing case dr
 1. **[Flash the memory card.](flashing_os.md){target=_blank}**
 
 2. **Build PiKVM** according to the video instruction or review the [illustrated instructions](v3_illustrated_install_instructions.md):
+    
     ??? tip "Video Guide: Metal case step by step" 
         NOTE: OLED will not light up till step 3 is performed, video was performed after it was already configured, heat sinks NOT included.
         ![type:video](https://www.youtube.com/embed/jdqiwHKQcD4)
diff --git a/docs/xh_hk4401.md b/docs/xh_hk4401.md
index 8b51fcd1..fd443928 100644
--- a/docs/xh_hk4401.md
+++ b/docs/xh_hk4401.md
@@ -42,6 +42,144 @@ need is to connect it to a micro-USB connector.
     ensure you always purchase from a reputable store and brand (Adafruit, Sparkfun, etc.), Amazon **is not** a
     reputable store.
 
+### Linux Instructions
+
+??? note "References I used to get my FTDIs working:"
+    * https://waterpigs.co.uk/articles/ftdi-configure-mac-linux/
+    * https://manpages.debian.org/testing/ftdi-eeprom/ftdi_eeprom.1.en.html
+    * https://manpages.ubuntu.com/manpages/bionic/man1/ftdi_eeprom.1.html
+    * http://developer.intra2net.com/git/?p=libftdi;a=blob;f=src/ftdi.h
+    * http://developer.intra2net.com/git/?p=libftdi;a=blob;f=src/ftdi.c
+    * http://developer.intra2net.com/git/?p=libftdi;a=tree;f=ftdi_eeprom
+    * http://developer.intra2net.com/git/?p=libftdi;a=blob;f=ftdi_eeprom/example.conf
+    * http://developer.intra2net.com/git/?p=libftdi;a=blob;f=ftdi_eeprom/main.c
+
+!!! warning
+    Steps were performed on Debian-like installation (Pop!_OS 21.10)
+
+This workflow has worked for a self-described NON-genuine FTDI FT232RL chip. The other MAY be genuine, but it is also working.
+
+Neither of the following FTDI UART adapters are recommended. Purchasing both chips was an error (only 1 intended). However, having two (potentially non-genuine) FTDI UART adapters helped to create these instructions.
+
+- [Possibly genuine, but working regardless, (DSD TECH) FTDI](https://amazon.com/dp/B07BBPX8B8)
+
+- [Not genuine (HiLetGo) FTDI](https://amazon.com/dp/B00IJXZQ7C)
+
+!!! warning 
+    The HiLetGo UART adapter comes with a USB MINI female connector and necessitates another adapter/cable for interfacing with the Pi.
+
+1. ??? note "Get info from FTDI"
+    * Plug the FTDI into a USB port on your Linux device and run `lsusb` to verify that the device is found
+        ```
+        lsusb
+        ```
+    * Ensure the device is recognized as FTDI
+        ```
+        sudo lshw | grep -B 10 ftdi
+        ```
+    * Record hardware information (not sure if needed, but was saved to prevent overwriting critical data in the EEPROM)
+
+2. ??? note "Blacklist ftdi_sio kernel module"
+    * The kernel module ==ftdi_sio== is currently enabled (and how you saw the device in the previous step). We need to disable this module to read/write to the EEPROM.
+    * The following command creates a file to blacklist the ==ftdi_sio== module.
+        ```
+        echo "blacklist ftdi_sio" | sudo tee /etc/modprobe.d/bl-ftdi.conf > /dev/null
+        ```
+
+3. ??? note "Reboot machine"
+    * We need to reboot into an environment without ftdi_sio active.
+        ```
+        shutdown -r 0
+        ```
+
+4. ??? note "Install ftdi_eeprom if not already installed"
+    * Install ==ftdi_eeprom== with the following command.
+        ```
+        sudo apt install ftdi_eeprom
+        ```
+
+5. ??? note "Make a folder to work from and change it to our working directory"
+    ```
+    mkdir ./ftdi_config
+    cd ./ftdi_config
+    ```
+
+6. ??? note "Create a valid FTDI configuration file for ftdi_eeprom consumption"
+    * The below command (copy/paste all lines) will create a valid configuration file. Change parameters as required.
+        ```
+        tee ./ftdi.conf > /dev/null <<EOF
+        filename=eeprom.bin
+        vendor_id=0x0403
+        product_id=0x6001
+        manufacturer="FTDI"
+        product="FT232 Serial (UART)"
+        serial="SERIAL"
+        use_serial=true
+        max_power=500
+        self_powered=false
+        invert_txd=true
+        invert_rxd=true
+        cha_type="UART"
+        EOF
+        ```
+    * This configuration is trimmed from the example due to size of the EEPROM on the FTDIs used.
+    * The example configuration at ==/usr/share/doc/ftdi-eeprom/example.conf== describes possible configuration options for the FTDI and is well-documented.
+    * The above configuration worked for the mentioned devices. The ==filename==, ==vendor_id==, ==product_id==, ==invert_txd==, and ==invert_rxd== variables are required. The others might not be, but seemed applicable.
+    * If you're using a different FTDI chip than used here, please update that in the above configuration. Ensure that vendor_id and product_id are what was obtained from the output of the initial `lsusb` command.
+    * ==max_power==, ==serial==, and ==product== were updated to reflect the output of the initial `lshw`. These updates may not be required and were done to avoid overwriting anything important. ==cha_type== was updated to ==UART== where both of the devices were originally designated as FIFO.
+
+7. ??? note "Test the configuration and read the eeprom initially before flashing"
+    * Read the EEPROM with the following command
+        ```
+        sudo ftdi_eeprom --read-eeprom ./ftdi.conf
+        ```
+    * If you get an error here, there's something wrong with your configuration. Check that the device is properly identified and try again.
+
+8. ??? note "Rename/preserve and review the contents of the binary read from the EEPROM"
+    * First, rename the output binary file so we don't overwrite it when we flash (flashing writes the flashed binary to the ==filename== path)
+        ```
+        mv ./eeprom.bin ./original_eeprom.bin
+        ```
+    * Then, display the outputs of the binary
+        ```
+        hexdump -C original_eeprom.bin
+        ```
+    * You can rename the binary in the configuration file by editing the ==filename== variable. If you can't be bothered to edit the file, rename it as detailed above.
+
+9. ??? note "Flash the configuration"
+    * Run the following command to flash the EEPROM of the FTDI
+        ```
+        sudo ftdi_eeprom --flash-eeprom ./ftdi.conf
+        ```
+    * Optional: compare the flashed configuration to the initial configuration with the below command. If there is no output, the files are the same. You will likely need to re-flash.
+        ```
+        diff <(xxd original_eeprom.bin) <(xxd eeprom.bin)
+        ```
+    * Alternatively, you can manually compare the files by running `hexdump -C original_eeprom.bin` and `hexdump -C eeprom.bin`
+
+10. ??? success "Your FTDI should be flashed and working to control the KVM!"
+    - Plug it into one of the Pi's USB slots (if not already), and it's good to go.
+    - The KVM will sink power from the FTDI (Pi) if Vcc is connected. If Vcc is disconnected, ensure that grounds between the Pi and KVM are tied.
+
+11. ??? note "Clean up the ftdi blacklist to reenable the ftdi_sio module"
+    * Comment out the line but leave the file with the following command:
+        ```
+        sudo sed -i 's/blacklist ftdi_sio/#blacklist ftdi_sio/g' /etc/modprobe.d/bl-ftdi.conf
+        ```
+    * If you'd need to read/flash FTDI EEPROM in the future, you can use the following command (followed by a reboot) to blacklist the ==ftdi_sio== module again.
+        ```
+        sudo sed -i 's/#blacklist ftdi_sio/blacklist ftdi_sio/g' /etc/modprobe.d/bl-ftdi.conf
+        ```
+    * If you want to wash your hands of FTDI flashing, then delete the blacklist file with the following command:
+        ```
+        sudo rm /etc/modprobe.d/bl-ftdi.conf
+        ```
+
+12. ??? note "Reboot the machine to reset to initial state (with ftdi_sio loaded)"
+    * ==ftdi_sio== should reload as the driver, and the FTDI should be able to be seen with `lshw` / `dmesg` once again. If you tried to run either command while ==ftdi_sio== was blacklisted, you probably would have come up empty.
+
+### Windows Instructions
+
 In order to invert the RX/TX signals, you can use [ft_prog](https://ftdichip.com/utilities/#ft_prog) and set the 
 following settings:
 
@@ -49,6 +187,8 @@ following settings:
 
 Once the UART is configured, please fully disconnect it and connect it back to the computer. Relaunch `ft_prog` and ensure the settings are still set. If they are not, you have a *fake* FTDI chip.
 
+### FTDI Terminal Configuration
+
 Finally, you will need to connect it to the micro USB port (**This it not a normal USB micro port.**)
 like so: