README.md

qube - Qt Creator "Bare-Metal" Qbs Project Templates for STM32 Development with STM32CubeMX

Brief

The aim of this project is to simplify using the Qt Creator IDE with its BareMetal plugin to program, compile and debug STM32 microcontroller projects generated by the STM32CubeMX software.

To use these templates you will need to install the Qt Creator, GNU ARM Embedded Toolchain, OpenOCD software packages and the Newlib C standard library into your system.

Screenshots

Debugging session:

Supported Microcontroller Series

• STM32F0

• STM32F1

• STM32F2

• STM32F3

• STM32F4

• STM32F7

• STM32L0

• STM32L1

• STM32L4

• STM32H7

Supported RTOS and Libraries

• FreeRTOS

• Newlib (C Standard Library)

• CMSIS

• CMSIS Math (DSP)

• HAL

• LL

• Audio

• USB Device

• USB Host

• STMTouch

• STemWin

• FatFs

• LibJPEG

• LwIP

• mbedTLS

• Custom (user-defined) Libraries

Installation

These templates are supposed to work correctly at least on fully updated Ubuntu 16.04 LTS, Ubuntu 18.04 LTS and Arch Linux operating systems using Qt Creator 4.6 or later versions.

Ubuntu 16.04 instructions

• Run sudo apt install gcc gcc-arm-none-eabi gdb gdbserver gdb-arm-none-eabi binutils-arm-none-eabi openocd libnewlib-dev libnewlib-doc libnewlib-arm-none-eabi libstdc++-arm-none-eabi-newlib newlib-source

• Next, you can try to use the default Qt Creator version from Ubuntu repositories by executing sudo apt install qtcreator qtcreator-doc qbs, or you can download and install Qt Creator from its official web-site (recommended)

• See the Known Issues below

Ubuntu 18.04 instructions

• Run sudo apt install gcc gcc-arm-none-eabi gdb gdbserver gdb-multiarch binutils-arm-none-eabi openocd libnewlib-dev libnewlib-doc libnewlib-arm-none-eabi libstdc++-arm-none-eabi-newlib newlib-source

• Next, you can try to use the default Qt Creator version from Ubuntu repositories by executing sudo apt install qtcreator qtcreator-doc qbs, or you can download and install Qt Creator from its official web-site (recommended)

• See the Known Issues below

Arch Linux Instructions

• Run pacman -S gcc gdb arm-none-eabi-binutils arm-none-eabi-gcc arm-none-eabi-gdb arm-none-eabi-newlib openocd qtcreator

Qt Creator Configuration

Make sure to configure Qt Creator as shown in the screenshots below.

Qt Creator Configuration Screenshots

• Enable the BareMetal plugin

• Add and configure OpenOCD as a GDB Server Provider for BareMetal projects

  • Start the OpenOCD session manually (recommended)

    

  • You may want to try using one of the available startup modes if you don't like starting up an OpenOCD session manually

    

  • OpenOCD startup commands

  set remote hardware-breakpoint-limit 6
  set remote hardware-watchpoint-limit 4
  set mem inaccessible-by-default off
  monitor arm semihosting enable
  monitor reset halt
  load
  monitor reset halt
  

• Add a new Device type named ST-Link v2 and set its GDB Server Provider the previously created OpenOCD item

  

• Configure the Debugger settings

  

• Configure the GDB settings

  

• Configure the GDB Extended settings

  

• Add a new debugger binary

  • If Qt Creator has already detected your GCC ARM GDB debugger then you can skip this step and use the automatically detected one in the next steps

  • Depending on your system, you should use either one of arm-none-eabi-gdb or gdb-multiarch binaries (whichever you have); if you have neither of those then it's possbile that your standard gdb binary comes with "multiarch" support built-in so you can just use it instead

  

• Add two new compiler binaries for C and C++

  • If Qt Creator has already detected your GCC ARM compilers (for C and C++) then you can skip this step and use the automatically detected ones in the next step

  

  

• Create a new Kit using the added device type, debugger and compilers, then make the kit as default

  

• Choose the Projects Directory as you wish, but make sure to change the Default build directory to the build directory of the project's directory, instead of an upper directory, by replacing the ../ prefix with ./build/

  

• Configure the Qbs profile for the newly added Kit

  

Usage

1. In your STM32CubeMX project choose "Makefile" as your "Toolchain / IDE" in the "Project" tab of the "Project Settings" window

2. Select the "Copy only the necessary library files" radio-button in the "Code Generator" tab of the "Project Settings" window

3. Generate the code using the "Project -> Generate Code" menu entry or the toolbar button or the "Ctrl+Shift-G" shortcut

4. Copy the contents of one of this repository's template directories (correcsponding to your microcontroller series) to the generated project's directory

5. Rename the template-stm32xy.qbs file to your-project-name.qbs (optional)

6. Open your-project-name.qbs file using Qt Creator's "Open Project" button

7. If the "ARM-None-EABI" kit wasn't selected as default in your Settings you will have to open the "Project" tab and activate the "ARM-None-EABI" kit under "Build & Run" while disactivating the other kits

8. Open the your-project-name.qbs file using the code editor and tune the project's properties according to your needs

9. Don't forget to set the microcontroller_series property in the Qbs file to choose your exact microcontroller series

10. If you need semihosting in your DEBUG build you should change the libc_sys property in the Qbs file to "semihosting"

11. To start debugging a firmware you'll need to start up a working OpenOCD session. You can use one of the provided configuration files, for example, by running openocd -f ./openocd/openocd-stlink-v2-1.cfg in the porject's directory, or you can use one of the stock configuration files (i.e. openocd -f boards/st_nucleo_f4.cfg) or a custom one.

Tips

• You should examine the Makefile generated by STM32CubeMX to find additional compiler definitions required for your project.

  Example:

  ...
  ...
  # C defines
  C_DEFS =  \
  -D_TIMEVAL_DEFINED \
  -D_SYS_TIME_H_ \
  -DUSE_HAL_DRIVER \
  -DSTM32H743xx
  ...
  ...

  The "USE_HAL_DRIVER" and "STM32H743xx" are already handled by the template, but you will have to add the other two definitions into your project:

  cpp.defines: {
      var defines = base
  
      defines.push("STM32")
      defines.push("STM32H7")
      defines.push(project.microcontroller_series)
  
      if (project.hal) {
          defines.push("USE_HAL_DRIVER")
      }
  
      // Added by us
      defines.push("_TIMEVAL_DEFINED")
      defines.push("_SYS_TIME_H_")
  
      return defines
  }

Known Issues

• On older toolchain versions (like the one in Ubuntu 16.04) there is an ABI mismatch issue between the objects when linking Cortex-M7 projects which make use of the FPU:

  /usr/lib/gcc/arm-none-eabi/4.9.3/../../../arm-none-eabi/bin/ld: failed to merge target specific data of file /path/to/xxx.c.o
  /usr/lib/gcc/arm-none-eabi/4.9.3/../../../arm-none-eabi/bin/ld: error: /path/to/xxx.c.o uses VFP register arguments, /path/to/firmware.elf does not
  

  If you can't use a newer version of the toolchain then, as a workaround, you can disactivate the fpu_dp property and activate the cm4_instr property to use only Cortex-M4 instructions, then copy/replace the required files from the STM32CubeF4 library.

• As of September 1, 2018, Ubuntu 18.04 has a known issue with the "newlib" library packaging.

  If it is still not fixed when you are reading this then you will have to download the updated packages from the next Ubuntu release (codenamed Cosmic) and install those over the buggy ones. Download the libnewlib-arm-none-eabi and libnewlib-dev packages and install them to fix the issue (i.e. sudo dpkg -i libnewlib-arm-none-eabi_3.0.0.20180802-2_all.deb libnewlib-dev_3.0.0.20180802-2_all.deb).

License

The code is released under the MIT license, see the LICENSE file.