Repository files navigation

The goal of this library is to provide access to the EEPROM of an Silabs CP210xunder Linux.

The CP210x is a series of USB-to-serial chip used in a lot of USB devices(similar to FTDIs and PL2303). Certain CP210x devices have an EEPROM onthe chip which can be programmed via USB, while others only have the OTPEPROM (which cannot be reprogrammed; seeModel notes). Silabs providesvarious source code examples for Windows and Linux, and multiple driversfor Windows.

The originalcp210x-program uses results from monitoring the USB bus whenthe windows library programs the CP210x device. The windows library was notdisassembled for the original protocol analysis.

• Python >= 3
• PyUSB

For the external cp2102N tool:

• GNU or clang toolchain
• make
• libusb-1.0

Since libusb is available on most Linux, Mac OS X and FreeBSD cp210x-programshould run flawlessly on these platforms. Currently it is tested in Github CIon Linux (Ubuntu), MacOS, and Windows (note the latter relies on the base GNUlibraries and tools installed on the Github CI runners).

If cp210x-program should run as non-root user, add the udev rule found indoc/45-cp210x-programming.rules to /etc/udev/rules.d. When devices with alreadyprogrammed IDs are reprogrammed at this IDs to 45-cp210x-programming.rules.

Install deps on Ubuntu:

$ sudo apt install python3-usb

Read EEPROM content into hexfile:

$ cp210x-program --read-cp210x -f eeprom-content.hex

Show EEPROM content from device 002 on bus 001:

$ cp210x-program --read-cp210x -m 001/002

Hint: The bus and device number can be queried using the `lsusb -t` command, which is available on most linux distributions.

Write some data to device with vendor id 0x10C4 and product id 0xEA62:

$ cp210x-program --write-cp210x -m 10C4:EA62 \               --set-product-string="Product String" \               --set-max-power=100 \               --set-bus-powered=no

Write default data to device:

$ cp210x-program --write-cp210x -F testdata/cp2102-orig.hex

This is for example required when the baud rate table is corrupted andthe CP210x always uses 500kBit/sec as baudrate.

• (re)Test on CP2102 and CP2103 (legacy parts)
• read config blob from CP2102N (new part)

Local tool dependencies to aid in development; install both tools formaximum enjoyment.

As long as you have git and at least Python 3.6, then you can installand usetox. After cloning the repository, you can run the repochecks with thetox command. It will build a virtual pythonenvironment for each installed version of python with all the pythondependencies and run the specified commands, eg:

$ git clone https://github.com/VCTLabs/cp210x-program$ cd cp210x-program/$ tox -e py

The above will run the default test commands using the (local) defaultPython version. To specify the Python version and host OS type, runsomething like:

$ tox -e py39-linux

To build and check the Python package, run:

$ tox -e deploy,check

Full list of additionaltox commands:

• tox -e deploy will build the python packages and run package checks
• tox -e check will install the wheel package from above and run the script
• tox -e lint will runpylint (somewhat less permissive than PEP8/flake8 checks)
• tox -e readhex will install the wheel package and try to read from a legacy device
• tox -e read will read the bulk USB descriptors from a device with SiLabs vendor ID
• tox -e badge will build the external cp2102N tool =>/ext/badge/bin/
• tox -e clean will clean the abovebin directory

For thetox -e badge command, you may want to set theCC variableeither in your shell environment or on the command-line, eg:

$ CC=gcc tox -e badge

This repo is nowpre-commit enabled for python/rst source and file-type linting.The checks run automatically on commit and will fail the commit (if notclean) and perform simple file corrections. If the mypy check failson commit, you must first fix any fatal errors for the commit to succeed.That said, pre-commit does nothing if you don't install it first (boththe program itself and the hooks in your local repository copy).

You will need to install pre-commit before contributing any changes;installing it using your system's package manager is recommended,otherwise install with pip into your usual virtual environment usingsomething like:

$ sudo emerge pre-commit  --or--$ pip install pre-commit

then install it into the repo you just cloned:

$ git clone https://github.com/VCTLabs/cp210x-program$ cd cp210x-program/$ pre-commit install

It's usually a good idea to update the hooks to the latest version:

$ pre-commit autoupdate

Most (but not all) of the pre-commit checks will make corrections for you,however, some will only report errors, so these you will need to correctmanually.

Automatic-fix checks include ffffff, isort, autoflake, the json/yaml/xml format checks,and the miscellaneous file fixers. If any of these fail, you can review the changeswithgit diff and just add them to your commit and continue.

If any of the mypy or rst source checks fail, you will get a report,and you must fix any errors before you can continue adding/committing.

To see a "replay" of anyrst check errors, run:

$ pre-commit run rst-backticks -a$ pre-commit run rst-directive-colons -a$ pre-commit run rst-inline-touching-normal -a

To run allpre-commit checks manually, try:

$ pre-commit run -a

Updated vendor links and basic model info; see the individual productdescriptions and data sheets for details.

Taken from the respective device Data Sheets:

• CP2101 - EEPROM (512 byte)may work
• CP2102 - EEPROM (1024 byte)should work
• CP2103 - EEPROM (1024 byte)should work
• CP2104 - EPROM only (1024 byte, not re-programmable)
• CP2105 - EPROM only (296 byte, not re-programmable)
• CP2109 - EPROM only (1024 byte, not re-programmable)
• CP2102N - EEPROM (960 byte)will not work with legacycp210x-program

The following table from AN721 shows the default SiLabs USB device IDs; notethird-party manufacturers often do not reprogram with their own vendor/productIDs.

• Original cp210x-program / CP210x Programmer project page by Petr Tesarik (a.k.a. tesarik)and Johannes Hölzl (a.k.a. johoelzl):https://sourceforge.net/projects/cp210x-program/
• CP2102N Product page and Data Sheet on Silicon Labs:
  • https://www.silabs.com/interface/usb-bridges/usbxpress/device.cp2102n-gqfn20
  • https://www.silabs.com/documents/public/data-sheets/cp2102n-datasheet.pdf
• AN978 CP210x USB-to-UART API Specification:
  • note this mainly documents HW/package and feature compatibility, and only discussesthe (newer) CP2102N model as far as configuration byte layout
  • https://www.silabs.com/documents/public/application-notes/an978-cp210x-usb-to-uart-api-specification.pdf
• AN721 Device Customization Guide:
  • https://www.silabs.com/documents/public/application-notes/AN721.pdf
  • https://www.silabs.com/documents/public/example-code/AN721SW.zip
• AN197 CP210x Serial Communications Guide:
  • https://www.silabs.com/documents/public/application-notes/an197.pdf
  • https://www.silabs.com/documents/public/example-code/AN197SW.zip
• AN223 Port Configuration and GPIO for CP210x
  • https://www.silabs.com/documents/public/application-notes/an223.pdf
  • https://www.silabs.com/documents/public/example-code/AN223SW.zip

The python package 'cp210x' and the python script 'cp210x-program' are providedunder the terms of the GNU LGPL. See LICENSE. Otherwise, anything under theext directory tree has its own license/copyrights.

Current external sources:

• cp2102 source and header files borrowed from:https://github.com/lowerrandom/DaBomb_dc27_badge/tree/master/software/tools/src
• requires GNU/Clang toolchain and libusb