Skip to content

Commit

Permalink
Updated documentation and fixed a few details
Browse files Browse the repository at this point in the history
  • Loading branch information
Vincent DEFERT committed Jun 2, 2023
1 parent ef06e31 commit 6254494
Show file tree
Hide file tree
Showing 4 changed files with 45 additions and 23 deletions.
34 changes: 23 additions & 11 deletions doc/USAGE.md
View file
Expand Up @@ -4,30 +4,33 @@ Usage
Call stcgal with ```-h``` for usage information.

```
usage: stcgal.py [-h] [-a] [-r RESETCMD]
[-P {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,usb15,auto}]
[-p PORT] [-b BAUD] [-l HANDSHAKE] [-o OPTION] [-t TRIM] [-D]
[-V]
[code_image] [eeprom_image]
usage: stcgal [-h] [-e] [-a] [-A {dtr,rts}] [-r RESETCMD]
[-P {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,stc8d,stc8g,usb15,auto}]
[-p PORT] [-b BAUD] [-l HANDSHAKE] [-o OPTION] [-t TRIM] [-D]
[-V]
[code_image] [eeprom_image]
stcgal 1.5 - an STC MCU ISP flash tool
stcgal 1.7 - an STC MCU ISP flash tool
(C) 2014-2018 Grigori Goronzy and others
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:
options:
-h, --help show this help message and exit
-e, --erase only erase flash memory
-a, --autoreset cycle power automatically by asserting DTR
-A {dtr,rts}, --resetpin {dtr,rts}
pin to hold down when using --autoreset (default: DTR)
-r RESETCMD, --resetcmd RESETCMD
shell command for board power-cycling (instead of DTR
assertion)
-P {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,usb15,auto}, --protocol {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,usb15,auto}
-P {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,stc8d,stc8g,usb15,auto}, --protocol {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,stc8d,stc8g,usb15,auto}
protocol version (default: auto)
-p PORT, --port PORT serial port device
-b BAUD, --baud BAUD transfer baud rate (default: 19200)
-b BAUD, --baud BAUD transfer baud rate (default: 115200)
-l HANDSHAKE, --handshake HANDSHAKE
handshake baud rate (default: 2400)
-o OPTION, --option OPTION
Expand All @@ -40,6 +43,12 @@ optional arguments:

Most importantly, ```-p``` sets the serial port to be used for programming.

### Transfer baud rate

The default value of 115200 Baud is supported by all MCU starting with
the STC15 family, and at least the STC12C5A56S2 before that. For older
MCU, you might have to use ```-b 19200``` for correct operation.

### Protocols

STC MCUs use a variety of related but incompatible protocols for the
Expand All @@ -49,12 +58,15 @@ and MCU series is as follows:

* ```auto``` Automatic detection of UART based protocols (default)
* ```stc89``` STC89/90 series
* ```stc89a``` STC89/90 series (BSL 7.2.5C)
* ```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
* ```stc8``` STC8A8K64S4A12 and STC8F series
* ```stc8d``` All STC8 and STC32 series
* ```stc8g``` STC8G1 and STC8H1 series
* ```usb15``` USB support on STC15W4 series

The text files in the doc/reverse-engineering subdirectory provide an
Expand Down Expand Up @@ -242,4 +254,4 @@ 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.
the USB protocol. RC frequency trimming is not supported.
28 changes: 19 additions & 9 deletions doc/zh_CN/USAGE.md
View file
Expand Up @@ -14,13 +14,13 @@ Last modified time: June 8, 2020
使用 ```-h``` 调用stcgal以获取使用信息。（'//'后面是翻译，实际使用过程中没有后面内容）

```
usage: stcgal.py [-h] [-a] [-r RESETCMD]
[-P {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,usb15,auto}]
[-p PORT] [-b BAUD] [-l HANDSHAKE] [-o OPTION] [-t TRIM] [-D]
[-V]
[code_image] [eeprom_image]
usage: stcgal [-h] [-e] [-a] [-A {dtr,rts}] [-r RESETCMD]
[-P {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,stc8d,stc8g,usb15,auto}]
[-p PORT] [-b BAUD] [-l HANDSHAKE] [-o OPTION] [-t TRIM] [-D]
[-V]
[code_image] [eeprom_image]
stcgal 1.5 - an STC MCU ISP flash tool
stcgal 1.7 - an STC MCU ISP flash tool
(C) 2014-2018 Grigori Goronzy and others
https://github.com/grigorig/stcgal
Expand All @@ -31,13 +31,15 @@ positional arguments:
optional arguments:
-h, --help show this help message and exit //显示此帮助消息并退出
-a, --autoreset cycle power automatically by asserting DTR//断言DTR自动重启电源
-A {dtr,rts}, --resetpin {dtr,rts}
pin to hold down when using --autoreset (default: DTR)
-r RESETCMD, --resetcmd RESETCMD
shell command for board power-cycling (instead of DTR //用于板上电重启的shell命令（而不是DTR断言）
assertion)
-P {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,usb15,auto}, --protocol {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,usb15,auto}
-P {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,stc8d,stc8g,usb15,auto}, --protocol {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,stc8d,stc8g,usb15,auto}
protocol version (default: auto) //协议版本（芯片系列）（在默认状态为auto）
-p PORT, --port PORT serial port device //串口设备
-b BAUD, --baud BAUD transfer baud rate (default: 19200) //传输波特率（默认值：19200）
-b BAUD, --baud BAUD transfer baud rate (default: 115200) //传输波特率（默认值：115200）
-l HANDSHAKE, --handshake HANDSHAKE
handshake baud rate (default: 2400) //握手波特率（默认值：2400）
-o OPTION, --option OPTION
Expand All @@ -50,19 +52,27 @@ optional arguments:

最重要的是， ```-p``` 设置用于编程的串行端口。

### 传输波特率

所有从 STC15 系列开始的 MCU 都支持默认值 115200 波特，至少是之前的 STC12C5A56S2。
对于较旧的 MCU，您可能必须使用 ```-b 19200``` 才能正确操作。

### 通讯协议与规定

STC MCU对BSL使用各种相关但不兼容的协议。协议可以用```-P``` 标志来指定。
默认情况下，使用UART协议自动检测。协议与MCU系列的对应关系如下：

* ```auto``` 自动检测基于UART的协议（默认）
* ```stc89``` STC89/90 系列
* ```stc89a``` STC89/90 系列（BSL 7.2.5C）
* ```stc12a``` STC12x052 系列和其他类似系列
* ```stc12b``` STC12x52 系列, STC12x56 系列和其他类似系列
* ```stc12``` 多数 STC10/11/12 系列
* ```stc15a``` STC15x104E 和 STC15x204E(A) 系列
* ```stc15``` 多数 STC15 系列
* ```stc8``` STC8 系列
* ```stc8``` STC8A8K64S4A12 和 STC8F 系列
* ```stc8d``` 所有 STC8 和 STC32 系列
* ```stc8g``` STC8G1 和 STC8H1 系列
* ```usb15``` 支持USB的STC15W4系列

doc / reverse-engineering子目录中的文本文件提供了BSL使用的反向工程协议的概述。
Expand Down
4 changes: 2 additions & 2 deletions stcgal/frontend.py
View file
Expand Up @@ -266,9 +266,9 @@ def cli():
choices=["dtr", "rts"], default="dtr")
parser.add_argument("-r", "--resetcmd", help="shell command for board power-cycling (instead of DTR assertion)", action="store")
parser.add_argument("-P", "--protocol", help="protocol version (default: auto)",
choices=["stc89", "stc12a", "stc12b", "stc12", "stc15a", "stc15", "stc8", "stc8d", "stc8g", "usb15", "auto"], default="auto")
choices=["stc89", "stc89a", "stc12a", "stc12b", "stc12", "stc15a", "stc15", "stc8", "stc8d", "stc8g", "usb15", "auto"], default="auto")
parser.add_argument("-p", "--port", help="serial port device", default="/dev/ttyUSB0")
parser.add_argument("-b", "--baud", help="transfer baud rate (default: 19200)", type=BaudType(), default=115200)
parser.add_argument("-b", "--baud", help="transfer baud rate (default: 115200)", type=BaudType(), default=115200)
parser.add_argument("-l", "--handshake", help="handshake baud rate (default: 2400)", type=BaudType(), default=2400)
parser.add_argument("-o", "--option", help="set option (can be used multiple times, see documentation)", action="append")
parser.add_argument("-t", "--trim", help="RC oscillator frequency in kHz (STC15+ series only)", type=float, default=0.0)
Expand Down
2 changes: 1 addition & 1 deletion stcgal/protocols.py
View file
Expand Up @@ -391,7 +391,7 @@ def initialize_model(self):
("stc15a", r"(STC|IAP)15[FL][012]0\d(E|EA|)$"),
("stc15", r"(STC|IAP|IRC)15\D"),
("stc8d", r"STC8H(3|4|8)K"),
("stc8d", r"STC32G"),
("stc8d", r"STC32"),
("stc8d", r"STC8A8K\d\dD4"),
("stc8g", r"STC8H"),
("stc8g", r"STC8G"),
Expand Down

0 comments on commit 6254494

Please sign in to comment.