Getting started with Mbed OS

Different IDEs for programming the codelabs

For programming your target device in the different codelabs, you may use different tools. This codelab presents the different alternatives, including the preferred ones which are Mbed Studio. You will program your first Mbed OS programs and run them on your target device.

What you’ll build

In this codelab, you will get started with your first Mbed OS programs through a simple example.

What you’ll learn

How to develop an application using Mbed Studio and the Mbed OS framework.
How to add tracing in your application for efficient debugging.

What you’ll need

Mbed Studio for developing and debugging C++ code snippets.
Some prior basic knowledge of C++ programming.

Installation of required software components

We are going to practice all codelabs using Mbed Studio, that allows you to develop and debug Mbed OS applications. It is available under Mbed Studio.

Note that it also possible to use an online tool named Arm Keil Studio Cloud. The user guide for the online tool is available here. The UI is quite similar to the offline tool. Be aware that there may exist some slight differences in the UI that are not always reflected in the codelabs.

For both tools, you need to create an account by following the instructions the Sign up under Keil Studio login.

Note that for flashing and debugging from the online tool, you need to use a browser that supports the WebUSB API. Browser compatibility is documented under WebUSB compability. Unfortunately, at this time, neither Firefox nor Safari does support it.

**Create your first Mbed OS project**

Once you are ready to use your development platform, you may create and compile a new empty program called “bike-computer” by executing the following steps:

Use “File -> New Program ->” and choose “Mbed OS 6 | mbed-os-example-blinky program” as the base program. Name your program “bike-computer”.
You should see a new program in your workspace as illustrated below.

Make sure that the Mbed OS library has been imported correctly. Your program should be using the latest version - for this codelab and the following ones, we will be using version 6.17.0. If the library imported when creating a new program is not the latest one, you may update it in the Mbed Libraries tab. Since the Mbed OS library occupies more than 1GB of storage space on your hard drive, it is useful to note that you may share the Mbed OS library among several projects.
Connect your target device. Under Target, select the DISCO_H747I device that should appear in the list. Your device should be recognized automatically.

Configuration and compilation

For configuring and compiling your program, you need to accomplish the following steps: - Before compiling the program, upload the mbed_app.json file provided below to your project (the file must be named “mbed_app.json”). This file contains useful information for the Mbed build tools as described in build rules. - Also upload the “.mbedignore” file as documented below before compiling. - Compile the program for the specific target. It should compile without errors. - After successfull compilation, you should be able to run the project on your target device by pressing the button. You should see the first led blinking on your development board.

mbed_app.json

{
    "macros": [
      "MBED_CONF_MBED_TRACE_FEA_IPV6=0"
    ],
    "config": {
      "main-stack-size": {
       "value": 4096
      }
    },
    "target_overrides": {
      "*": {
        "mbed-trace.enable": false,
        "platform.stdio-convert-newlines": true,
        "platform.stdio-baud-rate": 115200,
        "platform.default-serial-baud-rate": 115200,
        "platform.stdio-buffered-serial": true,
        "target.printf_lib":"minimal-printf",
        "platform.minimal-printf-enable-floating-point": true,
        "platform.minimal-printf-set-floating-point-max-decimals": 2
      },
      "DISCO_H747I": {
        "mbed-trace.enable": true,
        "mbed-trace.max-level": "TRACE_LEVEL_DEBUG"      
      }
    }
  }

Excluding some files from the build process

An advanced feature for accelerating the compilation phase when using the offline tool is to add a file called “.mbedignore” at the root of the project (see mbedignore for details). By default, all files included in the Mbed OS library are compiled, which may take quite some time. For many programs and in particular the programs that we will develop here, most components are not required and may be excluded from the build process. An example of “.mbedignore” file is provided below:

.mbedignore

mbed-os/drivers/device_key/*
mbed-os/drivers/source/usb/USBMSD.cpp
mbed-os/drivers/source/SFDP.cpp
mbed-os/connectivity/cellular/*
mbed-os/connectivity/drivers/*
mbed-os/connectivity/FEATURE_BLE/*
mbed-os/connectivity/libraries/*
mbed-os/connectivity/lorawan/*
mbed-os/connectivity/lwipstack/*
mbed-os/connectivity/nanostack/*
mbed-os/connectivity/netsocket/*
mbed-os/connectivity/nfc/*
mbed-os/features/FEATURE_BOOTLOADER/*
mbed-os/features/frameworks/mbed-client-cli/*
mbed-os/features/frameworks/COMPONENT_FPGA_CI_TEST_SHIELD/*
mbed-os/platform/randlib/*
mbed-os/storage/kvstore/*

Be aware that the “.mbedignore” file may need to be adapted to specific versions of the Mbed OS library, since the folder structure of the Mbed OS library may also be modified from a version to the next. The one provided as example is functional with version 6.17.0. Also do make sure to name the file “.mbedignore” without any extension.

Debugging with printf statements

Debugging is an important and required part of the development process. On embedded systems, debugging functionalities are often more limited as compared to other systems. Parts of the debugging process will be covered in a next codelab. In this section, we present how to use printf statements and predefined macros for efficient and flexible debugging using print.

A good introduction to using printf statements including using macros is given on Debugging using printf. The basic principle of the macros is to categorize printf statements by severity levels, such as DEBUG, WARNING and ERROR. To do so, one needs to:

Define levels of severity.
For compiling and running the program, specify which level has to be used.

The macros use the level you specified in an #if condition. That condition can control the format of the information the macro prints, or whether it prints anything at all. This gives the developer full control of the debug information presented at every run.

The mechanism described above is already implemented in the “mbed_trace” library ( mbed-trace library). For using this library, the developer needs to:

Define the trace-level configuration parameter and enable tracing for the application in the “mbed_app.json” file
Include the appropriate header file in the cpp file where tracing must be implemented and define a TRACE_GROUP for identifying the tracing specific to this file.
Initialize the library in the main function

main.cpp

#include "mbed.h" 

#include "mbed_trace.h"
#if defined(MBED_CONF_MBED_TRACE_ENABLE)
#define TRACE_GROUP  "MAIN"
#endif // MBED_CONF_MBED_TRACE_ENABLE

int main() {
   ...
#if defined(MBED_CONF_MBED_TRACE_ENABLE)
   mbed_trace_init();
#endif
   ...
}

To print something, use the tr_<level> macros in the code (tr_debug, tr_info, tr_warning, or tr_error).
In addition, set the output function (printf by default) and filter in run-time the traces by group filtering (see mbed-trace library for more details).

Modify your “main.cpp” file by adding some tracing. Compile it, run it and observe that your message prints correctly on the console. Do NOT forget to set the baud rate of your console to 115'200 baud, since this is the value set in the “mbed_app.json” file.

In conclusion, using printf statements is a required tool for debugging embedded systems, and using the mbed_trace library offers full flexibility in how tracing is enabled at compile time and filtered at run time.

At this point, it it time to dig into more C++ programming by experimenting the C++ Basics Codelab.