Upload Methods
Upload methods are the different tools that Mbed CE's build system can use to get code onto your device. Some methods also support debugging and stepping through code.
In order to enable uploading, your board will need to have one or more upload methods configured for it. Some boards already have configuration provided by us (see here in the source). For boards that don't, or custom boards, you will need to provide the configuration yourself, by defining certain parameters in your top-level buildscript (or an include file). The different parameters and their values are explained in this document.
IMPORTANT: These variables need to be set in your CMakeLists immediately after including app.cmake, before any add_subdirectory() calls.
Once you configure some upload methods, you can then run cmake with the -DUPLOAD_METHOD=<method> argument to select the method and enable uploading your code to the target.
To upload an executable, just run ninja flash-xxx, where xxx is replaced by the name of the executable target. Don't forget that you can also use ninja help to see the list of all available targets.
To debug, first run ninja gdbserver in one terminal to start up the debug probe server. Then, you can connect to the GDB server in your debug tool of choice, or run ninja debug-xxx in another terminal to start command-line GDB on the given program.
The below table lists each upload method, the device types it works on, its parameters (variables that will have a fixed value) and its options (variables that are different for different people and should be set on the command line when you run cmake). Since this config is set by standard CMake code, it's very easy to add your own custom logic to adjust these variables as needed!
All current upload methods (see below for details):
| Name | CMake Argument | Supports Uploading | Supports Debugging | Upload Speed | Supported On |
|---|---|---|---|---|---|
| No upload method | -DUPLOAD_METHOD=NONE |
❌ | ❌ | N/A | N/A |
| Mbed USB | -DUPLOAD_METHOD=MBED |
✔️ | ❌ | Fast | All Mbed certified boards |
| J-Link | -DUPLOAD_METHOD=JLINK |
✔️ | ✔️ | Fast | Mbed boards with J-Link On-Board. Custom boards with a J-Link probe. |
| pyOCD | -DUPLOAD_METHOD=PYOCD |
✔️ | ✔️ | Medium | Almost all Mbed boards. Custom boards with an ST-Link or DAPLink probe. |
| OpenOCD | -DUPLOAD_METHOD=OPENOCD |
✔️ | ✔️ | Fast, if configured properly | Many different debug probes, including DAPLink and ST-Link. However, requires configuration. |
| STM32Cube | -DUPLOAD_METHOD=STM32CUBE |
✔️ | ✔️ | Fast | All STMicroelectronics Mbed boards, custom boards with ST_Link probes. |
| stlink | -DUPLOAD_METHOD=STLINK |
✔️ | ✔️ | Fast | All STMicroelectronics Mbed boards, custom boards with ST_Link probes. |
| ArduinoBossac | -DUPLOAD_METHOD=ARDUINO_BOSSAC |
✔️ | ❌ | Fast | Arduino Boards (w/ Arduino bootloader) |
| LinkServer | -DUPLOAD_METHOD=LINKSERVER |
✔️ | ✔️ | Fast | NXP and Freescale boards, custom boards with DAPLink probes |
| Picotool | -DUPLOAD_METHOD=PICOTOOL |
✔️ | ❌ | Fast | Raspberry Pi boards |
UPLOAD_METHOD_DEFAULT
Type: String
This sets the default upload method that CMake will use if one is not explicitly set.
GDB_PORT
Type: Integer
This controls the port that GDB servers will be run on when debugging. A value higher than 1024 is recommended to allow debugging without root on Linux/Mac.
This upload method interfaces with standard MBed boards which present themselves as USB drives. The Mbed python tools are used to automatically locate and flash boards connected to the system.
⚠️ Personally, I have found the MBED upload method to be extremely unreliable on Linux. It seems to be some sort of issue with the CMSIS-DAP firmware. If code uploads are not working reliably, switch to one of the other upload methods.
MBED_UPLOAD_ENABLED
Type: Bool
Whether the MBed upload method can be activated.
MBED_RESET_BAUDRATE
Type: Integer
Default: 9600
On some boards, Mbed Tools has to connect to the board's serial port in order to reset them. This configuration requires Mbed Tools to know the board rate the board is operating at (though you can also likely get away with setting a slower baud rate here than what's in use).
MBED_TARGET_UID
Type: String
UID of the Mbed board to be programmed. This is only needed if multiple of the same target are connected to your machine -- if it is not set, any one target will be flashed. You can get a the list of UIDs from python -m pyocd list.
This upload method connects to your processor via a J-Link JTAG box and the J-Link command line tools. It supports both flashing and debugging. CMake will automatically locate the J-Link tools in their standard install locations on Windows, Mac, and Linux.
JLINK_UPLOAD_ENABLED
Type: Bool
Whether the J-Link upload method can be activated.
JLINK_CPU_NAME
Type: String
The name that your processor is known by to J-link. These are listed here.
JLINK_UPLOAD_INTERFACE
Type: String
Method that the J-Link uses to talk to your processor. Can be 'JTAG' or 'SWD'. If unset, defaults to 'JTAG'.
JLINK_CLOCK_SPEED
Type: Integer or String
Clock speed of the JTAG or SWD connection. Accepts either a speed in kHz or "adaptive" to automatically determine speed using the RTCK pin.
This upload method utilizes Mbed's own pyOCD application to flash and debug your processor. pyOCD mainly supports the DAPLink and STLink debug probes integrated into Mbed dev boards, but can also use standalone DAP-based programmers and has experimental support for the J-Link probe. Unlike all other debuggers, pyOCD has the ability to recognize and display the threads that are currently running in Mbed RTOS. This makes it the most convenient debugging solution for many Mbed applications. Just be prepared to wait a while when stepping through code...
Installation of pyOCD is usually as simple as python3 -m pip install pyocd, though on some platforms there are additional binary components that need to be installed for certain debug probes.
NOTE: Some older MBed boards will need to have their firmware updated to work with pyOCD.
PYOCD_UPLOAD_ENABLED
Type: Bool
Whether the pyOCD upload method can be activated.
PYOCD_TARGET_NAME
Type: String
Name of your processor as passed to the -t option of pyOCD. This is usually the full or partial model number.
PYOCD_CLOCK_SPEED
Type: Integer or String
Clock speed of the JTAG or SWD connection. Default is in Hz, but can use k and M suffixes for kHz and MHz
PYOCD_PROBE_UID
Type: String
Probe UID to pass to pyOCD commands. This selects which upload tool is used when multiple are connected to your computer. You can get the UIDs from python -m pyocd list.
This upload method utilizes the OpenOCD application to flash and debug your processor. OpenOCD is highly configurable and supports a huge array of targets, from processors to flash memories to FPGAs. However, this flexibility comes at a cost: it can be a bit of a pain to configure. Normally, using OpenOCD with your target requires you to find or write special config scripts to configure it for each target. However, Mbed CE is attempting to provide working OpenOCD configs for as many boards as we can test, so hopefully you won't have to deal with this. Onceconfigured correctly, OpenOCD can be used as a versatile GDB server and flash programmer.
OpenOCD can be installed through most distro package managers, and Windows binaries can be downloaded from here. On Windows, if you extract the downloaded files into a folder called e.g. openocd-0.11 in Program Files, it should be automatically be detected by CMake.
Note: We recommend using at least openocd 0.11, as this brings in a great deal of improvements and fixes. Additionally, for support of some newer targets such as STM32U5, OpenOCD 0.12 might be required.
OPENOCD_UPLOAD_ENABLED
Type: Bool
Whether the OpenOCD upload method can be activated.
OPENOCD_CHIP_CONFIG_COMMANDS
Type: List of Strings
This config option specifies all OpenOCD commands needed to configure the program for your target processor. At minimum, this should include loading an interface config file and a target config file. Since these options may need to access scripts in the OpenOCD install dir, CMake provides the variable OpenOCD_SCRIPT_DIR which will resolve to the scripts directory of OpenOCD on the current machine.
OPENOCD_VERSION_RANGE
Type: String (CMake version range)
Acceptable version range of OpenOCD. This may be a single version (e.g. "0.12"), in which case it is treated as a minimum, or a versionMin...<versionMax constraint, e.g. "0.12...<0.13", to accept any 0.12.x version but not 0.13 or higher.
OPENOCD_ADAPTER_SERIAL
Type: String
Debug adapter serial number to pass to OpenOCD commands (using the 'adapter serial' command or an equivalent). This selects which adapter is used when multiple of the same type are connected to your computer. You can get the serial number using pyocd, from python -m pyocd list.
This uploader uses STMicroelectronics' official upload and debugging tools for its ST-LINK programmers. The upload tool can be obtained from the standalone STM32CubeProg package, but for the GDB server you need the STM32CubeIDE(2.8GB) or STM32CubeCLT(1.7GB), which includes both programs.
In my testing, STM32Cube is at least 5 times faster than PyOCD at uploading code to the chip, so if you have a large program it might be worth taking the time to set up. Also, its debugger seems to be considerably faster at things like setting breakpoints and single-stepping through code.
If you need the programmer only, you can install the relatively lightweight STM32CubeProg application. Once installed, find the STM32_Programmer_CLI executable in its install dir and pass the -DSTM32CubeProg_PATH=<path to STM32_Programmer_CLI> argument to CMake to point to it.
If you need the programmer and the debugger, you must install the whole STM32CubeIDE or STM32CubeCLT. If you installed to the default install location, CMake should find it automatically. If not, set the STM32CUBE_IDE_PATH or STM32CUBE_CLT_PATH variable to point to the IDE or CLT install dir, which CMake will use to find the other tools. Note that on Macs this needs to point to the IDE dir inside the app package, e.g. -DSTM32CUBE_IDE_PATH=/Applications/STM32CubeIDE.app/Contents/Eclipse.
Unfortunately, one big limitation of STM32Cube is that there are no ARM Linux builds. So if you are trying to use something like a Raspberry Pi, you might have to use OpenOCD or stlink instead.
STM32CUBE_UPLOAD_ENABLED
Type: Bool
Whether the STM32Cube upload method can be activated.
STM32CUBE_CONNECT_COMMAND
Type: List
"Connect" (-c) command to pass to the programmer to connect to your target device. port=SWD should be all that's needed for most Mbed boards, but some also seem to need reset=HWrst.
STM32CUBE_GDBSERVER_ARGS
Type: List
Arguments to pass to the ST-Link gdbserver. --swd should be all that's needed in most situations.
STM32CUBE_PROBE_SN
Type: String
Serial number of the ST-Link probe to connect to. If blank, will connect to any probe. You can get the list of serial numbers plugged into your machine with STM32_Programmer_CLI -l.
This upload method is an open-source clone of ST's STM32CUBE flasher and debugger, supporting a wider range of devices and host machines.
It can be downloaded from the project releases page, or installed through your package manager on many linux distributions. On Windows, once the stlink folder has been extracted into Program Files, it should be automatically be detected by CMake.
STLINK_UPLOAD_ENABLED
Type: Bool
Whether the STLINK upload method can be activated.
STLINK_LOAD_ADDRESS
Type: String
Load address argument to pass to stlink.
STLINK_ARGS
Type: List of Strings
Arguments to pass to stlink programs. The list of valid options is here.
STLINK_PROBE_SN
Type: String
Serial number of the ST-Link probe to connect to. If blank, will connect to any probe. You can get the list of serial numbers plugged into your machine with st-info --serial.
This upload method is Arduino's variant of the bossac upload tool, with additional patches to enable it to work with certain Arduino devices. To install it, you must either:
- Install Arduino IDE, then install the board package for one of the bossac boards (e.g. Nano 33 BLE).
- Or, download and install one of the binary packages using TinyGo's instructions page.
By default, CMake will search the Arduino IDE's package install dir ($HOME/.arduino*/packages/arduino/tools/bossac/1.9.1-arduino2 on Linux/Mac, %LocalAppData%/Arduino*/packages/arduino/tools/bossac/1.9.1-arduino2 on Windows) for the bossac executable. If the executable is not located there, you will need to specify it manually via CMake argument, e.g. -DArduinoBossac=/path/to/bossac.
Warning: If you have non-Arduino bossac in your PATH, CMake may find that instead unless you manually specify. Unfortunately Arduino did not create any way to tell if a bossac executable is built from their fork or not.
To use a board with ArduinoBossac, first boot it into bootloader mode by double-tapping the reset button. Then, figure out what serial port it shows up as and pass that to the ARDUINO_BOSSAC_SERIAL_PORT CMake parameter. Then, you should be able to flash it.
ARDUINO_BOSSAC_UPLOAD_ENABLED
Type: Bool
Whether the ArduinoBossac upload method can be activated.
ARDUINO_BOSSAC_SERIAL_PORT
Type: String
Serial port name to talk to the bootloader on, e.g. COM7 or /dev/ttyACM0.
As of 2023, NXP has released an official command-line tool for debugging their development boards. This replaces the old Redlink system that was tightly integrated with MCUXpresso IDE. (though, technically it doesn't replace Redlink, it just adds a new command line user interface on top and packages it as a standalone tool).
To install LinkServer, download and run one of the installer packages from here. The installers seem pretty straightforward for Windows, Mac, and Linux -- you just run the file after downloading it. That said, they only seem to support a pretty limited set of Linux distros -- I was able to get the package to install on Ubuntu 20 x64 but you might have to get creative on other distros.
Once you install LinkServer, CMake should find it automatically. If not, pass -DLinkServer_PATH=</path/to/LinkServer> to CMake.
LINKSERVER_UPLOAD_ENABLED
Type: Bool
Whether the LINKSERVER upload method can be activated.
LINKSERVER_DEVICE
Type: String
Chip name and board to connect to, separated by a colon. Example: MIMXRT1062xxxxx:MIMXRT1060-EVKB. This gets passed as the "device" argument to the LinkServer executable.
LINKSERVER_PROBE_SN
Type: String
Serial number, or substring of the serial number, of the probe to connect to. You can get the list of probes and their serial numbers from LinkServer probes.
Picotool is a program for uploading code to Raspberry Pi devices with UF2 ROM bootloaders. It's needed in order for Mbed to program these devices.
To install Picotool, on Windows, you may download a binary for the tool here and copy it into any location on your PATH. For other platforms, you will likely need to install it from source. Install instructions can be found on the picotool repository.
As long as picotool is installed onto your PATH, it should be found automatically by CMake. If it's not, you can manually set its location by passing -DPicotool=/path/to/picotool. to CMake.
To use a board with Picotool, first boot it into bootloader mode by holding down the BOOT (aka BOOTSEL) button when plugging in the USB cable. To make sure it's working, run picotool info in a terminal, and you should see your board show up.
For Windows only: If your device is not showing up, you might need to manually install the WinUSB driver for it. This can be done using Zadig.
PICOTOOL_UPLOAD_ENABLED
Type: Bool
Whether the Picotool upload method can be activated.
PICOTOOL_TARGET_BUS
PICOTOOL_TARGET_ADDRESS
Type: Integer
If you have multiple RPi Pico devices plugged in, these options may be set in order to select which one you want to program. The bus number and address can be found by running picotool list when multiple RPi Picos in bootloader mode are plugged in.
These configurable options don't cover every single option that each upload method provides. To customize the commands used further, you can create your own upload method CMake module for your needs. First, copy one of the cmake scripts under mbed-os/tools/cmake/upload_methods to your own project (make sure that the location you add it to is on CMAKE_MODULE_PATH). Then, give it a new name, and change all variables using the old name to use the new name (e.g. UPLOAD_JLINK_FOUND -> UPLOAD_MYMETHOD_FOUND). Next, make the changes you need to the options and commands used, and add any needed configuration settings to your buildscript (including UPLOAD_MYMETHOD_ENABLED). Finally, you can activate the new upload method by passing the name to CMake via -DUPLOAD_METHOD=MYMETHOD.