Topcom butler 4012 and Linux

Disclaimer: the program I provide allows to use the Topcom butler 4012 as a sip phone. It doesn’t work with skype. I’ve no interest in using and promoting a closed, propietary, secret system when there are standard ones that are open, better, and cheaper. However my software is GPL, so feel free to use it to write your own interface to the closed skype system, just don’t ask me about that.

Quick give me the files

I recently bought on ebay a really cheap Topcom butler 4012. It’s a nice phone but it has no Linux drivers, and I want to connect it to my LSPro running freelink (i.e. debian etch) to make something similar to yeaphone.

I contacted topcom support (twice) asking for the documentation but they didn’t reply (now I know why: they’re ashamed of it, the protocol is really stupid), so I decided to reverse engineer it on my own.

Update they replied, after a month and a half, telling me that there’s no Linux driver! As if I couldn’t read and didn’t know that. In fact they’re the ones that cannot read, since I asked for the specifications, not for a driver. Anyway, my reply to them not to bother since I already have it working bounced, since the message came from a no-reply address. Great customer support!

I’m not a Linux kernel hacker, but since I recently wrote a driver for a dvb-t usb stick, I thought that this device should be much simpler.

So I subscribed to the linux-usb-devel mailing asking for help, but since the folks there were really helpful (read: I got zero replies) I decided to pursue another route: instead of writing a kernel driver I wrote a usermode driver using libusb. This way I could do in in freepascal instead of braindead C.

Here you’ll find the result of my efforts.

it’s still a work in progress so there are still some rough edges, don’t complain if it eats your data, burns your computer or it’ll make divorce your wife.

The driver

The “driver” is contained in the file butler.pas, where I define a class, TButlerPhone, to encapsulate the communication with the phone.

It should be simple to use, once you know how the phone works. It’s also well documented (I hope), so read it if you want to use it in your projects.

It uses libusb for usb access (so you need it installed), and the libusb.pp unit by Uwe Zimmermann (included in my tarball).

To show how to use it and to test the phone there’s a simple lazarus project, butlerexample. with it you can exercise all the functions of the phone and see what events it produces.

Note that it is not a real driver, it’s just a pascal class that allows you to interface with the phone. And, as I already told before, it doesn’t work with skype.


Since my ultimate goal was to connect the topcom butler 4012 to my Linkstation pro, I had to find a way to write a full featured sip phone that could be controlled exclusively by the 4012

I found the yeaphone project, and since the LSPro also uses an arm processor and should be more powerful than the NSLU2, I knew it was possible, what I didn’t know is if it would be possible to drive the linphone library from a freepascal program.

In fact, my first idea was to port sipinside, since I’d much prefer an all pascal solution. The problem is that sipinside is too windowsy and, while probably possible, it would be a lot of work.

On the other side, linphone, albeit in C, provides a library that in theory could be controlled by a pascal program, once the headers are translated to pascal, and so I did.

The header translation is neither complete nor elegant, but it’s enough to get botphone working

However, since I have some problems using the library, I took another approach: I spawn linphonec when needed.

Your linphonec needs to support the -S option , so you either use linphone-1.7.1 and apply the linphonec.patch contained in my tarball, or use linphone-2.0.x that already supports that option.

If you already have linphonec you can check with linphonec --help, if it supports the option you should see a line that says: -S show general state messages (disabled by default)

How does it work

Like yeaphone, you need to create a linphone configuration file using linphonec, so simply follow the instructions on the yeaphone page or the following quick start guide

Quick start

  • Look if your distribution provides a linphonec binary (e.g. if you’re using mandriva it’s in the linphone package, while ubuntu has it in the linphone-nox package), and check that it is at least 2.0.X. If so, install the distribution provided package, otherwise you’ll have to compile linphone from the sources.

  • Open a console and type linphonec

  • At the prompt type help to get an overview of the available commands and their syntax.

  • Use the proxy add command to configure your sip provider data.

  • In order to test that linphonec is working, make sure that it is using the normal pc soundcard (commands: soundcard list and soundcard use n).

  • Make a test call using a normal sound card to confirm that your settings are ok.

  • When you have linphonec working with a normal soundcard, configure it to use the phone (that’s the card identified with “C-Media usb” in the soundcard list output) and quit linphonec (type quit).

  • Now you can either grab botphone sources and compile them using lazarus or, if you trust me, just grab the binary, decompress it (gunzip botphone-i386.gz) and make it executable (chmod +x botphone).

Launching botphone

Put the botphone binary in a directory in your $PATH or invoke it with the full pathname or, if it is in your current directory, just type ./botphone.

Note that you need enough privileges to access the device, either by being root or by being in a group that can open the device, but most modern distributions should take care of that without the need of using the root account.

Launch botphone without parameters or with --help to see what other parameters are available.

If you have problems, launch it with -v so it will tell you more about what’s happening. You can add up to three -v to increase verboseness.

One useful parameter is --contacts filename, with it you can tell botphone to load an addressbook from the specified file, the format of the file is really simple: each line has to be name,number. If number starts with ! it is interpreted as a command to be executed (with an & automatically appended, so it will execute in the background, but you’ll have to do any stdout and stderr redirection yourself).

Once linphonec/botphone has registered with your configured sip provider, you should see Online (or the equivalent in your language) on the phone display, then you can make calls:

  • Dial a number and press the call button

  • Press the call button and, if you used the --contacts option, you’ll see the first contact in the list. Browse them with the up and down buttons and press the call button to make the call.

  • Press the calls button (right above the ok button) to browse the missed calls list. Pressing ok will show the number corresponding to the name (if available), pressing the down button will show the next call, pressing the up button once will show the date and time of the call, press it twice to go to the previous call. Press the call button to make a call (if you press it while the Delete calls? message is shown, the list will be cleared instead of making a call).

  • The redial button (bottom right) works like the calls button, but it will show the 10 last numbers you dialled.

Henrik Bengtsson reported that he was getting checksum errors with his phone (you can check it by invoking botphone with botphone -v -v -v and trying to use the phone), so starting with version 0.4 there’s a new option --ignore-checksum that you’ll have to use if it happens with your phone too.

Botphone on the lspro

So, after having botphone more or less working on my laptop, I grabbed a copy of the native fpc compiler for arm, installed it on my LSPro, recompiled botphone and… worked! (minus some problems, but anyway I’m impressed by what the fpc team accomplished).

The only snag is that usb sound, needed since the phone is after all a glorified sound card, currently doesn’t work with the LSPro kernel. But it’s only a matter of time, they’re working hard to prepare a newer kernel for the LSpro.

The files

My work is under the GPL.

Written by Luca Olivetti in software on Sun, 22 Mar 2009.