USB Button Solution

We finally found a good and cheap option to add custom buttons to AR Sandbox installations: Reyann Zero Delay Arcade USB Encoder. It comes as a modular package with a small circuit board, a USB cable, and thirteen button cables compatible with standard 4.8mm terminal microswitches. Assembling it and connecting buttons does not require soldering. Amazon also offers sets of six high-endurance arcade-style buttons in a variety of colors that match this encoder.

Most USB buttons emulate keys, and have a bug in key repeat handling that can cause input buffer overflows and AR Sandbox hangs. This encoder directly advertises up to twelve generic HID buttons, which is more stable and also does not cause interference with desktop applications.

To assemble the encoder, simply plug the provided USB cable into the matching four-prong plug on the circuit board, and your desired number of button cables into the two-prong button plugs along the opposite long edge of the board. Connect the other ends of the button cables firmly to the terminals on your microswitches; polarity does not matter.

Do not use the four two-prong plugs on the short edge; those have special functions and are not sent over the HID protocol. The button plugs along the long row are named “Button0” to “Button11”, in increasing order away from the two power and mode indicator LEDs. You can use any subset of button plugs, they don’t need to be connected consecutively.

After assembling the controller, visually double-checking for short circuits, and plugging the USB cable into your computer, run
lsusb
from a terminal to check that the encoder is detected. It will be listed as:
Bus XXX Device YYY: ID 0079:0006 DragonRise Inc. PC TWIN SHOCK Gamepad
where the bus and device numbers depend on your local setup.

Making the encoder usable from the AR Sandbox requires a few simple steps. First, create a device rule to allow non-administrative users to access the button device. From a terminal, run
sudo pluma /etc/udev/rules.d/69-USB-encoder.rules
(pluma is MATE’s text editor; adapt as appropriate). Into the empty file, insert exactly the following line:
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0079", ATTRS{idProduct}=="0006", TAG+="uaccess"
then save the file and exit the text editor. Unplug and re-plug the encoder’s USB cable to activate the new rule.

Next, create or open the AR Sandbox’s patch configuration file (please see this thread for more information and instructions). Insert the following lines into the “Desktop” section:

section Vrui
    section Desktop
        ...
        inputDeviceAdapterNames += (HIDAdapter)
        ...
        section HIDAdapter
            inputDeviceAdapterType HID
            inputDeviceNames (USBEncoder)
            
            section USBEncoder
                name USBEncoder
                deviceVendorProductId 0079:0006
                trackingDeviceName Mouse
            endsection
        endsection
        ...
    endsection
endsection

Save the new or edited file, and run the AR Sandbox as usual. If you now press and hold any of the connected buttons, the usual Vrui tool selection menu pops up. Move the mouse to select a tool, and release the pressed button. Then assign additional buttons as usual.

To make the new tool assignments permanent, save the input graph via the main menu’s “Vrui System”->”Devices”->”Save Input Graph” entry, and optionally add the new bindings to the AR Sandbox’s patch configuration file as explained in the forum post linked above. The device name to use for tool bindings is “USBEncoder”, and the button names are “Button0” to “Button11”.

One side effect of using a generic HID button interface is that it is no longer possible to bind desktop shortcuts to the buttons to execute external scripts, such as switching between water and lava rendering modes or changing color maps. To fix this, and to centralize and simplify script management, I added a “Script Executor” tool class to Vrui that can execute scripts from within a Vrui application, bypassing the desktop environment’s mechanism.

The new tool class has not yet landed in Vrui-4.2-006, but can easily be added to an existing installation. Download the tool class’s source code, ScriptExecutorTool.h and ScriptExecutorTool.cpp and save them into the Vrui/Tools subdirectory of the Vrui source code directory. Then run from a terminal:

cd ~/src/Vrui-4.2-006
make
sudo make install

to build the tool class and install it.

The new tool class needs to be activated before it can be bound to a button dynamically. Open the AR Sandbox’s patch configuration file again, and insert the following line into the “Tools” section:

section Vrui
    section Desktop
        ...
        section Tools
            ...
            toolClassNames += (ScriptExecutorTool)
            ...
        endsection
    endsection
endsection

After saving the file and running the AR Sandbox as normal, press some button and select a “Script Executor” tool from the “Utility” submenu of the tool selection menu. A file selection box will pop up where you can select the script you want to execute. It might be easier to bypass this dynamic set-up step and add tool binding sections for script tools directly to the AR Sandbox’s patch configuration file. Use the tool class name “ScriptExecutorTool” and specify the name of the script to be executed by inserting the following tag into the tool binding section:
executablePathName /path/to/and/name/of/your/script

It is also possible to pass command line arguments to scripts, but this can only be done by editing a configuration file or an input graph file. In the appropriate tool binding section, insert a tag
arguments ("argument 1", "argument 2", ..., "argument n")
where each argument is enclosed in double quotes.

• This topic was modified 4 years, 7 months ago by Oliver Kreylos. Reason: Added picture of assembled button encoder