Modifications

Sauter à la navigation Sauter à la recherche
8 895 octets ajoutés ,  24 octobre 2015 à 13:14
aucun résumé de modification
Ligne 1 : Ligne 1 :  
{{Spark-Core-Hacking-NAV}}
 
{{Spark-Core-Hacking-NAV}}
  −
{{traduction}}
      
== Contrôler des LEDs par Internet ==
 
== Contrôler des LEDs par Internet ==
Ligne 19 : Ligne 17 :  
Voici comment fonctionne le programme
 
Voici comment fonctionne le programme
 
* Activer les broches sur lesquelles sont banchées les LEDs en tant que sortie (''output'' en anglais)
 
* 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)
+
* Créer et répertorier (''register'') une fonction Particle (elle sera appelée automatiquement lorsque vous ferez un appel via l'API)
 
* Traiter la commande entrante (''parse'') pour prendre les actions appropriées.
 
* Traiter la commande entrante (''parse'') pour prendre les actions appropriées.
    
=== Le code ===
 
=== Le code ===
Voici le code proposé par Spark... avec traduction des commentaires pour faciliter la compréhension
+
Voici le code proposé par Particle... avec traduction des commentaires pour faciliter la compréhension
    
  <nowiki>// -----------------------------------
 
  <nowiki>// -----------------------------------
// Controlling LEDs over the Internet
+
// Controler des LEDs via Internet
 
// -----------------------------------
 
// -----------------------------------
   −
// name the pins
+
// Donner un nom aux broches
 
int led1 = D0;
 
int led1 = D0;
 
int led2 = D1;
 
int led2 = D1;
   −
// This routine runs only once upon reset
+
// Cette fonction est appelée une seule fois lors d'un reset
 
void setup()
 
void setup()
 
{
 
{
   //Register our Spark function here
+
   // Enregistrez votre fonction Particle ici
 +
  // Le point de contact de l'API est "led" et la
 +
  // fonction appelée est "ledControl"
 
   Spark.function("led", ledControl);
 
   Spark.function("led", ledControl);
   −
   // Configure the pins to be outputs
+
   // Configureer les broches en Sortie (output)
 
   pinMode(led1, OUTPUT);
 
   pinMode(led1, OUTPUT);
 
   pinMode(led2, OUTPUT);
 
   pinMode(led2, OUTPUT);
   −
   // Initialize both the LEDs to be OFF
+
   // Initialiser les deux LEDs pour qu'elles soient éteintes
 
   digitalWrite(led1, LOW);
 
   digitalWrite(led1, LOW);
 
   digitalWrite(led2, LOW);
 
   digitalWrite(led2, LOW);
Ligne 49 : Ligne 49 :       −
// This routine loops forever
+
// Cette boucle est exécutées continuellement
 
void loop()
 
void loop()
 
{
 
{
   // Nothing to do here
+
   // Rien à exécuter
 
}
 
}
      −
// This function gets called whenever there is a matching API request
+
// Cette fonction est appelée lorsqu'il y a un appel correspondant sur l'API
// the command string format is l<led number>,<state>
+
// Le format de la chaine de commande est l<numero de led>,<état>
// for example: l1,HIGH or l1,LOW
+
// Par exemple: l1,HIGH ou l1,LOW pour allumer ou éteindre la LED1
//              l2,HIGH or l2,LOW
+
//              l2,HIGH or l2,LOW pour allumer ou éteindre la LED2
 
+
//
 
int ledControl(String command)
 
int ledControl(String command)
 
{
 
{
 
   int state = 0;
 
   int state = 0;
   //find out the pin number and convert the ascii to integer
+
   // 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;
 
   int pinNumber = (command.charAt(1) - '0') - 1;
   //Sanity check to see if the pin numbers are within limits
+
 
 +
   // 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;
 
   if (pinNumber < 0 || pinNumber > 1) return -1;
   −
   // find out the state of the led
+
   // 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;
 
   if(command.substring(3,7) == "HIGH") state = 1;
 
   else if(command.substring(3,6) == "LOW") state = 0;
 
   else if(command.substring(3,6) == "LOW") state = 0;
 
   else return -1;
 
   else return -1;
   −
   // write to the appropriate pin
+
   // Modifier l'état de la broche
 
   digitalWrite(pinNumber, state);
 
   digitalWrite(pinNumber, state);
 
   return 1;
 
   return 1;
 
}</nowiki>
 
}</nowiki>
   −
=== Faire une requête sur l'API ===
+
== Faire une requête sur l'API ==
Note that the API endpoint is 'led', not 'ledControl'. This is because the endpoint is defined by the first argument of Spark.function(), which is a string of characters, rather than the second argument, which is a function.
+
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
   −
The API request will look something like this:
+
=== CURL? KASEKO?!?! ===
 +
[[Fichier:Curl-Logo.jpg|280px]]<small><br />Source: [http://curl.haxx.se/ curl.haxx.se]</small>
   −
POST /v1/devices/{DEVICE_ID}/led
     −
# EXAMPLE REQUEST IN TERMINAL
+
curl est une programme/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 (avec des requête POST) et peut aussi être utiliser en tant que client REST.
# Core ID is 0123456789abcdef
+
 
# Your access token is 123412341234
+
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 Particle Core avec leur Raspberry Pi :-)
 +
 
 +
Voyez:
 +
* [https://api.spark.io/v1/devices/0123456789abcdef/led CURL] sur WikiPedia pour plus d'information.
 +
* [http://curl.haxx.se/ Le site officiel de Curl]
 +
* Installation rapide: <code>sudo apt-get install curl</code>
 +
 
 +
=== Utiliser CURL ===
 +
EXEMPLE D'APPEL DANS UN TERMINAL<br />
 +
avec le Core ID 0123456789abcdef<br />
 +
et votre ''access token'' est 123412341234<br />
 +
<small>''Voyez ci-dessous pour l'identification de votre propre CORE_ID et ACCESS_TOKEN''</small>
 +
 
 
  <nowiki>curl https://api.spark.io/v1/devices/0123456789abcdef/led \
 
  <nowiki>curl https://api.spark.io/v1/devices/0123456789abcdef/led \
 
   -d access_token=123412341234 \
 
   -d access_token=123412341234 \
 
   -d params=l1,HIGH</nowiki>
 
   -d params=l1,HIGH</nowiki>
 +
 +
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).
 +
 +
<nowiki>{
 +
  "id": "54ff6xxxxxxxxxxxxx481467",
 +
  "name": "mch-demo",
 +
  "last_app": null,
 +
  "connected": true,
 +
  "return_value": 1
 +
}</nowiki>
 +
 +
La réponse contient, en autre, la valeur retournée par votre fonction <code>ledControl</code> (voyez ''return_value''). Nous savons également que notre PArticle 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 Particle Core.
 +
 +
Souvenez-vous, en enregistrant votre Core sur Particle 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 Particle. Connecter vous avec votre compte Particle Cloud.
 +
 +
Vous trouverez votre Particle Core ID ici...
 +
 +
[[Fichier:Spark-Core-NetLed-Core_ID.jpg|640px]]
 +
 +
=== Comment trouver l' ACCESS_TOKEN ===
 +
S'il ne fallait qu'un CORE ID pour contrôler un Particle Core, alors n'importe qui pourrait prendre le contrôle de n'importe quel Particle 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 Particle 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 Particle en utilisant votre compte Particle Cloud.
 +
 +
Vous trouverez l'information qui vous intéresse ici.
 +
 +
[[Fichier:Spark-Core-NetLed-Access_Token.jpg|640px]]
 +
 +
=== Et mon navigateur Internet? ===
 +
 +
Vous ne pourrez malheureusement pas utiliser directement votre navigateur Internet.<br />Les personnes un peu plus expérimentées en développement {{underline|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!
 +
 +
[[Fichier:Spark-Core-NetLed-Via-Browser.jpg|640px]]
 +
 +
Si vous faites attention à la commande '''curl''', vous noterez que <code>access_token</code> et <code>params</code> 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 {{underline|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 Particle Cloud nous répond laconiquement "''variable not found''" puisqu'il n'a pas trouvé (1) le formulaire et (2) les variables <code>access_token</code> et <code>params</code> 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 Particle 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:
 +
# Créer une page HTML sur notre ordinateur (elle contiendra toutes les informations nécessaires pour commander notre Core)
 +
# Charger la page HTML dans notre navigateur
 +
# Remplir/modifier les données du formulaire
 +
# Appeler notre API via le Particle 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!!!!
 +
 +
{{ambox|text=J'ai volontairement masqué une partie du CORE_ID avec des "''xxx''" et mon access_token avec des "''yyyyyyy''". Vous devrez les remplacer avec vos propres valeurs. Le but, c'est de jouer avec votre Particle Core, pas le mien ;-)<br />
 +
Nous avons déjà vu ci-avant comment retrouver votre CORE_ID et ACCESS_TOKEN.}}
 +
 +
Voici un exemple de page HTML:
 +
 +
<nowiki><!DOCTYPE html>
 +
<html>
 +
<body>
 +
<p style="width:480px">Exemple simpliste de FORMULAIRE POST permettant d'envoyer des donn&eacute;es vers votre Particle Core via le Particle 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>
 +
</nowiki>
 +
 +
Une page comme celle-ci sur votre ordinateur ou SmartPhone doit pouvoir vous permettre de commander facilement des fonctionnalités de votre Particle 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:
 +
 +
[[Fichier:Spark-Core-NetLed-Via-Browser-FORM.jpg|800px]]
 +
 +
Nous avons laissé l'ACCESS_TOKEN visible pour plus de compréhension. Il est possible d'encoder ce champs en hidden (masqué) de façon à ce que la valeur soit dans le formulaire sans être visible.
 +
 +
<nowiki><input type="hidden" name="access_token" id="access_token" value="1dyyyyyyyyyyyyyyyyyyyyyyyyyf8" required/></nowiki>
 +
 +
Si vous prêtez attention, j'ai demandé l'extinction de la LED 2 car le paramètre est
 +
 +
l2,LOW
 +
 +
==== Etape 3: Envoyer la requête ====
 +
Lorsque vous pressez le bouton "Allez Hop!" (bouton de type Submit, ''soumettre''), la formulaire envoi un requête de type "POST" version l'api de Particle Cloud (l'URL mentionnée dans ''action'').
 +
 +
Cette requête contient tous les paramètres nécessaire... et cette fois, vous recevez une réponse positive :-)
 +
 +
[[Fichier:Spark-Core-NetLed-Via-Browser-FORM-Response.jpg]]
    
== Mieux comprendre l'API ==
 
== Mieux comprendre l'API ==
To better understand the concept of making API calls to your Core over the cloud checkout the [[Spark-Cloud-API|Cloud API]] reference.
+
Pour mieux comprendre le concept des appels API sur votre Core via le Cloud, vous devriez lire notre référence sur [[Spark-Cloud-API|Cloud API]].
    
{{Spark-Core-Hacking-TRAILER}}
 
{{Spark-Core-Hacking-TRAILER}}
30 894

modifications

Menu de navigation