The core mbed library provides an API for controlling the interfaces of a microcontroller, and other useful startup and runtime functions to help create programs. The API is basically a set of useful C functions and classes, just like any additional functions or classes you may write yourself.

Including the mbed library¶

All the mbed library components are made available by including the "mbed.h" header file:

#include "mbed.h"

Any line starting with a # is a C Preprocessor directive. The C Preprocessor is a program that transforms your source code by doing text mangling, text substitution, etc before it is actually put through the C Compiler. In this case, the #include "mbed.h" can be thought of as "copy everything in the file mbed.h, and paste it here".

This file contains more #include directives, which in turn pull in things like DigitalIn.h, AnalogOut.h where all the individual interfaces are delclared. This tells the compiler about all the functions that are available for you to call. So by including mbed.h, you easily get access to all the different interfaces we have defined for you in the mbed library and in the C standard library.

Creating interfaces and calling them¶

Most of the interfaces provided by the mbed API are based on object oriented C++ classes, meaning you create an object to represent the physical interface, then call methods (functions of a class) to interact with them. For example, if we wanted to create a Pulse-width Modulated (PWM) output to control a pin, we create an instance of a PwmOut object:

#include "mbed.h"

PwmOut myoutput(p21);

Here we have created an instance of the class PwmOut, called it myoutput, and passed it the parameters it needs to be created to the constructor; in this case, the pin name to associate with it.

You can see the description of this object and the methods it supports at /handbook/PwmOut, or by expanding the mbed library within the compiler and selecting PwmOut.

Calling methods¶

Now we have an instance of a class, we can call method on it. As shown by the API documentation in the compiler or on the handbook, it has methods such as period and puslewidth. Here is an example:

This tells us about the method period, and the parameters it takes. To call a method of a function, you use the format:

instance.method(parameters);

So for this, we could end up with a program such as:

#include "mbed.h"

PwmOut myoutput(p21);

int main() {
    myoutput.period(0.02);
    myoutput.pulsewidth(0.01);
}

In this case, we have set the period of the PWM output to 20ms, and the pulsewidth to 10ms.

Just one more thing...¶

For some common things, we also add a bit of syntactic sugar. In C++ you can do operator overloading which means defining the functionality of operators like =. So for example, PwmOut includes a method called write which sets the duty cycle (between 0.0-1.0, i.e. 0-100%). So whilst you could call write to set it to 50%:

myoutput.write(0.5);

we also make the operator = map to the same method:

myoutput = 0.5;

This is nice for things like DigitalOut, DigitalIn, AnalogIn, PwmOut etc where the pin feels like a normal variable (that just happens to be controlled by or control the outside world), and hence this overloading makes it act like one.