lpc-checksum

library3.0.0pypypi✓ verified 22d ago

A Python script designed to calculate LPC firmware checksums, based on the C version by Roel Verdult. It functions both as a standalone application and as a Python module that can be integrated into build environments. The current version is 3.0.0, but its release cadence is stalled, with the last release approximately three years ago.

devops

pip install lpc-checksum

github ↗package ↗

INSTALL

IMPORT

SIG · LPC-CHECKSUM

lpc-checksum

devopspythonv3.0.0

Install

1.6s avg

Import

10ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.010s · 18.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.010s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

checksum

✓ import lpc_checksum

The primary function `checksum` is accessed directly from the imported module.

This quickstart demonstrates how to import `lpc_checksum` and use its `checksum` function to calculate and optionally inject the correct checksum into a dummy binary firmware file. The `checksum` function modifies the input file in place by default.

import lpc_checksum import os # Create a dummy binary file for demonstration dummy_firmware_path = 'firmware.bin' with open(dummy_firmware_path, 'wb') as f: f.write(b'\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00' \ b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00' \ b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00') # Calculate and inject the checksum try: # The checksum function modifies the file in place by default # or returns the checksum if read_only=True print(f"Calculating checksum for {dummy_firmware_path}") checksum_value = lpc_checksum.checksum(dummy_firmware_path, read_only=True) print(f"Calculated checksum (read-only): 0x{checksum_value:08x}") # To actually write the checksum to the file: lpc_checksum.checksum(dummy_firmware_path) print(f"Checksum injected into {dummy_firmware_path}") except Exception as e: print(f"An error occurred: {e}") finally: # Clean up the dummy file if os.path.exists(dummy_firmware_path): os.remove(dummy_firmware_path) print(f"Cleaned up {dummy_firmware_path}")

lpc-checksum --version

Debug

Known issues

gotchaLPC microcontrollers require a specific checksum at address 0x1C in the interrupt vector table for the firmware to boot correctly. If this checksum is missing or incorrect (e.g., if a standard GNU toolchain doesn't generate it), the device will not boot or will enter ISP mode. This library directly addresses this issue.

fix

Ensure `lpc_checksum.checksum(filepath)` is run on your firmware binary as part of your build process before flashing to an NXP LPC microcontroller.

affects: All versions, applies to target hardware requirements.

gotchaWhen calculating 32-bit checksums, improper handling of integer overflow can lead to incorrect results. An earlier version (v2.1.2) had a bug where modulo (%) was incorrectly used instead of bitwise AND (&) for 32-bit overflow, leading to discrepancies with C-based calculations. While fixed in current versions, it highlights a critical detail in checksum implementation.

fix

Always use the latest stable version of `lpc-checksum`. When implementing similar checksum logic, ensure correct 32-bit unsigned integer arithmetic, typically using bitwise AND `& 0xFFFFFFFF` to handle overflows if not implicitly handled by the language/platform.

affects: < 2.1.2 (bug fixed in 2.1.2, but principle applies generally)

deprecatedThe `lpc-checksum` library's release cadence is stalled, with the last release (v3.0.0) dating back approximately three years ago. This indicates a lack of active development, which could mean slower responses to bug reports or no new feature additions.

fix

Be aware that active maintenance may be limited. Consider contributing to the project if you encounter issues or require new features, or evaluate if the existing functionality meets your long-term needs without further updates.

affects: 3.0.0 and potentially future versions.

Errors

Common errors & fixes

Error: checksum mismatch - attempting binary compare embedded:startup.tcl:449: Error: ** Verify Failed **

The firmware image processed by `lpc-checksum` has an incorrect or mismatched checksum at the expected vector table location, which causes a verification failure when flashing or checking the firmware with tools like OpenOCD.

fix

Ensure you are using the latest version of `lpc-checksum` (3.0.0 or newer) and that the input binary file is correctly formatted for your specific NXP LPC microcontroller. Verify the tool's output against known good checksums or specifications for your target device. If using an older version, consider upgrading as past versions had overflow bugs in checksum calculation.

Warn : Verification will fail since checksum in image (0x...) to be written to flash is different from calculated vector checksum (0x...). Warn : To remove this warning modify build tools on developer PC to inject correct LPC vector checksum.

The `lpc-checksum` utility (or an older version of it) generated a checksum that does not match the value expected by the bootloader or a programming tool (like OpenOCD) for the target NXP LPC microcontroller. This often indicates a miscalculation or an issue with the input binary.

fix

Update `lpc-checksum` to its latest version (3.0.0 or newer) to benefit from bug fixes. Double-check that your firmware's vector table and the input binary file are compatible with the `lpc-checksum` tool's assumptions and the specific requirements of your LPC device's boot ROM. Ensure correct endianness and data interpretation if manually manipulating input.

ModuleNotFoundError: No module named 'lpc_checksum'

The Python interpreter cannot find the `lpc_checksum` module, usually because the library has not been installed, or the current Python environment's `PATH` does not include the installation location.

fix

Install the library using pip: `pip install lpc-checksum`. If already installed, ensure you are running your script in the same Python environment where `lpc-checksum` was installed.

SyntaxError: invalid syntax

This error can occur if you are running `lpc-checksum` on a Python version older than its requirement. The `lpc-checksum` library (version 3.0.0) explicitly requires Python 3.9 or newer.

fix

Upgrade your Python environment to version 3.9 or newer (e.g., Python 3.9, 3.10, 3.11). You can check your Python version with `python --version` and install a compatible version if needed.

Upgrade

Version history

3.0.0latest on PyPI · released Nov 13, 2022

Audit

Dependencies

intelhexrequiredRequired for handling Intel HEX file formats.

Agent activity

3 hits · last 30 days

node

Resources

githubhttps://github.com/basilfx/lpc_checksum ↗

packagehttps://pypi.org/project/lpc-checksum/ ↗