tttool - Hello, tiptoi World!

A German site about a tool to create your own content for the Ravensburger tiptoi pen: tttool was brought to my attention a while ago. The Tip-Toi-Reveng Wiki is also a good source of information about the pen.

The description of the corresponding GitHub page entropia/tip-toi-reveng is “Trying to understand the file format of Tip Toi“

Be warned, the tttool site starts:

Attention: The tttool is not an official product of Ravensburger, but developed by independent hobbyists. If it comes to a defect in the Tiptoi pen, then this is bad luck, but still done at your own risk. And anyone selling self-made Tiptoi products is likely to violate a number of patents and other intellectual property rights.

Anyway, I tried to get an example project up and running on a Mac.

The tiptoi tool

Windows releases are available directly from the project page.

For Linux/Mac there are installation instructions available to build tttool from source.

The project is written in Haskell. When building natively on a Mac you need the Haskell Platform installed. With a strong Docker background I decided to use a Docker-based approach for building and running tttool in a non-invasive way on my machine.

Build `tttool` with Docker

We started to build the project inside the official haskell image:

$ docker run -it -v $(pwd):/workspace haskell:8.4.3 /bin/bash
root@856000a85cc2:/# cd workspace
root@856000a85cc2:/workspace# cabal update
…

During the first experiments with tttool, we installed more and more tools for image processing or text-to-speech into this container.

After we were satisfied with our environment we prepared a Dockerfile to create the tttool in a reproducible and platform independent way.

FROM haskell:8.4.3

# Support Text to speech and audio via sox/alsa/pulseaudio
# also installs imagemagick for image manipulation

RUN apt-get update && apt-get install -y \
    espeak \
    vorbis-tools \
    imagemagick \
    sox \
    alsa-utils \
    libasound2 \
    libasound2-plugins \
    pulseaudio \
    pulseaudio-utils \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

ENV HOME /home/tttool
RUN useradd --create-home --home-dir $HOME tttool \
    && usermod -aG audio,pulse,pulse-access tttool \
    && chown -R tttool:tttool $HOME

WORKDIR $HOME
USER tttool

# Download the latest package list from hackage.haskell.org 
RUN cabal update

RUN git clone https://github.com/entropia/tip-toi-reveng.git tttool
RUN cd tttool && cabal install --only-dependencies
RUN cd tttool && cabal build

RUN mkdir /home/tttool/bin
RUN cp ./tttool/dist/build/tttool/tttool /home/tttool/bin

ENTRYPOINT [ "/home/tttool/bin/tttool" ]

Note: The Haskell images 8.4.3 already contain the latest version of libtinfo-dev, the replacement of libncurses5-dev required by tttool.

If you want to interactively follow this post you can easily build your own tttool image from the provided Dockerfile with:

$ docker build . -t tttool

Hello tiptoi World!

Below you can see the Hello, World version of a tiptoi product: hello.yaml.

product-id: 123
media-path: oggs/%s
comment: Hello, TipToi World!
# play welcome sound greeting.ogg
welcome: greeting
scripts:
  entry:
    - P(start) # play sound start.ogg

The sounds are located inside the media-path and use the Vorbis audio compression.

Besides the P command to play sounds we stumbled upon the J command to jump to other labels in later experiments:

command	description
`P(<mediafile>)`	Play media file .ogg
`J(<label>)`	Jump to label

`assemble` and `play`

With the tttool command assemble you can build your first gme archive:

$ docker run -it -v $(pwd):/workspace --workdir=/workspace tttool assemble hello.yaml

The build is successful when no warnings/output is issued to the console. Inside your current working directory, the new file hello.gme has been created with this command.

Before you can play your freshly created tiptoi product inside a Docker container you need to provide a possibility to play sounds on the host.

We described our findings of Running a Docker Soundbox on Mac in another post.

Hint: You’ll only need this “complicated” sound setup when running tttool inside a container.

$ docker run -it -e PULSE_SERVER=docker.for.mac.localhost -v ~/.config/pulse:/home/tttool/.config/pulse -v $(pwd):/workspace --workdir=/workspace tttool play hello.gme

In the play mode, you can simulate the pen input and interactively test your packaged product.

The real thing…pen and paper

Create the OID codes with:

$ docker run -it -v $(pwd):/workspace --workdir=/workspace tttool oid-codes hello.yaml
Writing oid-123-START.png.. (Code 123, raw code 1551)
Writing oid-123-entry.png.. (Code 1229, raw code 17173)

Grab a graphics tool of your choice. (e.g. Gimp) and assemble your prototype.

Tip: In Gimp you can add layers to the current image from new files with <⌥> + <⌘> + o.

Once the graphics are arranged and printed go to the final step… Upload your gme file onto your TipToi pen with the tiptoi Manager and enjoy your “Hello, tiptoi World!”.

That was a lot of fun and learning…