Arduino UNO Q - Actionneur avec Retour de Position
Dans ce guide, vous apprendrez à contrôler un actionneur linéaire avec retour de position via un potentiomètre sur Arduino UNO Q et le Motor Shield Rev3. Vous apprendrez :
- Comment calibrer le potentiomètre de retour de l'actionneur
- Comment calculer la position actuelle de l'actionneur en millimètres
- Comment piloter l'actionneur vers une position cible spécifique automatiquement
- Comment surveiller et contrôler la position de l'actionneur depuis Linux via le Bridge
- Comment contrôler la position de l'actionneur à distance via Telegram
Pour le contrôle basique d'extension/rétraction sans retour, voir Arduino UNO Q - Actionneur.
Matériel Requis
Ou vous pouvez acheter les kits suivants:
| 1 | × | Kit de Capteurs DIYables (18 capteurs/écrans) |
Divulgation : Certains des liens fournis dans cette section sont des liens affiliés Amazon. Nous pouvons recevoir une commission pour tout achat effectué via ces liens, sans coût supplémentaire pour vous. Nous vous remercions de votre soutien.
À Propos de l'Actionneur Linéaire avec Retour de Position
Un actionneur linéaire avec retour de position possède un potentiomètre intégré dont la résistance change au fur et à mesure que la tige s'étend et se rétracte. En lisant ce potentiomètre, vous pouvez calculer la position actuelle de la tige et la déplacer vers une position cible précise.
Brochage de l'Actionneur Linéaire avec Retour de Position
Un actionneur linéaire avec retour de position possède 5 fils (ou 4 sur certains modèles) :
- Fils moteur (2) : alimentation et contrôle de polarité via le canal A du Motor Shield Rev3
- Fils potentiomètre (3) : VCC, GND et signal (curseur)
※ Note:
Le canal A du Motor Shield Rev3 utilise A0 pour la mesure de courant. Connectez le fil de signal du potentiomètre de retour de l'actionneur à A2 pour éviter tout conflit.
Fonctionnement
- Alimentez le moteur via le Motor Shield Rev3 (motor.run(MOTOR_FORWARD, 255) pour étendre, motor.run(MOTOR_BACKWARD, 255) pour rétracter, motor.brake() pour arrêter).
- Lisez le signal du potentiomètre avec analogRead(A2) — retourne une valeur 12 bits (0–4095) sur Arduino UNO Q.
- Utilisez map() pour convertir la valeur brute ADC en millimètres.
- Comparez la position actuelle avec la cible ; continuez à bouger ou arrêtez en conséquence.
※ Note:
Avant de contrôler la position, vous devez calibrer l'actionneur : étendez-le jusqu'à la limite maximale, lisez POTENTIOMETER_MAX ; rétractez-le jusqu'à la limite minimale, lisez POTENTIOMETER_MIN. Ces valeurs remplacent les espaces réservés dans le code.
Si vous n'êtes pas familier avec le Motor Shield Rev3 (brochage, fonctionnement et programmation), consultez d'abord le tutoriel Arduino UNO Q - Bouclier Moteur DC.
Schéma de Câblage
Cette image a été créée avec Fritzing. Cliquez pour agrandir l'image.
Code MCU
L'Arduino UNO Q dispose de deux processeurs : le MCU STM32 (gère le contrôle matériel en temps réel) et le MPU Qualcomm (exécute Debian Linux). Dans cette section, seul le MCU STM32 est programmé. Une section ultérieure montrera comment les deux processeurs fonctionnent ensemble.
Ce tutoriel est divisé en trois étapes :
Étape 1 – Calibrage
Exécutez ce code pour trouver les valeurs ADC brutes lorsque l'actionneur est complètement étendu et complètement rétracté. Notez les valeurs — vous les utiliserez aux étapes 2 et 3.
/*
* Ce code Arduino UNO Q a été développé par newbiely.fr
* Ce code Arduino UNO Q est mis à disposition du public sans aucune restriction.
* Pour des instructions complètes et des schémas de câblage, veuillez visiter:
* https://newbiely.fr/tutorials/arduino-uno-q/arduino-uno-q-actuator-with-feedback
*/
// Step 1: Calibration — find POTENTIOMETER_MIN and POTENTIOMETER_MAX values
// NOTE: Motor Shield Channel A uses A0 for current sensing.
// Connect the actuator's feedback potentiometer signal wire to A2.
#include <DIYables_DC_Motor.h>
#define POTENTIOMETER_PIN A2 // The Arduino UNO Q pin connected to the actuator's feedback potentiometer
DIYables_DC_Motor motor(MOTOR_CH_A);
void setup() {
motor.begin();
}
void loop() {
// extend the actuator fully
motor.run(MOTOR_FORWARD, 255);
delay(20000); // wait for actuator to reach its limit
int POTENTIOMETER_MAX = analogRead(POTENTIOMETER_PIN); // read max position value (0-4095 on UNO Q)
// TODO: note this value
// retract the actuator fully
motor.run(MOTOR_BACKWARD, 255);
delay(20000); // wait for actuator to reach its limit
int POTENTIOMETER_MIN = analogRead(POTENTIOMETER_PIN); // read min position value
// TODO: note this value
// stop
motor.brake();
while (true); // stop after one calibration cycle
}
Étapes Rapides
- Monter le bouclier : Emboîtez fermement le Motor Shield Rev3 sur les connecteurs de l'Arduino UNO Q. Connectez les fils du moteur de l'actionneur aux borniers à vis du canal A. Connectez l'alimentation 12V aux borniers d'alimentation du bouclier. Connectez le fil de signal du potentiomètre à A2, VCC du potentiomètre à 3,3V, GND du potentiomètre à GND.
- Connecter : Branchez l'Arduino UNO Q sur votre ordinateur avec un câble USB-C.
- Ouvrir Arduino App Lab : Lancez Arduino App Lab et attendez qu'il détecte votre Arduino UNO Q.
- Créer une nouvelle application : Cliquez sur le bouton Créer une nouvelle application.
- Donnez un nom à l'application, par exemple : DIYables_ActuatorFeedback
- Cliquez sur Créer pour confirmer.
- Trouvez le fichier sketch/sketch.ino et collez-y le code de calibrage ci-dessus.
- Install the library: Click the Add sketch library button (the open book icon with a + sign) in the left sidebar.
- Search for DIYables_DC_Motor created by DIYables.io and click the Install button.
Bricks
No bricks added...
Sketch Libraries
No sketch libra...
Files
python
sketch
.gitignore
README.md
app.yaml
sketch.ino
- Téléverser : Cliquez sur Exécuter pour téléverser.
- Notez les valeurs : Après 40 secondes (extension 20s + rétraction 20s), notez les valeurs POTENTIOMETER_MAX et POTENTIOMETER_MIN.
Étape 2 – Calcul de la Position
Utilisez les valeurs calibrées pour calculer la position actuelle en millimètres :
- Remplacez STROKE_LENGTH par la longueur de course de votre actionneur en mm.
- Remplacez POTENTIOMETER_MAX et POTENTIOMETER_MIN par les valeurs notées à l'étape 1.
/*
* Ce code Arduino UNO Q a été développé par newbiely.fr
* Ce code Arduino UNO Q est mis à disposition du public sans aucune restriction.
* Pour des instructions complètes et des schémas de câblage, veuillez visiter:
* https://newbiely.fr/tutorials/arduino-uno-q/arduino-uno-q-actuator-with-feedback
*/
// Step 2: Calculate position from potentiometer feedback
// NOTE: Motor Shield Channel A uses A0 for current sensing.
// Connect the actuator's feedback potentiometer signal wire to A2.
#include <DIYables_DC_Motor.h>
#define POTENTIOMETER_PIN A2 // The Arduino UNO Q pin connected to the actuator's feedback potentiometer
#define STROKE_LENGTH 102 // PLEASE UPDATE THIS VALUE (in mm)
#define POTENTIOMETER_MAX 4050 // PLEASE UPDATE THIS VALUE (from calibration)
#define POTENTIOMETER_MIN 50 // PLEASE UPDATE THIS VALUE (from calibration)
DIYables_DC_Motor motor(MOTOR_CH_A);
void setup() {
motor.begin();
// extend the actuator continuously while displaying position
motor.run(MOTOR_FORWARD, 255);
}
void loop() {
int potentiometer_value = analogRead(POTENTIOMETER_PIN);
int stroke_pos = map(potentiometer_value, POTENTIOMETER_MIN, POTENTIOMETER_MAX, 0, STROKE_LENGTH);
// stroke_pos is the current position in mm — use this to verify feedback accuracy
(void)stroke_pos;
}
Étapes Rapides
- Mettez à jour les espaces réservés en haut du code avec vos valeurs réelles.
- Téléversez et observez : Regardez l'actionneur s'étendre tout en vérifiant la position calculée.
Étape 3 – Contrôle de la Position
Avec les valeurs calibrées, déplacez l'actionneur vers une position cible spécifique :
- Définissez targetPosition_mm sur la position souhaitée (0 = complètement rétracté, STROKE_LENGTH = complètement étendu).
/*
* Ce code Arduino UNO Q a été développé par newbiely.fr
* Ce code Arduino UNO Q est mis à disposition du public sans aucune restriction.
* Pour des instructions complètes et des schémas de câblage, veuillez visiter:
* https://newbiely.fr/tutorials/arduino-uno-q/arduino-uno-q-actuator-with-feedback
*/
// Step 3: Control actuator position using feedback
// NOTE: Motor Shield Channel A uses A0 for current sensing.
// Connect the actuator's feedback potentiometer signal wire to A2.
#include <DIYables_DC_Motor.h>
#define POTENTIOMETER_PIN A2 // The Arduino UNO Q pin connected to the actuator's feedback potentiometer
#define STROKE_LENGTH 102 // PLEASE UPDATE THIS VALUE (in mm)
#define POTENTIOMETER_MAX 4050 // PLEASE UPDATE THIS VALUE (from calibration)
#define POTENTIOMETER_MIN 50 // PLEASE UPDATE THIS VALUE (from calibration)
#define TOLERANCE 5 // position tolerance in mm
int targetPosition_mm = 50; // target position in mm
DIYables_DC_Motor motor(MOTOR_CH_A);
void setup() {
motor.begin();
motor.brake();
}
void loop() {
int potentiometer_value = analogRead(POTENTIOMETER_PIN);
int stroke_pos = map(potentiometer_value, POTENTIOMETER_MIN, POTENTIOMETER_MAX, 0, STROKE_LENGTH);
if (stroke_pos < (targetPosition_mm - TOLERANCE))
motor.run(MOTOR_FORWARD, 255);
else if (stroke_pos > (targetPosition_mm + TOLERANCE))
motor.run(MOTOR_BACKWARD, 255);
else
motor.brake();
}
Étapes Rapides
- Mettez à jour les espaces réservés (STROKE_LENGTH, POTENTIOMETER_MAX, POTENTIOMETER_MIN) et définissez targetPosition_mm.
- Téléversez et testez : L'actionneur se déplacera vers la cible et maintiendra sa position.
Programmation Bridge Linux + MCU
L'Arduino UNO Q dispose de deux processeurs fonctionnant ensemble : le MPU (Qualcomm, exécute Debian Linux) et le MCU (STM32, exécute Zephyr OS avec votre programme Arduino). Ils communiquent via RPC grâce à la bibliothèque Arduino_RouterBridge.
- Le Motor Shield Rev3 et l'actionneur sont contrôlés par le MCU (STM32) — la bibliothèque DIYables_DC_Motor pilote le canal A ; retour du potentiomètre sur A2.
- Le MPU ne peut pas contrôler l'actionneur directement — il appelle Bridge.call("read_position") pour invoquer la fonction MCU qui lit la position et pilote l'actionneur.
- Le MPU dispose du Wi-Fi — il peut donc accepter des commandes Telegram pour surveiller ou modifier la position cible à distance.
- Communication : Bridge.call() côté Linux invoque Bridge.provide_safe() côté MCU (car motor.run() et motor.brake() utilisent des API matérielles).
- ⚠️ Réservé : /dev/ttyHS1 (Linux) et Serial1 (MCU) sont utilisés par le routeur Arduino — ne les ouvrez jamais directement.
Programme MCU — retour de position avec Bridge :
/*
* Ce code Arduino UNO Q a été développé par newbiely.fr
* Ce code Arduino UNO Q est mis à disposition du public sans aucune restriction.
* Pour des instructions complètes et des schémas de câblage, veuillez visiter:
* https://newbiely.fr/tutorials/arduino-uno-q/arduino-uno-q-actuator-with-feedback
*/
#include "Arduino_RouterBridge.h"
#include <DIYables_DC_Motor.h>
#define POTENTIOMETER_PIN A2 // NOTE: A0 is used by Motor Shield current sensing; use A2
#define STROKE_LENGTH 102
#define POTENTIOMETER_MAX 4050 // PLEASE UPDATE THIS VALUE (from calibration)
#define POTENTIOMETER_MIN 50 // PLEASE UPDATE THIS VALUE (from calibration)
#define TOLERANCE 5
int targetPosition_mm = 50;
DIYables_DC_Motor motor(MOTOR_CH_A);
void read_position() {
int potentiometer_value = analogRead(POTENTIOMETER_PIN);
int stroke_pos = map(potentiometer_value, POTENTIOMETER_MIN, POTENTIOMETER_MAX, 0, STROKE_LENGTH);
if (stroke_pos < (targetPosition_mm - TOLERANCE))
motor.run(MOTOR_FORWARD, 255);
else if (stroke_pos > (targetPosition_mm + TOLERANCE))
motor.run(MOTOR_BACKWARD, 255);
else
motor.brake();
Monitor.print("Position: ");
Monitor.print(stroke_pos);
Monitor.print(" mm | Target: ");
Monitor.print(targetPosition_mm);
Monitor.println(" mm");
}
void setup() {
Bridge.begin();
Monitor.begin();
motor.begin();
motor.brake();
Bridge.provide_safe("read_position", read_position);
Monitor.println("Actuator Feedback Bridge ready");
}
void loop() {}
Script Python (Arduino App Lab) — lecture et contrôle continus de la position :
/*
* Ce code Arduino UNO Q a été développé par newbiely.fr
* Ce code Arduino UNO Q est mis à disposition du public sans aucune restriction.
* Pour des instructions complètes et des schémas de câblage, veuillez visiter:
* https://newbiely.fr/tutorials/arduino-uno-q/arduino-uno-q-actuator-with-feedback
*/
from arduino.app_utils import *
import time
def loop():
Bridge.call("read_position")
time.sleep(0.2)
App.run(user_loop=loop)
- Remarque : Assurez-vous que Bridge.begin() est appelé dans le programme MCU et que le programme est téléversé avant d'exécuter le script Python.
- ⚠️ Avertissement : N'ouvrez jamais directement /dev/ttyHS1 (sous Linux) ou Serial1 (sur MCU) — ces ports sont réservés par le routeur Arduino.
Étapes Rapides
- Mettez à jour les espaces réservés dans le programme MCU Bridge (STROKE_LENGTH, POTENTIOMETER_MAX, POTENTIOMETER_MIN) et définissez targetPosition_mm.
- Téléversez le programme MCU : Ouvrez Arduino App Lab, collez le programme MCU Bridge dans sketch/sketch.ino, installez les bibliothèques DIYables_DC_Motor et Arduino_RouterBridge, puis cliquez sur Exécuter.
- Ajoutez le script Python : Collez le code Python ci-dessus dans l'onglet Python.
- Exécutez l'application : Python appelle read_position toutes les 200 ms ; le MCU se déplace vers la cible et rapporte la position.
- Vérifiez la console : Ouvrez la Console → sous-onglet Moniteur MCU.
Sortie de la Console App Lab
sketch.ino
1#include "Arduino_RouterBridge.h"
Serial Monitor
Python
Actuator Feedback Bridge ready
Position: 30 mm | Target: 50 mm
Position: 38 mm | Target: 50 mm
Position: 47 mm | Target: 50 mm
Position: 50 mm | Target: 50 mm
Intégration Telegram
Surveillez et rapportez la position de l'actionneur via Telegram avec la commande /position.
Si vous n'avez pas encore de bot Telegram, consultez Arduino UNO Q - Bot Telegram pour obtenir votre token de bot avant de continuer.
Programme MCU : Conservez le même programme MCU de la section Bridge précédente — aucune modification nécessaire. Assurez-vous qu'il est déjà téléversé et en cours d'exécution sur le STM32 avant de continuer.
Script Python (Arduino App Lab) — bot Telegram pour la position de l'actionneur :
/*
* Ce code Arduino UNO Q a été développé par newbiely.fr
* Ce code Arduino UNO Q est mis à disposition du public sans aucune restriction.
* Pour des instructions complètes et des schémas de câblage, veuillez visiter:
* https://newbiely.fr/tutorials/arduino-uno-q/arduino-uno-q-actuator-with-feedback
*/
from arduino.app_utils import *
import requests
import time
BOT_TOKEN = "YOUR_BOT_TOKEN"
API_URL = f"https://api.telegram.org/bot{BOT_TOKEN}"
last_update_id = 0
def send_message(chat_id, text):
requests.post(f"{API_URL}/sendMessage", json={"chat_id": chat_id, "text": text})
def get_updates():
global last_update_id
resp = requests.get(f"{API_URL}/getUpdates", params={"offset": last_update_id + 1, "timeout": 5})
return resp.json().get("result", [])
def loop():
global last_update_id
updates = get_updates()
for update in updates:
last_update_id = update["update_id"]
msg = update.get("message", {})
chat_id = msg.get("chat", {}).get("id")
text = msg.get("text", "").strip()
if text == "/position":
position = Bridge.call("read_position")
send_message(chat_id, position)
else:
send_message(chat_id, "Commands:\n/position — read and control actuator position")
time.sleep(0.5)
App.run(user_loop=loop)
- Remarque : Remplacez YOUR_BOT_TOKEN par le token obtenu depuis @BotFather.
- Envoyez /position pour déclencher une lecture de position sur le MCU.
Étapes Rapides
- Téléversez le programme MCU : Utilisez le programme MCU Bridge (téléversez-le d'abord s'il ne l'est pas déjà).
- Collez le script Telegram : Copiez le code Python ci-dessus dans l'onglet Python de votre application.
- Définissez votre token : Remplacez YOUR_BOT_TOKEN par votre vrai token de bot.
- Exécutez l'application et envoyez /position via Telegram.
Sortie de la Console App Lab
sketch.ino
1#include "Arduino_RouterBridge.h"
Serial Monitor
Python
[2026-04-29 12:00:01] Telegram: /position
[2026-04-29 12:00:01] Position: 30 mm | Target: 50 mm
Telegram
12:45
Welcome to Telegram!
ArduinoBot
10:19
Chatting with Arduino...
BotFather
Yesterday
Your bot has been created.
ArduinoBot
bot
Intégration d'OpenClaw
Vous pouvez adapter OpenClaw à ce tutoriel en vous référant aux instructions du tutoriel Arduino UNO Q - OpenClaw.
Idées d'Applications / Projets
- Portail de précision : Ouvrir un portail à une position exacte (ex. 50 % de la course) selon un planning
- Panneau solaire orientable : Incliner un panneau à un angle calculé grâce au retour de position de l'actionneur
- Gabarit à hauteur réglable : Déplacer une pièce à une hauteur calibrée dans un atelier de fabrication
- Vanne automatisée : Positionner une vanne à un pourcentage d'ouverture spécifique en fonction de la demande de débit
- Dispositif de rééducation : Piloter un actionneur d'exercice vers des angles cibles avec suivi de position
Mettez-Vous au Défi
- Facile : Changez targetPosition_mm pour déplacer l'actionneur à 25 mm et vérifiez la précision
- Moyen : Ajoutez une commande Telegram /set50 qui déplace l'actionneur à 50 mm
- Avancé : Acceptez une commande /goto <mm> avec une cible dynamique et validez la plage avant de déplacer