Ever wish you could trigger actions by slamming your fist against a mighty Button of Doom? Bonkers is a lightweight C program to monitor this style of devices and let you activate any program. When the button is pressed you are able to run command-line programs. A little creativity and you can have your lights turn off, a thunderclap come from your speakers and computers.
These devices are supported:
- Dream Cheeky - Big Red Button (
1d34:000d) - Dream Cheeky - Stress Ball (
1d34:0020) - Dream Cheeky - USB Fidget (Soccer [US]/Football [World]
1d34:0001, Basketball1d34:0002, Golf1d34:0003) - EB Brands (E&B Giftware, LLC) - USB ! Key (
1130:6626)
Do you want another device to work with Bonkers?
- You may send me the device and software and I'll sniff the USB packets.
- If a developer has a device and information, I'll attempt to modify Bonkers to support it.
- I'd happily accept patches as well!
This guide breaks down the installation procedure into very small steps. When possible, I've included information for how to test that things are installed correctly.
Once compiled, requires libusb-1.0 installed, which is often installed by default.
The development package is necessary for compilation. On Debian/Ubuntu systems you use sudo apt-get install libusb-1.0-0-dev. Similar packages exist for other flavors of Linux/Unix.
To make sure this worked, the file /usr/include/libusb-1.0/libusb.h should exist on your system.
This step is optional. It helps to have the permissions on the device changed when you plug it in. This will let Bonkers communicate with the device without needing to run as root. If you do not do this, you must use sudo or somehow run Bonkers with the right permissions to read the file.
Adding these lines is the easy way to do things.
- As root, copy
doc/99-bonkers.rulesto/etc/udev/rules.d. - Run
udevadm control --reload-rules
Now we should test that it is working as expected.
- Plug in a supported device.
- Run
lsusband note the bus and device numbers. - Run
ls -l /dev/bus/usb/BUS_NUMBER/DEVICE_NUMBERand confirm the permissions are set properly.
For reference, this is the one line of output from lsusb we care about when using the Big Red Button:
Bus 003 Device 021: ID 1d34:000d Dream Cheeky Dream Cheeky Big Red Button
The important bits are the bus number and device number. This means it created a node under /dev/bus/usb/003/021. Simply use ls -l /dev/bus/usb/003/021 (change the filename to match yours) and you should see something like this.
crw-rw-rw- 1 root root 189, 276 Mar 27 17:30 /dev/bus/usb/003/021
You want it to say the "crw-rw-rw-" on the left. If the mode matches then the udev rule was applied successfully.
Check out the repository and cd into it. Now start the build.
make
It should have created a file called bonkers. Let's test it out by running it.
./bonkers -v
This will start the program and will report events to the console. The -v makes it very verbose as to what's going on. There's a few nice features you can enable; check them out by running ./bonkers -h. Stop the program by pressing control-C.
Let's start with something easy. Just echoing the result of what's happening, but disabling all other non-error output.
./bonkers -q -c "echo 'STATUS CHANGE'"
Run this for a bit and you'll see different messages. Again, press control-C to quit. My output for a Big Red Button (open the lid, press the button, stop pressing the button, close the lid) looks like this.
STATUS CHANGE 15 00
STATUS CHANGE 17 15
STATUS CHANGE 16 17
STATUS CHANGE 17 16
STATUS CHANGE 15 17
Because I have a Big Red Button, I can hook into one of the example scripts in the repository. Let's run this again with that script.
./bonkers -q -c examples/big-red-button.sh
And the output from the same procedure:
System is safe
Weapons are armed - proceed with caution
FIRE FIRE FIRE
Cease fire
System is safe
If you like, you can modify your /etc/udev/rules.d/99-bonkers.rules to run a command of your choice. Let's copy examples/udev.sh and bonkers to /usr/local/bin/. You'll likely need root privileges.
sudo cp examples/udev.sh /usr/local/bin/
sudo cp bonkers /usr/local/bin/
Now edit /usr/local/bin/udev.sh as root and make sure it does what you want. After that, edit /etc/udev/rules.d/99-bonkers.rules, look for your device and add a RUN section, like this:
# Dream Cheeky - Big Red Button
ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="1d34", ATTR{idProduct}=="000d", MODE="0666", RUN+="/usr/local/bin/udev.sh"
Each device seems to want to send its own codes, so Bonkers will standardize them for you. Also, repeated codes are not sent to your command; you are notified only when values change.
There are several different types of USB Fidget devices. There is a soccer ball (known as a football in most of the world), basketball, and golf ball. They all act identically.
Arguments passed to command:
- Current button value (0 when not pressed, 1 when pressed)
- Previous button value (0 or 1) - omitted on first call
Examples:
# First call:
your_command 0
# Button pressed:
your_command 1 0
# Button released:
your_command 0 1
Compiling bonkers and running ./bonkers -q -c examples/fidget.sh will report when you press and release the button.
Arguments passed to command:
- Current button state (0 when not pressed, 1 when pressed)
- Current lid state (0 when closed, 1 when open)
- Previous button state (0 or 1) - omitted on first call
- Previous lid state (0 or 1) - omitted on first call
Examples:
# First call:
your_command 0 0
# Lid opened:
your_command 0 1 0 0
# Button pressed:
your_command 1 1 0 1
# Button released:
your_command 0 1 1 1
# Lid closed:
your_command 0 0 0 1
Compiling bonkers and running ./bonkers -q -c examples/big-red-button.sh will explain the different states and let you experiment with the device.
The command that this executes is called EXTREMELY often. It will be called several times per second because the device is digitizing analog sensors and there's a continual wobble in the conversion. It would be wise to make it run as fast as possible. You will also want to manually debounce if this is used to trigger effects.
Arguments passed to command:
- Current squeeze sensor reading (0 to 255)
- Current twist sensor reading (0 to 255)
- Current push/pull sensor reading (0 to 255)
- Previous squeeze sensor reading (0 to 255) - omitted on first call
- Previous twist sensor reading (0 to 255) - omitted on first call
- Previous push/pull sensor reading (0 to 255) - omitted on first call
Examples:
# First call:
your_command 108 142 186
# Subsequent calls:
your_command 109 145 187 108 142 186
your_command 108 145 189 109 145 187
your_command 108 144 189 108 145 189
Compiling bonkers and running ./bonkers -q -c examples/stress-ball.sh will show the sensor values and graphs.
When pressed, this button fires events. It does not continually fire events while held; there is no way to differentiate between a held button and a momentarily pressed button.
Additionally, this button does not appear to respond well to rapid-fire pressing and will only trigger the event occasionally. Typically that would still be acceptable.
Arguments passed to command:
- Current button state (0 when not pressed, 1 when pressed)
- Previous button state (0 or 1) - omitted on first call
Examples:
# First call:
your_command 0
# Pressing the button:
your_command 1 0
your_command 0 1
Compiling bonkers and running ./bonkers -q -c examples/usb-exclamation-key.sh will report when you press the button.
This code is licensed under an MIT license with an additional non-advertising clause. Read the full text in LICENSE.md.
- Malcom Sparks authored an article for OpenSensors.IO that explained a lot about the button and provided source code.
- Arran Cudbard-Bell wrote big_red_button.c, which uses libusb.
- Derrick Spell wrote dream-cheeky, which supported the USB Fidget.
- Jan Axelson's generic HID example under Linux with libusb.
- Wireshark for sniffing USB.
- USB ID Repository for gathering information about more devices.