--- a/doc/DUART28-EEPROM-config	Sun Sep 10 21:26:04 2023 +0000
+++ b/doc/DUART28-EEPROM-config	Mon Sep 11 01:06:03 2023 +0000
@@ -23,48 +23,44 @@
 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
-=======================================
+Using fc-duart28-conf utility
+=============================
 
-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".
+The present fc-usbser-tools package includes a specialized high-level utility
+for examining and changing DUART28 adapter configuration.  This utility has two
+operation modes:
 
-Converting from DUART28S to DUART28C
-====================================
+fc-duart28-conf show		-- check and show current configuration
+fc-duart28-conf set C|S		-- set new config by programming the EEPROM
 
-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.
+The show command is completely non-invasive: it looks through the system tree
+of connected USB devices, looking for a DUART28 adapter (as identified not only
+by USB VID:PID, but also by manufacturer and product ID strings), and if it
+finds a DUART28 device, the tool reports its current configuration.
 
-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.
+The set command is invasive by necessity, as the fundamental identity of the
+connected USB device is being changed: the tool commands the Linux kernel to
+unbind the ftdi_sio driver from both interfaces (both ttyUSB devices disappear),
+checks the current EEPROM configuration, and then reprograms it for the new
+desired config.  Once the operation completes, the DUART28 adapter needs to be
+unplugged and replugged for the EEPROM change to take effect and for the
+ftdi_sio driver to rebind.
 
-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.
+Unless you intentionally fool it by programming DUART28C or DUART28S EEPROM
+config into some other FTDI device, fc-duart28-conf cannot hit a non-DUART28
+USB device by mistake: VID:PID, manufacturer ID string and product ID string
+all have to match either DUART28C or DUART28S.  If you have multiple DUART28
+adapters plugged in, the tool will hit the first one it finds - not a
+recommended arrangement, but also one which is not expected to arise by
+accident.
 
-Converting from DUART28C to DUART28S
-====================================
+Manual programming with ftee-gen2232c and fteeprom-prog
+=======================================================
 
-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
+In order to be safe in terms of not accidentally hitting some other FTDI-based
+USB device, fc-duart28-conf requires the current state of the DUART28 adapter
+to be either valid DUART28C or valid DUART28S.  Under ordinary expected usage
+this requirement is not a problem, but if you somehow manage to totally hose
+your adapter's EEPROM, then fc-duart28-conf won't be able to recover it.  If
+you find yourself in the latter situation, see DUART28-EEPROM-manual article
+for the older manual method which is always possible.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/DUART28-EEPROM-manual	Mon Sep 11 01:06:03 2023 +0000
@@ -0,0 +1,50 @@
+The new user-friendly (or fool-proof) way to examine and change DUART28 adapter
+configuration is fc-duart28-conf utility described in the DUART28-EEPROM-config
+article.  The present article describes the older method that existed before
+fc-duart28-conf, and which is used for initial factory programming.
+
+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 (or if you messed it up and
+have a blank or corrupt EEPROM), 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, which is a shell pipeline:
+
+ftee-gen2232c 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 duart28s $Serial | fteeprom-prog i:0x0403:0x7152