--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/DUART28-EEPROM-config	Thu Sep 17 04:18:46 2020 +0000
@@ -0,0 +1,70 @@
+The EEPROM on the DUART28 adapter board has two valid configurations: DUART28C
+and DUART28S.  As of this writing the S configuration is the default shipping
+one, but this situation may change in the future.  The difference between the
+two configs is in the USB VID:PID presented by the USB device, and this USB ID
+difference has the following practical impact:
+
+* The C configuration presents a custom USB ID and requires a custom patch to
+  the Linux kernel ftdi_sio driver in order to work - without this ftdi_sio
+  driver patch it won't work at all.  But if you do go through the pain of
+  applying the needed patch to your Linux kernel ftdi_sio driver, the reward
+  is that you get not only the two Calypso UARTs, but also working boot control
+  outputs.
+
+* The S configuration presents the default FT2232x USB ID and is therefore
+  supported out of the box by the standard Linux ftdi_sio driver without needing
+  any patches.  However, the adapter's CTL1 and CTL2 outputs cannot be used in
+  this configuration (they will be bogusly asserted whenever Channel B ttyUSB
+  device is opened), and thus they must be left unconnected, and you don't get
+  to play with the remote boot control feature.
+
+The physical hardware is identical between the two configurations, only the
+EEPROM programming changes, thus end users need to be able to switch freely
+between the two EEPROM configs as they wish.  This article explains how to
+program the EEPROM back and forth between the two configs.
+
+Determining your current DUART28 config
+=======================================
+
+Connect the USB cable between your DUART28 board and your Linux host, and
+observe dmesg output.  If your DUART28 board is in the C configuration, it will
+present as USB ID 0403:7152, and if it is in the S config, it will present as
+USB ID 0403:6010.  You can also see these USB IDs with lsusb.  The product ID
+string is also programmed as "DUART28C" or "DUART28S".
+
+Converting from DUART28S to DUART28C
+====================================
+
+If your DUART28 board is currently in the S config, its USB ID will be
+0403:6010, which is the default ID for FTDI's two-channel FT2232x family.
+Because it is the standard default, there are plenty of other gadgets using the
+same ID - thus you need to ensure that you have no other USB devices with the
+same ID connected to your system during the reprogramming operation.  Run lsusb
+and ensure that you see only one USB device with ID 0403:6010.  Ensure that this
+one device really is your DUART28 board: unplug that USB cable and make sure
+that the device disappears, plug it back in and make sure that it reappears.
+
+One you have confirmed that you won't inadvertently hit some other FT2232x
+device, execute the actual programming command as follows (from the top
+directory of this code repository):
+
+ftee-gen2232c eeproms/duart28c $Serial | fteeprom-prog i:0x0403:0x6010
+
+(See FTDI-EEPROM-tools article for other ways to specify the target device to
+ fteeprom-prog.)
+
+Replace the $Serial metavariable with the 3-digit serial number of your DUART28
+adapter board as it appears on the factory serial number sticker.
+
+After this operation completes successfully, unplug and replug the USB cable
+between the DUART28 board and your host - the adapter should now show up with
+USB ID 0403:7152.
+
+Converting from DUART28C to DUART28S
+====================================
+
+If your DUART28 board is currently in the C config, its USB ID will be
+0403:7152, which is a private ID that belongs to us and should not be used by
+other parties.  The reverse conversion command is as follows:
+
+ftee-gen2232c eeproms/duart28s $Serial | fteeprom-prog i:0x0403:0x7152