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

• 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…