OpenNab : An open PHP-based proxy framework for the Nabaztag™ (http://www.nabaztag.com/) electronic pet.
Copyright c 2007 OpenNab team - http://opennab.sourceforge.net/team/

Nabaztag is a trade mark of Violet. OpenNab is not owned by or affiliated with Violet.


I) Terms of use

This software is provided under a GPL license.
Read the COPYING file for details.

Some audio material is included in OpenNab package.
Except if stated otherwise, this audio material is provided under a Creative Commons 'by-nc-nd' license.
See http://creativecommons.org/licenses/by-nc-nd/2.5/ for details.

OpenNab includes SimpleTest (http://simpletest.sourceforge.net/) in its setup testing phase.
Read /vl/tests/simpletest/README for more information on SimpleTest including licensing issues

HTTP connections are handled by GuinuX Advanced HTTP Client which is included in the OpenNab package
See /vl/includes/http.inc for details about this 3rd party tool.


II) Features

OpenNab is a proxy. It means that connecting to it instead of connecting to the regular nabaztag.com servers does not result in a loss of features because OpenNab forwards the appropriate requests to nabaztag.com.

OpenNab allows Nabaztag users to get additional services which are NOT relying on the nabaztag.com platform. For instance, you could even use the Nabaztag on a local network with no internet connection.

OpenNab is composed of 2 distinct parts :
1) a core system performing the data passthrough + encoding/decoding and providing an extensible plugin/api framework.
2) a set of plugins.

This version of OpenNab includes the following plugins:
- 'ambient' plugin for customizing the "ambient" information displayed by the Nabaztag (lights on the bunny belly, ears position, blinking nose)
- 'asleep' plugin for setting the bunny in asleep/wake up modes
- 'dice' plugin to use the Nabaztag as a dice when playing board games.
- 'helloworld' sample for plugin developers
- 'message' plugin for testing the Nabaztag built-in message syntax.
- 'myradio' plugin to use the bunny as a multi-channel ear-controlled radio receiver.
- 'myweather' plugin to get custom weather information displayed and announced by the bunny.
- 'pinginterval' plugin to change the frequency of bunny ping.
- 'plsm3u' plugin to natively read mp3 streams in 'pls' and 'm3u' formats.
- 'quietears' plugin to suppress the ear rotating movement on each incoming message.
- 'quizz' plugin to play a quizz game : find correct answers to questions asked by Nabaztag.
- 'recordaudio' plugin to record the audio data of each voice recognition sequence into a wave file.
- 'reboot' plugin to force a reboot of the bunny.
- 'saveboot' plugin to make a backup of the bunny bytecode downloaded at bunny's boot.
- 'simpleplay' plugin for playback of local mp3 files or internet mp3 streams.
- 'language' plugin for setting the language (en or fr) used by other plugins (dice, quizz, ...)
- 'tts' plugin for sending text-to-speech commands
- 'audiorecordbypass' plugin for retrieving audio data of each voice recognition sequence in client application
- 'broadcache' plugin for caching remote media files.
- 'mood' plugin plays a random mp3 at random intervals
- 'downtime' plugin monitors the bunnies ping to compute their downtime.
- 'rfidsniff' plugin gets the tag id for the last sniffed rfid tag.
- 'rfid2http' plugin associate a rfid tag to a http call.

See readme files in the /vl/plugins folder for additional information on each plugin such as copyright, detailed features and API.

An API demo web page allows to use the standard set of plugin API features without writing a single line of code.
Just go to http://my.domain.com/vl/api_demo/ (where my.domain.com is the web site on which OpenNab is installed)


III) Requirements

- A Nabaztag/tag (OpenNab does not work with first version of Nabaztag, the one with no navel)
- An Apache server (use of .htaccess files with ErrorDocument directive) with PHP scripting (tested on PHP4.4.3)


IV) Installation

  a) Drop all files into a web server folder.
     This folder must the root of a domain or subdomain (e.g. my.domain.com)
		 
  b) Make sure that folders are not write protected.
     OpenNab needs to write files in folders : /vl/burrows, /vl/logs, /vl/plugins/*/files
     If you use a FTP client application such as FileZilla to install OpenNab, you can righ-click on a remote item and select 'File attributes...' to change permissions.
		 
  c) With any webbrowser, go to http://my.domain.com/vl/foobar
     It should display : 'ERROR 404 from OpenNab'. Some web browsers (e.g. Internet Explorer might need some changes in configuration options to display the actual error message)
		 If not, you have an issue with Apache configuration (ErrorDocument feature in .htaccess is not available).
		 You must sort it out before going further.
		 
	d) With any webbrowser, go to http://my.domain.com/vl/tests/
	   You should see a green status with all tests passed.
		 If not, you have a PHP issue. OpenNab code does not work on your PHP configuration.
		 If you get errors with either PHP 4.4.x or 5.2.x, ask on Nabaztag help forum http://sourceforge.net/forum/forum.php?forum_id=654766
		 If you get errors with another PHP version, this is normal. You must upgrade your PHP install.
		 
	e) With any webbrowser, go to http://my.domain.com/vl/bc.jsp?v=0.0.0.10&m=xx:xx:xx:xx:xx:xx&l=00:00:00:00:00:00&p=00:00:00:00:00:00&h=4
			You should get a weird text page starting with word 'amber'.
			If you have nothing or a PHP error, proceed as in c) : check your PHP version and eventually ask for support.
		 
	f) If all previous steps are ok, proceed with the bunny configuration
		 Configure the Nabaztag/tag to use 'my.domain.com/vl' in advanced settings during initial bunny set-up procedure (http://help.nabaztag.com/fiche.php?fiche=45)
		 
		 Beware : OpenNab is not tied to a given bunny. It means that you do not have to configure it with a serial number or anything. It also means that any Nabaztag who knows your web address can connect to your own OpenNab.
     
     The /vl/check_install.html can be used for testing the various links in steps (b), (c) and (d).


V) Support

OpenNab is currently an hobby open source project : that says it all regarding the support you can get for this software.

A good idea is to participate in the Nabaztag community forums.
These are the places where you might get help from other OpenNab users :
- http://nabaztag.forumactif.fr/ for French speaking community.
- http://www.nabaztalk.com/forum/ for English speaking community.

Pieces of documentation in French are also available at http://wikinab.org/

If you do not feel like joining these communities, just use the sourceforge OpenNab help forum http://sourceforge.net/forum/forum.php?forum_id=654766


VI) Upgrades

Migrating from OpenNab 0.08 or 0.07

Just replacing the files should be ok.
Backward compatibility is provided for existing API so that no change should be necessary to external applications


Migrating from OpenNab 0.06 :

If you want to keep your current custom configuration, you must manually transfer your settings in the opennab.ini file. From now on, it is advised to store the personal settings in a /vl/config/xxxxxxxxxxxx.ini file where xxxxxxxxxxxx is the serial number.

If you want to keep your existing plugin files (mp3 files for 'simpleplay', bootcode files from 'saveboot', ...) you must manually move them to the folders in the new plugin hierarchy


VII) History

2007-11-02  v0.09  No longer needs cURL (replaced by php native http client library). OpenNab connections to Violet servers can use an http proxy. Serial number in API can be replaced by a bunny name. RFID support (rfidsniff and rfid2http plugins). Other new plugins : broadcache, mood, downtime.
2007-10-09  v0.08  3rd party Text-to-speech systems integration. Plugin tts mimics Violet's tts API. Plugin AudioRecordBypass allows client applications to process audio data. New API demo user interface. Each plugin can define custom parameters in .ini files. Log files global or one for each bunny.
2007-09-28  v0.07  Cron system with OnCron plugin callback. OnPingForward default behaviour is to call detailed callbacks (OnSingleClick, etc.) MyWeather plugin automatically updates from URL. Language plugin to globally define the language used by plugins. Change in plugin hierarchy (one folder for each plugin). One .ini file for each bunny for settings override.
2007-03-01  v0.06  New plugins : asleep, quietears and quizz. Configuration in .ini file. Demo should now work fine when PHP 'register_globals' is off.
2007-02-10  v0.05  Three new plugins : plsm3u, pinginterval and reboot. Miscellaneous bugs fixes. Now should work fine with any level of PHP error reporting.
2007-02-03  v0.04  Major redesign of the software into a plugin architecture. Full 0a message encoding/decoding. Standalone mode to run the software with no other server connection. New applications through the use of plugins : mp3 streaming, ear-controlled radio, custom weather definition, dice rolling.
2007-01-27  v0.03  Ambient override, various bug fixes (speech recognition audio recording, case sensitivity of serial number), enhanced logs, direct connection to original server by configuration.
2007-01-20  v0.02  MP3 audio playback, HTTP API, analysis tools, burrows.
2007-01-15  v0.01  Initial revision. Merely a proxy hack to analyze the exchanged data.