An Availabot-like computer-controlled push puppet for Linux

An Availabot-like computer-controlled push puppet for Linux

by Pierre-Philippe Coupard

What is it?

This little project was inspired by the Availabot from Schulze and Webb (http://schulzeandwebb.com/2006/availabot/). The Availabot is a puppet guy that rises to its feet when a friend comes online on IM, and falls over when the friend disappears. It's a cool little toy, but it has 3 shortcomings:

It isn't in production yet

It apparently won't work with Linux

The puppet guy looks menacing, although I understand it will be customizable

But the Availabot is obviously only a push puppet with a servo. So it's easy to make a similar device with a push puppet of your liking.

You can download complete instructions and software to make this cute toy yourself and use it with Xchat or Gaim here: push_puppet_toy-0.0.5.tar.gz

I - Making the hardware

To make the device, you first need a push puppet. A push puppet is a small articulated character composed of several body parts held together by several strings that run through them under tension. The strings are all connected to a large spring-loaded button under the base. When the button is pressed, the strings go slack and the puppet collapses. When the button is released, the strings pull the puppet back to its normal erect shape. More information on push puppets can be had at http://www.pushpuppets.com/. Push puppets are cheap toys for small children, and can be found at most serious toy stores. Mine is a wooden dog from the "farm animals" series, made by Toys Pure. I paid 2.77€ for it and I find it much cuter than the Availabot guy. What's more, it doesn't "drop dead" like the Availabot guy when the button is pushed, but instead drops its head and bows its knees, which I find nicer.

You will also need a servo : it should be strong enough to push the base of the push puppet. Mine's a Protech B112, which provides a torque of 2.5kg.cm and doesn't cost too much. The spring in my push puppet pushes about 2kg and the button needs to move about 1cm, so the B112 is about right, although it does tend to strain a bit.

You will also need the following components to make the servo control circuit:

1 x 16F628A

1 x MAX232

1 x 4N33

1 x LM7805

1 x LM7806

1 x crystal 4MHz

1 x 1N4004

2 x 1N4148

1 x 47uF cap

1 x 10uF cap

4 x 1uF cap

2 x 0.1uF cap

2 x 4.7pF cap

1 x 12kohm resistor

2 x 1kohm resistor

1 x female DB9 connector

1 x 9V to 12V, 1A wall wart

perfboard, wiring, etc...

The 16F628A is a PIC microcontroller from Microchip. It requires a PIC programmer to burn the program into it. If you already have one, chances are you already know about PICs. If you don't, add one to your shopping list or make your own from one of the numerous plans out there on the internet and discover the fun of PIC programming. I personally use the Velleman K8048 (http://www.vellemanusa.com/us/enu/product/view/?id=500373) which is cheap, good quality, provides an ICSP (in-circuit) programming socket, and happens to work okay with Linux. All the other components are standard and easy to find. Here is the schematic for the controller circuit:

Finally, you will want a sturdy box that looks good on the outside to serve as a base for the push puppet, that will contain the circuit board, and the servo mechanism. For the mechanism, you're on your own, it depends on your box and your abilities with a hacksaw and a Dremel. My mechanism is housed in a 115mmx90mmx55mm polished aluminum box, and is basically a large piece of pipe that goes through the entire box, that the servo pushes up by pulling the base of with a simple linkage. The push puppet is fixed on the top cover of the box and the pipe pushes the button up when the servo rotates 180 degrees.

Check out the video and photos of my mechanism:

II - Building the software

Four pieces of software are supplied:

The firmware for the 16F628A on the controller board

An Xchat plugin that drives the puppet up and down when a friend joins or leaves a channel on IRC

A Gaim plugin that drives the puppet up and down when one or more buddies are signed on or off

A Pidgin plugin: Pidgin is the new name of the Gaim project since version 2.0.0, but the Gaim version of the plugin won't work as-is, so a Pidgin-specific plugin is built

To build them, type "make". You will need the GNU PIC Utilities to build the firmware (http://gputils.sourceforge.net/), and the Gaim or Pidgin development files (or package if your Linux distribution has it, like Debian) to build either the Gaim or Pidgin plugin. If you have Gaim installed, the Gaim version of the plugin is built. If you have Pidgin installed, the Pidgin version is built instead.

III - Installing and configuring the plugin(s)

Simply type make install. By default, the XChat plugin is installed in the ~/.xchat2/ directory, the Gaim plugin is installed in the ~/.gaim/plugins/ directory, and the Pidgin plugin in the ~/.purple/plugins/ directory.

To tell the plugin(s) which serial port your puppet is connected to, create a configuration file in your home directory called ~/.ppwrc containing a single line with the name of the serial device (for example "/dev/ttyS0"). Finally, start (or restart) Xchat, Gaim or Pidgin to enable the corresponding plugin.

IV - Programming the PIC

To program the 16F628A, you will need the pkp utility, part of the pikdev package (http://pikdev.free.fr/). if you use the Velleman K8048 programmer, simply connect your 16F628A to the board or your ICSP cable to your servo control board, connect the K8048 to your /dev/ttyS0 and type "make flash". If you use another programmer, you will have to modify the supplied .pkprc file to match your programmer's characteristics. You will also need to modify this file if your programmer is connected to another serial port.

If the programming operation doesn't seem to work, you can type make verify to compare the content of the PIC's flash memory with the firmware file.

If you want to take a peek at the firmware code without downloading the tarball, here is is: pushpuppet.asm. It can be easily adapted to be a generic servo controller: it is fully interrupt-driven and has an internal servo calibration menu.

V - Configuring the control board

No two servos are exactly alike, so you need to configure the controller for the "puppet up" and "puppet down" servo positions. To do this, connect your controller board to a serial port, start a terminal program like minicom, fire up the board and immediately send ENTER to the board (you have one second to do this). Upon receiving ENTER at startup time, the board goes into configuration mode and the terminal program displays this:

(P)WM period: 0x4E20 <-- (U)p position duty cycle: 0x0148 (D)own position duty cycle: 0x080C +/- to adjust (S)ave (Q)uit

From there you can modify the servo control signal's PWM period and duty cycles from both the "up" and "down" positions. You shouldn't need to modify the PWM period, it's normally 20ms (20000us == 0x4E20). Pressing U or D puts the servo in "up" or "down" position respectively, and you can then use + or - to lengthen or shorten the control pulse, effectively adjusting the selected position. Once you have adjusted the servo to have full throw (180 degrees) between "up" and "down" without going off scale (you will quickly know if a position is off limit: the servo will make worrying noises as it tries to maintain a position it can never reach), hit S to save the settings into EEPROM and either hit Q to quit or cycle the power. You can touch up the settings by re-entering the setup menu with ENTER later if you need to.

During normal operation, the board simply waits for "U" or "D" to be sent to the serial port. When it receives "U", it puts the puppet up. Similarly, when it receives "D", it puts the puppet down. When it's done, it sends back "OK".

Note that if you don't have a free serial port, it's perfectly possible to connect the puppet to a USB port with the help of a USB-to-RS232 dongle that's supported by Linux: the serial device is then usually called "/dev/ttyUSB?".

VI - Using the Xchat plugin

When XChat starts, it should display "PPW loaded successfully!". To use the plugin, you need to add friends to the nick list: to do this, type "/ppw add nick #channel" for each nick you want to link to the puppet. You can add up to 128 nicks.

Then enable the puppet by typing "/ppw on". the plugin will check if these nicks are is the specified channels, watch them join or leave the channels, track nick changes, disconnects, etc... when at least one nick is present in the specified channel, the puppet rises up. When all the nicks in the nick list part their respective channels, or aren't available to talk to for any other reason, the puppet goes back down.

To disable the puppet, simply type "/ppw off". Note that even when the puppet is disabled, the plugin keeps tracking the nicks in the list, so the puppet finds itself in the correct state should you decide to re-enable it.

VII - Using the Gaim/Pidgin plugin

Start Gaim or Pidgin, go into the "Tools --> plug-Ins" menu (or type CTRL-U) and enable the "Pushpuppet Watch" plugin. Then, in your buddy list, right-click on the buddy you want the puppet to represent and select "Link to push-puppet".

You can link several buddies to the puppet: if you do, the puppet rises as soon as at least one of them is signed on, and drops when all of them are signed off.

VIII - Video