updating readme, fixing help functions

Author: snhobbs

README.md

@@ -1,63 +1,84 @@
 # isp-programmer
 ISP Programmer for NXP Cortex-M Chips
 
-Command line programmer for the NXP ISP interface.
+Command-line tool for programming NXP microcontrollers via the UART ISP interface.
 
 ## Features
 ### Secure Write
-The checksum in flash is written to zero as the first write, so if the upload
-fails the chip will boot back into the ISP mode.
-The image is then written from the top most page down to the first page.
-The first sector contains the valid image checksum so a failed write will
-keep the device in ISP mode instead of just being bricked.
 
+To prevent bricking the chip during an interrupted write:
+
+- The checksum in flash is first set to zero, forcing the chip to boot into ISP mode if power is lost.
+- The image is then written from the topmost page down to the first page.
+- The first sector (which contains the valid checksum) is written last.
+
+This ensures that any failure during programming will leave the chip in ISP mode.
 
 ## Chip Families Supported:
++ LPC80x
+    + LPC802
+    + LPC804
++ LPC82x
+    + LPC822
+    + LPC824
 + LPC84x
-+  LPC82x
-+  LPC80x
+    + LPC844
+    + LPC845
+
+### Untested, expected to work
++ LPC81x
+    + LPC810
+    + LPC811
+    + LPC812
++ LPC83x
+    + LPC832
+    + LPC834
++ LPC86x
+    + LPC865
 
 Chips using UU-encoded protocols (e.g., LPC1700 family) are not supported.
-Other NXP devices with 1 kB sector sizes may work by adding their configuration to the lpctools_parts.def file.
+Other NXP devices with 1 kB sectors *may* work if added to the `lpctools_parts.def` file.
+
 The configuration file is identical to that used by the [lpctools project](http://git.techno-innov.fr/?p=lpctools).
 
-## Usage
-### Erase Entire Flash
+## Installation
+
+### From PyPI
+
 ```bash
-isp_programmer --device /dev/ttyUSB0 -b 9600 -crystal_frequency 12000 masserase
+pip install isp_programmer
 ```
 
-### Program Flash
+### From Source
 ```bash
-isp_programmer --device /dev/ttyUSB0 -b 9600 -crystal_frequency 12000 writeimage --imagein blinky804.hex
+git clone https://github.com/snhobbs/isp-programmer.git
+cd isp-programmer
+pip install .
 ```
 
-### Read Chip Info
+> Default chip definitions are bundled. For custom chips, use the --config-file flag or copy your lpctools_parts.def to /etc/lpctools_parts.def.
+
+
+## Usage
+### Erase Entire Flash
 ```bash
-isp_programmer --device /dev/ttyUSB0 -b 9600 -crystal_frequency 12000 querychip
+isp_programmer --device /dev/ttyUSB0 -b 9600 -crystal_frequency 12000 masserase
 ```
 
-## Installation
-### pypi
+### Program Flash Image
 ```bash
-pip install isp_programmer
+isp_programmer --device /dev/ttyUSB0 -b 9600 -crystal_frequency 12000 writeimage --imagein blinky804.hex
 ```
 
-### From Source
+### Read Chip Info
 ```bash
-git clone https://github.com/snhobbs/isp-programmer.git
-cd isp-programmer
-pip install .
+isp_programmer --device /dev/ttyUSB0 -b 9600 -crystal_frequency 12000 querychip
 ```
 
-The default location for the configuration file is at /etc/lpctools_parts.def.
-The file can either be copied there or the path passed in when calling the tool
-with the --config_file/-f flag. If none is given or found then the default parts are still available.
-
 ## Similar Projects
-+ https://github.com/JitterCompany/mxli
-+ https://github.com/idreamoferp/nxp_isp
-+ https://github.com/pzn1977/nxp_isp_loader
-+ https://github.com/laneboysrc/LPC81x-ISP-tool
-+ https://github.com/Senseg/lpc21isp
-+ https://github.com/ulfen/nxpprog
++ [MXLI by JitterCompany](https://github.com/JitterCompany/mxli)
++ [NXP ISP by idreamoferp](https://github.com/idreamoferp/nxp_isp)
++ [NXP ISP Loader by pzn1977](https://github.com/pzn1977/nxp_isp_loader)
++ [LPC81x ISP Tool by laneboysrc](https://github.com/laneboysrc/LPC81x-ISP-tool)
++ [LPC21ISP by Senseg](https://github.com/Senseg/lpc21isp)
++ [Nxpprog by ulfen](https://github.com/ulfen/nxpprog)

src/isp_programmer/cli.py

@@ -52,15 +52,15 @@ def gr1(ctx, **kwargs):
     _log.setLevel(level)
 
 
-@gr1.command("sync", help="Read the chip ID and boot code")
+@gr1.command("sync", help="Synchronize connection to chip")
 @click.pass_context
 def cli_sync(ctx):
     iodevice = UartDevice(ctx.obj["device"], baudrate=ctx.obj["baud"])
     isp = ISPConnection(iodevice)
     isp.SyncConnection()
 
 
-@gr1.command("query-chip", help="Read the chip ID and boot code")
+@gr1.command("query-chip", help="Read chip Part ID, UID, and boot code version")
 @click.pass_context
 def cli_QueryChip(ctx):
     iodevice = UartDevice(ctx.obj["device"], baudrate=ctx.obj["baud"])
@@ -87,9 +87,7 @@ def cli_MassErase(ctx):
     _log.info("Mass Erase Successful")
 
 
-@click.option(
-    "--start_sector", type=int, default=0, required=True, help="Sector to write to"
-)
+@click.option("--start_sector", type=int, default=0, help="Sector to write to")
 @click.option(
     "--imagein", type=str, required=True, help="Location of hex file to program"
 )

src/isp_programmer/lpctools_parts.def

@@ -21,6 +21,11 @@
 0x00008044, LPC804M101JHI33,    0x00000000, 0x08000, 32,   0x04,     0x10000000, 0x1000, 0x800, 0x400,   0
 
 # LPC84x
+0x00008442, LPC844M301JBD48,    0x00000000, 0x10000, 32,    0x04,   0x10000000, 0x4000, 0x800, 0x800,   0
+0x00008441, LPC844M301JBD64,    0x00000000, 0x10000, 32,    0x04,   0x10000000, 0x4000, 0x800, 0x800,   0
+0x00008444, LPC844M301JHI33,    0x00000000, 0x10000, 32,    0x04,   0x10000000, 0x4000, 0x800, 0x800,   0
+0x00008443, LPC844M301JHI48,    0x00000000, 0x10000, 32,    0x04,   0x10000000, 0x4000, 0x800, 0x800,   0
+
 0x00008452, LPC845M301JBD48,    0x00000000, 0x10000, 64,    0x04,   0x10000000, 0x4000, 0x800, 0x800,   0
 0x00008451, LPC845M301JBD64,    0x00000000, 0x10000, 64,    0x04,   0x10000000, 0x4000, 0x800, 0x800,   0
 0x00008454, LPC845M301JHI33,    0x00000000, 0x10000, 64,    0x04,   0x10000000, 0x4000, 0x800, 0x800,   0
@@ -29,14 +34,14 @@
 # LPC81X Family
 0x00008100, LPC810M021FN8,      0x00000000, 0x1000, 4,     0x04,    0x10000000, 0x0400, 0x300, 0x100,   0
 0x00008122, LPC812M101JDH20,    0x00000000, 0x4000, 16,    0x04,    0x10000000, 0x1000, 0x800, 0x400,   0
-#
+
 # LPC11XX Family
 0x2540102B, LPC1114FHN33/302,   0x00000000, 0x8000,  8,    0x04,    0x10000000, 0x2000, 0x800, 0x400,   1
 0x4d80002b, LPC11A04UK,         0x00000000, 0x8000,  8,    0x04,    0x10000000, 0x2000, 0x800, 0x400,   1
-#
+
 # LPC12XX Family
 0x3640C02B, LPC1224FBD48/101,   0x00000000, 0x8000,  8,    0x04,    0x10000000, 0x1000, 0x800, 0x400,   1
-#
+
 # LPC17XX Family
 0x26011922, LPC1764FBD100,      0x00000000, 0x10000, 16,   0x04,    0x10000000, 0x4000, 0x800, 0x800,   1
 

src/isp_programmer/parts_definitions.py

@@ -3,6 +3,8 @@
 consistent with other formats
 """
 
+from typing import Dict, List
+
 column_names = [
     "part id",
     "name",
@@ -21,7 +23,7 @@
 ]
 
 
-def read_lpcparts_string(string: str) -> dict[str, list]:
+def read_lpcparts_string(string: str) -> Dict[str, List]:
     lpc_tools_column_locations = {
         "part id": 0,
         "name": 1,
@@ -77,28 +79,27 @@ def ReadChipFile(fname: str) -> dict:
     return df
 
 
-def GetPartDescriptorLine(fname: str, partid: int) -> dict[str, str]:
+def GetPartDescriptorLine(fname: str, partid: int) -> Dict[str, str]:
     entries = ReadChipFile(fname)
     for i, line_part_id in enumerate(entries["part id"]):
         if partid == line_part_id:
             return {key: entries[key][i] for key in entries}
-    raise UserWarning(f"PartId {partid} not found in {fname}")
+    raise ValueError(f"PartId {hex(partid)} not found in {fname}")
 
 
 def GetPartDescriptor(fname: str, partid: int) -> dict[str, str]:
     # FIXME redundant function
     descriptor = GetPartDescriptorLine(fname, partid)
-    if descriptor is None:
-        raise UserWarning("Warning chip %s not found in file %s" % (hex(partid), fname))
     return descriptor
 
 
 def check_parts_definition_dataframe(df):
     """
-    Takes the standard layout dataframe, check the field validity
+    Takes the standard layout dataframe, check the field validity.
+    Works with dict or DataFrame
     """
     valid = True
-    for _, line in df.iterrows():
-        if line["RAMRange"][1] - line["RAMRange"][0] + 1 != line["RAMSize"]:
+    for start, end, size in zip(df["RAMStart"], df["RAMEnd"], df["RAMSize"]):
+        if end - start + 1 != size:
             valid = False
     return valid

src/isp_programmer/tools.py

@@ -3,20 +3,27 @@
 from pycrc.algorithms import Crc
 
 
-def collection_to_string(arr):
+def collection_to_string(arr) -> str:
+    """Convert a list of integer character codes to a string."""
     return "".join([chr(ch) for ch in arr])
 
 
-# 2s compliment of checksum
 def CalculateCheckSum(frame) -> int:
+    """
+    Calculate 2's complement checksum of the sum of frame entries.
+    Assumes 'frame' is an iterable of integers.
+    """
     csum = 0
     for entry in frame:
         csum += entry
     return (1 << 32) - (csum % (1 << 32))
 
 
-def Crc32(frame: bytes) -> int:
-    # CRC32
+def nxp_crc32(frame: bytes) -> int:
+    """
+    Calculate CRC32 using pycrc with standard polynomial.
+    Note: polynomial here is 0x104C11DB6, which is non-standard (33 bits).
+    """
     polynomial = 0x104C11DB6
     crc = Crc(
         width=32,
@@ -31,9 +38,11 @@ def Crc32(frame: bytes) -> int:
 
 
 def calc_crc(frame: bytes):
+    """Calculate CRC32 using zlib (fast, standard)."""
+    #  0x04C11DB7
     return zlib.crc32(frame, 0)
-    # return Crc32(frame)
 
 
-def calc_sector_count(image, sector_bytes):
+def calc_sector_count(image, sector_bytes: int) -> int:
+    """Calculate number of sectors needed to store the image."""
     return int(math.ceil(len(image) / sector_bytes))