Zoltan Hudak / QtCreator_Support

Mbed support for QtCreator IDE. Visit https://os.mbed.com/users/hudakz/notebook/building-offline-with-qt-creator/ for more info.

Building and debugging offline on Linux with QtCreator IDE

This page provides step by step instructions how to create, build and debug MBED applications offline using

• the QtCreator IDE (usually part of a Linux distribution) and
• the GNU Arm Embedded Toolchain.
  
  
  

Main features

• Mbed CLI is used as the backend engine and QtCreator IDE is the GUI making life easier.
• No makefiles shall be edited.
• Enables to build Mbed OS 2 (aka Mbed Classic) or Mbed OS 6 (aka Mbed OS) applications.
• Supports custom targets.
• Works on Linux. (MS Windows is not supported anymore.)
• A common repository is shared rather than having a separate instance of Mbed OS and user libraries for each project.

How does it work

A bash script is run to parse and execute commands typed into the QtCreator's Make arguments edit box (located in the Build Steps Details). The commands are stored along with the project file. The bash script is stored in the ~/.local/bin/mbed.bat file of your linux machine and you are free to adapt it to your needs.
In comparison to mbed-cli compile it accepts a few additional options :

• The -os option can be used to build for Mbed OS 2. For example:

-m LPC1768 -os 2

• Libraries can be added with the -l option. For example:

-m LPC1768 -l TextLCD -l DS1820

See below the User libraries section for more details.

• The -r or --release option can be used to build with release profile.

-m NUCLEO_F446RE -r

• The -D or --macro option can be used to define macros. For example:

-m NUCLEO_F103RB -macro MY_MACRO -l DS1820

Once the compilation is complete it can also flash the selected target MCU/board. At the present it is using pyOCD, OpenOCD and lpc21isp for flashing. You can use any programmer supported by these tools (e.g. a serial port, DAP link or ST-link programmer/debugger).

Usage

Once installed and configured, creating a new Mbed project becomes as easy as

• Launch the QtCreator and then click on the + New Project button.

• Choose the Mbed project template.
  

• Give it a name (for example Blinky-os ) and select a repository to create in.
  

• Select the mbed kit

• Finish the new project

• The main.cpp will be opened for editing

• In the left-hand toolbar select Projects and for Build & Run select mbed

• In Build Steps open Details and type -m followed by a space and the name of your target board into the Make arguments edit box. For example:

-m LPC1768

• If you don't want your program to be automatically downloaded to the connected board's flash then deselect the all checkbox.
  

• If you want a clean compilation (delete existing object files) then select the clean checkbox.
  

• To launch compilation, in the left-hand toolbar select Edit and click on the Build Project button (Hammer) or press Ctrl+B
  Happy coding :)

Installation

Install the following software to your PC

GNU Arm Embedded Toolchain

• Version 9-2019-q4-major for Mbed OS 6
• If you'd like to build Mbed OS 2 programs install also version 6-2017-q2-update (see below Juan Pedro's comments for more details).
  

Mbed CLI

pyOCD

OpenOCD

QtCreator IDE (usually part of a Linux distribution)

Mbed OS

• In your home directory, create a new src/arm/sys folder and open it in terminal
• Issue the following commands

mbed import mbed-os
cd mbed-os
mbed update master
mbed config -G toochain GCC_ARM

Mbed support for QtCreator

• Import the Mbed support for QtCreator project into the online compiler. Type QtCreator_Support into the Import Name edit box and save the project.
• Right-click on the mbed.bat file and select Export File ...
• Save the file to the ~/.local/bin folder. (NOTE: In Linux ~ is a shortcut (alias name) for your home directory.)

~/.local/bin/mbed.bat

• To make the script (text file) executable open a terminal in the ~/.local/bin directory and execute:chmod +x mbed.bat
  

ubuntu:~/.local/bin$  chmod +x mbed.bat

• Click on the mbed_wizard_linux_zip folder
• Right-click on the mbed_wizard_linux.zip file and select Export File...
• Save the file to the ~/.config/QtProject/qtcreator/templates/wizards folder and unzip. The result should be as below:

~/.config/QtProject
          └── qtcreator
		      └── templates
		          └── wizards
		              └── mbed
		                  ├── ARMmbedLogo.png
		                  ├── main.cpp
		                  ├── mbed_app.json
		                  ├── project.config
		                  ├── project.creator
		                  ├── project.files
		                  ├── project.includes
		                  └── wizard.json

• Right-click on the custom_targets folder and select Export Folder ...
• Save the file to the ~/src/arm/sys folder and unzip:

~/src/arm/sys
          ├── custom_targets
          └── mbed-os

• In your home directory create a new ~/src/arm/app folder:

~/src/arm
      ├── app
      └── sys

• In your home directory create a new ~/src/arm/lib folder and copy & paste (collect) the folders with your library sources there:

~/src/arm
      ├── app
      ├── lib
      └── sys

Optional: For building Mbed OS 2 programs

• Because at the present it's impossible to import the Mbed 2 library using Mbed CLI
  • Download the ZIP repository from mbed-dev to your local drive and unpack it to the ~/src/arm/sys folder.
• Rename the unpacked mbed-dev-master folder to mbed. After that it should be three sub-folders in the ~/src/arm/sys folder:

~/src/arm/sys
          ├── custom_targets
          ├── mbed
          └── mbed-os

• Copy & paste the tools folder from the mbed-os to the mbed folder.

Configuration

When the installation is complete launch the Qt Creator and in the Help menu select About Plugins ...
Make sure that the BareMetal (experimental) plugin is checked.

• Close the dialog box and restart the QtCreator.
• In Tools menu select Options ...
• Proceed to Build & Run and add new mbedCustom C and mbed Custom C++ compilers. Provide the actual paths according to your system.
  

For the new mbed Custom C and Custom C++ compilers change the Custom Parser Settings ...:

• Copy & paste the following text into the Error message capture pattern edit box:

^.*[Ee][Rr][Rr][Oo][Rr][^.c][ \]]*([^@:,]*)[@:,]([0-9]*)(.*)

• Copy & paste the following text into the Warning message capture pattern edit box:

^.*[Ww][Aa][Rr][Nn][Ii][Nn][Gg][ \]]*([^@:,]*)[@:,]([0-9]*)(.*)

This will assure capturing error and warning messages during compilation and quick navigation to the related line.

• Add a new arm-gdb debugger. Make sure you select the arm-none-eabi-gdb-py (arm-none-eabi-gdb won't work)
  

• Proceed to the Devices and click on the Add ... button.
  

• Select the Bare Metal Device and click on the Start Wizard button.
  

• In Devices proceed to the Bare Metal tab. Click on the Add button and select OpenOCD.
  

• Go back to the Devices tab and select OpenOCD as the GDB server provider.
  

• Select Build & Run and proceed to the Kits tab. Click on the Add button and add the following new kit.
  

User libraries

User libraries can be shared among all the projects. Such approach requres less disk space and makes sure all programs use the same version of a library. If you keep your libraries in the recommended repository ( ~/src/arm/lib) then just add the directory name of your library (the relative path inside the library repository) into the Make arguments edit box prepended with -l . For example if you have a TextLCD and DS1820 library stored in the ~/src/arm/lib repository as below:

~/src/arm/lib
          └── Display
		      └── TextLCD
          └── TempSensor
		      └── DS1820

Then you can add them to your project as:

-m LPC1768 -l Display/TextLCD -l TempSensor/DS1820  

Another option is to copy & paste a folder containing library files to the project folder using your favorite file manager utility. However, in this case the library is not shared with other projects. Any modification to the library will affect only the given project.
Notice that when you then open the project in QtCreator you won't see the library folder yet.

You have to launch the compilation to get the folder added to the Projects pane.

As an alternative you can import a library into your local project from its URL repository

• In the Projects pane right-click on the main.cpp file and select Open terminal here (on Linux) or Open command prompt here (on Windows)
• Use the mbed add command followed by the library's URL repository to import the library. For example:
• Close the terminal (command prompt) window and return to the QtCreator.
• Launch compilation and the new library will appear in the Projects pane.
  

Creating a new library

• Launch the Qt Creator and open your project (or create a new one).
• In the Projects pane right click on your project name and select Add new ....
• Choose the C++ template and C++ Class then click on the Choose... button.
• In the Class Name edit box provide a name for your new class (for example MyLcdDriver).
• Click on the Browse button and create a new folder (e.g. MyLcdDriver) in your Project folder and then click on the Next button.

• Choose <None> for Add to version control and click on the Finish button.

• Edit your library files as needed and then compile the project.

• Once you are happy with it move the library folder to your library repository so you can easily share it with other projects.
  

Importing projects from online repository

One way is to export the program from the online compiler for the QtCreator toolchain

• Right-click on the project in the online compiler and export for the QtCreator toolchain.
• Once saved to the local drive, unzip the file and open the project's folder in a file manager.
• Delete all files and folders (mbed and mbed-os included) except user library folders, the .creator project file, source and header files (like main.cpp) and .json files.
• Open the .creator project file in QtCreator.
• Select the target system and board and compile.

Another method is to use Mbed CLI for import

• Open a terminal (on Linux) or command prompt (on Windows) in your mbed projects repository.
• Use the mbed import command followed by the programs's URL repository to import the program.
  For example:

mbed import https://github.com/ARMmbed/mbed-os-example-blinky

• When finished, open the folder and delete all files and folders (mbed and mbed-os included) except user library folders, source and header files (like main.cpp) and .json files.
• In the project's folder create an empty PROJECT_NAME.creator file (substitute PROJECT_NAME with your project name).
• Open the .creator project file in QtCreator.
• Select the target system and board and compile.

Custom targets

It is possible to build projects also for custom targets. Read Adding and configuring targets and have a look at the provided custom targets. I'm sure you'll be able to extend them by your favorite ones.

Once a custom target is added you compile for it by simply using its name. For example, to build for the BLUEPILL target type

-m BLUEPILL

into the Make arguments edit box in the Build Steps Details.

Debugging

Setting up debug tools

• In the Menu select Tools > Options ... > Debugger and proceed to the GDB tab.
  
• Copy & Paste the following text into the Additional Attach Commands edit pane:

monitor reset halt
load
monitor reset halt

• Click on the OK button to save the changes.
  
  
• In the Tools menu select External > Configure ...
  
  
  
• Click on the Add button and select Add Category.
  
  
  
• Name it MBED.
• Select MBED, click on the Add button and select Add Tool.
  
• Change its name to pyOCD and provide Description, Executable, Arguments and Working directory according to the path selected when you installed pyOCD to your system.
  
  
  

• In ~/.local/bin create a new text file for each group of boards you'd like to debug. For example PyOCD, NUCLEO-F103, NUCLEO-F4XX, NUCLEO-F7XX
  

• Type or paste the following text into the PyOCD file:
  

#!/bin/bash
~/.local/bin/pyocd-gdbserver

• Type or paste the following text into the NUCLEO-F103 file:
  

!/bin/bash
openocd -s /usr/local/share/openocd/scripts -f /usr/local/share/openocd/scripts/board/st_nucleo_f103rb.cfg

• Type or paste the following text into the NUCLEO-F4XX.bat file:
  

#/bin/bash
openocd -s /usr/local/share/openocd/scripts -f /usr/local/share/openocd/scripts/board/st_nucleo_f4.cfg

• Type or paste the following text into the NUCLEO-F7XX.bat file:
  

#!/bin/bash
openocd -s /usr/local/share/openocd/scripts -f /usr/local/share/openocd/scripts/board/st_nucleo_f7.cfg

• NOTE: Modify the path to the OpenOCD folder in the scripts above according to the actual path on your system.

• Finally save and close all files and make them executable with the following commnad:

chmod +x file_name

Enter gnome-terminal as Executable and the path to the associated batch file prepended with -- as Arguments.
For example:

-- ~/.local/bin/OpenOCD_F103

Debugging on boards equipped with CMSIS-DAP interface

We'll use pyOCD GDB server to debug on boards equqipped with CMSIS-DAP interface (e.g. mbed LPC1768).

• Launch the Qt Creator.
  
• Open for example the Blinky-os project for the LPC1768 target (or create a new one) and open main.cpp for editing.
  
• Connect your mbed LPC1768 board over a USB cable to the PC.
• In the Tools menu select External > MBED > pyOCD.
  
  
  
• That will launch a pyOCD GDB server.
  
  
  
• Return to the Qt Creator and in the left-hand toolbar select Projects and for Build & Run select Mbed > Build.
  

For some unknown reason when local file system and semihosting is enabled debugging for LPC1768 boards fails. A workaround is to compile for a custom (dummy) LPC1768 target board with local file system and semihosting disabled. That's why a custom target LPC1768DBG is provided. Have a look at the ~/src/arm/sys/custom_targets/mbed-os/custom_targets.json configuration file.

• Build the project for the dummy LPC1768DBG custom target board:
  • Type -m LPC1768DBG to the Make aguments edit box and click on the 'Hammer' button.
• Setup a break point by clicking in front of a source line.
  
• In Menu select Debug > Start Debugging > Attach to Running Debug Server.
  
• For Local executable click on the Browse ... button and select the Blinky-os/BUILD/LPC1768DBG/GCC_ARM-DEBUG/Blinky-os.elf file.
  
  

Debugging on boards equipped with ST-Link or J-Link interface

We'll use OpenOCD GDB server to debug on boards equqipped with ST-Link or J-Link interface (e.g. STM NUCLEO boards).

• Launch the Qt Creator.
  
• Open for example the Blinky-os project for a target board e.g. NUCLEO-F446RE or create a new one and open main.cpp for editing and build the project
  
• Connect your MBED board NUCLEO-F446RE over a USB cable to the PC.
  
• In the Tools menu select External > MBED > OpenOCD NUCLEO-F4XX.
  
  
  
• That will launch an OpenOCD GDB server for the selected group of boards.
  
  
  
• Return to the Qt Creator and in the left-hand toolbar select Projects and for Build & Run select Mbed > Build
  
• Build the project for the NUCLEO-F446RE target:
  • Type -m NUCLEO_FF446RE to the Make aguments edit box and click on the 'Hammer' button.
    
• Setup a break point by clicking in front of a source line.
  
• In the Menu select Debug > Start Debugging > Attach to Running Debug Server.
  
• For Local executable click on the Browse ... button and select the Blinky-os/BUILD/NUCLEO_F446RE/GCC_ARM-DEBUG/Blinky-os.elf file.