🛠 Commander la Boron à distance avec Particle.function

Objectifs

Particle.function expose une fonction de votre firmware au cloud : n'importe quel client (CLI, curl, Python, application web) peut l'appeler via l'API REST, et Device OS gère l'authentification TLS et l'identité par device. Chaque device est une ressource REST sur https://api.particle.io — on POSTe un appel de fonction comme on enverrait une requête à un micro-serveur. Vous allez piloter une sortie (allumer/éteindre une charge via relais) depuis le terminal, puis comprendre les contraintes : argument de 63 caractères max, nom de fonction court, valeur de retour entière.

Matériel

• 1× Particle Boron connectée au cloud (tutoriel précédent validé)
• 1× module relais 3,3 V ou une LED + transistor selon la charge
• Particle CLI connecté (particle whoami)

Code complet

// Boron — commande cloud via Particle.function
const uint16_t RELAIS_PIN = D5;    // broche sortie — vérifier le pinout
bool chargeActive = false;

void setup {
    pinMode(RELAIS_PIN, OUTPUT);
    digitalWrite(RELAIS_PIN, LOW);
    Particle.function("setCharge", setChargeHandler);
}

int setChargeHandler(String args) {
    // args vient du champ POST "arg" (63 caractères max)
    if (args == "on") {
        digitalWrite(RELAIS_PIN, HIGH);
        chargeActive = true;
        return 1;
    }
    if (args == "off") {
        digitalWrite(RELAIS_PIN, LOW);
        chargeActive = false;
        return 0;
    }
    return -1;                     // argument inconnu
}

void loop {
    delay(1000);
}

Appels côté client : particle call <device> setCharge on puis particle call <device> setCharge off. En curl :

curl https://api.particle.io/v1/devices/<device_id>/setCharge \
  -d arg="on" -H "Authorization: Bearer $TOKEN"
# -> {"id":"...","return_value":1,"connected":true}

Vérification attendue

Chaque appel CLI ou REST renvoie le JSON avec return_value égal à la valeur retournée par votre handler (1, 0 ou -1), et la sortie physique bascule dans le même temps (millisecondes si le device est connecté). Testez aussi un argument invalide : vous devez recevoir -1, preuve que le handler s'exécute bien.

Erreurs fréquentes

• Nom de fonction trop long ou non enregistré avant l'appel : le cloud renvoie « Function not found » ; le device doit être online.
• Argument de plus de 63 caractères : il est tronqué ou rejeté — gardez la logique métier dans le firmware, pas dans la charge utile.
• Faire du blocage dans le handler (delays, I/O longues) : l'appel cloud expire ; déléguez le travail long à loop via un flag.
• Oublier le champ arg= dans curl : la fonction reçoit une chaîne vide et renvoie -1.
• Confondre function (action, retour int) et variable (lecture d'état) : pour lire un état, utilisez Particle.variable (tutoriel suivant).