{"id":3758,"library":"pylink-square","title":"PyLink: Python J-Link Interface","description":"PyLink is a Python package that provides an interface to SEGGER J-Link debug probes, allowing control and interaction with embedded targets from Python. It was developed by Square to integrate J-Link functionality into Python-based test infrastructure. The library is actively maintained, with the current version being 2.0.1, and typically sees updates for new features and bug fixes.","status":"active","version":"2.0.1","language":"en","source_language":"en","source_url":"https://github.com/Square/pylink","tags":["embedded","debugging","j-link","segger","hardware","microcontroller"],"install":[{"cmd":"pip install pylink-square","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"PyLink is a wrapper around the J-Link C SDK. The SEGGER J-Link drivers and shared libraries (DLL/SO) must be installed separately on the system for PyLink to function.","package":"SEGGER J-Link Software and Development Pack","optional":false},{"reason":"Used for system-level utilities, listed as an install requirement.","package":"psutil","optional":false}],"imports":[{"symbol":"JLink","correct":"from pylink import JLink"},{"symbol":"pylink","correct":"import pylink"}],"quickstart":{"code":"import pylink\nimport os\n\n# Replace with your J-Link's actual serial number (as a string).\n# Consider setting JLINK_SERIAL_NO and JLINK_TARGET_DEVICE as environment variables.\njlink_serial_no = os.environ.get('JLINK_SERIAL_NO', 'YOUR_JLINK_SERIAL_HERE')\ntarget_device = os.environ.get('JLINK_TARGET_DEVICE', 'CORTEX-M4') # Example: 'ATSAM4S2B' or 'STM32F407VG'\n\ntry:\n    # Initialize JLink object\n    jlink = pylink.JLink()\n\n    # Open a connection to your J-Link probe\n    jlink.open(serial_no=int(jlink_serial_no))\n    print(f\"Connected to J-Link: {jlink.product_name} (Serial: {jlink_serial_no})\")\n\n    # Connect to the target device\n    jlink.connect(target_device, verbose=True)\n    print(f\"Connected to target device: {target_device}\")\n\n    # Perform a simple operation, e.g., read target IDCODE\n    if jlink.connected() and jlink.target_connected():\n        print(f\"Target IDCODE: {hex(jlink.idcode())}\")\n        # Example: Reset the target\n        # jlink.reset()\n    else:\n        print(\"Failed to establish full connection to target device.\")\n\nexcept pylink.JLinkException as e:\n    print(f\"J-Link operation failed: {e}\")\nexcept ValueError:\n    print(\"Invalid J-Link serial number provided. Must be an integer.\")\nfinally:\n    # Always close the J-Link connection\n    if 'jlink' in locals() and jlink.opened():\n        jlink.close()\n        print(\"J-Link connection closed.\")\n","lang":"python","description":"This quickstart demonstrates how to establish a connection to a SEGGER J-Link debug probe and then connect to a target device. It then performs a basic operation, such as reading the target's IDCODE. Ensure `JLINK_SERIAL_NO` and `JLINK_TARGET_DEVICE` environment variables are set with your specific J-Link serial number and target CPU name, or replace the placeholder values. The SEGGER J-Link Software and Development Pack must be installed on your system."},"warnings":[{"fix":"Migrate your project to Python 3.x. If unable, pin `pylink-square<2.0.0`.","message":"Python 2 support has been entirely dropped starting from PyLink version 2.0.0. Projects still using Python 2 will need to upgrade their Python environment or use an older version of PyLink.","severity":"breaking","affected_versions":">= 2.0.0"},{"fix":"Download and install the appropriate J-Link Software and Development Pack from SEGGER's website for your operating system. Ensure the J-Link library path is correctly configured (e.g., via `PATH`, `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH` environment variables, or by copying to a system library directory).","message":"PyLink requires the SEGGER J-Link Software and Development Pack to be installed on the system, as it wraps the native C SDK. The library will not function without the underlying J-Link shared library (DLL on Windows, .dylib on macOS, .so on Linux) being present and discoverable by PyLink.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the `pylink` troubleshooting guide. Verify physical connections, ensure J-Link is not in use elsewhere, confirm target device name, interface, and power. For flash/erase, ensure the CPU is halted; sometimes a specific `set_reset_strategy` is needed for Cortex-M devices.","message":"Many operations, such as `open()`, `connect()`, `flash()`, and `erase()`, can raise 'Unspecified Error' exceptions. Common causes include: J-Link not physically connected, J-Link being used by another application, incorrect target device name, incorrect interface (JTAG vs. SWD), target not powered/connected, or the device not being properly halted before an operation.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that file paths are handled as expected by `os.fsencode()`. In most standard Python 3 applications, this change should be transparent or beneficial for UTF-8 paths.","message":"File paths passed to PyLink APIs (e.g., for flashing firmware) are now encoded using `os.fsencode()` to properly support UTF-8 file paths. If your application was implicitly relying on different encoding behavior for file paths prior to v2.0.0, this change might affect how non-ASCII paths are handled.","severity":"gotcha","affected_versions":">= 2.0.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}