..:: Planète-Domotique : Le Blog ::..
Guides et Tutoriels Karotz Tous les articles

Créer une application pour Karotz

Le nouveau petit lapin qui fait le buzz en ce moment n’est autre que … Karotz.

Le Karotz est le remplaçant du célèbre Nabaztag. Commercialisé depuis le début Avril par la société Mindscape, ce lapin HighTech permet bien plus que son grand frère !

Désormais, le lapin permet d’être animé suivant 2 types d’applications. Les applications distantes en mode REST qui pilote le lapin en utilisant des url web ou les applications EMBBED qui sont développées en Javascript.

Dans tous les cas, il faudra installer une application sur le Karotz. Cette application permettra de configurer les droits d’accès de votre application distante dans le cas d’une application web et elle contiendra aussi le code javascript dans le cas d’une application embarquée.

Le Store Karotz

Les différentes applications pourront ensuite êtres installées sur le Karotz un peu la manière de l’Apple Store :

N’importe qui peut créer une application pour le Karotz. Il suffit de créer un compte sur le site et de se rendre dans la partie Lab :

Après avoir validé le contrat de développement des applications, vous pourrez envoyer votre nouvelle application sur le Store.

Voici les différents paramètres nécessaires pour créer l’application sur le store :

  • Le nom de l’application
  • Une description courte
  • Une description longue
  • Une aide qui va s’afficher à coté de l’application dans le store
  • Une icône de 64×64 pixels
  • La langue de votre application
Une fois créée, l’application apparaît sous la forme suivante :
Voici une description des données de chaque application :
  • API Key : C’est l’identifiant unique de chaque application, c’est grâce à cette clef que l’application pourra être identifiée
  • Secret Key : Cette clef permet de limiter certaines fonctions de l’application (comme le développement
  • Version représente les différentes version qui ont été envoyés vers le serveur de Mindscape
  • Status représente l’état dans lequel se trouve l’application
  • Le bouton Edit details permet de modifier les paramètres de l’application saisie lors de la création (sauf le nom qui ne peut jamais être modifié)
  • Le bouton Add a new version vous permet d’envoyer une mise à jour sur le serveur
  • Le bouton Submit qui permet de soumettre l’application à l’équipe Karotz pour validation et ajout au Karotz Store publique.
  • Le bouton Test! permet d’avoir un lien directe vers l’application pour l’installer sur votre Karotz.
  • Le bouton Delete permet de supprimer une application qui n’a pas été publié sur le store.

Le bouton Test! a un gros avantage, c’est qu’il permet de faire tester l’application à n’importe quel utilisateur de Karotz, même si elle n’a pas encore été validée par Mindscape et n’apparaît donc pas dans le Karotz Store.

Vous pouvez par exemple tester mon application Vie de Merde (avec les citations du célèbre site VieDeMerde.fr) en cliquant sur le lien suivant :

La structure de base d’une application

Une application Karotz est un zip contenant l’ensemble des fichiers (descriptor.xml, screen.xml, ensemble des fichiers Javascript).

Deux fichiers sont indispensables :

  • descriptor.xml : Qui contient l’ensemble de la configuration de l’application
  • screen.xml : Qui contient les données configurables dans les différents profils de l’application.

Le fichier descriptor.xml

 

 

<descriptor>
 <version>1.1.0</version>
 <accesses>
 <access>tts</access>
 <access>button</access>
 <access>http</access>
 </accesses>

 <editor>PlanèteDomo</editor>
 <deployment>hosted</deployment>
 <multiConf>true</multiConf>

 <parameters>
 <parameter key="showInstallUuid" value="true"/>
 </parameters>

 <interruptible>true</interruptible>
 <awake>true</awake>
</descriptor>

 

Voici la description des différents TAGs de ce fichier xml :

  • version : contient la version de l’application. Cette version devra être différente pour chaque mise à jour sur le store Karotz.
  • accesses : Définie la liste des fonctions pour lesquelles l’application demande des droits. Ces droits seront affichés dans le store et permettront d’informer l’utilisateur sur les fonctions susceptibles d’être utilisées par l’application.
    Voici la liste des droits existants : led, ears, button, tts, webcam, asr, multimedia, rfid, http, file.
  • editor : Le nom de l’éditeur (qui sera affiché dans le Store). Par défaut, si il n’est pas spécifié, l’éditeur sera le nom et prénom du compte qui créé l’application.
  • asrName : Commande de reconnaissance vocale. Par défaut, la commande ASR (reconnaissance vocale) est le nom de l’application
  • deployment : Type d’application. Deux types existent : “external” ou “hosted” (valeur par defaut)
  • multiConf : Une application peut autoriser un ou plusieurs profils. Valeur  “true” ou “false” (valeur par defaut)
  • parameters : Gestion de paramètres particuliers de configuration de l’application (exemple showInstallUuid permet d’afficher dans la page du profil l’installID de l’application, voir ci-dessous)
  • interruptible : Indique si l’application peut être interrompu par une autre application. Valeur “true” ou “false” (par défaut)
  • awake : Indique si l’application peut réveiller le Karotz. Valeur “true” ou “false” (valeur par defaut)
  • callback : URL de Callback pour les applications externes

Le fichier screen.xml

 

 

<!-- triggers (use as attribute of screen tag)
You can choose which trigger will be available, by default all trigger will be available:
Configure with boolean like nanoTrigger="true" or nanoTrigger="false"

 nanoTrigger : rfid tag trigger (Manual activation)
 permanentTrigger : Permanent activation
 scheduledTrigger : Scheduled activation
 voiceTrigger : Asr activation
 scheduledDateTrigger : not implemented now -->

<screen nanoTrigger="true"
 permanentTrigger="true"
 scheduledTrigger="true"
 scheduledDateTrigger="true"
 voiceTrigger="true">

<!-- fields

You can add some fields for configuration :

Meteo example :
<screen>
 <text label="city" name="country" default="France" validation="" required="true" errorMessage="" />
 <text label="Country" name="city" default="Paris" validation="" required="true" errorMessage="" />
 <select label="Unit" name="unit" type="one" required="true">
 <option label="°C" key="C" checked="true"/>
 <option label="°F" key="F" checked="false"/>
 </select>
</screen>

text (provide a text field):

 label : text displayed before the field
 name : name of the balise. used to get the value
 default : default value
 required : if a value is required (true/false)
 validation : regexp to validate the value (default : empty)
 errorMessage : message printed if validation failed (default : empty)

select (provide a drop down list) :

 label : text displayed before the list
 name : name of the balise. used to get the value
 required : if a value is required (true/false)
 type : type of the list (default : “one”) (to be completed)
 select option :
 label : text displayed
 key : key of the element. it is the value returned
 checked : true/false.
-->
</screen>

 

 

Ce fichier décrit l’interface de paramétrage de l’application, il permet de lister la manière dont pourra être lancée l’application (Trigger) et les différents paramètres que l’utilisateur pourra configurer.

Cas d’une application embarquée

Dans le cas d’une application embarquée, un fichier javascript main.js doit être créé et il contient au minimum les instructions suivantes qui permettent de connecter l’application avec le Karotz :

karotz.connect("localhost",  9123);
karotz.start(onKarotzConnect, data);
var onKarotzConnect = function(data)
{
      // Fonction callback la première à être appelée
}

La documentation détaillée de développement pour une application Javascript peut être trouvé ici :

Interaction avec l’application Karotz

L’autre méthode de développement possible avec le Karotz est l’accès distant. Un ensemble d’instructions permet de contrôler les différentes fonctions (oreilles, webcam, leds…) sous forme d’appel à des urls.

La documentation de ce système d’url est disponible ici :

A noter que toute interaction d’une application distante avec le Karotz doit débuter par l’obtention d’un InteractiveID qui servira d’identifiant de session et permettra à l’application de communiquer avec le Karotz pendant toute sa durée de validité.

Un InteractiveID a une durée de vie de 15 minutes.

Pour obtenir un InteractiveID, il y a plusieurs solutions :

  • Grâce à un TAG rfid, lorsque le TAG est passé devant le Karotz, le callback est appelé avec en paramètre l’InteractiveID :
  • Grâce à une connexion sur le site www.karotz.com, en appelant l’url . Après la connexion, la redirection vers votre callback :
  • En utilisant une connexion signée (cf ci-dessous)

Ensuite, une fois l’InteractiveID obtenu, il suffit d’appeler des urls pour chaque fonction en passant l’InteractiveID en paramètre…

Par exemple, pour faire bouger les oreilles :

InteractiveID par authentification signée

L’obtention de l’InteractiveID en demandant à l’utilisateur de s’authentifier sur le site de Karotz peut ne pas être la mieux adaptée.

Par exemple, dans le cas d’une application développée sur PC ou pour associer le compte d’un utilisateur directement avec son compte Karotz.

Dans ce cas, il y a une procédure d’échange avec le serveur Karotz pour obtenir l’InteractiveID.

En utilisant les paramètres de l’application :

  • APIKey : Le APIKey est disponible dans le détail de l’application que vous avez publiée
  • SecretKey : Le SecretID est disponible dans le détail de l’application que vous avez publiée
  • InstallID : Identifiant unique qui s’affiche dans le profil de l’application (si elle l’autorise grâce au paramètre du descriptor.xml)

Voici un exemple de code décrivant l’authentification en PHP :

<?php

define("APIKEY",    "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
define("SECRET",    "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
define("INSTALLID", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");

$parameters['apikey'] = APIKEY;
$parameters['once'] = rand();
$parameters['timestamp'] = time();

if (isset($_GET['INSTALLID']))
  $parameters['installid'] = $_GET['INSTALLID'];
else
  $parameters['installid'] = INSTALLID;

ksort($parameters);

$query = "";

foreach($parameters as $key=>$value)
{
  if ($query!="")  $query .= "&";

  $query .= urlencode($key)."=".urlencode($value);
} 

$signature = base64_encode(hash_hmac('sha1', $query, SECRET, true));

$url_id = 'https://api.karotz.com/api/karotz/start?'.$query.'&signature='.urlencode($signature);

$curl = curl_init(); 

if (!$curl) exit;

curl_setopt($curl, CURLINFO_HEADER_OUT, true);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

curl_setopt($curl, CURLOPT_URL, $url_id);

$result = curl_exec($curl);

# Erreur
if (curl_errno($curl)) { $curl_error = curl_error($curl); echo '<p>Err> '.$curl_error.'</p>'; exit; }

# Lecture du InteractiveID
$interID = '';
if ($result!='') try
{
   $xml = new SimpleXMLElement($result);
   $interID = $xml->interactiveMode->interactiveId;
}
catch(Exception $e) {
  echo '<b>Error</b>: <font color="red">'.$e->getMessage().' (severity '.$e->getCode().')</font><br>';
}

# Bouger les oreilles
curl_setopt($curl, CURLOPT_URL, 'https://api.karotz.com/api/karotz/ears?left=5&right=8&interactiveid='.$interID);
curl_exec($curl);

# Flash
curl_setopt($curl, CURLOPT_URL, 'https://api.karotz.com/api/karotz/led?action=light&color='.$_GET['color'].'&interactiveid='.$interID);
curl_exec($curl);

# Parler
curl_setopt($curl, CURLOPT_URL, 'https://api.karotz.com/api/karotz/tts?action=speak&lang=FR&text='.urlencode($_GET['txt']).'&interactiveid='.$interID);
curl_exec($curl);

# Libérer le Kz au bout de 5 sec
sleep(5);
curl_setopt($curl, CURLOPT_URL, 'https://api.karotz.com/api/karotz/interactivemode?action=stop&interactiveid='.$interID);
curl_exec($curl);

curl_close($curl);

Ensuite, une fois votre fichier karotz.php sur votre serveur web, vous pouvez communiquer avec Karotz en passant en paramètre l’installID de votre application, la couleur et le texte :

https://monserveur/karotz.php?installid=xxxxxxx&color=FF0000&txt=je parle

Voila pour cette introduction au développement d’application sur le Karotz.

Dans d’autres articles à venir, je décrirais plus avant la partie développement pur…

0
0
Mickael

Je suis passionné de Domotique depuis des années. J'ai fait du développement en informatique industrielle pendant 12 ans, et un jour ... je me suis lancé !<br /> J'ai créé ma boutique de vente en ligne : https://www.planete-domotique.com

Commentaires

  1. Bonjour, un grand merci pour ce tutoriel qui me met le pied à l’etrier!

    J’ai essayé d’utiliser ces informations pour créer ma premiere appli REST.

    J’ai juste un doute. L’adresse de « callback » peut-elle etre une adresse du reseau local ?
    Ex : 192.168.1.14:8080/karotz/karotz.php

    Ensuite, j’ai essayé le script PHP mis en exemple.
    Pourrais tu precisier sur le billet comment l’utiliser, car c’est seulement apres 10 minutes que &’ai remarqué les $_GET.
    L’appel du script est donc quelquechose comme :
    karotz.php?color=FF8080&text=Bonjour

    Enfin, pour une raison inconnue, le screen.xml donné en exemple a été refusé par le serveur lors de la publication du .zip (mauvais format). J’a ôté les commentaires HTML et ca a fonctionné. Le screen.xml que tu utilises contient-il les commentaires ?

    Malgré ces quelques remarques, j’ai adoré ce billet ! J’ai hâte de lire le prochain :o)

  2. J’ai juste un doute. L’adresse de « callback » peut-elle etre une adresse du reseau local ?
    Ex : 192.168.1.14:8080/karotz/karotz.php

    Oui, aucun soucis. Je voulais faire le test avant de répondre, mais ça fonctionne parfaitement.

    Ensuite, j’ai essayé le script PHP mis en exemple.
    Pourrais tu precisier sur le billet comment l’utiliser, car c’est seulement apres 10 minutes que &’ai remarqué les $_GET.
    L’appel du script est donc quelquechose comme :
    karotz.php?color=FF8080&text=Bonjour

    Effectivement, je vais rajouter ça à la fin de l’article 🙂

    Le screen.xml que tu utilises contient-il les commentaires ?

    Oui, il contient les commentaires et j’ai pas eu de soucis.
    C’est peut être la publication sur le blog qui a modifié la mise en forme … ?

    Malgré ces quelques remarques, j’ai adoré ce billet ! J’ai hâte de lire le prochain

    Merci, le prochain arrive bientôt.

    A+

  3. Bonjour
    merci pour ce script, genial !
    toutefois un probleme
    l’instruction oreille est envoyée et executée correctement (pour l’instant les autres sont commentées)
    mais l instruction pour liberer le KZ remet a 0 les oreilles 5 secondes après !!
    si je supprime cette instruction lalors le lapin reste clignotant en blanc et n’est plus accessible
    merci de votre retour

    • C’est normal, le Karotz reviens toujours a un état de repos (vert clignotant et les oreilles dressées).

      Si vous souhaitez que le lapin reste dans un état donné, il faut « l’occuper » et laisser tourner votre application, en utilisant réguliérement l’instruction « ping ».

      Il reste blanc clignotant car l’application ne se termine pas, mais qu’elle n’a rien d’autre à faire, c’est à vous de lui donner quelque chose à faire 🙂

  4. donc on ne peutpas faire comme avec le nabaztag tag simplement lui orienter les oreilles et donner ces instructions une a deux fois par jour ?

  5. Si, mais dans ce cas, il faudra faire une application qui tourne en permanence. Dès que votre application se termine le Karotz revient dans l’état « repos », je sais c’est un peu agaçant 🙂 mais c’est comme ça…

    Il était prévu que mindscape (violet) fasse des applications « interruptibles », il aurait donc été possible de faire une appli qui tourne en permanence mais qui n’empêche pas d’autre application d’être lancé (comme l’horloge). Pour l’instant, je crois que ce n’est toujours pas mis en place… 🙁

  6. j’ai vu que la video serait ou devrait être accessible (je parle du streaming) serait il possible d’avoir le code pour récuperer le stream ?

    j’utilise le code ci dessus pour faire parler le lapin lorsque que mon détecteur de présence e déclenche, il doit être possible d’y ajouter la vidéo non ?

    ce qui donnerait, le detecteur de présence se déclenche > je fais parler le lapin ET je déclenche le streaming vidéo.

    Merci

  7. Bonjour,
    le lab site est différent maintenant et n’existe plus.
    Merci, Michaël

  8. bonjour a tous.
    merci pour cet article. j’ai une question, j’ai une vera (z-wave) et j’aimerai a l’aide d’un URL lancer la lecture d’un son sur le karotz.
    comment je peux faire?
    merci d’avance

  9. @Michaël : Merci, j’ai corrigé 🙂

    @michael (décidément que de michael ;)) : il faut suivre ce qui est dit dans l’article 🙂

    Tu peux éventuellement utiliser le fichier que j’héberge sur mon serveur

  10. Ca fonctionne encore ??
    parce que j’ai fait quelques essais sans succès ..

  11. Bonjour,
    Je souhaite avoir une app pour moi seul qui permette de notifier la fin d’un téléchargement. Je m’explique: Je suis codeur php/html, et j’ai récemment créer un vb un logiciel de téléchargement normal.
    Dès qu’un téléchargement est terminé, il appel une url externe

    La variable file et lapin sont récupérées par la méthode get (simple) et ensuite je demande à l’api d’envoyer un message du type ‘Votre téléchargement de ‘.$file.’ est terminé’.

    Jusque là je maîtrise, mais je ne comprend pas bien le système d’ID qui expire toutes les 15 minutes. Ca veut dire que je dois le préciser manuellement à chaque fois ? donc inutile, je demande à ce que ce soit automatique.

    Pour ce qui est de l’api, j’ai bien compris, l’install ID aussi, je pense pouvoir l’inclure dans une variable, par contre c’est l’interactive ID qui me gène. Comment le récupérer automatiquement dans mon fichier PHP ?

    Merci,
    Paul.

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

%d blogueurs aiment cette page :