Docs For Class Services

Services_Nabaztag

Description

Services_Nabaztag

The Nabaztag object is used to communicate with the Nabaztag. You only have to create this object once; you can use it for many requests. Use your Nabaztag serial number and API token when creating the object. You can get your API token at http://www.nabaztag.com/

Example:

$nabaztag = new Services_Nabaztag("010203040506", "1234567890");
$nabaztag->say("Hello World!");

Located in /Nabaztag.php (line 87)

Variable Summary

array $apiErrorMessages

array $apiSuccessMessages

string $apiURL

boolean $debug

string $defaultPitch

float $defaultSpeed

integer $defaultTTL

string $defaultVoice

string $error

string $idApp

boolean $inTransaction

array $request

string $response

string $serial

string $token

Method Summary

Services_Nabaztag __construct ([string $serial = null], [string $token = null], [string $idApp = null])

boolean apiRequest ()

string apiRequestSave (array $request)

boolean commitTransaction ()

boolean dance (string $choreography, [string $title = ""])

array getBlackList ()

array getEars ()

string getError ()

array getFriendList ()

array getInbox ()

string getName ()

array getSelectedLanguages ()

string getSignature ()

string getTimeZone ()

string getVersion ()

array getVoices ()

boolean initialized ()

boolean isSleeping ()

boolean playMessage (integer $messageId)

boolean recordNabcast ( $nabcastId, $nabcastTitle, string $message)

boolean say (string $message, [string $voice = false], [float $speed = false], [integer $ttl = false], [float $pitch = false])

void setDebug ([boolean $debug = true])

boolean setEars ([integer $leftPos = 0], [integer $rightPos = 0])

void setError (boolean $message)

boolean setSleep (boolean $state)

boolean sleep ()

boolean startTransaction ()

boolean wakeUp ()

Variables

array $apiErrorMessages = array(
"NOGOODTOKENORSERIAL", /* Serial number or API token not valid */
"NOTAVAILABLE", /* The action is temporarily not available */
"ABUSESENDING", /* Too much message sending,try later */
"MESSAGENOTSENT", /* Your message id is not correct or is private */
"NABCASTNOTSENT", /* Your nabcast id is not correct or is private */
"TTSNOTSENT", /* Your text could not be sent */
"CHORNOTSENT", /* Your chor could not be sent (bad chor) */
"EARPOSITIONNOTSENT", /* Your ears command could not be sent */
"WEBRADIONOTSENT", /* Your webradio could not be sent */
"NOCORRECTPARAMETERS", /* Please check urlList parameter ! */
"NOTV2RABBIT", /* V2 rabbit can use this action */
) (line 142)

Array of regexps that, when received from the API in the MESSAGE tag, signify an error from Nabaztag.com's servers.

access: protected

array $apiSuccessMessages = array(
"tts" => "TTSSENT",
"posleft" => "EARPOSITIONSENT",
"posright" => "EARPOSITIONSENT",
"ears" => "POSITIONEAR",
"idmessage" => "MESSAGESENT",
"chor" => "CHORSENT",
"nabcast" => "NABCASTSENT",
"webradio" => "WEBRADIOSENT",
"_setSleep" => "COMMANDSENT",
) (line 163)

Associative array of parameter => regexp. When we send the parameter, we expect the regexp in the MESSAGE tag. If it is not received, we assume that the command has been unsuccessful.

access: protected

string $apiURL = "http://api.nabaztag.com/vl/FR/api.jsp" (line 134)

Default URL for Nabaztag.com API. This has changed in Nabaztag API 2.0.

access: protected

boolean $debug = false (line 241)

True if setDebug() has been called; we will echo debug information when doing an API request.

access: protected

string $defaultPitch = 1 (line 127)

Default pitch for Text-To-Speech messages created with say(). As of 2006-12-27, this does not seem to alter the pitch but instead alters the speed.

access: protected

float $defaultSpeed = 1 (line 109)

Default speed for Text-To-Speech messages created with say(). Higher is faster. A speed of 1 is normal, 0.5 is half speed, 2 is double speed.

access: protected

integer $defaultTTL = 3600 (line 101)

Default time-to-live (TTL) of the Text-To-Speech messages created with say(), in seconds. After this time, the messages are automatically deleted from the Nabaztag owner's web interface.

access: protected

string $defaultVoice = "" (line 118)

Default voice for Text-To-Speech messages created with say(). According to Nabaztag.com's documentation, voice "heather22k" is used for English rabbits and voice "claire22s" for French rabbits.

access: protected

string $error = null (line 207)

Message from the last error.

access: protected

string $idApp = null (line 200)

API "idapp" number. Reserved for future use by Nabaztag.com API. These numbers might be given out by nabaztag.com to specific users.

access: protected

boolean $inTransaction = false (line 214)

True whenever we are in a transaction started with startTransaction().

access: protected

array $request = array() (line 225)

Cache of all the requests that we will send to the Nabaztag API in transaction mode.

This is an associative array of parameter => value. All these parameters and values are appended to the URL when Nabaztag.com is contacted.

access: protected

string $response = null (line 233)

Cache of the response. We set this in apiRequest(), but we could use it later, for instance in getEars() and for debugging.

access: protected

string $serial = null (line 185)

Serial number of the Nabaztag rabbit (equal to the MAC address without the ":" characters).

access: protected

string $token = null (line 192)

API token of the Nabaztag rabbit (get this at http://www.nabaztag.com/)

access: protected

Methods

Constructor __construct (line 459)

Constructs a Nabaztag control object for users with a Nabaztag.com "idapp" number.

As the third argument of the constructor, you can optionally specify an "idapp" number for your application. This seems to be a future Nabaztag.com parameter. As of 2006-12-27, you can omit this argument.

Example:

$nabaztag = new Services_Nabaztag("010203040506", "1234567890", 123);

access: public

Services_Nabaztag __construct ([string $serial = null], [string $token = null], [string $idApp = null])

string $serial: Your Nabaztag's serial number, usually the MAC address without ":" characters
string $token: Your Nabaztag API token. You must request this at http://www.nabaztag.com/vl/action/gererAPI.do
string $idApp: The Nabaztag "idapp" number for your application. You probably do not need this.

apiRequest (line 274)

Perform a single API call to Nabaztag.com.

This call is made whenever a transaction is carried out with commitTransaction() or whenever a command such as say() is issued directly.

Throws Services_Nabaztag_Exception whenever a fatal error is encountered. This can either be a communication error (e.g. Nabaztag server down), or an error from Nabaztag.com (invalid serial number, invalid input, et cetera).

return: True if all the requested commands have been successful.
access: protected

boolean apiRequest ()

apiRequestSave (line 420)

Saves the currently buffered transaction requests, performs a request $request, and restores the current transaction.

Note: This function preempts any possible running transactions by saving the old request state ($this->request) and restoring it afterwards. It is used for getting status information (requiring a call to the API) while the user is currently busy filling a transaction.

return: Return string
todo: It would be more logical to have apiRequest call this function (call it apiRequestRaw), instead of the other way around.
access: protected

string apiRequestSave (array $request)

array $request: Associative request array (parameter => value)

commitTransaction (line 578)

End a transaction and send the pending commands to the Nabaztag.

The Nabaztag class can combine multiple commands (like say()) in one API request. Using this will save HTTP calls and processing time on Nabaztag's servers.

To use this, simply group your commands between $nabaztag->startTransaction() and $nabaztag->commitTransaction(). If you do this, you MUST always end with a commitTransaction().

Example:

$nabaztag = new Services_Nabaztag("010203040506", "1234567890");
$nabaztag->startTransaction();
$nabaztag->say("Hello World!");
$nabaztag->say("And more text.");
$nabaztag->setEars(12, 12);
$result = $nabaztag->commitTransaction();

return: True if all the commands have been sent successfully; false if one or more commands failed.
access: public

boolean commitTransaction ()

dance (line 608)

Send a dance ("choreography") to the Nabaztag, changing the LEDs and ears of the Nabaztag in a specified pattern.

For a description of the choreography format, please refer to the Nabaztag API documentation at: http://www.nabaztag.com/vl/FR/gfx/2/Documentation%20API-revA001_uk.pdf

Example:

$nabaztag = new Services_Nabaztag("010203040506", "1234567890");
$result = $nabaztag->dance("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");

return: True if the dance has been successfully sent.
access: public

boolean dance (string $choreography, [string $title = ""])

string $choreography: Script for the dance in Nabaztag API format.
string $title: Optional title for the dance as specified by Nabaztag API.

getBlackList (line 1046)

Returns a list of blacklisted rabbits for this rabbit.

return: Array of blacklisted rabbit names
access: public

array getBlackList ()

getEars (line 822)

Get the current position of the Nabaztag's left and right ear.

Will return an associative array of the left and right values, which are integers in the range 0-16.

Please see the documentation on setEars() for more information about position values.

Example:

$nabaztag = new Services_Nabaztag("010203040506", "1234567890");
$ears = $nabaztag->getEars();
echo "Left ear is at {$ears[left]} and right ear is at {$ears[right]}";

return: Associative array $result with integer 0-16 values in $result["left"] and $result["right"]
access: public

array getEars ()

getError (line 500)

Provides a descriptive error message in case a problem has occurred.

If an error has occurred (signified by a 'false' result from a function), you can retrieve a descriptive error message by calling getError().

Note that the Nabaztag class now uses exceptions as well. On every error, a Services_Nabaztag_Exception is thrown. You can also read the message from the exception.

Example:

if (!$nabaztag->say("Hello")) {
echo "An error occurred: " . $nabaztag->getError();
}

return: The full error message.
access: public

string getError ()

getFriendList (line 1028)

Returns a list of the friend names for this rabbit.

return: Array of friend rabbit names
access: public

array getFriendList ()

getInbox (line 1010)

Returns the messages in the inbox.

Example:

$messages = $nabaztag->getInbox();
foreach ($messages as $message) {
echo "Message from {$message->from}, {$message->date} with title {$message->title} and url {$message->url}\n";
}

Example output: Message from Slartibartfast, today 01:27:13 with title Testing! and url broad/001/154/461/401.mp3

return: Array of SimpleXMLElement objects with properties ->from, ->date, ->title and ->url
access: public

array getInbox ()

getName (line 911)

Returns the configured name of the rabbit.

return: Name of the rabbit
access: public

string getName ()

getSelectedLanguages (line 1064)

Returns the current list of selected languages for the rabbit.

return: Array of language codes ("de", "uk", etc.)
access: public

array getSelectedLanguages ()

getSignature (line 943)

Returns the configured signature of the rabbit which will be added to text messages sent through the API.

This is a string in the form "cdll=long,3,none,broad/config/signature/HarpeGlisse.mp3, 0,7,0,led,4,255,0,255,1,led,4,0,0,0,2,led,4,255,0,255,3,led,4,0,0,0,4,led,4,255,0,255, 5,led,4,0,0,0,6,led,4,255,0,255,7,led,4,0,0,0,8,led,4,255,0,255,9,led,4,0,0,0,10,led, 4,255,0,255,11,led,4,0,0,0" (without newlines or spaces).

return: Signature of the rabbit
access: public

string getSignature ()

getTimeZone (line 924)

Returns the configured timezone of the rabbit.

return: Timezone of the rabbit
access: public

string getTimeZone ()

getVersion (line 898)

Returns the version string of the rabbit, which determines if the rabbit is a Nabaztag ("V1") or a Nabaztag/tag ("V2").

return: Version description string; "V1" for Nabaztag, "V2" for Nabaztag/tag
access: public

string getVersion ()

getVoices (line 858)

Returns an associative array of allowed voices => languages that are recognized by Nabaztag.com API.

One of these voices can be supplied as the second parameter to say().

Example:

$nabaztag = new Services_Nabaztag("010203040506", "1234567890");
$voices = $nabaztag->getVoices();
$randomVoice = array_rand($voices);
$nabaztag->say("Hello world!", $randomVoice);

return: Associative array of voice => language
access: public

array getVoices ()

initialized (line 511)

Returns true if and only if the Nabaztag object has been constructed correctly with Nabaztag serial number and token.

return: True if the Nabaztag object is initialized and ready.
access: public

boolean initialized ()

isSleeping (line 883)

Checks if the rabbit is sleeping.

Sleep times can be defined in the nabaztag.com control panel. The rabbit can also sleep when sleep() is called.

return: true if the rabbit is currently sleeping, false if it is awake
see: Nabaztag::sleep
todo: Check if @see works correctly in phpdoc
access: public

boolean isSleeping ()

playMessage (line 716)

Let the Nabaztag play back a stored message with a certain messageId.

The messageId is the number of the message on Nabaztag.com. The messageId can refer to one of the messages in the library, or an mp3 file that was uploaded to my.nabaztag.com.

Example:

$nabaztag = new Services_Nabaztag("010203040506", "1234567890");
$result = $nabaztag->play(123);

return: True if the play request has been successfully sent.
access: public

boolean playMessage (integer $messageId)

integer $messageId: Number of the message stored on Nabaztag.com.

recordNabcast (line 746)

Create a Nabcast from the text message sent.

Currently, this can only be used from within a transaction. All the say() commands during the transaction will be sent as the Nabcast.

Example:

$nabaztag = new Services_Nabaztag("010203040506", "1234567890");
$nabaztag->startTransaction();
$nabaztag->recordNabcast(12345, "mynabcast");
$nabaztag->say("Hello world!");
$result = $nabaztag->commitTransaction();

return: True if the Nabcast request has been successfully sent.
access: public

boolean recordNabcast ( $nabcastId, $nabcastTitle, string $message)

string $message: The text to say. There is no maximum length specified; however, there may be delivery problems with very long messages.
$nabcastId
$nabcastTitle

say (line 643)

Send a text to the Nabaztag, which will be spoken using Text-To-Speech.

Possible languages for the Text-To-Speech are English and French, depending on the language chosen by the Nabaztag API user on the nabaztag.com site.

Example:

$nabaztag = new Services_Nabaztag("010203040506", "1234567890");
$result = $nabaztag->say("Hello World!", "graham");

return: True if the text message has been successfully sent.
access: public

boolean say (string $message, [string $voice = false], [float $speed = false], [integer $ttl = false], [float $pitch = false])

string $message: The text to say. There is no maximum length specified; however, there may be delivery problems with very long messages.
string $voice: The type of voice as specified by Nabaztag API. Allowed voices can be found in allowedVoices.
float $speed: The speed of the voice; higher is faster. 1 is the default speed; 0.5 is half speed; 2 is double speed.
integer $ttl: The time, in seconds, that the message will be retained on the nabaztag.com site. Defaults to 3600 seconds (one hour).
float $pitch: The pitch of the voice. 1 is the default pitch; 0.5 is half pitch (lower); 2 is double pitch (higher). As of 2006-12-28, this parameter seems to affect the speed instead of the pitch.

setDebug (line 479)

Enable debug mode, in which extra output is printed about the request and response.

Note: Using debug mode could print sensitive output. Don't use this on a public website.

Example:

$nabaztag->setDebug();

access: public

void setDebug ([boolean $debug = true])

boolean $debug: Omit or set true to enable debugging. Set to false to disable it again.

setEars (line 786)

Set the position of the Nabaztag's ears.

The position is specified by two integers (left ear and right ear) in the range 0-16.

Note: The same numbers of the left and right position do not seem to correspond to the same physical ear directions. On the author's Nabaztag, for instance, calling $nabaztag->setEars(8, 0) will move both ears fully into the "up" position, while $nabaztag->setEars(12,4) moves both ears forward. According to the Nabaztag.com documentation (0, 0) is "ear horizontal".

Comments and experiences with setting ear positions are welcome. After gathering more experiences, perhaps a symbolic input like $nabaztag->setEars("up", "up") could be considered for a future version.

Example:

$nabaztag = new Services_Nabaztag("010203040506", "1234567890");
$nabaztag->setEars(8, 4);

return: True if the ear positions have been successfully sent.
access: public

boolean setEars ([integer $leftPos = 0], [integer $rightPos = 0])

integer $leftPos: Position of the left ear (value from 0 to 16).
integer $rightPos: Position of the right ear (value from 0 to 16).

setError (line 250)

Set the error value. This throws a Services_Nabaztag_Exception.

You can retrieve the error value later with getError().

access: protected

void setError (boolean $message)

boolean $message: True if the error has been set. (Currently always true.)

setSleep (line 958)

Sets the sleep state of the rabbit.

return: True if the command was sent successfully
access: public

boolean setSleep (boolean $state)

boolean $state: True to let the rabbit sleep, false to wake the rabbit up

sleep (line 977)

Lets the rabbit sleep.

Same as $nabaztag->setSleep(true).

return: True if the command was sent successfully
see: Nabaztag::setSleep
access: public

boolean sleep ()

startTransaction (line 545)

Start a transaction (batch for multiple commands).

The Nabaztag class can combine multiple commands (like say()) in one API request. Using this will save HTTP calls and processing time on Nabaztag's servers.

To use this, simply group your commands between $nabaztag->startTransaction() and $nabaztag->commitTransaction(). If you do this, you MUST always end with a commitTransaction().

Note 1: All say() commands in one transaction use the same speed and voice. The first speed or voice parameters will be saved and used for all say() commands.

Note 2: You can only use one dance() in a transaction; these commands can not be combined.

Example:

$nabaztag = new Services_Nabaztag("010203040506", "1234567890");
$nabaztag->startTransaction();
$nabaztag->say("Hello World!");
$nabaztag->say("And more text.");
$nabaztag->setEars(12, 12);
$result = $nabaztag->commitTransaction();

return: True if the transaction has been started.
access: public

boolean startTransaction ()

wakeUp (line 990)

Lets the rabbit wake up from sleep.

Same as $nabaztag->setSleep(false).

return: True if the command was sent successfully
see: Nabaztag::setSleep
access: public

boolean wakeUp ()

Documentation generated on Mon, 07 Apr 2008 01:56:33 +0200 by phpDocumentor 1.4.1