The goal of this library is to provide access to the EEPROM of an Silabs CP210x under Linux.
Warning
THE LEGACY VERSION OF cp210x-program IS NOT FULLY TESTED, AND MAY RENDER
YOUR CP210x USELESS OR DESTROY IT. Be aware that the current
(legacy) version was only tested on the original CP2102 part.
Similarly, the cp2102N programmer in ext/badge is only
"lightly" tested here. Be warned...
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 on the chip which can be programmed via USB, while others only have the OTP EPROM (which cannot be reprogrammed; see Model notes). Silabs provides various source code examples for Windows and Linux, and multiple drivers for Windows.
The original cp210x-program uses results from monitoring the USB bus when
the windows library programs the CP210x device. The windows library was not
disassembled 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-program should run flawlessly on these platforms. Currently it is tested in Github CI on Linux (Ubuntu), MacOS, and Windows (note the latter relies on the base GNU libraries and tools installed on the Github CI runners).
If cp210x-program should run as non-root user, add the udev rule found in doc/45-cp210x-programming.rules to /etc/udev/rules.d. When devices with already programmed 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 and the 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 for maximum enjoyment.
As long as you have git and at least Python 3.6, then you can install
and use tox. After cloning the repository, you can run the repo
checks with the tox command. It will build a virtual python
environment for each installed version of python with all the python
dependencies 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) default Python version. To specify the Python version and host OS type, run something like:
$ tox -e py39-linux
To build and check the Python package, run:
$ tox -e deploy,check
Full list of additional tox commands:
tox -e deploywill build the python packages and run package checkstox -e checkwill install the wheel package from above and run the scripttox -e lintwill runpylint(somewhat less permissive than PEP8/flake8 checks)tox -e readhexwill install the wheel package and try to read from a legacy devicetox -e readwill read the bulk USB descriptors from a device with SiLabs vendor IDtox -e badgewill build the external cp2102N tool =>/ext/badge/bin/tox -e cleanwill clean the abovebindirectory
For the tox -e badge command, you may want to set the CC variable
either in your shell environment or on the command-line, eg:
$ CC=gcc tox -e badge
This repo is now pre-commit enabled for python/rst source and file-type linting. The checks run automatically on commit and will fail the commit (if not clean) and perform simple file corrections. If the mypy check fails on 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 (both the 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 using something 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 correct manually.
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 changes
with git 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 any rst 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 all pre-commit checks manually, try:
$ pre-commit run -a
Updated vendor links and basic model info; see the individual product descriptions 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 legacy
cp210x-program
The following table from AN721 shows the default SiLabs USB device IDs; note third-party manufacturers often do not reprogram with their own vendor/product IDs.
- 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:
- AN978 CP210x USB-to-UART API Specification:
- note this mainly documents HW/package and feature compatibility, and only discusses the (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:
- AN197 CP210x Serial Communications Guide:
- AN223 Port Configuration and GPIO for CP210x
The python package 'cp210x' and the python script 'cp210x-program' are provided
under the terms of the GNU LGPL. See LICENSE. Otherwise, anything under the
ext 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
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent