Secure Provisioning SDK (SPSDK)

Common errors

• Building wheel for hidapi (pyproject.toml) did not run successfully.

  cause The `hidapi` package, often a dependency for USB communication features, requires native C compilation during installation. This error typically means that necessary build tools (like C/C++ compilers or development headers) are missing on the system, especially on Windows (e.g., MS Build Tools) or Linux (e.g., `libudev-dev`).
  fix Ensure you have the required build tools for your operating system. For Windows, install 'Build Tools for Visual Studio'. For Linux, install `python3-dev` and `libudev-dev` or similar packages (`sudo apt-get install python3-dev libudev-dev`). Try `pip install --no-binary :all: hidapi` as a workaround if the issue persists.

• Response status = 10200 (0x27d8) Memory Range Invalid.

  cause This error, often encountered when using `blhost` to program flash, indicates that the target memory region you are trying to write to is either already programmed or protected, or the specified address/range is invalid for the operation.
  fix Before writing to flash, ensure it is properly erased. Use the `blhost flash-erase-region` or `blhost flash-erase-all-unsecure` command to clear the flash memory. Verify the memory addresses and sizes specified in your commands or configuration files are correct for your target device.

• Error: 'nxpcertgen' command not found

  cause The `nxpcertgen` application was removed in SPSDK v3.0.0 as part of the consolidation into the `nxpcrypto` module.
  fix Migrate your scripts and workflows to use the `nxpcrypto` application for certificate generation and management. Refer to the SPSDK v3.0.0 migration guide for updated command-line syntax and API usage.

Warnings

• breaking SPSDK v3.0.0 introduced significant breaking changes. Key applications like `nxpcertgen`, `tphost`, and `tpconfig` were removed or consolidated into `nxpcrypto` and `pfr`. The `--plugin` CLI option was removed, requiring plugins to be installed as Python packages with entry points. Command-line options for `nxpcrypto` (e.g., `-k`/`--private-key` and `-sp`/`--signature-provider` unified to `-s`/`--signer`) and `nxpimage` configurations (e.g., `image_type` replaced by `target_memory`) were also updated.
  Fix: Refer to the official `spsdk` Migration Guide for a detailed list of changes and updated usage patterns. Re-evaluate CLI commands and API calls, especially for `nxpcrypto` and `nxpimage` operations.
• breaking SPSDK v2.0.0 also introduced major breaking changes for users migrating from v1.x. The `elftosb` tool was replaced by `nxpimage`, and `nxpcertgen`/`nxpkeygen` functionalities were moved into `nxpcrypto`. The `--device` (`-d`) parameter was replaced by `--family` (`-f`) for device selection across many tools. Crypto backends were refactored and removed.
  Fix: Consult the `spsdk` v2.0.0 release notes and migration guide. Update scripts to use `nxpimage` instead of `elftosb` and `nxpcrypto` for certificate/key operations. Use `--family` for device specification.
• gotcha For `blhost` users, a Rust-based alternative called `rblhost` was introduced in SPSDK v3.2.0. `rblhost` offers significantly faster startup times and improved overall performance compared to the Python-based `blhost` implementation. If you experience performance issues with `blhost`, `rblhost` is recommended.
  Fix: Consider installing and using `rblhost` (available via `pip install pymboot-rs`) as a drop-in replacement or alongside the Python `blhost` for performance-critical operations. The CLI interface is designed to be compatible.
• gotcha The 'Restricted Data Package', which was previously required for certain functionalities, is no longer needed for SPSDK versions 3.2.0 and onwards. Users upgrading from older versions or following outdated documentation might mistakenly try to acquire or install this package.
  Fix: If using SPSDK v3.2.0 or newer, you do not need to download or install the 'Restricted Data Package'. If you encounter references to it, disregard them for current versions.

Install

• pip install spsdk Install latest version

Imports

• SPSDKError

  from spsdk.exceptions import SPSDKError

  A base exception for handling SPSDK-related errors.
• sdp

  from spsdk.sdp import sdp

  Accessing the Serial Download Protocol (SDP) communication module for device interaction.
• nxpimage

  import spsdk.image as nxpimage

  The primary module for image processing and generation, replacing older tools like elftosb.

Quickstart

SPSDK is primarily used through its command-line applications (like `blhost`, `nxpimage`, `sdphost`). This quickstart demonstrates invoking `blhost` to read a property from a connected NXP MCU. For direct API interaction, modules such as `spsdk.sdp` or `spsdk.image` would be used.

# Connect to a device via blhost (command-line tool wrapper)
# This example assumes a device is connected and blhost is configured.
# For actual usage, replace 'serial' with 'usb' if applicable and provide correct port/device.
# The blhost command-line utility is typically used directly.
import subprocess

try:
    # Example: Get property (e.g., status) from the bootloader
    # In a real scenario, you'd provide specific device connection parameters.
    command = ['blhost', '-p', 'COMx', 'get-property', '1'] # Replace COMx with your serial port
    result = subprocess.run(command, capture_output=True, text=True, check=True)
    print("blhost output:")
    print(result.stdout)
except subprocess.CalledProcessError as e:
    print(f"Error executing blhost: {e}")
    print(f"Stderr: {e.stderr}")
except FileNotFoundError:
    print("Error: 'blhost' command not found. Ensure SPSDK is installed and your PATH is correct, or use the 'spsdk' wrapper utility.")

# For API usage, you might interact with specific modules directly, e.g., spsdk.sdp