A simple SDK to get your hands dirty with Nabaztag
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Nabaztag Hack Kit

Everything you need to hack the Rabbit: a sinatra server including simple api framework to run custom bytecode on Nabaztag v1/v2. Includes original compiler sources for linux and a modified mac os x version.

Getting Started


The Hack Kit is distributed as a ruby gem. It comes with a simple web server (based on sinatra) which runs out-of-the for connecting you rabbit and distributing the nabaztag bytecode. In addition it includes sinatra helpers/modules to communicate with the rabbit easily. Lastly it provides binaries to compile your own Nabaztag bytecode (see Binaries below).

Simple Server

The Server is the communication endpoint for the rabbit. Its two main purposes are:

  1. serving the bytecode on bootup
  2. receive and respond to HTTP requests in a defined format.


  1. Install dependencies first:
gem install nabaztag_hack_kit

or if you have a Gemfile

bundle install --path=vendor/bundle
  1. Then, create a config.ru file
require 'nabaztag_hack_kit/server'

run NabaztagHackKit::Server.new
  1. Finally, to start and run the server, execute:
bundle exec rackup -p <portnumer>

See examples/ folder for more sophisticated usage.


The kit comes with violet sources and binaries to compile custom Nabaztag bytecode. See folder compiler/. The linux sources are (more or less) the original ones by violet, the mac osx version was created by @ztalbot2000. The compiler binaries are compiled on installation of the gem.

Following three binaries are available:


A wrapper around mtl_comp. Compiles a *.mtl file. It calls mtl_merge before


A wrapper around mtl_simu. Runs a *.mtl file. It calls mtl_merge before


Merges multiple *.mtl files into one. Files are included like in C: #include "<relative path to file>". Output is temporary file .tmp.mtl.


Be sure to checkout mtl_linux submodule first:

git submodule update

To update the kit run:

bundle exec rake build && bundle exec gem install -V pkg/nabaztag_hack_kit-0.1.0.beta6.gem

Understanding the Bytecode

The bytecode is written in a custom language by Sylvain Huet. It is referenced as Metal and files end with .mtl. Unfortunately documentation is very poor (and in french). Check directory bytecode/_original which contains a basic overview & documentation as well as a list of (common) commands. A good reference is the original bytecode, included in the directory as well. Major parts got extracted into seperate files, found in bytecode/lib/ directory and ready to be included in your code.

Grammar: https://docs.google.com/document/d/1KMg2wSyMKTmsilCpOByi_59uk5dD8XMfGAu20W63kZE/edit?hl=en_US


The kit includes a simple test framework to test custom bytecode. See bytecode/test/test.mtl. A typical test looks like this:

 let test "math operations" -> t in
    assert_equalI 0 10 - (2 * 5);

The framework offers assertions similar to Ruby Test::Unit style. Mind that the variable type has to be given explicit. Convention is:

  • I = integer
  • S = string
  • L = list
  • T = table

Following assertions are available (see bytecode/test/helper.mtl)

  • assert_equalI I I
  • assert_equalI S S
  • assert_nil I
  • assert_equalIL
  • assert_equalSL
  • assert_equalTL


As example and for my own purposes I implemented a simple API to deal with RFID, LEDS, BUTTON and EARS easily. (see bytecode/main.mtl)

Input Devices


see my other project NabaztagInjector


Current Button has very basic functionality: a short press send HTTP Request of type Log to server, a long press forces the bunny to restart.

Output Devices

Data for all output devices are stored in buffers. Each device has two: one for onetime, imediate playback, another for permanent loops.


Buffers 0 - 9, where 0-4 are used for onetime, and 5-9 for loop playback.


Buffers 10 - 13, where 10 & 11 are used for onetime, and 12 & 13 for loop playback.


The server part was heavily inspired by Trudy.rb, compiler code copied from OpenJabNab. Thanks!

Nabaztag Background

Read following posting for more background on Nabaztag Hacking (uses google translate:)

Related Projects

New firmware with WPA2

  1. https://github.com/ccarlo64/firmware_nabaztag (see http://nabaztag.forumactif.fr/t15323-firmware-for-wpa-wpa2-test)

  2. https://github.com/RedoXyde/nabgcc https://github.com/RedoXyde/mtl_linux (see http://nabaztag.forumactif.fr/t15280p25-nabaztagtag-en-wpa2)

ServerlessNabaztag -> https://github.com/andreax79/ServerlessNabaztag

CloudServer replace: http://nabaztaglives.com/

Rebuild Nabaztag:


Websocket HowTo:


I'd like to hack the Violet mir:ror too. Some starting points: