# Custom

Configuration

  debug_tool = `custom`

PIO Unified Debugger can be configured from “platformio.ini” (Project Configuration File):

- Debugging options
  - `debug_tool`
  - `debug_build_flags`
  - `debug_init_break`
  - `debug_init_cmds`
  - `debug_extra_cmds`
  - `debug_load_cmds`
  - `debug_load_mode`
  - `debug_server`
  - `debug_port`
  - `debug_svd_path`

## Examples

- J-Link and ST Nucleo

- J-Link as debugger and uploader

- ST-Util and ST-Link

- OpenOCD and ST-Link

- pyOCD and CMSIS-DAP

### J-Link and ST Nucleo

Segger J-Link probe and ST Nucleo F446RE board in pair with J-Link GDB Server:

- Install J-Link GDB Server

- Convert ST-LINK On-Board Into a J-Link

Note

You can use configuration below in pair with other boards, not only with ST Nucleo F446RE. In this case, please replace `STM32F446RE` with your own device name in `debug_server` option.

See full list with J-Link Supported Devices.

    [env:debug_jlink]
    platform = ststm32
    framework = mbed
    board = nucleo_f446re

    debug_tool = custom
    debug_port = :2331

    debug_server =
      /full/path/to/JLinkGDBServerCL
      -singlerun
      -if
      SWD
      -select
      USB
      -port
      2331
      -device
      STM32F446RE

    debug_init_cmds =
      define pio_reset_halt_target
          monitor reset
          monitor halt
      end
      define pio_reset_run_target
          monitor clrbp
          monitor reset
          monitor go
      end
      target extended-remote $DEBUG_PORT
      monitor clrbp
      monitor speed auto
      pio_reset_halt_target
      $LOAD_CMDS
      $INIT_BREAK

### J-Link as debugger and uploader

Segger J-Link probe as debugger and uploader for a custom board. If you plan to use with other board, please change device `MK20DX256xxx7` to a valid identifier. See supported J-Link devices at J-LINK.

- Install J-Link GDB Server

    [env:jlink_debug_and_upload]
    platform = teensy
    framework = arduino
    board = teensy31
    extra_scripts = extra_script.py
    upload_protocol = custom
    debug_tool = jlink
    debug_server =
      /full/path/to/JLinkGDBServerCL
      -singlerun
      -if
      SWD
      -select
      USB
      -port
      2331
      -device
      MK20DX256xxx7

extra_script.py

Place this file on the same level as “platformio.ini” (Project Configuration File).

    from os import makedirs
    from os.path import isdir, join
    Import('env')

    def _jlink_cmd_script(env, source):
        build_dir = env.subst("$BUILD_DIR")
        if not isdir(build_dir):
            makedirs(build_dir)
        script_path = join(build_dir, "upload.jlink")
        commands = ["h", "loadbin %s,0x0" % source, "r", "q"]
        with open(script_path, "w") as fp:
            fp.write("\n".join(commands))
        return script_path

    env.Replace(
        __jlink_cmd_script=_jlink_cmd_script,
        UPLOADER="/full/path/to/JLink",
        UPLOADERFLAGS=[
            "-device", "MK20DX256xxx7",
            "-speed", "4000",
            "-if", "swd",
            "-autoconnect", "1"
        ],
        UPLOADCMD='"$UPLOADER" $UPLOADERFLAGS -CommanderScript ${__jlink_cmd_script(__env__, SOURCE)}'
    )

### ST-Util and ST-Link

On-board ST-Link V2/V2-1 in pair with ST-Util GDB Server:

    [env:debug]
    platform = ststm32
    framework = mbed
    board = ...
    debug_tool = custom
    debug_port = :4242
    debug_server = $PLATFORMIO_CORE_DIR/packages/tool-stlink/bin/st-util

### OpenOCD and ST-Link

On-board ST-Link V2/V2-1 in pair with OpenOCD GDB Server:

    [env:debug]
    platform = ststm32
    framework = mbed
    board = ...
    debug_tool = custom
    debug_server =
      $PLATFORMIO_CORE_DIR/packages/tool-openocd/bin/openocd
      -f
      $PLATFORMIO_CORE_DIR/packages/tool-openocd/scripts/board/st_nucleo_f4.cfg

### pyOCD and CMSIS-DAP

Using pyOCD for CMSIS-DAP based boards

Firstly, please install pyOCD and check that `pyocd-gdbserver --version` command works.

    [env:debug]
    platform = ...
    board = ...
    framework = mbed
    debug_tool = custom
    debug_server = pyocd-gdbserver