LPC Checksum

3.0.0 · maintenance · verified Sun Apr 12

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.

Warnings

gotcha LPC 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.
gotcha When 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.
deprecated The `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.

Install

pip install lpc-checksum Install via pip

Imports

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

Quickstart

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}")

view raw JSON →