Segfault Research > Projects > Other > USButton2key > USButton2key: usage (simple)
First published on: 19-May-2014

Start

If you just try to run the app ("./usbutton2key") without any arguments then you'll only get its help.
To be able to run it you'll have to tell the program which USB device you want to use.

The easiest way to do so is to plug in your USB-device and issue an "lsusb" command.
Check in that list if you see your device and if not then plug it out => issue an "lsusb" command => plug it in => issue again an "lsusb" command => check what has changed and you'll see which is the device that you're trying to use.

In my case, after plugging in my USB controller I see...
===============
# lsusb
Bus 001 Device 004: ID 056a:00ec Wacom Co., Ltd
Bus 001 Device 003: ID 0483:91d1 STMicroelectronics
Bus 003 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 002 Device 002: ID 04f3:0254 Elan Microelectronics Corp.
Bus 002 Device 005: ID 046d:c21a Logitech, Inc. Precision Gamepad
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:8000 Intel Corp.
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
===============
...that the USB device I am interested is identified by the vendor ID "046d" and product ID "c21a" => this is all you need to make the utility work.
Therefore, start again the utility by providing the vendor and product ID of the device that you want you use (copied straight from the output of "lsusb"):
./usbutton2key -ti 046d:c21a

 

Troubleshooting

At this point you might get a message saying...
ERROR-Could not connect to device - does your user have read access to it? => terminating program.
...but that's ok:

  • Start again the program, but this time with the additional parameter "-dc" which stands for "debug to console"...
    ./usbutton2key -ti 046d:c21a -dc
    ...and have a look at its output once the utility terminates => at around the end of its output you might see something that says...
    20:40:25 Opening device DEV path /dev/input/event13
    20:40:25 ERROR-Could not connect to device - does your user have read access to it? => terminating program.
    ...and that's what you might need - a read access to that particular device (change "event13" with whatever you see in your case) for your user (who is currently not authorized to read from it).

    To fix this ... authorize your user to read from it :o)
    Generally speaking you should become the "root" user ( command "sudo su - root" in many distributions) and execute "chmod o+r /dev/input/event13" to give to other users the permission to read from that specific device (#13 in my case, but it will be different in your case).
  • That's it - start again the utility with "./usbutton2key -ti 046d:c21a" ("046d:c21a" replaced by what you get in your case) and you should be able to see the UI and can start configuring mappings to ASCII keys - they'll become active once you click on the "Save" button.

Compliments! You should now see a GUI.


Configuration

What can you do in the GUI?
The first thing you should try to do is to press a couple of buttons on your USB device => every time you press or release a different button a new line show show up in the GUI:

In the screenshot above you can see that I on my USB-throttle I pressed 3 different buttons/switches and that when I took the screenshot two out of the three were still pressed (or better said: they were still in their "on" position). I see their on/off state through the column "Current state" - if the checkbox is checked then the button is in its "on" position, otherwise it's the opposite.
Try therefore to press and release a couple of buttons and see if the lines show up and if the column "Current state" keeps updating and matches the state of your buttons.

The ID of the buttons is just the unique identifier of the button that has changed its state.

Next, do a small test:
write some characters into the columns "Key bindings for ON" and "Key bindings for OFF" as I did here...

...and then press the "Save" button => your configuration has been saved and is now active!
Now start a terminal, focus to it and press on your USB device one of the buttons that you have just mapped to a character => you should see those characters showing up in the terminal as if you had just typed them:

You're basically done.
Just modify the mapping as you wish (right now only ASCII characters are supported!), click on "Save" when you want to activate the mapping and instead of putting the focus the terminal, put the focus on the application that you want to use using your USB-device.

If you don't specify something different with the parameter "-c <your config file>" then the program will tell you when it starts where it will try to save the configuration file (in a file called "USButton2key.cfg" in your home directory).

If you have created a mapping and have clicked on "Save" but nothing happens when you press those buttons, run in a shell/terminal the command "echo $DISPLAY" to see what your display name is and replace the default ":0.0" that you see in the GUI in the "Display name:" parameter with what you got, save, and try again.