🛠 Commander la Boron à distance avec Particle.function

Objetivos

Particle.function expone una función de su firmware a la nube: cualquier cliente (CLI, curl, Python, aplicación web) puede llamarla a través de la API REST, y Device OS gestiona la autenticación TLS y la identidad por dispositivo. Cada dispositivo es un recurso REST en https://api.particle.io — se envía una llamada de función mediante POST como si se enviara una solicitud a un microservidor. Usted controlará una salida (encender/apagar una carga mediante relé) desde la terminal, y luego entenderá las restricciones: argumento de máximo 63 caracteres, nombre de función corto y valor de retorno entero.

Material

• 1× Particle Boron conectada a la nube (tutorial anterior validado)
• 1× módulo de relé de 3,3 V o un LED + transistor según la carga
• Particle CLI conectado (particle whoami)

Código completo

// Boron — commande cloud via Particle.function
const uint16_t RELAIS_PIN = D5;    // broche sortie — verifier 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 caracteres 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);
}

Llamadas desde el cliente: particle call <device> setCharge on y luego 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}

Verificación esperada

Cada llamada CLI o REST devuelve el JSON con return_value igual al valor devuelto por su handler (1, 0 o -1), y la salida física cambia en ese mismo momento (en milisegundos si el dispositivo está conectado). Pruebe también con un argumento inválido: debe recibir -1, lo que demuestra que el handler se ejecuta correctamente.

Errores frecuentes

• Nombre de función demasiado largo o no registrado antes de la llamada: la nube devuelve «Function not found»; el dispositivo debe estar en línea.
• Argumento de más de 63 caracteres: se trunca o se rechaza — mantenga la lógica de negocio en el firmware, no en la carga útil.
• Realizar operaciones bloqueantes en el handler (delays, E/S largas): la llamada a la nube expira; delegue el trabajo largo a loop mediante una bandera.
• Olvidar el campo arg= en curl: la función recibe una cadena vacía y devuelve -1.
• Confundir function (acción, devuelve int) y variable (lectura de estado): para leer un estado, utilice Particle.variable (siguiente tutorial).