mardi 12 avril 2011

Karotz API - full Php Class


Karotz Php Class - Rel. 1.0b màj 24-04-2011

La version 1.0b de la "Wizz.cc Karotz Class for Php" est en ligne... On accède, au travers de cette classe, à toutes les fonctionnalités de l'Api Web du Karotz publiée par Mindscape.

Cela facilitera le développement des applis web et notamment la migration des sites Nabaztag...

Fichier Zip.

Utilisation :

1 - Inclusion : include('wizz.cc_karotz_class.php');

2 - Instanciation : $Kz = new wizz_karotz($interactiveid, true); (true or false for debug_mode)

3 - Commandes :
$result = $Kz->say('Wizz php class for karotz', 'en');
ou : echo $Kz->ears(2, 5);
ou : $Kz->led_light('FF0000');

$Kz->quit();

4 - Contrôle du résultat si nécessaire : if($Kz->get_responsecode()=='OK') echo 'Cool';

Méthodes implémentées :

$Kz->say($text, $lang)
$Kz->ears($left, $right, $relative)
$Kz->ears_reset()
$Kz->led_pulse($color, $period, $pulse)
$Kz->led_fade($color, $period)
$Kz->led_light($color)
$Kz->play($url)
$Kz->play('previous|next|pause'|'resume'|'stop')
$Kz->play('allsong::'|'title::xx'|'artist::xx'|'folder::xx'|'genre::xx')
$Kz->usb_unlock()
$Kz->usb_allsong()
$Kz->usb_folder()
$Kz->usb_artist()
$Kz->usb_genre
$Kz->usb_playlist()
$Kz->photo($url)
$Kz->video()
$Kz->chor($chor) - not yet released by the Kz DevTeam
$Kz->chor_file($url)
$Kz->chor_stop()
$Kz->config()
$Kz->quit()

Différentes informations sont accessibles : deboggage, paramètres de l'api, réponse des serveurs Karotz (VoosMsg), erreurs rencontrées... :

VoosMsg :
echo $Kz->get_voosmsgid();
echo $Kz->get_correlationid();
echo $Kz->get_interactiveid();
echo $Kz->get_responsecode();
print_r($Kz->get_api_params());
echo $Kz->get_api_response();
print_r($Kz->get_api_resp_array());
echo $Kz->get_api_error();
echo $Kz->isDebug();
echo $Kz->showDebug();

Les informations retournées peuvent changer en fonction de l'api appelée.

Un exemple complet est fourni dans le zip.

Cette classe est maintenue à jour régulièrement en fonction des publications/évolutions apportées à l'Api par Violet/Mindscape[RIP].

dimanche 10 avril 2011

Karotz SDK Javascript - Tuto de base


Karotz SDK Javascript

SDK Javascript : ma 1ère application embarquée

1 - On passe sur les créations de comptes, accès au lab, etc... acquis à ce stade sur karotz.com.

2 - Créer une application dans le Lab.

3 - Charger la version zippée (prête à l'emploi) contenant les fichiers nécessaires à l'installation de l'application embarquée sur le Karotz :

Add a new version : indiquer une note (Radio Zen 1.0) puis l'emplacement du zip

Make private pourla rendre privée dans son store et voir apparaitre le bouton Test!

cliquer sur le bouton Test! puis sur Télécharger gratuitement.

Dans le panneau de configuration qui apparait, la rendre déclenchable par un Nanoz.

Validez, le Kz flashe un instant en orange et bouge ses oreilles pour indiquer qu'il vient de se mettre à jour avec l'application.

Il n'y a plus qu'à passer le Nanoz sous le nez du Kz et l'application démarre...

Cliquer une ou deux fois sur la tête du Kz pour arrêter la radio.

Karotz_SDK_example_radiozen.zip

samedi 9 avril 2011

Karotz API Web - Webcam


On se base sur le tuto précédent pour les acquis.

1 - Votre site web fait appel à la méthode suivante pour déclencher la prise de photo :

http://www.karotz.com/api/karotz/webcam?action=photo&url=http://mywebsite/my_photo.php&interactiveid=xxx

L'url de call-back indiquée en paramètre va donc recevoir l'image envoyée par le Karotz.

2 - Installer le script suivant my_photo.php sur votre site : Zip
<?php  define('MODE_DEBUG', true);

 # Log de quelques infos...
 #
 if (MODE_DEBUG) {
if ($fh = fopen('_log.txt', 'a')) {
fwrite($fh, 'Params (key/value) : ['.PHP_OS.']'.PHP_EOL);
fwrite($fh, '--$_REQUEST--'.PHP_EOL);
foreach ($_REQUEST as $key => $value) fwrite($fh, $key.' = '.$value.PHP_EOL);
if (!empty($_FILES)) {
fwrite($fh, '--$_FILES--'.PHP_EOL);
foreach ($_FILES as $key => $value) fwrite($fh, $key.' = '.$value.PHP_EOL);
if (isset($_FILES['sendfile'])) foreach ($_FILES['sendfile'] as $key => $value) fwrite($fh, $key.' = '.$value.PHP_EOL);
}
fclose($fh);
}
 }

 # Quelques tests au cas où...
 #
 if (empty($_FILES)) exit;
 if ($_FILES['sendfile']['error'] !== UPLOAD_ERR_OK) exit; # !== not !=
 if ($_FILES['sendfile']['type'] != 'image/jpeg') exit;
 if ($_FILES['sendfile']['size'] <= 0) exit;

 # Le répertoire de destination
 # Le nom donné à l'image reçue
 #
 $udir  = 'my_dir/';
 $ufile = $udir.basename( $_FILES['sendfile']['name']);

 # Pas besoin de tester le résultat... sauf pour le logger
 #
 move_uploaded_file($_FILES['sendfile']['tmp_name'], $ufile);
?>
  • L'image est alors disponible au format jpeg (640x480, 96dpi, 24bits) dans le répertoire my_dir.
  • On pourra nommer les images à sa convenance en modifiant la variable $ufile.
Notes : Les variables transmises au script lors du callback sont les suivantes :

$_POST
filename = snapshot_2011_04_21_22_40_17.jpg
interactiveid = bfe84c04-8396-4b71-953d-3630a6963e2b
correlationid = fb68d2b9-784f-46c7-9e65-0b8252d4097e
uuid = fb68d2b9-784f-46c7-9e65-0b8252d4097e
submit = send

$_FILES
sendfile = Array
name = snapshot_2011_04_09_22_40_17.jpg
type = image/jpeg
tmp_name = /var/log/tmp/phpEZiVvU
error = 0
size = 31445

L'interactiveID récupéré permet alors de faire le lien avec l'utilisateur qui a déclenché la prise de vue.

mercredi 6 avril 2011

Karotz API Web - Tuto de base


API REST Web : Développer une application en mode Web

1 - On passe sur les créations de comptes, accès au lab, etc... acquis à ce stade sur karotz.com.

2 - Créer une application dans le Lab et noter la clé publique de l'appli générée.

3 - Copier et créer le descripteur ci-dessous (cf plus bas descriptor.xml), le zipper avec son fichier screen.xml, charger le tout -bouton "Envoyer le code"-, rendre l'application privée et la tester (acheter et installer sur le kz) -bouton "Tester"-.

Deux tags importants : <deployment> ("external" pour un site web) et <callback> qui indique l'url du site web -le vôtre- qui va récupérer les informations de session interactiveid et installid.

Ne pas oublier de modifier les tags <apikey> et <callback> avec les bonnes informations...

3b - Ftposter le script php de test sur votre serveur (cf plus bas kztest.php).

4 - Dans votre navigateur, allez à http://www.karotz.com/authentication/run/karotz/votre_api_key_récupérée_au_2
C'est aussi ce lien que l'on pourra indiquer sur un site web ou dans un mail.

5 - L'url amène alors sur karotz.com qui requiert une identification -email+pass de son compte Karotz.com-...

6 - ... qui à son tour -après validation de l'identification- renvoie sur l'url de callback saisie dans le descripteur -soit ici http://mon_site_web/kztest.php- AVEC les fameux interactiveID et installID passés en paramètres !

Conclusion : La -grosse- différence avec les Nabz est que désormais il faut s'identifier... fini le temps où il suffisait de coller un "serialnumber/token" dans la requête ! Pour le coup, cela va sembler moins ouvert à certains ;-)) ne serait-ce que pour envoyer un message à son(sa) voisin(e)... A confirmer. Mais beaucoup de possibilités offertes... à nos cla(p)viers !

NB : Après avoir énoncé son texte ou bougé les oreilles, la session peut rester activée -si l'ordre "stop" n'a pas été traité correctement pour une raison quelconque. Le Karotz clignote alors en blanc. Lui cliquer (rapidement) 3 fois sur la tête afin de lui faire reprendre ses esprits... ou attendre 15 minutes -délai actuel du timeout-.

Descripteur descriptor.xml : peut sans doute être réduit, certaines infos n'ayant pas d'intérêt pour une application "externe". Finalement le tag <api_key> n'est pas obligatoire.
 <descriptor> <name>WWW</name>
<apikey>votre_api_key_récupérée_au_2</apikey>
<version>1.0</version>
<accesses>
<access>ears</access>
<access>led</access>
<access>tts</access>
</accesses>
<editor>Bunny</editor>
        <asrName>webapi</asrName>
<deployment>external</deployment>
<interruptible>true</interruptible>
<awake>true</awake>
<callback>http://mon_site_web/kztest.php</callback>
</descriptor>
Paramètres screen.xml
<screen nanoTrigger="false"
permanentTrigger="false"
scheduledTrigger="false"
scheduledDateTrigger="false"
voiceTrigger="false">
<button label="Cliquez-ici pour lancer Mon_Appli..." link="http://www.karotz.com/authentication/run/karotz/votre_api_key_récupérée_au_2" />
</screen>
Script kztest.php
<?php
 # Wizz.cc
 # http://www.karotz.com/authentication/run/karotz/YOUR-APIKEY

 echo 'Referer:'.$_SERVER['HTTP_REFERER'].'<br>';

 $interID = $HTTP_GET_VARS['interactiveid'];
 echo 'interactiveID = ['.$interID.']<br>';
 echo 'installID = ['.$HTTP_GET_VARS['installid'].']<br>';

 # Play with Karotz
 #
 $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);

 # Parler : Quoi de neuf Docteur ?
 curl_setopt($curl, CURLOPT_URL, 'http://www.karotz.com/api/karotz/tts?action=speak&lang=FR&text=quoi%20de%20neuf%20docteur&interactiveid='.$interID);
 $result = curl_exec($curl);
 # Erreur
 if (curl_errno($curl)) { $curl_error = curl_error($curl); echo '<p>Err>&nbsp;'.$curl_error.'</p>'; exit; }

 echo '<hr>';
 $curl_info = curl_getinfo($curl);
 echo '<ul><li>Request time:&nbsp;'.$curl_info['total_time'].' sec.'
. '<li>Request header:&nbsp;'.$curl_info['request_header']
. '<li>Bytes transfered:&nbsp;'.number_format($curl_info['size_download'], 0, '', ' ')
.'</ul>';

 # Decode Xml response from server
 #
 $code = '';
 if ($result!='') try {
   $xml = new SimpleXMLElement($result);
   echo '<p>Speak response:</p><pre>'; print_r($xml); echo '</pre>';
   # Le code retourné
   $code = $xml->response->code;
 } catch(Exception $e) { echo '<b>Error</b>: <font color="red">'.$e->getMessage().' (severity '.$e->getCode().')</font><br>'; }
 echo '<hr>';
 if ($code=='OK') echo '<font color="green">Cool !</font><br>';

 # Bouger les oreilles
 curl_setopt($curl, CURLOPT_URL, 'http://www.karotz.com/api/karotz/ears?left=20&right=-30&interactiveid='.$interID);
 curl_exec($curl);

 # Flash
 curl_setopt($curl, CURLOPT_URL, 'http://www.karotz.com/api/karotz/led?action=light&color=FF00FF&interactiveid='.$interID);
 curl_exec($curl);

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

 curl_close($curl);
?>
Résultat :
Referer:http://www.karotz.com/login
interactiveID = [3a0ce7bc-c169-4266-ab3d-0c51d564d651]
installID = [7319bdb4-169d-4181-8cd4-fea9de4f4e9a]

Request time: 0.395879 sec.
Request header: GET /api/karotz/tts?action=speak&lang=FR&text=quoi%20de%20neuf%20docteur&interactiveid=3a0ce7bc-c169-4266-ab3d-0c51d564d651 HTTP/1.1 Host: www.karotz.com Accept: */*
Bytes transfered: 234

Speak response:
SimpleXMLElement Object
(
    [id] => eb310b17-a77e-4cfb-ad21-a99c114a52eb
    [correlationId] => 2e6fa6a2-f2a8-4795-b20c-c6366c001adb
    [interactiveId] => 3a0ce7bc-c169-4266-ab3d-0c51d564d651
    [response] => SimpleXMLElement Object
        (
            [code] => OK
        )
)