Possible fix/workaround for OSX frequency trimming

This allows stcgal to be started with "python3 -m stcgal" or similar.
Addresses stcgal#24.

README.md

@@ -25,14 +25,14 @@ 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)
+* 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)
+* STC12C5A60S2 (BSL version: 6.2I/7.1I)
 * STC11F02E (BSL version: 6.5K)
 * STC10F04XE (BSL version: 6.5J)
 * STC11F08XE (BSL version: 6.5M)
@@ -111,17 +111,18 @@ 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. Optionally,
-experimental protocol autodetection can be used. The mapping between
-protocols and MCU series is as follows:
+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``` STC 89/90 series
-* ```stc12a``` STC12Cx052AD and possibly others
-* ```stc12``` Most STC10/11/12 series (default)
+* ```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
 * ```usb15``` USB support on STC15W4 series
-* ```auto``` Automatic detection of UART based protocols
+* ```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,

debian/changelog

@@ -1,3 +1,16 @@
+stcgal (1.3) unstable; urgency=low
+
+  * Update to 1.3
+
+ -- Grigori Goronzy <greg@chown.ath.cx>  Sat, 10 Jun 2017 10:01:07 +0200
+
+stcgal (1.2) unstable; urgency=low
+
+  * Update to 1.2
+  * Add optional python3-usb dependency
+
+ -- Grigori Goronzy <greg@chown.ath.cx>  Fri, 20 May 2016 03:21:25 +0200
+
 stcgal (1.0git) unstable; urgency=low
 
   * Initial Debianized Release

debian/control

@@ -10,17 +10,17 @@ X-Python3-Version: >= 3.2
 Package: stcgal
 Architecture: all
 Depends: ${misc:Depends}, python3, python3-serial
+Recommends: python3-usb (>= 1.0.0~b2)
 Description: STC MCU ISP flash tool
- stcgal is a command line flash programming tool for STC MCU Ltd. 8051
- compatible microcontrollers. The name was inspired by avrdude.
+ stcgal is a command line flash programming tool for STC MCU Ltd.
+ 8051 compatible microcontrollers. The name was inspired by avrdude.
  .
- STC microcontrollers have a UART based boot strap loader (BSL). It
- utilizes a packet-based protocol to flash the code memory and
- IAP memory over a serial link. This is referred to as in-system
- programming (ISP). 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.
+ STC microcontrollers have an UART/USB based boot strap loader (BSL). It
+ utilizes a packet-based protocol to flash the code memory and IAP
+ memory over a serial link. This is referred to as in-system programming
+ (ISP). 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 Open Source replacement for STC's Windows
  software; it supports a wide range of MCUs, it is very portable and

doc/stc15-usb-protocol.txt

@@ -0,0 +1,46 @@
+STC15 series USB ISP protocol
+=============================
+
+General principle
+-----------------
+
+- host does OUT and IN control transfers for write and read
+- IN transfer with wLength = 132, wValue = 0, wIndex = 0, bRequest = 0 are used for all reads
+- OUT transfers with with specific bRequest, wValue, wIndex are used for writes
+
+
+Packet coding
+-------------
+
+- packets from MCU
+  always start with 0x46 0xb9, similar to serial protocols
+  third byte is packet length, followed by data bytes
+  checksum at the end: 8 bit modular sum
+
+- packets from host
+  no header bytes
+  bRequest sets packet type
+  wValue, wIndex interpretation according to packet type
+  8 bit modular checksum for every 7 bytes, interleaved
+  
+- packet types derived from the serial protocol
+
+Specific packet information
+---------------------------
+
+- flash data
+  wIndex specifies write address
+  wValue is 0xa55a
+  bRequest is 0x22 for first packet, 0x02 for the following ones
+  unusually encoded: a total of 128 bytes per packet,
+  with every 7 byte checksummed in some way,
+  for a total of 18x7 byte segments and a final 2 byte segment
+  checksum: 8 bit modular sum
+
+- option packet
+  generally same as with serial protocol, some header stuff omitted
+  wIndex is 0
+  wValue is 0xa55a
+  bRequest is 4
+  seems to use the same checksumming scheme as flash writes
+

stcgal/__init__.py

@@ -1 +1 @@
-__version__ = "1.0"
+__version__ = "1.3"

stcgal/__main__.py

@@ -0,0 +1,27 @@
+#
+# Copyright (c) 2013-2015 Grigori Goronzy <greg@chown.ath.cx>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+
+import sys
+import stcgal.frontend
+
+if __name__ == "__main__":
+    sys.exit(stcgal.frontend.cli())

stcgal/frontend.py

@@ -37,6 +37,8 @@ class StcGal:
             self.protocol = Stc89Protocol(opts.port, opts.handshake, opts.baud)
         elif opts.protocol == "stc12a":
             self.protocol = Stc12AProtocol(opts.port, opts.handshake, opts.baud)
+        elif opts.protocol == "stc12b":
+            self.protocol = Stc12BProtocol(opts.port, opts.handshake, opts.baud)
         elif opts.protocol == "stc12":
             self.protocol = Stc12Protocol(opts.port, opts.handshake, opts.baud)
         elif opts.protocol == "stc15a":
@@ -190,11 +192,11 @@ class StcGal:
 def cli():
     # check arguments
     parser = argparse.ArgumentParser(formatter_class=argparse.RawDescriptionHelpFormatter,
-                                     description="stcgal %s - an STC MCU ISP flash tool\n(C) 2014-2015 Grigori Goronzy\nhttps://github.com/grigorig/stcgal" %stcgal.__version__)
+                                     description="stcgal %s - an STC MCU ISP flash tool\n(C) 2014-2017 Grigori Goronzy\nhttps://github.com/grigorig/stcgal" %stcgal.__version__)
     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("-P", "--protocol", help="protocol version", choices=["stc89", "stc12a", "stc12", "stc15a", "stc15", "usb15", "auto"], default="stc12")
+    parser.add_argument("-P", "--protocol", help="protocol version (default: auto)", choices=["stc89", "stc12a", "stc12b", "stc12", "stc15a", "stc15", "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)

stcgal/protocols.py

@@ -21,7 +21,7 @@
 #
 
 import serial
-import sys, os, time, struct, re
+import sys, os, time, struct, re, errno
 import argparse
 import collections
 from stcgal.models import MCUModelDatabase
@@ -114,7 +114,11 @@ class StcBaseProtocol:
 
         # read and check frame start magic
         packet = bytes()
-        packet += self.read_bytes_safe(1)
+        # XXX: skip extraneous 0xFE byte?
+        leading = self.read_bytes_safe(1)
+        if leading == 0xfe:
+            leading = self.read_bytes_safe(1)
+        packet += leading
         # Some (?) BSL versions don't send a frame start with the status
         # packet. Let's be liberal and accept that always, just in case.
         if packet[0] == self.PACKET_MCU[0]:
@@ -194,6 +198,7 @@ class StcBaseProtocol:
 
         protocol_database = [("stc89", "STC(89|90)(C|LE)\d"),
                              ("stc12a", "STC12(C|LE)\d052"),
+                             ("stc12b", "STC12(C|LE)(52|56)"),
                              ("stc12", "(STC|IAP)(10|11|12)\D"),
                              ("stc15a", "(STC|IAP)15[FL][01]0\d(E|EA|)$"),
                              ("stc15", "(STC|IAP|IRC)15\D")]
@@ -529,7 +534,37 @@ class Stc89Protocol(StcBaseProtocol):
         print("done")
 
 
-class Stc12AProtocol(Stc89Protocol):
+class Stc12AOptionsMixIn:
+    def program_options(self):
+        print("Setting options: ", end="")
+        sys.stdout.flush()
+        msr = self.options.get_msr()
+        packet = bytes([0x8d, msr[0], msr[1], msr[2], 0xff, msr[3]])
+        packet += struct.pack(">I", int(self.mcu_clock_hz))
+        packet += bytes([msr[3]])
+        packet += bytes([0xff, msr[0], msr[1], 0xff, 0xff, 0xff, 0xff, msr[2]])
+        packet += bytes([0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff])
+        packet += struct.pack(">I", int(self.mcu_clock_hz))
+        packet += bytes([0xff, 0xff, 0xff])
+
+        self.write_packet(packet)
+        response = self.read_packet()
+        if response[0] != 0x80:
+            raise StcProtocolException("incorrect magic in option packet")
+
+        # XXX: this is done by STC-ISP on newer parts. not sure why, but let's
+        # just replicate it, just to be sure.
+        if self.bsl_version >= 0x66:
+            packet = bytes([0x50])
+            self.write_packet(packet)
+            response = self.read_packet()
+            if response[0] != 0x10:
+                raise StcProtocolException("incorrect magic in option packet")
+
+        print("done")
+
+
+class Stc12AProtocol(Stc12AOptionsMixIn, Stc89Protocol):
 
     """countdown value for flash erase"""
     ERASE_COUNTDOWN = 0x0d
@@ -650,37 +685,34 @@ class Stc12AProtocol(Stc89Protocol):
             raise StcProtocolException("incorrect magic in erase packet")
         print("done")
 
+
+class Stc12OptionsMixIn:
     def program_options(self):
         print("Setting options: ", end="")
         sys.stdout.flush()
         msr = self.options.get_msr()
-        packet = bytes([0x8d, msr[0], msr[1], msr[2], 0xff, msr[3]])
-        packet += struct.pack(">I", int(self.mcu_clock_hz))
-        packet += bytes([msr[3]])
-        packet += bytes([0xff, msr[0], msr[1], 0xff, 0xff, 0xff, 0xff, msr[2]])
-        packet += bytes([0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff])
-        packet += struct.pack(">I", int(self.mcu_clock_hz))
-        packet += bytes([0xff, 0xff, 0xff])
+        # XXX: it's not 100% clear if the index of msr[3] is consistent
+        # between devices, so write it to both indices.
+        packet = bytes([0x8d, msr[0], msr[1], msr[2], msr[3],
+                        0xff, 0xff, 0xff, 0xff, msr[3], 0xff,
+                        0xff, 0xff, 0xff, 0xff, 0xff, 0xff])
 
+        packet += struct.pack(">I", int(self.mcu_clock_hz))
         self.write_packet(packet)
         response = self.read_packet()
-        if response[0] != 0x80:
+        if response[0] != 0x50:
             raise StcProtocolException("incorrect magic in option packet")
-
-        # XXX: this is done by STC-ISP on newer parts. not sure why, but let's
-        # just replicate it, just to be sure.
-        if self.bsl_version >= 0x66:
-            packet = bytes([0x50])
-            self.write_packet(packet)
-            response = self.read_packet()
-            if response[0] != 0x10:
-                raise StcProtocolException("incorrect magic in option packet")
-
         print("done")
 
+        # If UID wasn't sent with erase acknowledge, it should be in this packet
+        if not self.uid:
+            self.uid = response[18:25]
 
-class Stc12Protocol(StcBaseProtocol):
-    """Protocol handler for STC 10/11/12 series"""
+        print("Target UID: %s" % Utils.hexstr(self.uid))
+
+
+class Stc12BaseProtocol(StcBaseProtocol):
+    """Base class for STC 10/11/12 series protocol handlers"""
 
     """block size for programming flash"""
     PROGRAM_BLOCKSIZE = 128
@@ -742,6 +774,8 @@ class Stc12Protocol(StcBaseProtocol):
         self.mcu_bsl_version = "%d.%d%s" % (bl_version >> 4, bl_version & 0x0f,
                                            chr(bl_stepping))
 
+        self.bsl_version = bl_version
+
     def calculate_baud(self):
         """Calculate MCU baudrate setting.
 
@@ -861,8 +895,6 @@ class Stc12Protocol(StcBaseProtocol):
             response = self.read_packet()
             if response[0] != 0x00:
                 raise StcProtocolException("incorrect magic in write packet")
-            elif response[1] != csum:
-                raise StcProtocolException("verification checksum mismatch")
             print(".", end="")
             sys.stdout.flush()
         print(" done")
@@ -877,28 +909,19 @@ class Stc12Protocol(StcBaseProtocol):
             raise StcProtocolException("incorrect magic in finish packet")
         print("done")
 
-    def program_options(self):
-        print("Setting options: ", end="")
-        sys.stdout.flush()
-        msr = self.options.get_msr()
-        # XXX: it's not 100% clear if the index of msr[3] is consistent
-        # between devices, so write it to both indices.
-        packet = bytes([0x8d, msr[0], msr[1], msr[2], msr[3],
-                        0xff, 0xff, 0xff, 0xff, msr[3], 0xff,
-                        0xff, 0xff, 0xff, 0xff, 0xff, 0xff])
 
-        packet += struct.pack(">I", int(self.mcu_clock_hz))
-        self.write_packet(packet)
-        response = self.read_packet()
-        if response[0] != 0x50:
-            raise StcProtocolException("incorrect magic in option packet")
-        print("done")
+class Stc12Protocol(Stc12OptionsMixIn, Stc12BaseProtocol):
+    """STC 10/11/12 series protocol handler"""
 
-        # If UID wasn't sent with erase acknowledge, it should be in this packet
-        if not self.uid:
-            self.uid = response[18:25]
+    def __init__(self, port, handshake, baud):
+        Stc12BaseProtocol.__init__(self, port, handshake, baud)
 
-        print("Target UID: %s" % Utils.hexstr(self.uid))
+
+class Stc12BProtocol(Stc12AOptionsMixIn, Stc12BaseProtocol):
+    """STC 10/11/12 variant protocol handler"""
+
+    def __init__(self, port, handshake, baud):
+        Stc12BaseProtocol.__init__(self, port, handshake, baud)
 
 
 class Stc15AProtocol(Stc12Protocol):
@@ -1274,7 +1297,7 @@ class Stc15Protocol(Stc15AProtocol):
         # This is a bit of a hack, but it works.
         bauds = self.baud_transfer if (self.mcu_magic >> 8) == 0xf2 else self.baud_transfer * 4
         packet += struct.pack(">H", int(65535 - program_speed / bauds))
-        packet += struct.pack(">H", int(65535 - (program_speed / bauds) * 1.5))
+        packet += bytes(user_trim)
         iap_wait = self.get_iap_delay(program_speed)
         packet += bytes([iap_wait])
         self.write_packet(packet)
@@ -1507,7 +1530,11 @@ class StcUsb15Protocol(Stc15Protocol):
                         self.status_packet = None
                         raise StcFramingException
                 else: raise StcFramingException
-            except (StcFramingException, usb.core.USBError): time.sleep(0.5)
+            except StcFramingException:
+                time.sleep(0.5)
+            except usb.core.USBError as err:
+                if err.errno == errno.EACCES:
+                    raise IOError(err.strerror)
 
         self.initialize_model()
         print("done")