Control Software for the Inland USB LED Badge

Blog Administration

Tuesday, March 24. 2009

Posted by Tim Hentenaar in Linux, Programming at 02:33 | Comments (11) | Trackbacks (0)

Control Software for the Inland USB LED Badge

Update 12/14/09: I've moved the code for this program to GitHub and now provide binary packages. See the README for details.

I bought one of these at Micro Center a couple of weeks ago (I just now got around to posting the code -- I've been busy with a few other things) because I wanted to flex my reverse engineering muscles, and work with libhid. I knew there was no way in hell it would come with control software for Linux, and at $14.99 it was quite affordable.

0x04d9:0xe002
USB Vendor ID: 0x04d9 Holtek Semiconductor, Inc.
USB Product ID: 0xe002 FURI KEYSHINE USB LED Badge

You can download the source here. The program is written in C, and licensed under the GNU GPLv3. Instructions for how to compile the program are included in the README. You'll find the original documentation (converted to PDF) in the doc directory. Please make sure the badge is connected before running the program.

Requirements:
- GTK+ >= 2.14
- libusb >= 0.1 (Legacy version - libusb 1.x has a much different API)
- libhid >= 0.2.16
- pkg-config, GLib/GDK/GTK+ headers, libusb headers, libhid headers, etc.

Upon starting the program, you'll see the following window:

If you've used the manufacturer-supplied Delphi progam, then this should seem fairly familiar. If not, it should be fairly obvious what each field is for. The first four fields are text input fields corresponding to the first four messages that can be stored on the device. You simply enter the text you want, choose a speed (the higher the number, the faster the action happens), and an action (e.g. "Move.")

The final two fields are for the two bitmap messages available on the device. If you click on the image, a bitmap editor dialog will appear:

By clicking in the grid, you can set or unset the pixels that comprise the image displayed. If you right click on the grid, you'll get an option to clear the bitmap. When you're done with a bitmap, close the dialog.

The last input item is the "Luminance" spin button. This will set the luminance (intensity) for the LEDs. The default is usually sufficient.

When you click "Send," the data will be sent to the device, and you'll be ready to disconnect the device and use it.

Trackbacks

Trackback specific URI for this entry

No Trackbacks

Comments

Display comments as (Linear | Threaded)

Thank you for this software. Works great, except . . .

When editing a graphical message, it seems unstable and crashes.

When installing on Ubuntu 9.04, it is necessary to install development tools (I didn't note which ones) and also packages:

libgtk2.0-dev
libhid0
libhid-dev

It was not clear that the program must be run as root. If not run as root, you get:

Unable to allocate badge structure, or open device!

which should go in the FAQ. Better yet, the message itself could suggest:

Unable to allocate badge structure, or open device! Is this program not running as root?

Maybe it is not root per se, but the fact that the program simply has insufficient permissions.

#1 DannyB on 2009-10-03 17:24 (Reply)

I don't recall having to be root to execute the program. The first thing I would do in this scenario is check the permissions on the device node.

#1.1 Tim Hentenaar on 2009-11-14 00:31 (Reply)

Hi, I'm triing it but I think it doesn't even detect it.

Unable to allocate badge structure, or open device!
Please ensure you have the proper permissions.

this is what I get with lsusb:
xa2@imladris:~$ lsusb
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 001 Device 009: ID 10c4:82cd Cygnal Integrated Products, Inc.
Bus 001 Device 006: ID 08e6:3437 Gemplus GemPC Twin SmartCard Reader
Bus 001 Device 004: ID 413c:2106 Dell Computer Corp.
Bus 001 Device 002: ID 0424:2504 Standard Microsystems Corp. USB 2.0 Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 004: ID 059f:0c41 LaCie, Ltd
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 007 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 006 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 005 Device 003: ID 08ff:2580 AuthenTec, Inc. AES2501 Fingerprint Sensor
Bus 005 Device 002: ID 046d:c51b Logitech, Inc. V220 Cordless Optical Mouse for Notebooks
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub

Any help?

#1.1.1 xa2 on 2010-01-26 11:28 (Reply)

That's interesting... I don't see it in your lsusb output.

#1.1.1.1 Tim Hentenaar on 2010-01-26 12:24 (Reply)

Very impressed with your work! It compiled and ran perfectly (though, under root as per previous comment).

What you created has certainly saved me the headache of finding Windows machines available to change my badge messages, whilst surrounded by my Linux-only machines.

I'm dying of curiosity though: How did you reverse engineer that software? I would love to learn that process!

#2 Tam (Homepage) on 2009-12-04 11:49 (Reply)

Thanks for the comment.

I reverse engineered it with a Winblows VM, a run-time debugger, a USB protocol analyzer, and plenty of patience.

It's a matter of watching the data flow, postulating theories, and then proving those theories with code. The more you can affect the data sent, the easier it is to see how your changes effect that data. It's a lot of trial and error, really.

Btw, I found your website rather interesting.

Tim

#2.1 Tim Hentenaar on 2009-12-04 19:05 (Reply)

I've never heard of Winblows; and a quick google just gives me a whole bunch of Windows rants. Could you possibly point me in the right direction, and more information on that USB analyzer?

And ya, haha, the website a work in progress.

#2.1.1 Tam (Homepage) on 2009-12-08 16:32 (Reply)

FWIW I tried it with my badge (which is different but appears to be by the same manufacturer:

dmesg
[ 4769.953757] usb 5-2: USB disconnect, address 3
[ 4771.680025] usb 5-2: new low speed USB device using uhci_hcd and address 4
[ 4771.906278] usb 5-2: configuration #1 chosen from 1 choice
[ 4771.929483] generic-usb 0003:1241:1301.0007: hiddev97,hidraw4: USB HID v1.10 Device [HOLTEK LED Badge] on usb-0000:00:1d.3-2/input0

but nothing on lsusb

So i tried your software anyway and got:
>sudo usb-badge-gui
Unable to allocate badge structure, or open device!
Please ensure you have the proper permissions.

#3 Izaak Alpert on 2010-03-24 10:02 (Reply)

Awesome program. Except for the fact that Bill keeps me employed, I would use linux exclusively. This is just another example of great work by people who try to avoid the M$ tax.

Thanks!

#4 Kevin Shumaker on 2010-04-23 21:35 (Reply)

Cool. Just picked one of these up on a whim at Microcenter myself, and felt sure that someone would have built Linux support. You are that person (and thus, a GENIUS)

Couple of thoughts.

1) make the udev rule a file in the .deb/rpm so that it gets installed with the package and no manual editing of additional files is needed. Right now, it fails silently on Ubuntu 10.04 due to permissions, until I went ahead and created the udev rule.
2) would be useful to have a cmdline utility as well as the GUI version. "what if" I wanted to plug this in to a headless system?

Actually I originally thought I might be able to use this as a cheap way of displaying alerts at my desk machine. I'm now wondering if it will always say USB(.) when plugged in, and only display one of the programmable messages when disconnected? That would defeat the object of that idea, I guess.

#5 Andy Piper (Homepage) on 2010-08-05 00:06 (Reply)

Thank you so much for this brilliant program!

I just bought one of these devices just for funs, when much to my dismay, I discovered that you couldn't program messages in on the device itself, as I had been lead to believe... I'd need to install some random program written for windows

I first turned to Wine, but decided against it in favor of looking for a native solution. my package manager turned up nothing, but Google brought me right to this page. I utilized your Debian binary repositories (I'm actually running Ubuntu, but it still worked fine...), installed it and it worked flawlessly. I didn't have to set any udev rules, but that may be due to me running several test systems in virtualbox, and the permissions already being set up so virtualbox can use USB devices (since the permissions group was set to vboxusers for me at least).

Thanks once again! Also, for the benefit of others, here's my relevent specs:

OS:
Ubuntu 10.04 (kernel linux-2.6.23-24-generic-x86_64)

USB Badge (as listed when plugging it in):
generic-usb 0003:04D9:E002.000A: hiddev97,hidraw6: USB HID v1.10 Device [FURI KEYSHINE USB LED Badge]

As listed in lsusb:
ID 04d9:e002 Holtek Semiconductor, Inc.

#6 Andrew Farris on 2010-08-20 22:34 (Reply)

Add Comment

Name
Email
Homepage
In reply to
Comment	You can use [geshi lang=lang_name [,ln={y\|n}]][/lang] tags to embed source code snippets Enclosing asterisks marks text as bold (word), underscore are made via _word_. Standard emoticons like :-) and ;-) are converted to images. To prevent automated Bots from commentspamming, please enter the string you see in the image below in the appropriate input box. Your comment will only be submitted if the strings match. Please ensure that your browser supports and accepts cookies, or your comment cannot be verified correctly. Enter the string from the spam-prevention image above:
	Remember Information?