API Nabaztag

Prenez le contrôle total de votre Lapin

Notre API vous permet d'activer, depuis une application de tierce-partie, un évènement sur votre Nabaztag. Par exemple : contrôler le mouvement des oreilles, commander les DEL, envoyer des messages en TTS (text to speech, texte qui sera transformé en parole) ou avec un nabcast.
Voici une liste de choses que vous pouvez faire avec l'API Nabaztag :

• Envoyer des messages de texte à un Lapin


• Envoyer des chorégraphies à un Lapin


• Envoyer n'importe quel nabcast à un Lapin


• Obtenir la position des oreilles d'un Lapin


• "Streamer" un MP3 sur votre Nabaztag/tag (comme une webradio, un podcast ou encore une de vos musiques)


• Récupérer ds informations sur le statut du lapin et le compte qui y est associé

Table des matières

1. Informations importantes


2. Public visé par ce document


3. Activer la réception d'évènements sur votre Nabaztag


4. Comment puis-je envoyer un évènement à un Nabaztag ?


5. Langage des chorégraphies
   
   
   
   1. Définir le tempo
   
   
   2. Commander les oreilles
   
   
   3. Commander les DEL
   
   
   4. Combiner les commandes des oreilles et des DEL
   
   
   5. Choisir la voix pour le TTS
   
   
   
   


6. Envoyer une URL au Lapin pour qui'il la lise en "streaming"


7. Récupérer des infos sur votre Nabaztag


8. Comprendre les messages retournés par l'API Nabaztag


9. Donnez-nous vos réactions !

Informations importantes

Les nabcasts étant supprimés après la disparition de my.nabaztag.com, les fonctionnalités les concernant sont désormais inutiles.

La durée de vie minimale d'un message est, suite à un bug, supprimée elle aussi : tout message envoyé par l'API n'est plus re-jouable !

Public visé par ce document

Ce document est à destination des programmeurs qui veulent développer des applications client pour Nabaztag.

Activer la réception d'évènements sur votre Nabaztag

1. Connectez-vous avec votre compte sur my.violet.net


2. Choisissez votre Nabaztag dans le sélecteur d'objets


3. Allez dans Paramètres > Ecosystème


4. Cochez la case "Je veux recevoir les services et les applications de l'écosystème", si ce n'est déjà fait


5. Cliquez sur le bouton "Enregistrer les paramètres"


6. Votre token et votre serial number sont affichés en dessous !

Ecrivez et sauvegardez votre token et votre serial quelque part, vu que vous devez l'utiliser pour envoyer des messages depuis votre application
Note : si vous désactivez puis réactivez la réception d'évènements, vous obtiendrez un nouveau token.

Comment puis-je envoyer un évènement à un Nabaztag ?

Vous n'avez qu'à simplement appeler l'URL http://api.nabaztag.com/vl/FR/api.jsp avec les paramètres suivants :

• sn : Serial number du Lapin qui recevra les évènements.


• token : Le token est une série de nombres donnés lorsque vous activez la réception des évènements sur le Nabaztag. Cette identification supplémentaire limite le risque de spam puisque, pour envoyer un message, vous devez connaître le token et le serial.


• idmessage : Le numéro du message à envoyer. Le nombre puet se référer à un message dans la Bibliothèque ou un de vos propres MP3 que vous avez téléchargés. Cette identification se trouve sous le nom du titre que vous êtes en train d'écouter.


• nabcast : ID de votre nabcast, si vous voulez y publier du contenu.


• nabcasttitle : Titre de l'épisode dans votre nabcast.


• posright : Position de l'oreille droite comprise entre 0 et 16 (0 = oreille verticale).


• posleft : Position de l'oreille gauche comprise entre 0 et 16 (0 = oreille verticale).


• ears=ok : Envoie la position des oreilles au Nabaztag.


• idapp : C'est l'ID de votre application. Il vous permettra d'authentifier l'émetteur de l'évènement. Ce paramètre n'est pas encore en service.


• voice : Vous permet de choisir la voix qui lira le message.


• tts : Vous permet d'envoyer un texte configuré pour la synthèse vocale (TTS.


• chor : Vous permet d'envoyer une chorégraphie à votre Nabaztag.


• chortitle : Le nom de la chorégraphie.


• ttlive : Vous permet de définir la durée durant laquelle le message demeurera sur le site (en secondes). Par défaut, le message sert stocké pour une période de deux mois.


• action : Voyez plus loin pour ce paramètre.

Par exemple :

Code:

http://api.nabaztag.com/vl/FR/api.jsp?sn=00039D4022DE&token=112231049046144&posleft=0&posright=0&idmessage=10333&idapp=10

Comment puis-je envoyer un message en TTS au sein d'un nabcast qui a l'ID 52 avec le titre : myttsinmynabcast ?

Code:

http://api.nabaztag.com/vl/FR/api.jsp? [...] nabcast=52&nabcasttitle=myttsinmynabcast&tts=the+nabcast

Comment puis-je envoyer le message 1033 au sein du nabcast qui a l'ID 52 avec un titre de son : mymp3inmynabcast ?

Code:

http://api.nabaztag.com/vl/FR/api.jsp? [...] nabcast=52&nabcasttitle=mymp3inmynabcast&idmessage=10333

Note : les messages envoyés grâce à l'API ont une durée de vie d'un jour, ce qui signifie qu'ils seront visibles dans votre compte sur my.violet.net et vous serez en mesure de les rejouer pendant une journée uniquement, après quoi ils seront supprimés.

Langage des chorégraphies

Une chorégraphie est une série d'actions effectuées par les DEL et les oreilles.
Le paramètre principal de la chorégraphie est un tempo ajustable.
Une fois que le tempo est défini, les actions vont être découpées à ce rythme. Chaque action est lancée à un moment précis, appelé "l'heure" de l'action : ce nombre est exprimé par le nombre de battements écoulés depuis le début de la chorégraphie jusqu'à l'évènement désiré.

Par exemple, avec un tempo d'un dixième de seconde, l'action associée à l'heure '10' se produira une seconde après le début de la chorégraphie. De même, l'action associée à l'heure '25' se produira 2,5s après le début de la chorégraphie et ainsi de suite...

La syntaxe d'une chorégraphie est une série de mots-clef ou de nombres, séparés par des virgules.
Les nombres sont toujours des entiers, exprimés sur en base 10. Les mots-clef sont soit 'motor' pour commander les oreilles, soit 'led' pour commander les DEL.

Cette série débute par le tempo, puis se constitue d'une succession d'actions sur les moteurs (des oreilles) ou les DEL.

Chaque action ('motor' ou 'led') commence avec "l'heure" (exprimée par le nombre de battements écoulés depuis le début de la chorégraphie jusqu'à l'évènement désiré), suivie par la commande ('motor' ou 'led') et une série de variables qui décrivent l'action.

Si deux actions sont commandées en même temps, elles seront effectuées en même temps.

1. Définir le tempo

Le tempo est exprimé en Hz. '10' représente donc un tempo d'une seconde.

2. Commander les oreilles

Pour commander les oreilles, on utilise une série de valeurs séparées par des virgules.
Les commandes sont les suivantes :

1. Première valeur : "l'heure" de l'action, '0' si c'est la première commande


2. Deuxième valeur : 'motor', pour bouger une oreille


3. Troisième valeur : commande des oreilles :
   
   
   
   • '1' pour commander l'oreille gauche
   
   
   • '0' pour commander l'oreille droite
   
   
   
   


4. Quatrième valeur : angle de l'oreille, compris entre 0 et 180


5. Cinquième valeur : inutilisée, mettre à '0'


6. Sixième valeur : sens de rotation des oreilles
   
   
   
   • '1' : sens horaire : haut->arrière->bas->face->haut...
   
   
   • '0' : sens antihoraire : haut->face->bas->arrière->haut...
   
   
   
   

Exemple d'une commande qui tourne l'oreille gauche dans le sens antihoraire avec un angle de 20°, à "l'heure" 0 :

Code:

0,motor,1,20,0,0

3. Commander les DEL

Pour commander les DEL, on utilise une série de valeurs séparées par des virgules.
Les commandes sont les suivantes :

1. Première valeur : "l'heure" de l'action, '0' si c'est la première commande


2. Deuxième valeur : 'led', pour changer la couleur d'une DEL


3. Troisième valeur : utilisée pour définir quelle DEL vous voulez illuminer :
   
   
   
   • '0' : DEL du dessous
   
   
   • '1' : DEL de gauche
   
   
   • '2' : DEL du milieu
   
   
   • '3' : DEL de droite
   
   
   • '4' : DEL du nez du lapin
   
   
   
   


4. Quatrième, cinquième et sixième valeurs : la couleur en RVB, les valeurs sont comprises entre 0 et 255.

Exemple d'une commande qui met la DEL du milieu en vert, puis qui met celle de gauche en rouge, et pour finir qui éteint celle de droite :

Code:

0,led,2,0,238,0,2,led,1,250,0,0,3,led,2,0,0,0

Combiner les commandes des oreilles et des DEL

Voici comment combiner les trois actions, avec les paramètres initaux de tempo :

Code:

10,0,motor,1,20,0,0,0,led,2,0,238,0,2,led,1,250,0,0,3,led,2,0,0,0

Si vous avez bien suivi, c'est un jeu d'enfant d'envoyer la chorégraphie ainsi écrite ! Il suffit d'appeler cette URL :

Code:

http://api.nabaztag.com/vl/FR/api.jsp?sn=00039D4022DE&token=112231049046144&chor=0,led,2,0,238,0,2,led,1,250,0,0,3,led,2,0,0,0

Choisir la voix pour le TTS

Vous pouvez choisir la voix qui lira votre message ! Voici une liste (non exhaustive) qui recense en priorité les voix francophones disponibles (il y en a actuellement 82 !) :

Voix françaises :

• FR-Gertrude


• FR-Philomene


• FR-Maxence


• FR-Julie


• FR-Anastasie


• FR-Archibald

Voix canadiennes :

• CA-Felix


• CA-Antonine

Voix belge :

• BE-Minna

Pour obtenir une liste complète et à jour des voix disponibles, appelez l'action n°9 (voyez cette section pour plus de détails).

Envoyer une URL au Lapin pour qu'il la lise en "streaming"

Maintenant, grâce au travail des développeurs sur l'API, vous pouvez maintenant envoyer des URL, ou des MP3, ou encore des flux à un tag/tag.
Cette nouvelle caractéristique vous permet d'intégrer dans vos applications des MP3, des podcasts et des webradios. Maintenant, créer des applications utilisant du son en "streaming" pour votre Lapin exceptionnellement talentueux !

Comment est-ce que ça marche ?

Si vous avez un tag/tag, vous pouvez utiliser l'API pour lui envoyer des URL de fichiers MP3 pour lui faire jouer des podcasts ou des webradios.
Tout ce que vous avez à faire, c'est d'inclure ou d'appeler l'URL http://api.nabaztag.com/vl/FR/api_stream.jsp dans votre application, avec les options suivantes :

• sn : Serial number du Lapin qui recevra les évènements.


• token : Le token est une série de nombres donnés lorsque vous activez la réception des évènements sur le Nabaztag. Cette identification supplémentaire limite le risque de spam puisque, pour envoyer un message, vous devez connaître le token et le serial.


• urlList : l'adresse du fichier MP3 que vous voulez que votre tag/tag lise.
  Si vous voulez lire plusieurs fichiers à la suite, vous devez les séparer avec le caractère 'pipe' "|" (Alt Gr + 6 sur un clavier français).
  

Exemple : lire une station de webradio :

Code:

http://api.nabaztag.com/vl/FR/api_stream.jsp?token=1267440739&sn=0013D380FD3C&urlList=http://213.205.96.91:9915

Second exemple : lire plusieurs flux MP3 à la suite :

Code:

http://api.nabaztag.com/vl/FR/api_stream.jsp?token=1267440739&sn=0013D380FD3C&urlList=http://my.server.org/music.mp3|http://m.server.org/music2.mp3

Si le fichier est disponible, votre tag/tag vous le lira.

Pour comprendre les réponses de l'api_stream.jsp, référez-vous à cette section.

Récupérer des infos sur votre Nabaztag

Tout comme vous pouvez envoyer des évènements à votre Nabaztag, vous pouvez récupérer des informations sur votre compte ou encore sur votre Nabaztag lui-même.
Pour ce faire, appelez l'URL de base (http://api.nabaztag.com/vl/FR/api.jsp?sn=VOTRENUMERODESERIE&token=VOTRETOKEN) en ajoutant, à la fin de cette URL, le paramètre 'action' avec les valeurs suivantes :

• action=1 : Obtenir un extrait de la musique ou du TTS sans l'envoyer.
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <message>LINKPREVIEW</message>
        <comment>XXXX</comment>
     </rsp>
     



• action=2 : Renvoie une liste de vos amis.
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <listfriend nb="1"/>
        <friend name="toto"/>
     </rsp>
     



• action=3 : Renvoie le nombre de messages et les messages que vous avez dans votre boîte de réception.
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <listreceivedmsg nb="1"/>
        <msg from="toto" title="my message" date="today 11:59" url="broad/001/948.mp3"/>
     </rsp>
     



• action=4 : Renvoie le fuseau horaire du Lapin.
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <timezone>(GMT) Greenwich Mean Time : Dublin, Edinburgh, Lisbon, London</timezone>
     </rsp>
     



• action=5 : Renvoie la signature du Lapin.
  
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <signature>XXXXX</signature>
     </rsp>
     



• action=6 : Renvoie le nombre de personnes et leurs noms qui sont dans votre liste noire.
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <blacklist nb="1"/>
        <pseudo name="toto"/>
     </rsp>
     



• action=7 : Savoir si votre Lapin dort (YES) ou est réveillé (NO).
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <rabbitSleep>YES</rabbitSleep>
     </rsp>
     



• action=8 : Savoir si votre Lapin est un Nabaztag (V1) ou un Nabaztag:tag (V2).
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <rabbitVersion>V1</rabbitVersion>
     </rsp>
     



• action=9 : Obtenir la liste complète des voix supportées pour le TTS.
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <voiceListTTS nb="2"/>
        <voice lang="fr" command="FR-Anastasie"/>
        <voice lang="de" command="DE-Otto"/>
     </rsp>
     



• action=10 : Obtenir le nom du Nabaztag.
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <rabbitName>nabmaster</rabbitName>
     </rsp>
     



• action=11 : Renvoie les langages définis pour le Nabaztag.
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <langListUser nb="4"/>
        <myLang lang="fr"/>
        <myLang lang="us"/>
        <myLang lang="uk"/>
        <myLang lang="de"/>
     </rsp>
     



• action=12 : Obtenir une prévisualisation du message. Marche uniquement avec le paramètre urlPlay et des URL comme broad/001/076/801/262.mp3.
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <message>LINKPREVIEW</message>
        <comment>XXXX</comment>
     </rsp>
     



• action=13 : Endort votre Lapin.
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <message>COMMANDSENT</message>
        <comment>You rabbit will change status</comment>
     </rsp>
     



• action=14 : Réveille votre Lapin.
  Exemple :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <message>COMMANDSENT</message>
        <comment>You rabbit will change status</comment>
     </rsp>
     

Comprendre les messages retournés par l'API Nabaztag

• Trop de requêtes envoyées : vous avez un nombre maximal de requêtes que vous pouvez envoyer pendant une période de temps donnée.
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>ABUSESENDING</message>
           <comment>Too many messages sent in the allowed time try again later please</comment>
        </rsp>
        



• Mauvais token ou serial number.
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>NOGOODTOKENORSERIAL</message>
           <comment>Your token or serial number are not correct !</comment>
        </rsp>
        



• Mauvais ID de la musique (soit c'est qu'il n'est pas dans votre Bibliothèque, soit c'est qu'il n'existe pas).
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>MESSAGENOTSENT</message>
           <comment>Your message id is not correct or is private</comment>
        </rsp>
        



• Nabcast non posté car l'ID de la musique ne fait pas partie de votre Bibliothèque, ou alors c'est que le nabcast n'existe pas.
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>NABCASTNOTSENT</message>
           <comment>Your nabcast id is not correct or is private</comment>
        </rsp>
        



• Nabcast posté avec succès.
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>NABCASTSENT</message>
           <comment>Your nabcast has been sent</comment>
        </rsp>
        



• Message envoyé avec succès.
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>MESSAGESENT</message>
           <comment>Your message has been sent</comment>
        </rsp>
        



• Message non envoyé.
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>MESSAGENOTSENT</message>
           <comment>Your message id is not correct or is private</comment>
        </rsp>
        



• TTS envoyé avec succès.
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>TTSSENT</message>
           <comment>Your text has been sent</comment>
        </rsp>
        



• Problème dans la création du TTS.
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>TTSNOTSENT</message>
           <comment>Your text could not be sent</comment>
        </rsp>
        



• Chorégraphie envoyée avec succès.
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>CHORSENT</message>
           <comment>Your chor has been sent</comment>
        </rsp>
        



• Chorégraphie non envoyé car le paramètre 'chor' n'était pas correct.
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>CHORNOTSENT</message>
           <comment>Your chor could not be sent (bad chor)</comment>
        </rsp>
        



• Position des oreilles envoyée avec succès :
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>EARPOSITIONSENT</message>
           <comment>Your ears command has been sent</comment>
        </rsp>
        



• Position des oreilles non envoyée car la position donnée n'était pas correcte (pour qu'elle le soit, il faut qu'il s'agisse d'un entier compris entre 0 et 16, 0 étant la position correspondante à l'oreille verticale) :
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>EARPOSITIONNOTSENT</message>
           <comment>Your ears command could not be sent</comment>
        </rsp>
        

Obtenir la position des oreilles :


Code:


      <?xml version="1.0" encoding="UTF-8"?>
      <rsp>
         <message>POSITIONEAR</message>
         <leftposition>8</leftposition>
         <rightposition>10</rightposition>
      </rsp>
      



• L'URL a été envoyée avec succès (uniquement pour l'api_stream.jsp) :
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>WEBRADIOSENT</message>
           <comment>Your webradio has been sent</comment>
        </rsp>
        



• L'URL n'a pas été envoyée (uniquement pour l'api_stream.jsp) :
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>WEBRADIONOTSENT</message>
           <comment>Your webradio could not be sent</comment>
        </rsp>
        



• Le paramètre urlList est manquant, donc le flux n'a pus être envoyé (uniquement pour l'api_stream.jsp) :
  

  Code:

  
        <?xml version="1.0" encoding="UTF-8"?>
        <rsp>
           <message>NOCORRECTPARAMETERS</message>
           <comment>Please check urlList parameter !</comment>
        </rsp>
        



• Le lapin n'est pas un Nabaztag:tag (V2) :
  

  Code:

  
     <?xml version="1.0" encoding="UTF-8"?>
     <rsp>
        <message>NOTV2RABBIT</message>
        <comment>V2 rabbit can use this action</comment>
     </rsp>
     

Donnez-nous vos réactions !

Si vous avez des questions, des remarques et des suggestion à propos de l'API Nabaztag ou si vous avez développée une application sympa et vous voulez nous l'envoyer (comme ça nous pourrons la promouvoir sur notre site web), contactez-nous à l'adresse : api [at] violet.net.