🛠 Commander une LED à distance avec Particle.function

Objetivos

Exponer una función del firmware al Particle Cloud con Particle.function, y luego llamarla desde Internet mediante una simple solicitud HTTP: la nube llama a su función C++ registrada, que devuelve un entero.

Material

• 1 Particle Photon conectado a la nube (tutorial photon-wifi-publish)
• 1 LED externa (con resistencia) o el LED integrado D7
• una cuenta de Particle y un token: particle token create o el flujo OAuth2 POST https://api.particle.io/oauth/token

Código completo

// photon-fonction-distance.ino — fonction appelée depuis le cloud
void setup {
  pinMode(D7, OUTPUT);
  Particle.function("led", ledCmd);   // enregistrement auprès du cloud
}

void loop { }

// Appelee par le cloud : POST /v1/devices/<id>/led?args=on
int ledCmd(String args) {
  if (args == "on")  { digitalWrite(D7, HIGH); return 1; }
  if (args == "off") { digitalWrite(D7, LOW);  return 0; }
  return -1;   // argument invalide
}

Verificación esperada

Desde una terminal: curl -H "Authorization: Bearer $TOKEN" -d args=on
1
enciende el LED D7; args=off lo apaga; un argumento desconocido devuelve -1. La lista de sus dispositivos (y el ID de 24 caracteres en hexadecimal) se obtiene con curl -H "Authorization: Bearer $TOKEN" https://api.particle.io/v1/devices`.

Errores frecuentes

• Nombre de función demasiado largo o no alfanumérico: mantenga un nombre corto como « led ».
• Olvidar el encabezado Authorization Bearer: la API responde con un error de autenticación (se requiere TLS 1.2+).
• Esperar un String como retorno: la función devuelve un int, visible en el lado de la API en el campo de retorno.
• Realizar un procesamiento largo en la función: se ejecuta en el contexto del sistema, sea breve y ponga el trabajo real en una cola de espera.