Update documentation

Minor updates and improvements to the documentation.

doc/USAGE.md

@@ -4,12 +4,14 @@ Usage
 Call stcgal with ```-h``` for usage information.
 
 ```
-usage: stcgal.py [-h] [-a] [-P {stc89,stc12a,stc12,stc15a,stc15,auto}]
+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]
 
-stcgal 1.0 - an STC MCU ISP flash tool
+stcgal 1.5 - an STC MCU ISP flash tool
-(C) 2014-2015 Grigori Goronzy
+(C) 2014-2018 Grigori Goronzy and others
 https://github.com/grigorig/stcgal
 
 positional arguments:
@@ -20,18 +22,20 @@ 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
+                        shell command for board power-cycling (instead of DTR
-                        (instead of DTR assertion)
+                        assertion)
-  -P {stc89,stc12a,stc12,stc15a,stc15,auto}, --protocol {stc89,stc12a,stc12,stc15a,stc15,auto}
+  -P {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,usb15,auto}, --protocol {stc89,stc12a,stc12b,stc12,stc15a,stc15,stc8,usb15,auto}
-                        protocol version
+                        protocol version (default: auto)
   -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)
+                        set option (can be used multiple times, see
-  -t TRIM, --trim TRIM  RC oscillator frequency in kHz (STC15 series only)
+                        documentation)
+  -t TRIM, --trim TRIM  RC oscillator frequency in kHz (STC15+ series only)
   -D, --debug           enable debug output
+  -V, --version         print version info and exit
 ```
 
 Most importantly, ```-p``` sets the serial port to be used for programming.
@@ -43,6 +47,7 @@ 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:
 
+* ```auto``` Automatic detection of UART based protocols (default)
 * ```stc89``` STC89/90 series
 * ```stc12a``` STC12x052 series and possibly others
 * ```stc12b``` STC12x52 series, STC12x56 series and possibly others
@@ -51,11 +56,10 @@ and MCU series is as follows:
 * ```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 text files in the doc/reverse-engineering subdirectory provide an
-the reverse engineered protocols used by the BSLs. For more details,
+overview over the reverse engineered protocols used by the BSLs. For
-please read the source code.
+more details, please read the source code.
 
 ### Getting MCU information
 
@@ -92,6 +96,8 @@ Target options:
 Disconnected!
 ```
 
+If the identification fails, see the [FAQ](FAQ.md) for troubleshooting.
+
 ### Program the flash memory
 
 stcgal supports Intel HEX encoded files as well as binary files. Intel
@@ -195,8 +201,8 @@ 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
+value. Generally, frequencies between 4000 and 30000 kHz can be achieved.
-trimming fails, stcgal will abort.
+If trimming fails, stcgal will abort.
 
 ### Automatic power-cycling
 

stcgal/frontend.py

@@ -226,14 +226,14 @@ def cli():
     parser.add_argument("code_image", help="code segment file to flash (BIN/HEX)", type=argparse.FileType("rb"), nargs='?')
     parser.add_argument("eeprom_image", help="eeprom segment file to flash (BIN/HEX)", type=argparse.FileType("rb"), nargs='?')
     parser.add_argument("-a", "--autoreset", help="cycle power automatically by asserting DTR", action="store_true")
-    parser.add_argument("-r", "--resetcmd",  help="Use this shell command for board power-cycling (instead of DTR assertion)", action="store")
+    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", "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=19200)
     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)", action="append")
+    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)
+    parser.add_argument("-t", "--trim", help="RC oscillator frequency in kHz (STC15+ series only)", type=float, default=0.0)
     parser.add_argument("-D", "--debug", help="enable debug output", action="store_true")
     parser.add_argument("-V", "--version", help="print version info and exit", action="store_true")
     opts = parser.parse_args()