stcgal - STC MCU flash tool =========================== stcgal is a command line flash programming tool for STC MCU Ltd. [1] 8051 compatible microcontrollers. The name was inspired by avrdude [2]. STC microcontrollers have a UART based boot strap loader (BSL). It utilizes a packet-based protocol to flash the code memory and IAP memory. The BSL is also used to configure various (fuse-like) device options. Unfortunately, this protocol is not publicly documented and STC only provide a (crude) Windows GUI application for programming. stcgal is a full-featured replacement for STC's Windows software; it is very portable and suitable for automation. [1] http://stcmcu.com/ [2] http://www.nongnu.org/avrdude/ Supported MCU models -------------------- stcgal should fully support STC 89/90/10/11/12/15 series MCUs. So far, stcgal was tested with the following MCU models: * STC89C52RC (BSL version: 4.3C) * STC12C2052AD (BSL version: 5.8D) * STC12C5A60S2 (BSL version: 6.2I) * STC11F08XE (BSL version: 6.5M) * STC15F104E (BSL version: 6.7Q) * STC15F204EA (BSL version: 6.7R) * STC15L104W (BSL version: 7.1Q) * IAP15F2K61S2 (BSL version: 7.1S) More compatibility testing is going to happen soon. Features -------- * Display part info * Program flash memory * Program IAP/EEPROM * Set device options * Read unique device ID (STC 10/11/12/15) * Trim RC oscillator frequency (STC 15) Installation ------------ stcgal requires Python 3.2 (or later) and pySerial. Apart from that, no particular installation is required. Usage ----- See ```stcgal.py -h``` for usage information. ``` $ ./stcgal.py -h usage: stcgal.py [-h] [-P {stc89,stc12a,stc12,stc15a,stc15}] [-p PORT] [-b BAUD] [-l HANDSHAKE] [-o OPTION] [-t TRIM] [-D] [code_binary] [eeprom_binary] stcgal - an STC MCU ISP flash tool positional arguments: code_binary code segment binary file to flash eeprom_binary eeprom segment binary file to flash optional arguments: -h, --help show this help message and exit -P {stc89,stc12a,stc12,stc15a,stc15}, --protocol {stc89,stc12a,stc12,stc15a,stc15} protocol version -p PORT, --port PORT serial port device -b BAUD, --baud BAUD transfer baud rate (default: 19200) -l HANDSHAKE, --handshake HANDSHAKE handshake baud rate (default: 2400) -o OPTION, --option OPTION set option (can be used multiple times) -t TRIM, --trim TRIM RC oscillator frequency in kHz (STC15 series only) -D, --debug enable debug output ``` Most importantly, ```-p``` sets the serial port to be used for programming. ### Protocols STC MCUs use a variety of related but incompatible protocols for the BSL. The protocol must be specified with the ```-P``` flag. Here's the general mapping between protocols and MCU series: * ```stc89``` STC 89/90 series * ```stc12a``` STC12Cx052AD and possibly others * ```stc12``` Most STC10/11/12 series * ```stc15a``` STC15x104E and STC15x204E(A) series * ```stc15``` Most STC15 series The text files in the doc/ subdirectory provide an overview over the reverse engineered protocols used by the BSLs. For more details, please read the source code. ### Getting MCU information Call stcgal without any file to program. It will dump information about the MCU, e.g.: ``` $ ./stcgal.py -P stc15 Waiting for MCU, please cycle power: done Target model: Name: IAP15F2K61S2 Magic: F449 Code flash: 61.0 KB EEPROM flash: 0.0 KB Target frequency: 11.054 MHz Target BSL version: 7.1S Target options: reset_pin_enabled=False clock_source=internal clock_gain=high watchdog_por_enabled=False watchdog_stop_idle=True watchdog_prescale=256 low_voltage_reset=True low_voltage_threshold=3 eeprom_lvd_inhibit=True eeprom_erase_enabled=False bsl_pindetect_enabled=False power_on_reset_delay=long rstout_por_state=high uart_passthrough=False uart_pin_mode=normal Disconnected! ``` ### Program the flash memory Please note that stcgal only handles raw binary encoded files at this point. You can easily convert common Intel HEX files with ```objcopy -I ihex -O binary input.hex output.bin```. Call stcgal just like before, but provide the path to the code binary: ``` $ ./stcgal.py -P stc15 hello.bin Waiting for MCU, please cycle power: done Target model: Name: IAP15F2K61S2 Magic: F449 Code flash: 61.0 KB EEPROM flash: 0.0 KB Target frequency: 11.054 MHz Target BSL version: 7.1S Target options: reset_pin_enabled=False clock_source=internal clock_gain=high watchdog_por_enabled=False watchdog_stop_idle=True watchdog_prescale=256 low_voltage_reset=True low_voltage_threshold=3 eeprom_lvd_inhibit=True eeprom_erase_enabled=False bsl_pindetect_enabled=False power_on_reset_delay=long rstout_por_state=high uart_passthrough=False uart_pin_mode=normal Trimming frequency: 11.104 MHz Switching to 19200 baud: done Erasing flash: done Writing 256 bytes: .... done Setting options: done Target UID: 0D000021022632 Disconnected! ``` You can also program the EEPROM part of the memory, if applicable. Add the EEPROM binary to the commandline after the code binary. stcgal uses a conservative baud rate of 19200 bps by default. Programming can be sped up by choosing a faster baud rate with the flag ```-b```. ### Device options stcgal dumps a number of target options. These can be modified as well. Provide one (or more) ```-o``` flags followed by a key-value pair on the commandline to adjust these settings. For instance, you can enable the external crystal as clock source: ``` $ ./stcgal.py -P stc15 -o clock_source=external hello.bin ``` Detailed documentation for the settings is not available yet. However, most settings should be self-explaining. Otherwise, please refer to STC-ISP and the datasheets. Please note that device options can only be set when flash memory is programmed! ### Frequency trimming If the internal RC oscillator is used (```clock_source=internal```), stcgal can execute a trim procedure to adjust it to a given value. This is only supported by STC15 series. The trim values are stored with device options. Use the ```-t``` flag to request trimming to a certain value. Generally, frequencies between 4 and 35 MHz can be achieved. If trimming fails, stcgal will abort. License ------- stcgal is published under the MIT license.