Hello mbed Users,

 

How does one call an API?

 

To use Library functions do you just use #include at the beginning of the program?

 

Maybe a more basic tutorial for new C/C++ biginners?

Thanks,

Jim Mahoney

There are many C/C++ tutorials on the Internet, e.g. http://www.cplusplus.com/doc/tutorial/ Of course they do not cover the specific mbed libraries, but the principles are the same.

Thanks Mr. Meiners,

 

I did get a C++ Book, C++ Without Fear by Brian Overland, very down to earth, Very Readable, and very clear!

I am after how to use APIs in mbed, as you say mbed is for embedded microcontrollers and not PCs.

My background is a Forth Programmer, which is different, in Forth we define a word (a function or suboutine in other languages) and it is added to language, placed in the Dictionary, after which one just types the newly defined word into your program without worrying about including anything from a Library, the Dictionary is the Library in this case so everything is available at all times. Once you have finished your program and tested it you can optimize it by automaticly stripping out all unused Words from its runtime library.

C/C++, like Pascal the other language I use, is much more formal so it is a new learning experience, I am working on learning C/C++ because of the mbed concept and because I also want to learn C# for PC programs and C and C++ are the background for C#.

 

Thanks,

Jim Mahoney

Hi Jim,

We're going to be putting live a new cookbook soon, which will be the central community area for mbed resources such as mature libraries/components, and tutorials. I think this is a great opportunity to capture some of the information that could go in to a 101 type page to help new starters; it is sometimes very hard to put yourself in the position of a learner again, so if we work through it then it can be distilled in to a tutorial at a later date.

So, here are some notes to get us started, and you and others can add to it with questions/answers/examples and we'll see what is useful...

Introduction

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:

 

PwmOut myoutput(p21);

Here we have created an instance of the class PwmOut, called it myouput, 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 hance this overloading makes it act like one.

I hope that is some useful information. Anyone, feel free to ask questions, suggest what information would have been useful to know now you know it, make suggestions, contribute...

Simon

Thanks Simon!

 

That is very clear and easy to follow!

 

Thanks Again,

 

Jim Mahoney