XBee API pour pilotage à distance

version mise à jour en avril 2011

Nous avons déjà utilisé précédemment les XBee très simplement pour faire une liaison série sans fil entre plusieurs modules (voir cet article), mais maintenant on va s’attaquer au mode "API" pour piloter à distance les ports entrée/sortie numérique ou analogique de plusieurs modules XBee sans utiliser de microcontrôleur supplémentaire.

Cet article est le résultat de nos ateliers hebdomadaires. Nous avons tout appris de zéro concernant les XBee grâce aux différentes explications qu’on trouve sur Internet. Remercions tous ceux qui ont documenté leurs projets et qui contribuent par des fichiers, des codes sources, des articles. Parmi eux :
 Tom Igoe pour son livre "Making Things Talk"
 Daniel Menesplier pour sa doc en français sur son site web
 le wiki de l’ITP (NYU) pour son article similaire à celui-ci et qui m’a bien aidé à terminer l’expérimentation.

 Principe

On va tester les deux sens d’accès aux données connectées sur un XBee :
 recevoir une information distante (patte en sortie du XBee)
 contrôler une led à distance (patte en entrée du XBee)

 Matériel et circuit

Voici le matériel nécessaire pour cette manip’ :

La majorité de ces produits ont été offerts au club pour ses expériences pédagogiques, merci !

On a donc :
 un XBee connecté par USB à un ordinateur
 un XBee connecté à une led (sortie) et un capteur (entrée).

Voici le XBee installé sur une carte USB :

Adaptateur USB "sparkfun"

un des plus courants

Interface XBee/USB

Une autre version, cette fois de Droids.it, vendue en France par Matlog.

Voici le XBee distant avec une led, un bouton et une résistance variable :

Circuit XBee

On utilise une résistance variable pour tester le XBee en réception d’une valeur analogique.

Notez qu’il faut une alimentation 3,3 volts. Il existe désormais de petites cartes qui permettent d’obtenir les tensions fréquemment utilisées depuis une simple alimentation secteur universelle.

Alimentation 3,3 volts

Très important : tension de référence

Si vous souhaitez utiliser le convertisseur analogique/numérique d’un XBee, il faut absolument que vous fournissiez une tension de référence sur la patte 14 : un simple fil entre la tension d’alimentation (3,3 volts) et la patte 14 suffit.

 TP n°1 : recevoir une information

Régler les paramètres radio

Nous avions déjà vu dans un précédent article comment modifier les paramètres des modules XBee. On va donc le réutiliser pour spécifier les adresses d’émetteur, de récepteur et de réseau personnel, mais également pour régler les paramètres des pattes d’entrée/sortie du XBee.

Côté PC, le XBee va tout d’abord recevoir des informations (détecteur de présence sur le XBee distant, ou interrupteur). Il n’y a donc pas d’adresse de destinataire (DL 0) donc la configuration est très simple :

Côté platine d’essai, on va voir apparaitre des codes nouveaux : D0, IR, IU et IT. Il s’agit en fait de configurer le XBee pour qu’il utilise les pattes d’entrées/sorties et les envoie sur l’UART (IU à 1) puis qu’il prenne une valeur en entrée numérique sur une de ses pattes de données : D0, la patte de donnée (D) numéro zéro (0) toutes les IR microsecondes (en hexa) et qu’il envoie la valeur au XBee dont il a l’adresse en destinataire (DL et DH si besoin) au bout de IT échantillons.

Ce qui donne dans notre cas :

Premier test

Avec un simple logiciel d’écoute de la liaison série (ici, Docklight comme souvent), on peut voir que le module distant est bien en train d’envoyer une trame (qu’on appelle bizarrement API, d’où le titre de cet article) à notre module "base", et sans que le XBee base ne demande rien, ce qui peut être déroutant car on aurait pu penser que la mention "API" signifiait justement qu’il y avait des commandes d’accès aux valeurs par question/réponse (polling). Et bien non, c’est toute mon erreur et j’espère que vous n’aurez pas fait la même grâce (à votre grande intelligence ou) à cet article.

Récupération depuis un logiciel

Comme le XBee "base" est connecté au port USB par une liaison série, on peut récupérer la trame et commencer à la traiter (i.e. découper et récupérer la valeur qui nous intéresse) dans un logiciel dans le langage de votre choix. J’ai choisi Java et plus particulièrement l’environnement Processing.

Voici le résultat : on peut voir que j’ai déjà fait un test sur "7E" pour détecter un début de trame.

Analyse d’une trame API

On va analyser cette ligne :

Bien sûr les 00 ne sont pas significatifs, ils sont ajoutés par la fonction Java qui transforme les caractères reçus en valeurs hexadécimales.

Pour info, vous trouverez la documentation officielle dans ce document.

Si on fait varier la valeur de la résistance variable, on voit bien ces 2 octets varier :

Utilisation d’une bibliothèque

On peut également utiliser la bibliothèque décrite dans cet article car elle est dédiée à Processing même si on peut aussi utiliser une librairie Java plus commune, comme celle-ci : Java XBee API

import processing.serial.*;

import xbee.XBeeDataFrame;
import xbee.XBeeReader;

Serial port;
XBeeReader xbee;

void setup()
{
  println(Serial.list());
  port = new Serial(this,Serial.list()[2],9600);
  xbee = new XBeeReader(this,port);
  xbee.startXBee();
}

void xBeeEvent(XBeeReader xbee) {
  XBeeDataFrame data = xbee.getXBeeReading();
  
  if (data.getApiID() == xbee.SERIES1_IOPACKET) {    
    int analogVal = data.frameData[8] * 256 + data.frameData[9];    
    println("A: "+analogVal);    
  } 
  else {
    println("Non supporté");
  }
}

void draw() { }

Je dois à la vérité dire que cette bibliothèque n’a pas très bien marché pour la lecture des valeurs analogiques, j’ai donc simplement récupéré les 2 octets 8 et 9 du tableau de 10 (rappelez-vous, 0A), et je les ai ajouté avec une multiplication par 256 pour l’octet le plus haut (2^8 = 256).

 TP n°2 : allumer une led