Spark-Core-NetLED

Contrôler des LEDs par Internet

Maintenant que nous savons comment faire clignoter une LED, nous allons voir comment la contrôler via Internet? C'est maintenant que nous allons avoir du fun.

Montage

Cette fois, nous allons brancher deux LEDs.

Crédit: Particle.IO www.particle.io

Comme la fois précédente, nous allons utiliser des résistances de 1K Ohms pour limiter le courant dans les LEDs.

Le Programme

L'algorithme

Voici comment fonctionne le programme

• Activer les broches sur lesquelles sont banchées les LEDs en tant que sortie (output en anglais)
• Créer et répertorier (register) une fonction Spark (elle sera appelée automatiquement lorsque vous ferez un appel via l'API)
• Traiter la commande entrante (parse) pour prendre les actions appropriées.

Le code

Voici le code proposé par Spark... avec traduction des commentaires pour faciliter la compréhension

// -----------------------------------
// Controler des LEDs via Internet
// -----------------------------------

// Donner un nom aux broches
int led1 = D0;
int led2 = D1;

// Cette fonction est appelée une seule fois lors d'un reset
void setup()
{
   // Enregistrez votre fonction Spark ici
   // Le point de contact de l'API est "led" et la 
   // fonction appelée est "ledControl"
   Spark.function("led", ledControl);

   // Configureer les broches en Sortie (output)
   pinMode(led1, OUTPUT);
   pinMode(led2, OUTPUT);

   // Initialiser les deux LEDs pour qu'elles soient éteintes
   digitalWrite(led1, LOW);
   digitalWrite(led2, LOW);
}


// Cette boucle est exécutées continuellement
void loop()
{
   // Rien à exécuter
}


// Cette fonction est appelée lorsqu'il y a un appel correspondant sur l'API
// Le format de la chaine de commande est l<numero de led>,<état>
// Par exemple: l1,HIGH ou l1,LOW  pour allumer ou éteindre la LED1
//              l2,HIGH or l2,LOW  pour allumer ou éteindre la LED2
//
int ledControl(String command)
{
   int state = 0;
   // Trouver le numéro de broche dans la commande ET convertir 
   // la valeur du caractere ASCII en valeur entière (en integer)
   int pinNumber = (command.charAt(1) - '0') - 1;

   // Vérifier que la valeur de la broche est bien dans
   // les limites acceptables SINON on quitte de la fonction ledControl
   if (pinNumber < 0 || pinNumber > 1) return -1;

   // Trouver l'état de la Led dans la commande
   // SI l'état n'est pas identifié ALORS on quitte la fonction ledControl
   if(command.substring(3,7) == "HIGH") state = 1;
   else if(command.substring(3,6) == "LOW") state = 0;
   else return -1;

   // Modifier l'état de la broche 
   digitalWrite(pinNumber, state);
   return 1;
}

Faire une requête sur l'API

Notez que le point de contact de l'API (endpoint) est est "led", et non "ledControl".

C'est parce que le point de contact (endpoint) est défini en premier paramètre de l'appel Spark.function(). Ce premier paramètre est une chaîne de caractère.

Le second paramètre de l'appel Spark.function() est une fonction. Cette est automatiquement exécutée lorsque le point de contact est appelé sur l'API.

L'appel à l'API doit avoir la structure suivante.

POST /v1/devices/{CORE_ID}/led

EXEMPLE D'APPEL DANS UN TERMINAL
avec le Core ID 0123456789abcdef
et votre access token est 123412341234
Voyez ci-dessous pour l'identification de votre propre CORE_ID et ACCESS_TOKEN

curl https://api.spark.io/v1/devices/0123456789abcdef/led \
  -d access_token=123412341234 \
  -d params=l1,HIGH

Vous pourriez également utiliser une commande curl sur une seule ligne

curl https://api.spark.io/v1/devices/0123456789abcdef/led -d access_token=123412341234 -d params=l1,HIGH

Lorsque l'appel est concluant, curl retourne la réponse produite par l'API (structure JSon).

{
  "id": "54ff6xxxxxxxxxxxxx481467",
  "name": "mch-demo",
  "last_app": null,
  "connected": true,
  "return_value": 1
}

La réponse contient, en autre, la valeur retournée par votre fonction ledControl (voyez return_value). Nous savons également que notre Spark Core est en ligne puisque connected est à true (valeur booléenne vrai)

Comment trouver votre CORE_ID

Le CORE_ID (aussi appelé DEVICE_ID) est une valeur permettant d'identifier votre Spark Core.

Souvenez-vous, en enregistrant votre Core sur Spark Cloud, vous lui avez donné un Nom. Le notre, nous l'avons nommé MCH-DEMO.

Cependant, l'informatique préfère les identifiants barbares comme 0123456789abcdef... oui, c'est barbare mais évite aussi les erreurs par confusion, les tentatives d'identifications par ingénierie sociale et sont faciles à stocker (dans un fichier ou une base de donnée).

Vous pouvez trouver le Core ID dans le Web IDE (build) de Spark. Connecter vous avec votre compte Spark Cloud.

Vous trouverez votre Spark Core ID ici...

Comment trouver l' ACCESS_TOKEN

S'il ne fallait qu'un CORE ID pour contrôler un Spark Core, alors n'importe qui pourrait prendre le contrôle de n'importe quel Spark Core s'il connait le CORE ID.

Imaginez que quelqu'un tente sa chance en utilisant des CORE ID au hasard? Lui, ou n'importe quel opportuniste, pourrait prendre le contrôle de votre Core!

C'est pour cela qu'il y a ACCESS_TOKEN! Ce dernier est lié à votre compte Spark Cloud et aussi barbare que le CORE ID.

Il est virtuellement impossible pour quelqu'un de trouver à la fois votre CORE_ID et le ACCESS_TOKEN pour piloter votre Core. Ouf!

Pour identifier votre ACCESS_TOKEN, vous devez-vous connecter sur le Web IDE (build) de Spark en utilisant votre compte Spark Cloud.

Vous trouverez l'information qui vous intéresse ici.

CURL? KASEKO?!?!

Source: curl.haxx.se

curl est une interface en ligne de commande destinée à récupérer le contenu d'une ressource accessible sur Internet (les réseaux informatiques en général). La ressource est désignée à l'aide d'une URL (comme https://api.spark.io/v1/devices/0123456789abcdef/led dans notre exemple). Contrairement à wget, curl est capable de créer et modifier des ressources et peut aussi être utiliser en tant que client REST.

C'est donc l'outil idéal pour tester vos API Spark... et et disponible en multiplateforme (Linux, MacOS, Windows, ect). Les plus perspicaces verront là l'opportunité d'utiliser Spark Core avec leur Raspberry Pi :-)

Voyez:

• CURL sur WikiPedia pour plus d'information.
• Le site officiel de Curl
• Installation rapide: sudo apt-get install curl

Et mon navigateur Internet?

Vous ne pourrez malheureusement pas utiliser directement votre navigateur Internet.
Les personnes un peu plus expérimentées en développement sauront facilement utiliser la bonne approche que nous présentons ci-dessous... pour les autres, je vais vous expliquer pourquoi l'essai DIRECT ci-dessous est non concluant!

Si vous faites attention à la commande curl, vous noterez que access_token et params sont précédés de la mention -d.

Ce -d indique à curl qui doit faire une requête de type POST d'un formulaire incluant les valeurs access_token et params inclus. C'est exactement la même opération que celle effectuée lorsque vous remplissez et envoyez un formulaire sur un site internet.

Les requêtes de type POST sont utilisée pour indiquer au site marchand que vous envoyez des "modifications" de données!

Dans l'image ci-dessus, nous avons encodé l'URL dans la barre de navigation, cette requête est de type GET (pour obtenir une ressource/information depuis un serveur WEB).

Un GET, ce n'est pas un POST! Et Spark Cloud nous répond laconiquement "variable not found" puisqu'il n'a pas trouvé (1) le formulaire et (2) les variables access_token et params qu'il devrait contenir!

Mon navigateur Internet + FORMULAIRE

Comme vous l'avez vu ci-dessus, le simple fait d'encoder une URL dans la barre de navigation n'est pas suffisant pour commander votre Spark Core.

Il y a de nombreuses technique de commandes possible via Curl, Python, C, Php, Ajax et bien d'autre... mais ici, nous allons nous concentrer sur l'approche la plus simple possible.

Nous allons:

1. Créer une page HTML sur notre ordinateur (elle contiendra toutes les informations nécessaires pour commander notre Core)
2. Charger la page HTML dans notre navigateur
3. Remplir/modifier les données du formulaire
4. Appeler notre API via le Spark Cloud

Etape 1: Créer le formulaire

A la pure et dure, prenez votre éditeur de texte (notepad, Pluma, Nano)... le plus rudimentaire possible sera certainement le mieux!

Créer ensuite un document portant l'extension htm ou html et encodé le contenu suivant. Soyez très scrupuleux avec la syntaxe!!!!

Voici un exemple de page HTML:

<!DOCTYPE html>
<html>
<body>
<p style="width:480px">Exemple simpliste de FORMULAIRE POST permettant d'envoyer des données vers votre Spark Core via le Spark Cloud</p>
<form id="form" name="form" action="https://api.spark.io/v1/devices/54xxxxxxxxxxxxxxxxxx67/led" method="post">
		<label id="label1" for="access_token">access_token</label>
		<input type="text" name="access_token" id="access_token" value="1dyyyyyyyyyyyyyyyyyyyyyyyyyf8" required/><br />
		<label id="label2" for="params">Params</label>
		<input type="text" name="params" id="params" value="l1,HIGH" required /><br />
		<input type="submit" id="submit" name="submit" value="Allez Hop!"/>
</form>
</body>
</html>

Une page comme celle-ci sur votre ordinateur ou SmartPhone doit pouvoir vous permettre de commander facilement des fonctionnalités de votre Spark Core ;-).

Etape 2: Charger la page

Chargez cette page dans votre navigateur Internet. Cela doit être possible via le menu "Fichier | Ouvrir" de votre navigateur Internet.

Vous devriez voir un résultat comme celui-ci:

Mieux comprendre l'API

Pour mieux comprendre le concept des appels API sur votre Core via le Cloud, vous devriez lire notre référence sur Cloud API.

---

Source: Particle Core Examples créé par Particle.IO.

Traduction (et augmentation de contenu) réalisée par Meurisse D pour MCHobby.be - Translated (and enhanced) by Meurisse D. for MCHobby.be

Traduit avec l'autorisation de Particle.IO - Translated with the permission from Particle.IO - Particle.IO

Toute référence, mention ou extrait de cette traduction doit être explicitement accompagné du texte suivant : «  Traduction par MCHobby (www.MCHobby.be) - Vente de kit et composants » avec un lien vers la source (donc cette page) et ce quelque soit le média utilisé.

L'utilisation commercial de la traduction (texte) et/ou réalisation, même partielle, pourrait être soumis à redevance. Dans tous les cas de figures, vous devez également obtenir l'accord du(des) détenteur initial des droits. Celui de MC Hobby s'arrêtant au travail de traduction proprement dit.