FreeCalypso > hg > fc-usbser-tools
view doc/CP2102-EEPROM-tools @ 102:4f72e09fb698
doc/CP2102-EEPROM-tools: complete for now
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Thu, 28 Sep 2023 21:13:33 +0000 |
parents | ba741a1af0e3 |
children |
line wrap: on
line source
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.