The present package includes a set of command line tools for reading and
modifying the EEPROM content of Silabs CP2102 USB-serial adapters.  These tools
have been developed because:

* CP2102 adapters hold significance in FreeCalypso family of projects: it is
  the most common USB-serial chip in cables that connect from USB to the headset
  jack serial port of Motorola C1xx and Openmoko GTA01/02 phones, and the same
  chip also appears inside the legendary Pirelli DP-L10 phone.

* Classic CP2102 (as opposed to CP2102N) requires EEPROM reprogramming to switch
  between 230400/460800/921600 and 203125/406250/812500 baud rates.

* The original Python tools that were once popularized via OsmocomBB wiki are
  an enormous pain for those of us who aren't interested in Python view of the
  world, plus dependency hell.

The present tools support only classic CP2102, not CP2102N or CP2105.  The
latter chips aren't supported because:

* CP2102N does not remap baud rates like classic CP2102, hence the primary
  reason for having to delve into EEPROM configuration is eliminated;

* CP2105 cannot be casually programmed at all because it is OTP, and I am not
  in the business of designing ZIF socket fixtures for tiny QFN packages and
  burning through sacrificial chips.

Basic usage
===========

If have a CP2102-25 USB to headset jack cable from Sysmocom, or some other
CP2102 adapter at the default USB ID 10C4:EA60, you can check its current baud
rate configuration by running:

cp2102-read-baudtab

Without any options, this command will look for a connected CP2102 device at
the default USB ID, read out its EEPROM and dump its 32-entry baud rate table.
Looking at this printed table, you can immediately tell if your adapter is
currently configured for 230400/460800/921600 or for 203125/406250/812500 baud.

To program the EEPROM for GSM baud rates (203125/406250/812500 bps), run this
command:

cp2102-update-eeprom -b gsm

To program the EEPROM for "standard" baud rates (230400/460800/921600 bps), run
this command:

cp2102-update-eeprom -b std

After this programming operation, unplug and replug the USB device - see
Replug-after-EEPROM-write article for more info.

More detailed theory
====================

FreeCalypso CP2102 EEPROM tools are built on a different principle than our FTDI
EEPROM tools.  In the case of FTDI chips, our tools are designed to generate
EEPROM images de novo - this approach is necessary because in the case of
FT2232x and other FTDI chips that use external EEPROMs, those EEPROMs start out
blank.  The internal EEPROM of CP2102 is different - this EEPROM already holds
a valid image as the chip leaves Silabs, and valid EEPROM content is required
for this chip to function - thus there is no use case for constructing CP2102
EEPROM images de novo.  Instead we provide the following tools for CP2102:

* cp2102-read-eeprom reads the full EEPROM content out of the chip and saves it
  in an Intel HEX file.  The file format has been copied from Python-language
  cp210x-program-1.0 and is suspected (without certain proof) of also being the
  format used by Silabs' own tools.

* cp2102-write-eeprom programs the chip's EEPROM with a new image read from an
  Intel HEX file.

* cp2102-decode-baudtab and cp2102-decode-ee-desc read Intel HEX images of
  EEPROMs and decode portions of interest: the baud rate table and USB
  descriptors, respectively.

* cp2102-patch-ee-image reads an Intel HEX EEPROM image, applies a set of
  patches to it, and writes out a new Intel HEX EEPROM image.

* cp2102-update-eeprom applies a set of EEPROM patches directly in place: reads
  current EEPROM content from a physical chip, applies the desired patches and
  writes the new EEPROM image into the hardware.  This utility replaces the
  cumbersome sequence of cp2102-read-eeprom, cp2102-patch-ee-image and
  cp2102-write-eeprom for most common workflows.

* cp2102-read-baudtab combines the steps of cp2102-read-eeprom and
  cp2102-decode-baudtab into a single command that works without intermediate
  files - an easy utility for the common use case of checking the current baud
  rate table programming.

Selecting the device to operate on
==================================

By default our CP2102 tools look for USB ID 10C4:EA60, which is the default ID
code for CP2102; if there is more than one USB device with this ID, the tool
hits the first matching device it finds.  If you need to operate on a CP2102
chip whose ID code has been changed away from the default, or if you need to
select one of several USB devices with the same ID code, you can pass a device
selector string (see FTDI-EEPROM-tools article - we've implemented the same
mechanism for CP2102, even though it originates from libftdi) with -d option.
For example, to read the baud rate table from the CP2102 inside a Pirelli DP-L10
phone, run this command:

cp2102-read-baudtab -d i:0x0489:0xE003

EEPROM patch language
=====================

The "canonical" use case for patching CP2102 EEPROM config would be designing a
new custom hw gadget that contains a CP2102 chip and configuring that USB
interface chip with custom ID strings, or perhaps a custom VID:PID code or other
USB descriptor changes.  However, it is now 2023, and we (FreeCalypso) are not
planning on building any new hw with CP2102 chips - thus in the present time
the only real use case for CP2102 EEPROM manipulation is programming the baud
rate table on already existing CP2102-based cables and adapters (particularly
those sold by Sysmocom) to switch between 230400/460800/921600 baud and
203125/406250/812500 baud configs, or perhaps configure other non-standard baud
rates for various hacking applications.

Nonetheless and for the sake of completeness, our cp2102-update-eeprom and
cp2102-patch-ee-image tools allow any part of the EEPROM structure to be
patched: the baud rate table can be replaced in whole or in part, any bytes in
any of the USB descriptors can be patched, and new textual ID strings can be
set.

Given the lack of real-life use cases beyond switching between two possible baud
rate tables of interest as described earlier in this article, the full EEPROM
patching mechanism is not currently documented in detail - read the source code
if you are interested.

Checking CP2102 chip version
============================

To check if your CP2102 adapter is really classic CP2102 or CP2102N or some
other CP210x, run this command:

cp2102-read-partno

The result should be 0x02 on classic CP2102 or various codes (0x20, 0x21 or 0x22
depending on QFN package variant) on CP2102N.  Note that at least on classic
CP2102 this byte is stored in the EEPROM and can be modified - but hopefully no
sane person will patch the EEPROM on a classic CP2102 to make it pretend to be
CP2102N.