Nabaztag Hack Kit

A complete MTL firmware and SDK for the Nabaztag v1/v2 IoT rabbit — including a dockerized toolchain, a reusable MTL standard library, a Forth interpreter, and a full application stack for WiFi, audio, RFID, LEDs, and ears.

Getting Started

The only host requirements are Docker and Task. Every build runs inside Docker — no toolchain to install locally.

Architecture

The project is split into three components: a toolchain and build system (tools/), a reusable standard library (lib/), and applications which integrates those. These are either the initial boot image (src/boot/), or main applications (src/app-**) loaded from remote.

 ┌─ Layer 3  Forth scripts (vl/*.forth)        edit-at-runtime, REPL      ← nabaztag-piper/vl
 │              ▲ interpreted by
 ├─ Layer 2  MTL app  (src/app-**/*.mtl)       incl. a Forth interpreter  ← nabaztag-piper/firmware
 │           + MTL stdlib (lib/*.mtl)          written in MTL             ← mtl_library/lib
 │              ▲ compiled to bytecode by
 │           MTL toolchain (mtl_comp/simu)     host-side                  ← nabgcc(mtl_linux)
 │              ▲ remotely loaded by
 ├─ Layer 1  MTL Boot app  (src/boot/*.mtl)    written in MTL             ← mtl_library/lib
 │              ▲ compiled to bytecode by
 │           MTL toolchain (mtl_comp/simu)     host-side                  ← nabgcc(mtl_linux)
 │              ▲ is packed with and runs on
 └─ Layer 0  C bytecode VM + drivers + WPA2    bare-metal ARM7TDMI        ← nabgcc  (origin: firmware_nabaztag)
              flashed once to Oki ML67Q4051

Directory Layout

docs/                Grammar, commands, hardware notes
lib/                 Reusable MTL standard library
src/app-piper/       Main application (Forth interpreter, audio, RFID, LEDs, ears, networking)
src/boot/            Boot/provisioning image
src/firmware/        C firmware (VM, HAL, USB, audio)
tools/mtl_linux/     Dockerized MTL compiler and simulator
tools/preprocessor/  Dockerized C preprocessor for MTL (pcpp-based)
tools/mkfirmware/    Dockerized firmware packaging tool (.bin → signed .sim)
tools/openocd/       JTAG debrick configs (Raspberry Pi + FTDI)
test/                MTL unit tests (lib/ coverage)
CHANGELOG.md         SDK-side changes, tagged by source area, so a diff can be cherry-picked back

Toolchain and build system - tools/

Run task --list to list all targets.

Compile & Simulate

Run the fwV1 test suite:

task verify

Run the fwV2 test suite:

task verifyV2

Standard Library - lib/

Each layer depends only on layers below it. The dependency rule is strict: nothing in lib/ may reference hardware, WiFi, or app-specific state.

Layer	Modules	Dependencies
0 — Utilities	`integer.mtl`, `string.mtl`, `list.mtl`	none (MTL built-ins only)
1 — Types	`protos/sock_protos.mtl`, `protos/forth_protos.mtl`, `protos/word_protos.mtl`, `protos/ascii_protos.mtl`	none
2 — Encoding	`b64.mtl`, `url.mtl`, `json.mtl`, `net.mtl`, `md5.mtl`	Layer 0
3 — Network	`sock.mtl`, `http_server.mtl`	Layers 0–2
4 — Hardware	tbd.	tbd.
5 — Forth	`forth.mtl` + `forth/*.mtl`	Layers 0–2 only

lib/forth sits at Layer 5 I/O is wired by the caller through two callbacks stored in the interpreter state:
write_fn — output callback; called by the interpreter whenever it needs to write a string. Set to nil to buffer output in f.output instead.
readline_cb — pending-read callback; set by READ-LINE when the interpreter suspends waiting for a line. The transport layer delivers input by calling f.readline_cb input and clears this field.

This keeps the interpreter transport-agnostic. A socket-backed REPL, an HTTP-triggered script, and a task-spawned evaluation all use the same interpreter code with different write functions.

src/boot/ — Boot Image

The boot image handles WiFi provisioning (serves a captive-portal config page) and OTA firmware upgrades. It does not include lib/ — it has its own minimal HTTP and TCP stack to keep the flash footprint small.

┌─────────────────────────────────────────────────────────┐ │ src/boot/ Boot image │ │ ─ config server WiFi provisioning UI │ │ ─ firmware OTA firmware upgrade │ └─────────────────────────────────────────────────────────┘