Merge branch 'better-docs'
This commit is contained in:
Grigori Goronzy
commit
b0e882ff32
293
README.md
293
README.md
@ -3,8 +3,8 @@
|
||||
stcgal - STC MCU ISP 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].
|
||||
stcgal is a command line flash programming tool for [STC MCU Ltd](http://stcmcu.com/).
|
||||
8051 compatible microcontrollers.
|
||||
|
||||
STC microcontrollers have an UART/USB based boot strap loader (BSL). It
|
||||
utilizes a packet-based protocol to flash the code memory and IAP
|
||||
@ -17,45 +17,10 @@ stcgal is a full-featured Open Source replacement for STC's Windows
|
||||
software; it supports a wide range of MCUs, 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. Support for STC8 series MCUs is work in progress.
|
||||
|
||||
So far, stcgal was tested with the following MCU models:
|
||||
|
||||
* STC89C52RC (BSL version: 4.3C/6.6C)
|
||||
* STC90C52RC (BSL version: 4.3C)
|
||||
* STC89C54RD+ (BSL version: 4.3C)
|
||||
* STC12C2052 (BSL version: 5.8D)
|
||||
* STC12C2052AD (BSL version: 5.8D)
|
||||
* STC12C5608AD (BSL version: 6.0G)
|
||||
* STC12C5A16S2 (BSL version: 6.2I)
|
||||
* STC12C5A60S2 (BSL version: 6.2I/7.1I)
|
||||
* STC11F02E (BSL version: 6.5K)
|
||||
* STC10F04XE (BSL version: 6.5J)
|
||||
* STC11F08XE (BSL version: 6.5M)
|
||||
* STC12C5204AD (BSL version: 6.6H)
|
||||
* STC15F104E (BSL version: 6.7Q)
|
||||
* STC15F204EA (BSL version: 6.7R)
|
||||
* STC15L104W (BSL version: 7.1.4Q)
|
||||
* STC15F104W (BSL version: 7.1.4Q)
|
||||
* IAP15F2K61S2 (BSL version: 7.1.4S)
|
||||
* STC15L2K16S2 (BSL version: 7.2.4S)
|
||||
* IAP15L2K61S2 (BSL version: 7.2.5S)
|
||||
* STC15W408AS (BSL version: 7.2.4T)
|
||||
* STC15W4K56S4 (BSL version: 7.3.4T, UART and USB mode)
|
||||
* STC8A8K64S4A12 (BSL version: 7.3.9U)
|
||||
* STC8F2K08S2 (BSL version: 7.3.10U)
|
||||
|
||||
Compatibility reports, both negative and positive, are welcome.
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
* Support for STC 89/90/10/11/12/15/8 series
|
||||
* UART and USB BSL support
|
||||
* Display part info
|
||||
* Determine operating frequency
|
||||
@ -67,256 +32,16 @@ Features
|
||||
* Automatic power-cycling with DTR toggle or a custom shell command
|
||||
* Automatic UART protocol detection
|
||||
|
||||
Installation
|
||||
------------
|
||||
Further information
|
||||
-------------------
|
||||
|
||||
stcgal requires Python 3.2 (or later) and pySerial. USB support is
|
||||
optional and requires pyusb 1.0.0b2 or later. You can run stcgal
|
||||
directly with the included ```stcgal.py``` script. The recommended
|
||||
method for permanent installation is to use Python's setuptools. Run
|
||||
```./setup.py build``` to build and ```sudo ./setup.py install```
|
||||
to install stcgal. A permanent installation provides the ```stcgal```
|
||||
command.
|
||||
[Installation](doc/INSTALL.md)
|
||||
|
||||
Usage
|
||||
-----
|
||||
[How to use stcgal](doc/USAGE.md)
|
||||
|
||||
Call stcgal with ```-h``` for usage information.
|
||||
[Frequently Asked Questions](doc/FAQ.md)
|
||||
|
||||
```
|
||||
usage: stcgal.py [-h] [-a] [-P {stc89,stc12a,stc12,stc15a,stc15,auto}]
|
||||
[-p PORT] [-b BAUD] [-l HANDSHAKE] [-o OPTION] [-t TRIM] [-D]
|
||||
[code_image] [eeprom_image]
|
||||
|
||||
stcgal 1.0 - an STC MCU ISP flash tool
|
||||
(C) 2014-2015 Grigori Goronzy
|
||||
https://github.com/grigorig/stcgal
|
||||
|
||||
positional arguments:
|
||||
code_image code segment file to flash (BIN/HEX)
|
||||
eeprom_image eeprom segment file to flash (BIN/HEX)
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
-a, --autoreset cycle power automatically by asserting DTR
|
||||
-r RESETCMD, --resetcmd RESETCMD
|
||||
Use this shell command for board power-cycling
|
||||
(instead of DTR assertion)
|
||||
-P {stc89,stc12a,stc12,stc15a,stc15,auto}, --protocol {stc89,stc12a,stc12,stc15a,stc15,auto}
|
||||
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 can be specified with the ```-P``` flag. By default
|
||||
UART protocol autodetection is used. The mapping between protocols
|
||||
and MCU series is as follows:
|
||||
|
||||
* ```stc89``` STC89/90 series
|
||||
* ```stc12a``` STC12x052 series and possibly others
|
||||
* ```stc12b``` STC12x52 series, STC12x56 series and possibly others
|
||||
* ```stc12``` Most STC10/11/12 series
|
||||
* ```stc15a``` STC15x104E and STC15x204E(A) series
|
||||
* ```stc15``` Most STC15 series
|
||||
* ```stc8``` STC8 series
|
||||
* ```usb15``` USB support on STC15W4 series
|
||||
* ```auto``` Automatic detection of UART based protocols (default)
|
||||
|
||||
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: 10.046 MHz
|
||||
Target BSL version: 7.1S
|
||||
Target wakeup frequency: 34.771 KHz
|
||||
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
|
||||
por_reset_delay=long
|
||||
rstout_por_state=high
|
||||
uart2_passthrough=False
|
||||
uart2_pin_mode=normal
|
||||
Disconnected!
|
||||
```
|
||||
|
||||
### Program the flash memory
|
||||
|
||||
stcgal supports Intel HEX encoded files as well as binary files. Intel
|
||||
HEX is autodetected by file extension (.hex, .ihx or .ihex).
|
||||
|
||||
Call stcgal just like before, but provide the path to the code image:
|
||||
|
||||
```
|
||||
$ ./stcgal.py -P stc15 hello.hex
|
||||
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: 10.046 MHz
|
||||
Target BSL version: 7.1S
|
||||
Target wakeup frequency: 34.771 KHz
|
||||
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
|
||||
por_reset_delay=long
|
||||
rstout_por_state=high
|
||||
uart2_passthrough=False
|
||||
uart2_pin_mode=normal
|
||||
Loading flash: 80 bytes (Intel HEX)
|
||||
Trimming frequency: 10.046 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 image path to the commandline after the flash image path.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
Please note that device options can only be set when flash memory is
|
||||
programmed!
|
||||
|
||||
#### Option keys
|
||||
|
||||
Not all parts support all options. The protocols or parts that support each option are listed in the description.
|
||||
|
||||
Option key | Possible values | Protocols/Models | Description
|
||||
------------------------------|-------------------|---------------------|------------
|
||||
```cpu_6t_enabled``` | true/false | STC89 only | 6T fast mode
|
||||
```bsl_pindetect_enabled``` | true/false | All | BSL only enabled when P3.2/P3.3 or P1.0/P1.1 (depends on model) are low
|
||||
```eeprom_erase_enabled``` | true/false | All | Erase EEPROM with next programming cycle
|
||||
```clock_gain``` | low/high | All with XTAL pins | Clock gain for external crystal
|
||||
```ale_enabled``` | true/false | STC89 only | ALE pin enabled if true, normal GPIO if false
|
||||
```xram_enabled``` | true/false | STC89 only | Use internal XRAM (STC89 only)
|
||||
```watchdog_por_enabled``` | true/false | All | Watchdog state after power-on reset (POR)
|
||||
```low_voltage_reset``` | low/high | STC12A/STC12 | Low-voltage reset level (low: ~3.3V, high: ~3.7V)
|
||||
```low_voltage_reset``` | true/false | STC12 | Enable RESET2 pin low voltage detect
|
||||
```low_voltage_reset``` | true/false | STC15A | Enable low-voltage reset (brownout)
|
||||
```clock_source``` | internal/external | STC12A+ with XTAL | Use internal (RC) or external (crystal) clock
|
||||
```watchdog_stop_idle``` | true/false | STC12A+ | Stop watchdog in IDLE mode
|
||||
```watchdog_prescale``` | 2,4,8,...,256 | STC12A+ | Watchdog timer prescaler, must be a power of two.
|
||||
```reset_pin_enabled``` | true/false | STC12+ | RESET pin enabled if true, normal GPIO if false
|
||||
```oscillator_stable_delay``` | 4096,...,32768 | STC11F series only | Crystal stabilization delay in clocks. Must be a power of two.
|
||||
```por_reset_delay``` | short/long | STC12+ | Power-on reset (POR) delay
|
||||
```low_voltage_threshold``` | 0...7 | STC15A+ | Low-voltage detection threshold. Model specific.
|
||||
```eeprom_lvd_inhibit``` | true/false | STC15A+ | Ignore EEPROM writes in low-voltage situations
|
||||
```rstout_por_state``` | low/high | STC15+ | RSTOUT/RSTSV pin state after power-on reset
|
||||
```uart1_remap``` | true/false | STC8 | Remap UART1 pins (P3.0/P3.1) to UART2 pins (P3.6/P3.7)
|
||||
```uart2_passthrough``` | true/false | STC15+ | Pass-through UART1 to UART2 pins (for single-wire UART mode)
|
||||
```uart2_pin_mode``` | push-pull/normal | STC15+ | Output mode of UART2 TX pin
|
||||
```cpu_core_voltage``` | low/mid/high | STC15W+ | CPU core voltage (low: ~2.7V, mid: ~3.3V, high: ~3.6V)
|
||||
```epwm_open_drain``` | true/false | STC8 | Use open-drain pin mode for EPWM pins after power-on reset
|
||||
```program_eeprom_split``` | 512 - 65024 | STC8A8 w/ 64 KB | Select split between code flash and EEPROM flash (in 512 byte blocks)
|
||||
|
||||
### 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 and newer. 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.
|
||||
|
||||
### Automatic power-cycling
|
||||
|
||||
STC's microcontrollers require a power-on reset to invoke the bootloader,
|
||||
which can be inconvenient. stcgal can use the DTR control signal of a
|
||||
serial interface to automate this. The DTR signal is asserted for
|
||||
approximately 500 ms when the autoreset feature is enabled with the
|
||||
```-a``` flag. This requires external circuitry to actually switch the
|
||||
power. In some cases, when the microcontroller draws only little power,
|
||||
it is possible to directly supply power from the DTR signal.
|
||||
|
||||
As an alternative to DTR, you can use a custom shell command or an external
|
||||
script (via -r option) to reset the device. You should specify the command
|
||||
along with -a option. Do not forget the quotes!
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
$ ./stcgal.py -P stc15 -a -r "echo 1 > /sys/class/gpio/gpio666/value"
|
||||
```
|
||||
or
|
||||
|
||||
```
|
||||
$ ./stcgal.py -P stc15 -a -r "./powercycle.sh"
|
||||
```
|
||||
|
||||
### Exit status
|
||||
|
||||
The exit status is 0 if no error occured while executing stcgal. Any
|
||||
error, such as a protocol error or I/O error, results in an exit
|
||||
status of 1. If the the user aborted stcgal by pressing CTRL-C,
|
||||
that results in an exit status of 2.
|
||||
|
||||
### USB support
|
||||
|
||||
STC15W4 series have an USB-based BSL that can be optionally
|
||||
used. USB support in stcgal is experimental and might change in the
|
||||
future. USB mode is enabled by using the ```usb15``` protocol. The
|
||||
port (```-p```) flag as well as the baudrate options are ignored for
|
||||
the USB protocol. RC frequency trimming is not supported.
|
||||
[List of tested MCU models](doc/MODELS.md)
|
||||
|
||||
License
|
||||
-------
|
||||
|
||||
68
doc/FAQ.md
Normal file
68
doc/FAQ.md
Normal file
@ -0,0 +1,68 @@
|
||||
Frequently Asked Questions
|
||||
==========================
|
||||
|
||||
### Is it possible to read code (or EEPROM) memory out of a chip?
|
||||
|
||||
By design, this is not possible with STC's bootloader protocols. This is considered a security feature by STC. There is no known workaround at this time. See issue #7 for more details and discussion.
|
||||
|
||||
### Which serial interfaces have been tested with stcgal?
|
||||
|
||||
The following USB-based UART interface chips have been successfully tested with stcgal:
|
||||
|
||||
* FT232 family (OS: Linux, Windows)
|
||||
* CH340/CH341 (OS: Windows, Linux requires Kernel 4.10)
|
||||
* PL2303 (OS: Windows, Linux)
|
||||
* CP2102 (OS: Windows, Linux, macOS)
|
||||
|
||||
Interfaces that are known to not work:
|
||||
|
||||
* Raspberry Pi Mini UART (lacks parity support, enable the PL011 UART instead)
|
||||
|
||||
In general, stcgal requires accurate baud rate timings and parity support.
|
||||
|
||||
### stcgal fails to recognize the MCU and is stuck at "Waiting for MCU"
|
||||
|
||||
There are a number of issues that can result in this symptom:
|
||||
|
||||
* Electrical issues and wrong connections. Make sure that RX/TX, GND and VCC are connected correctly. If you do not use the autoreset feature, also make sure to connect power only after stcgal starts, as the bootloader is only invoked on power-on reset.
|
||||
* Parasitic powering through I/O pins. The MCU can be powered through I/O pins (such as RX/TX) even if VCC is not connected. In this case, the power-on reset logic does not work. See next question.
|
||||
* Serial interface incompatibilities. Some USB-based UARTs have bad compatibility with STC MCUs for various reasons. You can try to lower the handshake baudrate from the standard 2400 baud to 1200 baud with the option `-l 1200`, which works around these issues in some cases.
|
||||
|
||||
### How can I avoid parasitic powering?
|
||||
|
||||
Various remedies are possible to avoid parasitic powering.
|
||||
|
||||
* You can try to connect a resistor (< 1k) between MCU VCC and GND to short-circuit injected power and hopefully drop the voltage below the brown-out value.
|
||||
* Another option is to insert series resistor on I/O lines that might inject power. Try a value like 1k on the RX/TX lines, for instance.
|
||||
* Yet another possibility is to switch GND instead of VCC. This should be a fairly reliable solution in most cases.
|
||||
|
||||
### RC frequency trimming fails
|
||||
|
||||
First, make sure that the frequency specified uses the correct unit. The frequency is specified in kHz and the safe range is approximately 5000 kHz - 30000 kHz. Furthermore, frequency trimming uses the UART clock as the clock reference, so UART incompatibilities or clock inaccuracies can also result in issues with frequency trimming. If possible, try another UART chip.
|
||||
|
||||
### Baud rate switching fails
|
||||
|
||||
This can especially happen at high programming baud rates, e.g. 115200 baud. Try a lower baudrate, or stick to the default of 19200 baud. Some USB UARTs are known to cause problems due to inaccurate timing as well, which can lead to various issues.
|
||||
|
||||
### How can I use the autoreset feature?
|
||||
|
||||
The standard autoreset feature works somewhat similarly to Arduino. DTR is an active low signal, and is asserted on startup of stcgal for 500 ms and then deasserted for the rest of the programming sequence. On a standard USB UART, this results in 500 ms low pulse, followed by a high phase. The stcgal author recommends the following circuit:
|
||||
|
||||
```
|
||||
VCC --o o-- MCU GND
|
||||
| |
|
||||
.-. |
|
||||
| | 1k |
|
||||
| | |
|
||||
'_' |
|
||||
| |
|
||||
| ||-+
|
||||
DTR --o --||<- BS170/BSS138
|
||||
||-| (N-CH MOSFET)
|
||||
|
|
||||
|
|
||||
GND ---------o
|
||||
```
|
||||
|
||||
This circuit uses an N-channel MOSFET as a low-side switch to switch the MCU's GND. VCC is directly connected. This avoids parasitic powering issues. The pull-up resistor ensures that the MCU is switched on when the DTR input is floating.
|
||||
|
||||
10
doc/INSTALL.md
Normal file
10
doc/INSTALL.md
Normal file
@ -0,0 +1,10 @@
|
||||
Installation
|
||||
============
|
||||
|
||||
stcgal requires Python 3.2 (or later) and pySerial. USB support is
|
||||
optional and requires pyusb 1.0.0b2 or later. You can run stcgal
|
||||
directly with the included ```stcgal.py``` script. The recommended
|
||||
method for permanent installation is to use Python's setuptools. Run
|
||||
```./setup.py build``` to build and ```sudo ./setup.py install```
|
||||
to install stcgal. A permanent installation provides the ```stcgal```
|
||||
command.
|
||||
32
doc/MODELS.md
Normal file
32
doc/MODELS.md
Normal file
@ -0,0 +1,32 @@
|
||||
Supported MCU models
|
||||
====================
|
||||
|
||||
stcgal should fully support STC 89/90/10/11/12/15 series MCUs. Support for STC8 series MCUs is work in progress.
|
||||
|
||||
So far, stcgal was tested with the following MCU models:
|
||||
|
||||
* STC89C52RC (BSL version: 4.3C/6.6C)
|
||||
* STC90C52RC (BSL version: 4.3C)
|
||||
* STC89C54RD+ (BSL version: 4.3C)
|
||||
* STC12C2052 (BSL version: 5.8D)
|
||||
* STC12C2052AD (BSL version: 5.8D)
|
||||
* STC12C5608AD (BSL version: 6.0G)
|
||||
* STC12C5A16S2 (BSL version: 6.2I)
|
||||
* STC12C5A60S2 (BSL version: 6.2I/7.1I)
|
||||
* STC11F02E (BSL version: 6.5K)
|
||||
* STC10F04XE (BSL version: 6.5J)
|
||||
* STC11F08XE (BSL version: 6.5M)
|
||||
* STC12C5204AD (BSL version: 6.6H)
|
||||
* STC15F104E (BSL version: 6.7Q)
|
||||
* STC15F204EA (BSL version: 6.7R)
|
||||
* STC15L104W (BSL version: 7.1.4Q)
|
||||
* STC15F104W (BSL version: 7.1.4Q)
|
||||
* IAP15F2K61S2 (BSL version: 7.1.4S)
|
||||
* STC15L2K16S2 (BSL version: 7.2.4S)
|
||||
* IAP15L2K61S2 (BSL version: 7.2.5S)
|
||||
* STC15W408AS (BSL version: 7.2.4T)
|
||||
* STC15W4K56S4 (BSL version: 7.3.4T, UART and USB mode)
|
||||
* STC8A8K64S4A12 (BSL version: 7.3.9U)
|
||||
* STC8F2K08S2 (BSL version: 7.3.10U)
|
||||
|
||||
Compatibility reports, both negative and positive, are welcome.
|
||||
239
doc/USAGE.md
Normal file
239
doc/USAGE.md
Normal file
@ -0,0 +1,239 @@
|
||||
Usage
|
||||
=====
|
||||
|
||||
Call stcgal with ```-h``` for usage information.
|
||||
|
||||
```
|
||||
usage: stcgal.py [-h] [-a] [-P {stc89,stc12a,stc12,stc15a,stc15,auto}]
|
||||
[-p PORT] [-b BAUD] [-l HANDSHAKE] [-o OPTION] [-t TRIM] [-D]
|
||||
[code_image] [eeprom_image]
|
||||
|
||||
stcgal 1.0 - an STC MCU ISP flash tool
|
||||
(C) 2014-2015 Grigori Goronzy
|
||||
https://github.com/grigorig/stcgal
|
||||
|
||||
positional arguments:
|
||||
code_image code segment file to flash (BIN/HEX)
|
||||
eeprom_image eeprom segment file to flash (BIN/HEX)
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
-a, --autoreset cycle power automatically by asserting DTR
|
||||
-r RESETCMD, --resetcmd RESETCMD
|
||||
Use this shell command for board power-cycling
|
||||
(instead of DTR assertion)
|
||||
-P {stc89,stc12a,stc12,stc15a,stc15,auto}, --protocol {stc89,stc12a,stc12,stc15a,stc15,auto}
|
||||
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 can be specified with the ```-P``` flag. By default
|
||||
UART protocol autodetection is used. The mapping between protocols
|
||||
and MCU series is as follows:
|
||||
|
||||
* ```stc89``` STC89/90 series
|
||||
* ```stc12a``` STC12x052 series and possibly others
|
||||
* ```stc12b``` STC12x52 series, STC12x56 series and possibly others
|
||||
* ```stc12``` Most STC10/11/12 series
|
||||
* ```stc15a``` STC15x104E and STC15x204E(A) series
|
||||
* ```stc15``` Most STC15 series
|
||||
* ```stc8``` STC8 series
|
||||
* ```usb15``` USB support on STC15W4 series
|
||||
* ```auto``` Automatic detection of UART based protocols (default)
|
||||
|
||||
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: 10.046 MHz
|
||||
Target BSL version: 7.1S
|
||||
Target wakeup frequency: 34.771 KHz
|
||||
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
|
||||
por_reset_delay=long
|
||||
rstout_por_state=high
|
||||
uart2_passthrough=False
|
||||
uart2_pin_mode=normal
|
||||
Disconnected!
|
||||
```
|
||||
|
||||
### Program the flash memory
|
||||
|
||||
stcgal supports Intel HEX encoded files as well as binary files. Intel
|
||||
HEX is autodetected by file extension (.hex, .ihx or .ihex).
|
||||
|
||||
Call stcgal just like before, but provide the path to the code image:
|
||||
|
||||
```
|
||||
$ ./stcgal.py -P stc15 hello.hex
|
||||
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: 10.046 MHz
|
||||
Target BSL version: 7.1S
|
||||
Target wakeup frequency: 34.771 KHz
|
||||
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
|
||||
por_reset_delay=long
|
||||
rstout_por_state=high
|
||||
uart2_passthrough=False
|
||||
uart2_pin_mode=normal
|
||||
Loading flash: 80 bytes (Intel HEX)
|
||||
Trimming frequency: 10.046 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 image path to the commandline after the flash image path.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
Please note that device options can only be set when flash memory is
|
||||
programmed!
|
||||
|
||||
#### Option keys
|
||||
|
||||
Not all parts support all options. The protocols or parts that support each option are listed in the description.
|
||||
|
||||
Option key | Possible values | Protocols/Models | Description
|
||||
------------------------------|-------------------|---------------------|------------
|
||||
```cpu_6t_enabled``` | true/false | STC89 only | 6T fast mode
|
||||
```bsl_pindetect_enabled``` | true/false | All | BSL only enabled when P3.2/P3.3 or P1.0/P1.1 (depends on model) are low
|
||||
```eeprom_erase_enabled``` | true/false | All | Erase EEPROM with next programming cycle
|
||||
```clock_gain``` | low/high | All with XTAL pins | Clock gain for external crystal
|
||||
```ale_enabled``` | true/false | STC89 only | ALE pin enabled if true, normal GPIO if false
|
||||
```xram_enabled``` | true/false | STC89 only | Use internal XRAM (STC89 only)
|
||||
```watchdog_por_enabled``` | true/false | All | Watchdog state after power-on reset (POR)
|
||||
```low_voltage_reset``` | low/high | STC12A/STC12 | Low-voltage reset level (low: ~3.3V, high: ~3.7V)
|
||||
```low_voltage_reset``` | true/false | STC12 | Enable RESET2 pin low voltage detect
|
||||
```low_voltage_reset``` | true/false | STC15A | Enable low-voltage reset (brownout)
|
||||
```clock_source``` | internal/external | STC12A+ with XTAL | Use internal (RC) or external (crystal) clock
|
||||
```watchdog_stop_idle``` | true/false | STC12A+ | Stop watchdog in IDLE mode
|
||||
```watchdog_prescale``` | 2,4,8,...,256 | STC12A+ | Watchdog timer prescaler, must be a power of two.
|
||||
```reset_pin_enabled``` | true/false | STC12+ | RESET pin enabled if true, normal GPIO if false
|
||||
```oscillator_stable_delay``` | 4096,...,32768 | STC11F series only | Crystal stabilization delay in clocks. Must be a power of two.
|
||||
```por_reset_delay``` | short/long | STC12+ | Power-on reset (POR) delay
|
||||
```low_voltage_threshold``` | 0...7 | STC15A+ | Low-voltage detection threshold. Model specific.
|
||||
```eeprom_lvd_inhibit``` | true/false | STC15A+ | Ignore EEPROM writes in low-voltage situations
|
||||
```rstout_por_state``` | low/high | STC15+ | RSTOUT/RSTSV pin state after power-on reset
|
||||
```uart1_remap``` | true/false | STC8 | Remap UART1 pins (P3.0/P3.1) to UART2 pins (P3.6/P3.7)
|
||||
```uart2_passthrough``` | true/false | STC15+ | Pass-through UART1 to UART2 pins (for single-wire UART mode)
|
||||
```uart2_pin_mode``` | push-pull/normal | STC15+ | Output mode of UART2 TX pin
|
||||
```cpu_core_voltage``` | low/mid/high | STC15W+ | CPU core voltage (low: ~2.7V, mid: ~3.3V, high: ~3.6V)
|
||||
```epwm_open_drain``` | true/false | STC8 | Use open-drain pin mode for EPWM pins after power-on reset
|
||||
```program_eeprom_split``` | 512 - 65024 | STC8A8 w/ 64 KB | Select split between code flash and EEPROM flash (in 512 byte blocks)
|
||||
|
||||
### 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 and newer. 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.
|
||||
|
||||
### Automatic power-cycling
|
||||
|
||||
STC's microcontrollers require a power-on reset to invoke the bootloader,
|
||||
which can be inconvenient. stcgal can use the DTR control signal of a
|
||||
serial interface to automate this. The DTR signal is asserted for
|
||||
approximately 500 ms when the autoreset feature is enabled with the
|
||||
```-a``` flag. This requires external circuitry to actually switch the
|
||||
power. In some cases, when the microcontroller draws only little power,
|
||||
it is possible to directly supply power from the DTR signal.
|
||||
|
||||
As an alternative to DTR, you can use a custom shell command or an external
|
||||
script (via -r option) to reset the device. You should specify the command
|
||||
along with -a option. Do not forget the quotes!
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
$ ./stcgal.py -P stc15 -a -r "echo 1 > /sys/class/gpio/gpio666/value"
|
||||
```
|
||||
or
|
||||
|
||||
```
|
||||
$ ./stcgal.py -P stc15 -a -r "./powercycle.sh"
|
||||
```
|
||||
|
||||
### Exit status
|
||||
|
||||
The exit status is 0 if no error occured while executing stcgal. Any
|
||||
error, such as a protocol error or I/O error, results in an exit
|
||||
status of 1. If the the user aborted stcgal by pressing CTRL-C,
|
||||
that results in an exit status of 2.
|
||||
|
||||
### USB support
|
||||
|
||||
STC15W4 series have an USB-based BSL that can be optionally
|
||||
used. USB support in stcgal is experimental and might change in the
|
||||
future. USB mode is enabled by using the ```usb15``` protocol. The
|
||||
port (```-p```) flag as well as the baudrate options are ignored for
|
||||
the USB protocol. RC frequency trimming is not supported.
|
||||
Loading…
Reference in New Issue
Block a user