====== XBee en étoile ======
([[.en|English version]])
* Auteur : Jérôme Abel (Reso-nance)
* Date : 09/2014
* Licence : GNU/FDL3
* Fichiers : {{:materiel:xbee:star:codes.zip|}}
* Remerciements : Martin Peach, Hans-Christop Steiner, Vincent Pillet
Les modules XBee sont une solution pour transmettre des données sans-fils, par ondes radio. Si cela ne vous dit rien et que vous êtes plus déterminé que jamais, veuillez suivre l'initiation [[http://jeromeabel.net/ressources/xbee-arduino|Xbee & Arduino]]. Nous avons vu comment transmettre des données d'un module à un autre en remplacement d'un câble, c'est une topologie de réseau "point-à-point". Ici, nous explorerons une autre topologie très utile qui est en "étoile". Cela permet deux types de configuration : un émetteur (//Coordinator//) envoie des données à plusieurs receveurs (//End Device//) ou bien l'inverse, plusieurs émetteurs envoient des données à un seul receveur. L'article décrit comment faire ça avec les modules **XBee Series 1**, **Pure Data** et **Arduino**. Certaines de mes pièces artistiques ([[:projets:patatas-de-goma:|Patatas de goma]] et [[:projets:chimeres-orchestra:|Chimères Orchestra]]) utiliseront cette technique.
{{ :materiel:xbee:star:xbee-star-topology.png |}}
{{ vimeo>106574642?medium }}
===== Pré-requis =====
* Bases de [[logiciels:puredata:|Pure Data]]
* Bases d'[[logiciels:arduino:|Arduino]]
* Bases de la [[logiciels:serial:|Communication série]] (Arduino/Pure Data)
* Configuration d'un module XBee, vue dans l'initiation [[http://jeromeabel.net/ressources/xbee-arduino|Xbee & Arduino]]
==== Matériel ====
Matériel utilisé ici pour les tests :
* 3 XBee series 1 + 3 supports
* 3 Arduinos
* 2 Serial converter ou XBee board
* 3 platines à essais
* 4 leds
* 2 coupleurs pour piles 1,5V AAA + 4 piles
* fils de prototypage
==== Logiciels ====
Logiciels à installer :
* [[http://puredata.info/downloads/pd-extended|Pure Data Extended]], qui contient [mrpeach/packxbee] et [mrpeach/unpackxbee]
* [[http://arduino.cc/en/Main/Software|Arduino]]
* [[https://processing.org/download/?processing|Processing]]
* {{:materiel:xbee:star:xbeeterminal.zip|}} (fait en processing), pour configurer le XBee
* Bibliothèques additionnelles (dans "codes.zip") : [[http://code.google.com/p/xbee-api/|xbee-api]], [[https://code.google.com/p/xbee-arduino/|xbee-arduino]] et [[https://github.com/scogswell/ArduinoSerialCommand|SerialCommand]]
==== Ressources ====
* XBee Datasheet : {{:materiel:xbee:star:xbee_product_manual.pdf|}}
* XBee Arduino : [[https://code.google.com/p/etrack/wiki/XBeeAPIsTutorial|XBeeAPIsTutorial]], [[https://code.google.com/p/xbee-arduino/wiki/DevelopersGuide|XBee Arduino Developers Guide]] et[[http://www.tunnelsup.com/xbee-s2-quick-reference-guide-cheat-sheet|XBee series 2 quick reference guide]]
* XBee Pure Data : [[http://www.faludi.com/downloads/xbee/Max_Patch/xbee_io_reader.pat|xbee_io_reader.pat]] et [[http://lists.puredata.info/pipermail/pd-list/2009-03/079021.html|lists.puredata.info]]
==== Précautions ====
Quelques précautions et erreurs communes :
* Les modules XBee sont alimentés autour de **3V**, le 3,3V de l'Arduino est parfait ou bien deux piles 1,5V. Faites bien attention à ne pas l'alimenter avec le 5V de l'Arduino
* **RX/TX** : attention à l'orientation RX va vers TX et TX va vers RX.
* **RX/TX** : enlever les cables RX/TX branchés à l'Arduino quand vous téléversez le code vers l'Arduino
* Attention au **baudrate** du port série et au numéro de port. Si vous changez de carte, le port n'est sans doute plus le même. De même si vous changez le //baudrate// du XBee, vous devez impacter ce changement dans le programme "xbeeSerialTerminal", dans les codes Arduino (//Serial.begin(...)//), dans Pure Data (//[comport .. ....]//) et dans le moniteur série d'Arduino. En effet, parfois on croit ne plus pouvoir se connecter au module, mais c'est que son //baudrate// est différent de celui que l'on utilise pour s'y connecter.
* **Leonardo** : utiliser Serial1 à la place de Serial : //Serial1.begin(9600); xbee.setSerial(Serial1);//
==== Astuce ====
En ouvrant deux fois le logiciel Arduino, on peut téléverser des codes dans deux Arduinos différentes. Cela évite de devoir changer la carte de destination à chaque fois.
=====1/ To XBee (direct) =====
Le premier exemple consiste à contrôler directement les sorties numériques et PWM des XBees à partir de Pure Data sans passer par Arduino. Pour les tests, nous branchons une LED sur la sortie D0 (digital) et une autre sur la sortie PWM1 (PWM).
**Schéma** : Pd/AT/SERIAL/XBEE1 ---> XBEE2/LEDS, XBEE3/LEDS, ... \\
**Code** : to-xbee-star.pd
{{:materiel:xbee:star:xbee-star-direct.jpg|}}
==== Configuration ====
Ouvrir le XBee Terminal avec Processing et entrer pour chaque XBee sa configuration :
* XBEE#1 Coordinator: ATRE, ATID1111, ATAP2, ATCE1, ATWR
* XBEE#2 End Device : ATRE, ATID1111, ATMY2, ATWR
* XBEE#3 End Device : ATRE, ATID1111, ATMY3, ATWR
La grande différence par rapport aux précédentes configurations est le fait que nous ne spécifions pas d'adresse de destinataire en "dur", nous la spécifions directement dans la commande envoyée au coordinateur grâce au **mode API** (ATAP2). Voir les [[.:#annexes|annexes]] en bas pour en savoir plus.
{{:materiel:xbee:star:xbee-terminal.png|}}
==== Explications ====
^ AT Command ^ Description ^
| ATRE | Revenir à la configuration de base |
| ATID1111 | Adresse du réseau |
| ATAP2 | Coordinateur en mode API |
| ATCE1 | Rôle de coordinateur |
| ATMY2 | Adresse du XBee |
| ATWR | Enregistrement de la configuration |
**Remarques** :
| ATAP2 | Par défaut : le mode API est optionnel pour les End Devices|
| ATMY0 | Par défaut : l'adresse du coordinateur est à 0 par défaut |
| ATAP0 | Par défaut : mode AT pour les End Devices |
| ATCE0 | Par défaut : comportement End Devices |
| ATDH0 | Par défaut : adresse en 16 bits|
| ATDL0 | Par défaut : Adresse du destinataire|
| ATIU0 | ? : pour ne pas utiliser les entrées/sorties RX/TX dans ce cas-là (direct) |
| ATMY1 | ? : si l'adresse du coordinateur est 1, cela pourrait éviter d'envoyer des infos inutiles au coordinateur |
==== Pure Data ====
Envois des commandes avec Pure Data
{{:materiel:xbee:star:to-xbee-star.png|}}
=== Explications ===
^ AT Command ^ Description ^
|RAT 0x0 0x2 2 D0 4 | digital switch off|
|RAT 0x0 0x2 2 D0 5 | digital switch on|
|RAT 0x0 0x3 2 P1 2 | PWM mode (2) for PWM1 pin|
|RAT 0x0 0x3 2 M1 $1 | Control PWM (0-255) with M1 (use P0 and M0 for PWM0 pin)|
**Décryptage du message "Remote AT commands (RAT)"**
|64-bit_destination| 0x0 (any, not needed here)|
|16-bit_destination:| XBee end devices addresses|
|options| 2 (apply changes immediately)|
|command| D0 (pin 20 of the XBees)|
|parameters| 4 (switch off), 5 (switch on)|
Si vous envoyer des données très rapidement, vous verrez que les LEDs réagissent lentement. On observe une inertie qui n'est pas souhaitable pour du contrôle en temps-réel. C'est parce que le **baudrate** par défaut est de 9600, ce qui est très lent. Pour avoir une meilleure réponse, on peut le changer dans les modules XBee, avec la commande **ATBD6** pour 57600. Attention, pour reconfigurer le XBee avec le terminal, il faudra le lancer avec nouveau //baudrate// sinon vous n'avez plus accès au module : //myPort = new Serial(this, portnum, 57600);//. Pareil dans Pure Data, il faut le changer.
=====2/ Analyse de la trame =====
Pour comprendre ce qu'envoie les modules XBee, on peut afficher le contenu de la trame pour savoir où sont les données utiles envoyées. Le schéma est très simple, on utilise le moniteur série du logiciel Arduino pour visualiser ces données.
**Schéma** : Pd/SERIAL/XBEE1 ---> XBEE2/RX/ARDUINO \\
**Fichiers** : to-xbee-serial.pd, from_serial.ino, from_xbee_serial.ino (get packet), from_xbee_serial_2.ino (get one data)\\
{{:materiel:xbee:star:xbee-monitor.png|}}
**Remarque** : en passant par le convertisseur série, sans Arduino, je n'arrive pas à voir les trames... Je ne comprend pas.
==== Configuration ====
* XBEE#1 Coordinator: ATRE, ATID1111, ATDL2, ATWR
* XBEE#2 End Device : ATRE, ATID1111, ATMY2, ATWR
==== Résultats ====
^ Données ^ Résultats ^
|Chiffres quelconques | OK. Limités à 0-255 (byte)|
|print **A** | **65**|
|print **hello**| **104 101 108 108 111**|
|RAT 0x0 0x2 2 D0 5| 126 0 16 23 23 0 0 0 0 0 0 0 0 0 2 2 **68 48 5** 84|
|TX 0x0 0x2 0 0 **120** | 126 0 15 16 24 0 0 0 0 0 0 0 0 0 2 0 0 **120** 93|
|TX 0x0 0x2 0 0 **10 11 12 13 14 15**| 126 0 125 51 16 30 0 0 0 0 0 0 0 0 0 2 0 0 **10 11 12 13 14 15** 145|
==== Récupérer une donnée (parser) ====
{{:materiel:xbee:star:xbee-monitor-get-data.png|}}
=====3/ XBee API - Arduino =====
On fait communiquer uniquement des Arduinos entre elles pour comprendre comment envoyer et recevoir des trames XBee avec Arduino. On branche une LED sur la pin 9 pour voir le résultat.
**Schéma** : ARDUINO/TX/XBEE1 ---> XBEE2/RX/ARDUINO/LED et XBEE3/RX/ARDUINO/LED\\
**Codes** : to_xbee_api.ino, from_xbee_api.ino\\
{{:materiel:xbee:star:xbee-star-arduino-api.jpg|}}
==== Configuration ====
* XBEE#1 Coordinator: ATRE, ATID1111, ATAP2, ATCE1, ATWR
* XBEE#2 End Device : ATRE, ATID1111, ATAP2, ATMY2, ATWR
* XBEE#3 End Device : ATRE, ATID1111, ATAP2, ATMY3, ATWR
==== Résultat ====
{{:materiel:xbee:star:xbee-api-monitor.png?400|}}
=====4/ XBee API - Arduino et Pure Data =====
N'étant pas arrivé à envoyer des données en passant par le convertisseur série, j'ai dû utilisé une Arduino pour formater correctement ces données pour les autres modules récepteurs. On utilise la bibliothèque //SerialCommand// dans Arduino pour récupérer six données envoyées de Pure Data (une liste de six données). Celles-ci sont ensuite formatées par Arduino et la bibliothèque //XBee//. Les récepteurs récupèrent uniquement le tableau de données de la trame. La LED branchée sur la pin 9 permet toujours de visualiser ce qu'il se passe.
**Schéma** : Pd/CMD/ARDUINO/XBEE1 ---> XBEE2/RX/ARDUINO/LED et XBEE3/RX/ARDUINO/LED\\
**Codes** : to-xbee-cmd.pd, to_xbee_api_cmd.ino, from_xbee_cmd.ino
{{:materiel:xbee:star:xbee-star-puredata-cmd.jpg|}}
==== Configuration ====
* XBEE#1 Coordinator: ATRE, ATID1111, ATAP2, ATCE1, ATBD6, ATWR
* XBEE#2 End Device : ATRE, ATID1111, ATAP2, ATMY2, ATBD6, ATWR
* XBEE#3 End Device : ATRE, ATID1111, ATAP2, ATMY3, ATBD6, ATWR
**Changement de baudrate** : il faut donc les changer partout (Pure Data, Arduino, xbeeTerminal, moniteur série).
==== Pure Data ====
{{:materiel:xbee:star:xbee-star-cmd-puredata-bd.png|}}
=====4/ Réception des données (direct) =====
Réception des données directes (capteurs) de plusieurs XBees sans Arduinos par le XBee coordinateur, avec Pure Data ou Processing. Très pratique pour récupérer les données d'un réseau de capteurs.
**Schéma** : CAPTEUR/XBEE2 et CAPTEUR/XBEE3 (seules) ---> SERIAL/XBEE1\\
**Codes** : from-xbee-star-1.pd, from-xbee-star-2.pd\\
==== Configuration ====
* XBEE#1 Coordinator: ATRE, ATID1111, ATAP2, ATMY1, ATWR
* XBEE#2 End Device : ATRE, ATID1111, ATAP2, ATMY2222, ATDL1, ATWR
* XBEE#3 End Device : ATRE, ATID1111, ATAP2, ATMY3333, ATDL1, ATWR
Les adresses des destinataires doivent être celles du coordinateur.
==== Pure Data ====
Sans [mrpeach/unpackxbee]\\
{{:materiel:xbee:star:from-xbee-star-1.png|}}
Avec [mrpeach/unpackxbee]\\
{{:materiel:xbee:star:from-xbee-star-2.png|}}
==== Processing ====
[[.:processing-codes]]
===== Annexes ======
==== API ====
In AT Command mode (Transparent Mode) , everything got in RX of XBee will be sent out via antenna , the incoming data from antenna will go to TX. But in API Mode , it won't send out anything until it received the correct form of commands from serial interface. ([[https://sites.google.com/site/xbeetutorial/xbee-introduction/api_mode|xbee introduction]])
**Data Structure in API Mode:**\\
7E 00 0A 01 01 50 01 00 48 65 6C 6C 6F B8\\
|7E |Start delimiter|
|00 0A |Length bytes|
|01 |API identifier|
|01 |API frame ID|
|50 01 |Destination address low|
|00 |Option byte|
|48 65 6C 6C 6F |Data packet (ASCII: "Hello")|
|B8 |Checksum|
Series 1 radios support both AT and API modes with a single firmware version, allowing you switch between the modes with X-CTU. However, Series 2 requires a specific firmware for API mode. As of now there are two firmware versions for Series 2 API mode: ZNet and ZB Pro. ZNet is recommended as it is the easiest to work with.
**What is API (Application Programming Interface) Mode and how does it work?** ([[http://www.digi.com/support/kbase/kbaseresultdetl?id=2184|digi.com]])\\
API (Application Programming Interface) mode is a frame-based method for sending and receiving data to and from a radio's serial UART. The API is an alternative to the default transparent mode.
The API allows the programmer the ability to:
* Change parameters without entering command mode (XBee only)
* View RSSI and source address on a packet by packet basis
* Receive packet delivery confirmation on every transmitted packet
**XBee product manual :** \\
The API operation option facilitates many operations such as the examples cited below:
* Transmitting data to multiple destinations without entering Command Mode
* Receive success/failure status of each transmitted RF packet
* Identify the source address of each received packet
==== Broadcast / Unicast ====
Pour envoyer des commandes à plusieurs destinataires, une autre solution aurait été d'envoyer des messages à tout le monde (Broadcast) et que les destinataires analysent les données (parser) pour ne récupérer que ce qui leur était destiné. Je pars du principe que le mode API fait pour cela est peut-être plus rapide à exécuter ces opérations, sachant que l'envoi de message physiquement (ondes radio) est envoyé à tout le monde. Ce sont les modules entre eux qui font le travail de déterminer qui est le destinataire, quelles sont les bonnes données, etc.
**Series 2** ([[https://forum.sparkfun.com/viewtopic.php?f=13&t=31047|forum.sparkfun.com]]) : \\
Transmitting data using broadcast addressing with XBee ZB modules will generally give you much, much less performance than transmitting an individual unicast to each node you want to talk to. This is because broadcasting works very differently on the XBee ZB modules than with the XBee 802.15.4 modules.
**Series 1** ([[https://forum.sparkfun.com/viewtopic.php?f=13&t=24290|forum.sparkfun.com]], [[http://electronics.stackexchange.com/questions/76924/making-a-star-network-using-5-xbee-series-1-modules-in-at-mode-how-to-do-it|electronics.stackexchange.com]]) : \\
If you don't want to use API, and strictly want to use AT mode, then I suggest you simply put a destination prefix string at the beginning of each of your messages, and then broadcast all messages to all end-nodes. On the receiving end-nodes, write some code to check whether the destination prefix string of a received message matches that particular end-node's address/name (which you can assign randomly yourself in code). I don't think it's a good idea to change ATDL dynamically for each message. Not only might it affect the timing and require re-pairing but also remember that ATDL is written to the Xbee's EEPROM -- which only allows a finite number of rewrites.