stcgal Documentation

stcgal is an open-source replacement for STC's Windows programming software, designed for flashing STC MCU Ltd 8051-compatible microcontrollers via UART or USB BSL (Boot Strap Loader).

Key capabilities include:

• MCU Support: STC 89/90/10/11/12/15/8/32 series.
• Memory Programming: Flash memory and IAP/EEPROM programming.
• Device Configuration: Setting device options and trimming RC oscillator frequency (STC 15/8).
• Information Retrieval: Displaying part info, determining operating frequency, and reading unique device IDs (STC 10/11/12/15/8).
• Automation Features: Automatic UART protocol detection and automatic power-cycling via DTR toggle or custom shell commands.

stcgal is a command-line ISP (In-System Programming) flash tool for STC MCU Ltd microcontrollers. It is a fully-featured open-source alternative to the official STC Windows GUI programming software.

Key features include:

• Compatibility with 8051 microcontrollers.
• Support for various STC MCUs via UART/USB-based Bootloader (BSL).
• Ability to refresh code memory and IAP memory using the packet-based serial protocol.
• Support for configuring various device options.
• Portability, making it suitable for automated download/programming environments.

stcgal provides the following capabilities for STC microcontrollers:

• Supported Series: STC 89/90/10/11/12/15/8/32 series.
• Interface Support: UART and USB BSL.
• Programming: Program program flash and IAP/EEPROM.
• Device Configuration: Set device options and set RC oscillator frequency (specifically for STC 15/8).
• Information Retrieval: Read unique device IDs (STC 10/11/12/15/8) and determine working frequency.
• Automation Support: Automatic power control (using DTR switching or custom Shell command loops) and automatic UART protocol detection.

No. By design, STC's bootloader protocols do not allow reading back code flash memory as a security feature. There is no known workaround.

While some MCUs allow erasing code flash without erasing EEPROM (which could theoretically be used to create a custom EEPROM dump program), stcgal does not currently provide native support for this.

STC microcontrollers require a power cycle to enter the Bootloader (BSL). stcgal can automate this using the DTR signal on the serial interface via the -a flag.

Requirements:

• An external circuit must be present to actually switch the power based on the DTR signal.
• When using -a, the DTR signal is asserted for approximately 500 ms.

Alternative (Custom Reset Command): If you cannot use DTR, you can use the -r flag to provide a shell command or script to cycle the board power. You must use -a in conjunction with -r.

Examples:

# Using a shell command to toggle GPIO
$ ./stcgal.py -P stc15 -a -r "echo 1 > /sys/class/gpio/gpio666/value"

# Using an external script
$ ./stcgal.py -P stc15 -a -r "./powercycle.sh"

The STC15W4 series supports a USB-based BSL. In stcgal, this is an experimental feature enabled by using the usb15 protocol via the -P flag.

Note: When using usb15, the -p (port) and baudrate options are ignored, and RC frequency trimming is not supported.

# Use USB protocol for STC15W4
stcgal -P usb15 hello.hex

To see the full list of available commands, positional arguments, and optional flags, run the stcgal command with the -h or --help flag.

./stcgal.py -h

You can modify target device options (like clock source or watchdog settings) during the programming process by using the -o flag. Note that device options can only be set when flash memory is being programmed.

Example: Enabling an external crystal as the clock source:

./stcgal.py -P stc15 -o clock_source=external hello.bin

Parasitic powering occurs when the MCU is powered through I/O pins instead of VCC, which can interfere with the power-on reset required for the bootloader. Use one of these remedies:

• Shunt VCC to GND: Connect a resistor (< 1k) between MCU VCC and GND to drop the injected voltage below the brown-out threshold.
• Series Resistors: Insert a series resistor (e.g., 1k) on the RX/TX lines to limit injected current.
• GND Switching: Switch the GND line instead of the VCC line (recommended for reliability).

You can dump detailed information about a connected MCU (such as model name, magic number, flash sizes, target frequency, and current device options) by calling stcgal without providing any image files to flash. This is useful for verifying connection and checking current settings.

$ ./stcgal.py -P stc15

The autoreset feature uses the DTR signal (active low) to trigger a reset. Upon startup, stcgal asserts DTR for 500 ms. To avoid parasitic powering while using this feature, it is recommended to use an N-channel MOSFET (like BS170 or BSS138) as a low-side switch to toggle the MCU's GND.

VCC --o      o-- MCU GND
      |      |
     .-.     |
     | | 1k  |
     | |     |
     '_'     |
      |      |
      |   ||-+ 
DTR --o --||<- BS170/BSS138
          ||-| (N-CH MOSFET)
             |
             |
GND ---------o

To retrieve details about the connected MCU (such as model name, magic number, flash size, target frequency, and current device options), run stcgal without providing any image files.

If identification fails, check the project's FAQ for troubleshooting.

./stcgal.py -P stc15