Comment trouver des informations dans la documentation technique ?

NIVEAU 1

Objectifs

  • Trouver l’information sur les différentes fonctions disponibles en ligne
  • Importer de nouvelles bibliothèques de fonctions
  • Comprendre la structure simplifiée d’un microcontroleur

Pré-requis

Qu’est-ce qu’une API ?

Application Programming Interface

Une API, ou Application Programming Interface, ou interface de programmation en français, est un ensemble de méthodes et de fonctions, rassemblées la plupart du temps en bibliothèques ordonnées. Ces méthodes et fonctions permettent alors de simplifier l’écriture d’une application complète en fournissant à leurs programmeurs des briques et des outils de base pour accéder aux divers modules du microcontroleur.

 

Les différentes bibliothèques de fonctions sont souvent fournies par le fabricant de la cible utilisée, qui a déjà réfléchi à la structure interne et matérielle du composant et qui est donc le plus à même de réaliser ce type de service pour ses utilisateurs. La plupart du temps, les bibliothèques sont associées à une documentation complète.

Cependant, de plus en plus de communautés de développement (quelque soit la cible ou le langage de programmation) proposent également des librairies complètes de fonctions pour des applications très spécifiques. Elles restent, normalement, bien documentées et utilisables par tout utilisateur du domaine.

Que contient l’API associée à MBED ?

Une nouvelle version de l’API de MBED vient de sortir, elle se nomme MBED-OS.5 (version 5.6 en novembre 2017). La documentation associée est disponible à l’adresse suivante : https://os.mbed.com/docs/v5.6.

 

MBED Compiler / MBed OS Version 5.6

Vous pouvez accéder à l’ensemble des méthodes de cette API à l’adresse suivante : https://os.mbed.com/docs/v5.6/reference/api-overview.html.

Cette dernière version contient plusieurs groupes de classes (programmées en C++, orientées objet) dont les suivantes :

  • Platform permettant la gestion des fonctions de base du microcontroleur, en particulier l’attente (wait)
  • Drivers permettant l’accès aux diverses interfaces d’entrées/sorties du composant (y compris les bus de communications standards)

Où trouver les bibliothèques et les fonctions ?

MBED-OS et sa documentation

L’API de base qui est fournie dans l’ensemble des exemples proposés lors de la création d’un projet est la bibliothèque MBED (ou MBED-OS). Comme mentionné dans le paragraphe précédent, elle contient les fonctions de base pour que le microcontroleur puisse interagir avec l’extérieur.

Les classes et fonctions proposées sont déjà nombreuses. Comment s’y retrouver alors dans tout ceci ? Il existe plusieurs méthodes pour trouver la documentation associée à telle ou telle fonction.

Si vous connaissez le nom de la fonction

Le plus simple est d’aller sur la page web de l’API de MBED-OS et de taper dans la barre de recherche le nom de la fonction recherchée :

Après avoir lancé la recherche, vous obtenez alors une page de la sorte :

Vous trouvez alors les différents renseignements sur l’utilisation de la fonction en question. Vous pouvez également trouver des fonctions équivalentes ou proches, ainsi que des exemples de code.

Si vous connaissez le nom de la classe associée

Vous pouvez également aller directement dans votre projet (en ligne) et cliquer sur l’API nommé mbed (ou mbed-os). Apparaissent alors la liste des classes et des structures associées à cette API.

Que contient cette documentation ?

Lorsqu’on arrive sur la documentation (en ligne ou via le projet) d’une classe, on obtient une page de cette sorte :

 

On retrouve, en tête de cette page, la liste des différentes fonctions que contient cette classe (regroupement de fonctions autour d’un même thème).

Chacune des fonctions est ensuite expliquée. On retrouve le prototype, pour pouvoir l’utiliser, un bref descriptif et parfois un exemple d’utilisation.

Importer des bibliothèques répertoriées par MBED

Pour pouvoir importer des bibliothèques répertoriées par MBED, il suffit, lorsque vous êtes dans le projet dans lequel vous voulez importer la bibliothèque (au niveau du workspace), de cliquer dans la barre d’outils sur Import :

 

Une nouvelle page s’ouvre alors, il faut choisir l’onglet Libraries :

Il faut ensuite lancer une recherche par mot clef :

Il suffit alors de double-cliquer sur la bibliothèque que vous souhaitez importer et quelques secondes plus tard, elle se retrouve dans votre projet.
La dernière étape consiste à inclure cette bibliothèque (par exemple ici la bibliothèque mbed.h) par la ligne de code suivante, placée tout en haut de votre code principal :

#include "mbed.h"

Comment utiliser des bibliothèques externes ?

Ajout à un projet existant

Il est également possible d’importer des bibliothèques externes (comme la plupart que vous utiliserez dans les prochains tutoriaux). Pour cela, il faut disposer d’un fichier archivé (type *.zip) contenant cette bibliothèque (voir paragraphe suivant).

 

Pour pouvoir importer ensuite cette bibliothèque, il suffit, lorsque vous êtes dans le projet dans lequel vous voulez importer la bibliothèque (au niveau du workspace), de cliquer dans la barre d’outils sur Import :

Dans la fenêtre suivante, il faut sélectionner l’onglet Upload :

En bas de cet onglet, vous avez la possibilité de choisir un fichier à ajouter :

Quelques exemples de bibliothèques

Voici quelques bibliothèques que vous pouvez utiliser lors des prochains tutoriaux :

 

C’est quoi le CookBook de MBED ?

Il existe une section appelée Cookbook sur le site de MBED. Cette section regroupe un grand nombre d’exemples d’applications associant souvent des modules spécifiques. Ces exemples sont souvent associés à des bibliothèques que l’on peut directement inclure depuis la page du CookBook en cliquant sur Import to Compiler.

Tutoriel lié

MInE Prototyper Prototyper avec Nucleo et MBED

Nucleo – Trouver des informations dans la documentation