{"id":4199,"library":"pyocd","title":"pyOCD","description":"pyOCD is an open-source Python library and command-line tool for programming and debugging Arm Cortex-M microcontrollers using various debug probes such as CMSIS-DAP, J-Link, and ST-Link. It provides a flexible Python API for low-level target control, suitable for automated testing and CI/CD workflows, alongside a powerful command-line interface for common operations like GDB server, flashing, and erasing. Currently at version 0.44.0, pyOCD maintains an active development cycle with several minor releases annually.","status":"active","version":"0.44.0","language":"en","source_language":"en","source_url":"https://github.com/pyocd/pyOCD","tags":["debugger","embedded","arm","cortex-m","cmsis-dap","flashing","gdbserver","real-time-transfer","systemview"],"install":[{"cmd":"pip install pyocd","lang":"bash","label":"Standard Installation"},{"cmd":"pip install pyocd[pemicro]","lang":"bash","label":"With PE Micro Probe Support"}],"dependencies":[{"reason":"Required for execution","package":"Python","minimum_version":"3.8.0"},{"reason":"Binary shared library backend for USB communication with debug probes","package":"libusb","optional":false}],"imports":[{"symbol":"ConnectHelper","correct":"from pyocd.core.helpers import ConnectHelper"},{"symbol":"FileProgrammer","correct":"from pyocd.flash.file_programmer import FileProgrammer"}],"quickstart":{"code":"import time\nimport logging\nimport os\n\nfrom pyocd.core.helpers import ConnectHelper\nfrom pyocd.flash.file_programmer import FileProgrammer\n\nlogging.basicConfig(level=logging.INFO)\n\nFIRMWARE_PATH = \"your_firmware.hex\" # Replace with the actual path to your firmware\n\n# Create a dummy firmware file for demonstration if it doesn't exist\nif not os.path.exists(FIRMWARE_PATH):\n    with open(FIRMWARE_PATH, \"w\") as f:\n        f.write(\":100000000000000000000000000000000000000000\\n\") # Minimal valid HEX file\n\ntry:\n    # Connect to the target with the first found probe.\n    # For a specific probe, use unique_id=\"E6616407E3646B29\"\n    # For a specific target, use options={\"target_override\": \"nrf52840\"}\n    with ConnectHelper.session_with_chosen_probe() as session:\n        target = session.target\n        board_id = session.board.unique_id if session.board else \"Unknown\"\n        logging.info(f\"Connected to probe: {board_id}, target: {target.name}\")\n\n        # Halt the target\n        target.halt()\n        logging.info(\"Target halted.\")\n\n        # Program firmware\n        logging.info(f\"Programming {FIRMWARE_PATH}...\")\n        FileProgrammer(session).program(FIRMWARE_PATH)\n        logging.info(\"Programming complete.\")\n\n        # Reset and run\n        target.reset_and_run()\n        logging.info(\"Target reset and running.\")\n\n        # Allow the target to run for a short period (demonstration)\n        time.sleep(1)\n\nexcept Exception as e:\n    logging.error(f\"An error occurred: {e}\")\n    logging.info(\"Please ensure a debug probe is connected and compatible firmware is specified.\")\n","lang":"python","description":"This quickstart demonstrates how to connect to a debug probe, halt the target microcontroller, program a firmware image (HEX format in this example), and then reset and run the target using the pyOCD Python API. Ensure a debug probe is connected and `your_firmware.hex` is replaced with an actual firmware file or created as a dummy for testing."},"warnings":[{"fix":"Upgrade your Python environment to 3.8 or a newer compatible version.","message":"Python 3.7 is no longer supported starting with pyOCD v0.37.0. Projects must use Python 3.8 or later.","severity":"breaking","affected_versions":">=0.37.0"},{"fix":"Review the official documentation for the `run` subcommand and update scripts to use the new features and configuration methods, particularly for RTT (`server` mode renamed from `telnet` in v0.44.0) and SystemView.","message":"The `run` subcommand introduced significant changes and new configurations for RTT, SystemView, and Semihosting in versions 0.42.0 and 0.43.0. Older scripts relying on specific `run` subcommand behaviors or arguments might need updates.","severity":"breaking","affected_versions":">=0.42.0"},{"fix":"Adjust custom flash programming scripts to account for the explicit erase/program separation as detailed in the v0.44.0 changelog.","message":"Flash programming operations were split into separate erase and program operations starting from v0.44.0. Direct flash programming might now require explicit erase calls depending on the workflow.","severity":"breaking","affected_versions":">=0.44.0"},{"fix":"Update any configurations or scripts referencing the `telnet` RTT channel mode to use `server` instead.","message":"The RTT channel mode `telnet` was renamed to `server` in pyOCD v0.44.0.","severity":"breaking","affected_versions":">=0.44.0"},{"fix":"While the `0.x` API is stable, be prepared for potential breaking changes when upgrading to version 1.0 and beyond. Refer to the release notes for migration guides.","message":"The Python API is considered unstable prior to version 1.0, with planned breaking changes to align with PEP8 naming conventions. Additionally, the command-line tools are planned to be merged into a single utility in future 1.0 releases.","severity":"gotcha","affected_versions":"<1.0"},{"fix":"Install `libusb` according to your operating system's instructions: `brew install libusb` on macOS, usually pre-installed on Linux, and manual DLL placement on Windows (matching Python's architecture).","message":"Installation of the `libusb` binary shared library is a manual, OS-dependent step and is not handled automatically by pip. Without it, pyOCD cannot communicate with USB debug probes.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add appropriate udev rules for your debug probe to allow unprivileged user access. An example for NXP FRDM-K64F involves creating `/etc/udev/rules.d/50-mbed.rules` with `SUBSYSTEM==\"usb\", ATTR{idVendor}==\"0d28\", ATTR{idProduct}==\"0204\", MODE:=\"666\"`. Check `dmesg` for your device's Vendor/Product IDs.","message":"On Linux, without proper udev rules, pyOCD might require root privileges (sudo) to detect and access debug probes. This is a common permission issue.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}