lecore 0.2.6__tar.gz → 0.2.7__tar.gz

{lecore-0.2.6/src/lecore.egg-info → lecore-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lecore
-Version: 0.2.6
+Version: 0.2.7
 Summary: Logic Elements core utilities
 Author-email: Jan Bartovský <jan.bartovsky@logicelements.cz>
 License-Expression: MIT

{lecore-0.2.6 → lecore-0.2.7}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "lecore"
 description = "Logic Elements core utilities"
-version = "0.2.6"
+version = "0.2.7"
 authors = [
   { name="Jan Bartovský", email="jan.bartovsky@logicelements.cz" },
 ]

{lecore-0.2.6 → lecore-0.2.7}/src/lecore/FwBuild.py

@@ -6,6 +6,8 @@ The CRC is the one of the STM32 hardware CRC unit: polynom 0x04C11DB7, init 0xFF
 words, no reflection and no final XOR. The same CRC is produced for all targets.
 
 Targets 1-7 are verified byte by byte against BinBuild.exe (build of 2024-09). Target 8 is not implemented.
+Intel HEX files are supported too (except target 1): the image from the lowest address is processed like a binary,
+gaps are filled with 0x00 (like ``objcopy -O binary``) and the result is written as a contiguous HEX.
 """
 import datetime
 import struct
@@ -74,6 +76,9 @@ TARGETS = {
     7: Target(512, True, 16, "512 B offset in the FW, decimal information (Fixture)"),
 }
 
+_HEX_MAX_SIZE = 16 * 1024 * 1024  # protection against huge gaps (e.g. option bytes far away from the FW)
+_HEX_RECORD = 16
+
 _LEGACY_OFFSET = 512  # target 1 checks the same free space as the targets with a 512 B offset
 
 
@@ -132,13 +137,92 @@ def build(data: bytes, target: int, version: str, dev_id: str = "", date: Option
     return stamped[:offset] + info + stamped[offset + len(info):], crc
 
 
+def read_hex(text: str) -> tuple:
+    """
+    Parse an Intel HEX file into a contiguous image, gaps are filled with 0x00
+    :param text: HEX file content
+    :return: Tuple (base address, image, start address record line or None)
+    """
+    chunks = {}
+    upper = 0
+    start = None
+    for number, line in enumerate(text.splitlines(), 1):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            if line[0] != ":":
+                raise ValueError
+            record = bytes.fromhex(line[1:])
+        except ValueError:
+            raise ValueError(f"line {number}: not an Intel HEX record") from None
+        if len(record) < 5 or len(record) != record[0] + 5:
+            raise ValueError(f"line {number}: wrong record length")
+        if sum(record) & 0xFF:
+            raise ValueError(f"line {number}: wrong checksum")
+        rtype, payload = record[3], record[4:-1]
+        if rtype == 0x00:
+            address = upper + int.from_bytes(record[1:3], "big")
+            chunks[address] = chunks.get(address, b"") + payload
+        elif rtype == 0x01:
+            break
+        elif rtype == 0x02:
+            upper = int.from_bytes(payload, "big") << 4
+        elif rtype == 0x04:
+            upper = int.from_bytes(payload, "big") << 16
+        elif rtype in (0x03, 0x05):
+            start = line
+        else:
+            raise ValueError(f"line {number}: unknown record type {rtype:02X}")
+    if not chunks:
+        raise ValueError("no data in the HEX file")
+    base = min(chunks)
+    size = max(address + len(payload) for address, payload in chunks.items()) - base
+    if size > _HEX_MAX_SIZE:
+        raise ValueError(f"HEX image is too large ({size} B from 0x{base:08X}), check for data at distant addresses")
+    image = bytearray(size)
+    for address, payload in chunks.items():
+        image[address - base:address - base + len(payload)] = payload
+    return base, bytes(image), start
+
+
+def _hex_record(rtype: int, address: int, payload: bytes) -> str:
+    record = bytes([len(payload)]) + address.to_bytes(2, "big") + bytes([rtype]) + payload
+    return ":" + (record + bytes([-sum(record) & 0xFF])).hex().upper()
+
+
+def write_hex(base: int, image: bytes, start: Optional[str] = None) -> str:
+    """
+    Write a contiguous image as an Intel HEX file
+    :param base: Address of the image
+    :param image: Image content
+    :param start: Start address record line (from ``read_hex``)
+    :return: HEX file content
+    """
+    lines = []
+    upper = None
+    address = base
+    end = base + len(image)
+    while address < end:
+        if address >> 16 != upper:
+            upper = address >> 16
+            lines.append(_hex_record(0x04, 0, upper.to_bytes(2, "big")))
+        length = min(_HEX_RECORD, end - address, 0x10000 - (address & 0xFFFF))
+        lines.append(_hex_record(0x00, address & 0xFFFF, image[address - base:address - base + length]))
+        address += length
+    if start:
+        lines.append(start)
+    lines.append(_hex_record(0x01, 0, b""))
+    return "\n".join(lines) + "\n"
+
+
 def build_file(target: int, path, version: str, suffix: str = "", out_dir=None,
                date: Optional[datetime.date] = None) -> tuple:
     """
-    Stamp the FW information block into a binary file, the result is written next to it (or to ``out_dir``) as
-    ``<name>[-<suffix>]-<yyyymmdd>-<version>.bin``
+    Stamp the FW information block into a binary or Intel HEX (``.hex``) file, the result is written next to it
+    (or to ``out_dir``) as ``<name>[-<suffix>]-<yyyymmdd>-<version>.bin`` (``.hex``)
     :param target: Target number, see ``TARGETS``
-    :param path: Binary file
+    :param path: Binary or Intel HEX file
     :param version: FW version, hexadecimal (BCD)
     :param suffix: Suffix of the output name, also used as the device ID of target 4
     :param out_dir: Output directory (default directory of the input file)
@@ -147,8 +231,17 @@ def build_file(target: int, path, version: str, suffix: str = "", out_dir=None,
     """
     path = Path(path)
     date = date or datetime.date.today()
-    result, crc = build(path.read_bytes(), target, version, suffix, date)
-    name = f"{path.stem}{'-' + suffix if suffix else ''}-{date:%Y%m%d}-{int(version, 16):X}.bin"
+    is_hex = path.suffix.lower() == ".hex"
+    if is_hex:
+        if TARGETS.get(target) is not None and TARGETS[target].offset is None:
+            raise ValueError(f"target {target} prepends the block to the file, it is not supported for HEX files")
+        base, image, start = read_hex(path.read_text(encoding="ascii"))
+        result, crc = build(image, target, version, suffix, date)
+        content = write_hex(base, result, start).encode("ascii")
+    else:
+        content, crc = build(path.read_bytes(), target, version, suffix, date)
+    name = f"{path.stem}{'-' + suffix if suffix else ''}-{date:%Y%m%d}-{int(version, 16):X}"
+    name += ".hex" if is_hex else ".bin"
     out = Path(out_dir) / name if out_dir else path.with_name(name)
-    out.write_bytes(result)
+    out.write_bytes(content)
     return out, crc

{lecore-0.2.6 → lecore-0.2.7}/src/lecore/__main__.py

@@ -1,89 +1,89 @@
-"""
-Command line jump-start for lecore, see ``python -m lecore --help``
-"""
-import argparse
-import sys
-import warnings
-
-from .Scaffold import guide, new_device, generate_regs, generate_tests
-from .FwBuild import TARGETS, build_file
-
-
-def _show_warning(message, category, filename, lineno, file=None, line=None):
-    print(f"warning: {message}", file=sys.stderr)
-
-
-def main(argv=None) -> int:
-    warnings.showwarning = _show_warning
-    parser = argparse.ArgumentParser(prog="lecore", description="Logic Elements core utilities")
-    sub = parser.add_subparsers(dest="cmd", required=True)
-
-    sub.add_parser("guide", help="print quick guide for creating devices with lecore")
-
-    p = sub.add_parser("new-device", help="create device class and missing configuration files next to the "
-                                          "register map")
-    p.add_argument("name", help="device class name, e.g., MyDevice")
-    proto = p.add_mutually_exclusive_group()
-    proto.add_argument("--modbus", dest="protocol", action="store_const", const="modbus",
-                       help="Modbus device (default: detected from register map)")
-    proto.add_argument("--lebin", dest="protocol", action="store_const", const="lebin", help="LeBin device")
-    p.add_argument("--dir", default=".", help="directory with register map (default: current)")
-    p.add_argument("--reg-map", help="register map JSON in the directory (default: the single one found)")
-    p.add_argument("--template", action="store_true",
-                   help="create minimal register map template and *Regs.py when no register map is present")
-    p.add_argument("--gen-regs", action="store_true", help="generate missing *Regs.py from the register map")
-    p.add_argument("--slave", type=int, default=1, help="default Modbus slave address")
-    p.add_argument("--comport", default="COM1", help="default COM port")
-    p.add_argument("--baud-rate", type=int, default=19200, help="default baud rate")
-    p.add_argument("--parity", default="E", choices=("N", "E", "O"), help="default parity")
-    p.add_argument("--usb", nargs=3, metavar=("VID", "PID", "SN"), help="LeBin USB identification for search_com()")
-    p.add_argument("--force", action="store_true", help="overwrite existing device module and configuration files")
-
-    p = sub.add_parser("new-tests", help="create missing communication test files (test_modbus.py, test_lebin.py) "
-                                         "for device classes in a directory")
-    p.add_argument("--dir", default=".", help="directory with device modules (default: current)")
-    p.add_argument("--force", action="store_true", help="overwrite existing test files")
-
-    p = sub.add_parser("regs", help="generate class with register name constants from a register map")
-    p.add_argument("reg_map", help="register map JSON (Modbus or LeBin)")
-    p.add_argument("--class", dest="class_name", default="Regs", help="generated class name")
-    p.add_argument("-o", "--output", help="output Python file (default: print)")
-
-    p = sub.add_parser("binbuild", help="stamp the FW information block (CRC, version, size) into a binary "
-                                        "(replaces BinBuild.exe)",
-                       formatter_class=argparse.RawDescriptionHelpFormatter,
-                       epilog="targets:\n" + "\n".join(f"  {n} - {t.description}" for n, t in TARGETS.items()))
-    p.add_argument("target", type=int, choices=sorted(TARGETS), help="FW information block layout")
-    p.add_argument("file", help="binary file")
-    p.add_argument("version", help="FW version, hexadecimal (BCD)")
-    p.add_argument("--suffix", default="", help="suffix of the output name, device ID for target 4")
-    p.add_argument("--out-dir", help="output directory (default: directory of the binary)")
-
-    args = parser.parse_args(argv)
-    try:
-        if args.cmd == "guide":
-            print(guide())
-        elif args.cmd == "new-device":
-            usb = (int(args.usb[0], 0), int(args.usb[1], 0), args.usb[2]) if args.usb else None
-            result = new_device(args.name, args.protocol, args.dir, args.reg_map, args.template, args.gen_regs,
-                                args.slave, args.comport, args.baud_rate, args.parity, usb, args.force)
-            for path, status in result.items():
-                print(f"{status:12}{path}")
-        elif args.cmd == "new-tests":
-            for path, status in generate_tests(args.dir, args.force).items():
-                print(f"{status:12}{path}")
-        elif args.cmd == "regs":
-            src = generate_regs(args.reg_map, args.class_name, args.output)
-            if args.output is None:
-                print(src, end="")
-        elif args.cmd == "binbuild":
-            out, crc = build_file(args.target, args.file, args.version, args.suffix, args.out_dir)
-            print(f"{out}\nNew File created with CRC value {crc:08X}")
-    except (ValueError, OSError) as e:
-        print(f"error: {e}", file=sys.stderr)
-        return 1
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())
+"""
+Command line jump-start for lecore, see ``python -m lecore --help``
+"""
+import argparse
+import sys
+import warnings
+
+from .Scaffold import guide, new_device, generate_regs, generate_tests
+from .FwBuild import TARGETS, build_file
+
+
+def _show_warning(message, category, filename, lineno, file=None, line=None):
+    print(f"warning: {message}", file=sys.stderr)
+
+
+def main(argv=None) -> int:
+    warnings.showwarning = _show_warning
+    parser = argparse.ArgumentParser(prog="lecore", description="Logic Elements core utilities")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("guide", help="print quick guide for creating devices with lecore")
+
+    p = sub.add_parser("new-device", help="create device class and missing configuration files next to the "
+                                          "register map")
+    p.add_argument("name", help="device class name, e.g., MyDevice")
+    proto = p.add_mutually_exclusive_group()
+    proto.add_argument("--modbus", dest="protocol", action="store_const", const="modbus",
+                       help="Modbus device (default: detected from register map)")
+    proto.add_argument("--lebin", dest="protocol", action="store_const", const="lebin", help="LeBin device")
+    p.add_argument("--dir", default=".", help="directory with register map (default: current)")
+    p.add_argument("--reg-map", help="register map JSON in the directory (default: the single one found)")
+    p.add_argument("--template", action="store_true",
+                   help="create minimal register map template and *Regs.py when no register map is present")
+    p.add_argument("--gen-regs", action="store_true", help="generate missing *Regs.py from the register map")
+    p.add_argument("--slave", type=int, default=1, help="default Modbus slave address")
+    p.add_argument("--comport", default="COM1", help="default COM port")
+    p.add_argument("--baud-rate", type=int, default=19200, help="default baud rate")
+    p.add_argument("--parity", default="E", choices=("N", "E", "O"), help="default parity")
+    p.add_argument("--usb", nargs=3, metavar=("VID", "PID", "SN"), help="LeBin USB identification for search_com()")
+    p.add_argument("--force", action="store_true", help="overwrite existing device module and configuration files")
+
+    p = sub.add_parser("new-tests", help="create missing communication test files (test_modbus.py, test_lebin.py) "
+                                         "for device classes in a directory")
+    p.add_argument("--dir", default=".", help="directory with device modules (default: current)")
+    p.add_argument("--force", action="store_true", help="overwrite existing test files")
+
+    p = sub.add_parser("regs", help="generate class with register name constants from a register map")
+    p.add_argument("reg_map", help="register map JSON (Modbus or LeBin)")
+    p.add_argument("--class", dest="class_name", default="Regs", help="generated class name")
+    p.add_argument("-o", "--output", help="output Python file (default: print)")
+
+    p = sub.add_parser("binbuild", help="stamp the FW information block (CRC, version, size) into a binary or HEX "
+                                        "(replaces BinBuild.exe)",
+                       formatter_class=argparse.RawDescriptionHelpFormatter,
+                       epilog="targets:\n" + "\n".join(f"  {n} - {t.description}" for n, t in TARGETS.items()))
+    p.add_argument("target", type=int, choices=sorted(TARGETS), help="FW information block layout")
+    p.add_argument("file", help="binary or Intel HEX (.hex) file")
+    p.add_argument("version", help="FW version, hexadecimal (BCD)")
+    p.add_argument("--suffix", default="", help="suffix of the output name, device ID for target 4")
+    p.add_argument("--out-dir", help="output directory (default: directory of the binary)")
+
+    args = parser.parse_args(argv)
+    try:
+        if args.cmd == "guide":
+            print(guide())
+        elif args.cmd == "new-device":
+            usb = (int(args.usb[0], 0), int(args.usb[1], 0), args.usb[2]) if args.usb else None
+            result = new_device(args.name, args.protocol, args.dir, args.reg_map, args.template, args.gen_regs,
+                                args.slave, args.comport, args.baud_rate, args.parity, usb, args.force)
+            for path, status in result.items():
+                print(f"{status:12}{path}")
+        elif args.cmd == "new-tests":
+            for path, status in generate_tests(args.dir, args.force).items():
+                print(f"{status:12}{path}")
+        elif args.cmd == "regs":
+            src = generate_regs(args.reg_map, args.class_name, args.output)
+            if args.output is None:
+                print(src, end="")
+        elif args.cmd == "binbuild":
+            out, crc = build_file(args.target, args.file, args.version, args.suffix, args.out_dir)
+            print(f"{out}\nNew File created with CRC value {crc:08X}")
+    except (ValueError, OSError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{lecore-0.2.6 → lecore-0.2.7/src/lecore.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lecore
-Version: 0.2.6
+Version: 0.2.7
 Summary: Logic Elements core utilities
 Author-email: Jan Bartovský <jan.bartovsky@logicelements.cz>
 License-Expression: MIT