Introduction
Bonjour,
Ne trouvant pas de tuto clair en Français sur l’utilisation de la bibliothèque OneButton, mais plutôt des infos parsemées sur le forum et sur GitHub, je me suis dit que j’allais en faire un.
Ce tuto se veut le plus simple possible, mais n'étant pas très pédagogue, il est probable que des précisions ou modifications soient apportées au fur et à mesure.
Gérer un bouton ce n'est pas toujours aussi simple qu'il y parait, car il y a ce que l'on appelle des rebonds. Pour ne pas avoir à créer soit même son anti-rebonds, utiliser une bibliothèque simplifie la vie L'avantage c'est que OneButton inclut un anti-rebonds (basé sur une machine à état décrite ici).
Bien entendu il existe d’autres bibliothèque très simples et bien conçues pour gérer les boutons, comme Toggle ou SimpleBouton, par exemple... Je vous laisse les découvrir, ce tuto parle de OneButton.
Manipulation de la bibliothèque OneButton
Installation
Pour utiliser la bibliothèque OneButton, rien n’est plus simple ! Elle est disponible dans le gestionnaire de bibliothèques Arduino, il suffit donc de la chercher et de taper installer.
Si vous préférez faire cela à la main, tout d’abord téléchargez le fichier .zip sur GitHub :
Ensuite, décompressez le fichier et ajoutez le à votre code, en cliquant sur Croquis → Inclure une bibliothèque → Ajouter la bibliothèque .ZIP …
Initialisation
Ensuite, dans votre code, vous incluez la bibliothèque avec la directive de préprocesseur #include
#include <OneButton.h>
Puis vous définissez une instance de la classe - un objet - bouton rattachée par exemple ici à la pin n°2 de votre carte Arduino :
OneButton bouton(2); // bouton sur la pin 2 câblage pin - bouton – GND
Attention, depuis qu'un bug à été découvert (cf cette issue sur GitHub) - sur certaines cartes Arduino spéciales comme la NANO ESP32 par exemple l'utilisation de pinMode dans le constructeur ne fonctionne pas comme espéré (le mode est perdu avant d'arriver au setup()), et donc la pin n'est pas configurée comme voulu pour le bouton.
Pour corriger cela, Matthias Hertel a modifié sa bibliothèque pour y intégrer une fonction appelée setup dans laquelle on peut passer
- La pin du bouton,
- Le mode (c'est-à-dire si la pin est en
INPUT_PULLUPou non) - Le sens dans lequel le bouton fonctionne (si il est actif à
LOWou àHIGH)
Pour l'utiliser, il vous suffit d'ajouter dans le setup, avant d'attacher vos fonctions de callback aux actions possibles sur le bouton (click, etc...), l'instance du bouton suivie de la fonction et de ses paramètres. Par exemple :
// on crée l'instance du bouton, sans lui passer la pin en paramètre
OneButton bouton;
...
void setup()
{
/*
On indique que le bouton est sur la pin 2, que cette pin est
en INPUT_PULLUP, et que le bp est actif à `LOW` (il retourne `LOW`
quand il est pressé) :
*/
bouton.setup(2, INPUT_PULLUP, true);
// la suite du code...
}
Pour que votre programme soit fiable sur toutes les cartes (+ de portabilité) - et de manière général parce que c'est une bonne pratique d'utiliser des fonctions qui sont sûr de marcher sans "tomber en marche" - il est préférable d'utiliser cette fonction
setup.
Ensuite vous pouvez définir quelles fonctions appeler lors du click, doubleclick ou click long. Ces fonctions sont appelées callback (en anglais pour fonction de rappel) – voir réponse de @J-M-L
void fonctionSimpleClick() {...}
void fonctionDoubleClick() {...}
Vous pouvez les appeler comme vous le voulez ! Il faut juste que ce soit ces fonctions que vous attachiez au(x) bouton(s) dans le setup !
Utilisation
Dans le setup, vous liez les fonctions aux objets boutons que vous avez créés ( qui correspondent aux boutons physiques ) :
void setup()
{
bouton.attachClick(fonctionSimpleClick);
bouton.attachDoubleClick(fonctionDoubleClick);
}
Enfin dans la loop vous demandez au bouton de vérifier si quelque chose s’est passé par l’appel de tick() sur le bouton. Il faut le faire assez souvent pour ne pas rater d’événements donc il ne faut pas que la loop ou les callbacks soient bloquants bien sûr (ce qui exlue l'utilisation des delay - mieux vaut utiliser millis!). C’est cet appel qui déclenchera l’appel de la fonction de callback si une action pré enregistrée (donc ici le simple click ou le double click) est activée
void loop()
{
bouton.tick();
}
Il existe d'autres méthodes dans cette bibliothèque, mais pour gérer un bouton c'est la base.
Voici un tableau regroupant toutes les fonctions utiles gérants des événements avec cette bibliothèque :
| Attacher la fonction | Description |
|---|---|
| attachClick | Se déclenche dès qu'un seul clic est détecté. |
| attachDoubleClick | Se déclenche dès qu'un double clic est détecté. |
| attachMultiClick | Se déclenche dès que plusieurs clics ont été détectés. |
| attachLongPressStart | Se déclenche dès que le bouton est maintenu enfoncé pendant 800 millisecondes. |
| attachDuringLongPress | Se déclenche périodiquement tant que le bouton est maintenu enfoncé. |
| attachLongPressStop | Se déclenche lorsque le bouton est relâché après un long maintien. |
"Les événements valides se produisent lorsque tick() est appelé après un nombre spécifié de millisecondes. Vous pouvez utiliser les fonctions suivantes pour modifier la synchronisation.
Remarque : Attacher un double-clic augmentera le délai de détection d'un simple clic. Si un événement de double-clic n'est pas attaché, la bibliothèque assumera un simple clic valide après une durée d'un clic, sinon elle doit attendre que le délai d'expiration du double-clic passe. En effet, un appel du callback pour un seul clic ne doit pas être déclenché en cas d'événement de double clic.
| Fonction | Défaut | Description |
|---|---|---|
setDebounceMs(int) |
50 msec |
Période de temps pendant laquelle ignorer les changements de niveau supplémentaires. |
setClickMs(int) |
400 msec |
Délai d'attente utilisé pour distinguer les clics simples des doubles clics. |
setPressMs(int) |
800 msec |
Durée de maintien d'un bouton pour déclencher un appui long. |
Vous pouvez modifier ces valeurs par défaut, mais sachez que lorsque vous spécifiez des durées trop courtes, il est difficile de cliquer deux fois ou vous créerez une pression au lieu d'un clic.
Fonctions supplémentaires
OneButton fournit également quelques fonctions supplémentaires à utiliser pour interroger l'état des boutons :
| Fonction | Description |
|---|---|
bool isLongPressed() |
Détecter si oui ou non le bouton est actuellement à l'intérieur d'un appui long. |
int getPressedMs() |
Obtenir le nombre actuel de millisecondes pendant lesquelles le bouton a été maintenu enfoncé. |
int pin() |
Obtenez la broche OneButton |
int state() |
Obtenir l'état OneButton |
int debouncedValue() |
Obtenir la valeur anti-rebond OneButton |
tick() et reset()
Vous pouvez spécifier un niveau logique lors de l'appel de tick(bool) , ce qui sautera la lecture de la broche et utilisera ce niveau à la place. Si vous souhaitez réinitialiser l'état interne de vos boutons, appelez reset()"
Cathode ==> GND
