0.9.2

3dmouse-hid

Use a 3D mouse as a web input device. Great for controlling robot end effectors.

Originally forked from webhid-space, with device support information taken from pyspacenavigator.

Usage

We have tested this code under Ubuntu 22.04 and Ubuntu 24.04. Note that WebHID is only supported by Chrome and Edge as of February 2026. You may experience issues using WebHID with Chromium in recent Ubuntu releases due to Snap isolation.

Connecting a 3D Mouse

When using (Ubuntu) Linux, you need to give your user permission to access the device. Add a udev rule using the USB Vendor ID returned from lsusb (e.g. /etc/udev/rules.d/50-3d-mouse.rules):

# Check the Vendor ID using `lsusb`! See the full set of possible values in `dist/deviceSpecs.js`
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="046d", MODE:="0666", GROUP="input"

And run sudo udevadm control --reload-rules && sudo udevadm trigger

On other systems, this is not necessary.

Included Demos

No build steps are required to run our included demos. Simply run a server using:

npm run test

Open localhost:8000/test in Chrome. Note WebHID is typically only available in HTTPS contexts.

Interactive Visualization and Filters

You can test out the twist visualization using viz_test.html by opening http://localhost:8000/test/viz_test.html.

Simulated UR5

The easiest path to try out the libary with a simulated robot is the included Docker Compose. No ROS installation is required on the host.

docker compose up --build sim web

By default, this will use ROS Jazzy. To run against a different ROS distro image (for example Humble), set ROS_DISTRO when building/running:

ROS_DISTRO=humble docker compose up --build sim web

Then open http://localhost:8000/test in Chrome and connect the device.

Notes:

• This setup is currently Linux-oriented because ROS 2 discovery between containers is configured with network_mode: host.
• sim serves rosbridge on ws://127.0.0.1:9090, which matches the default in test/robot.js.

sudo apt install ros-humble-ur-description ros-humble-controller-manager ros-humble-ur-moveit-config ros-humble-ur-simulation-gz ros-humble-ros-gz-bridge ros-humble-ros-gz-image ros-humble-rosbridge-suite ros-humble-ros2-control ros-humble-position-controllers ros-humble-image-transport ros-humble-image-transport-plugins

cd 3dmouse-hid/test/ros && ros2 launch ur_teleop_sim.launch.py

ros2 topic pub /servo_node/delta_twist_cmds geometry_msgs/msg/TwistStamped "{ header: { stamp: 'now', 'frame_id': 'tool0' },  twist: {linear: {x: -0.1}, angular: {  }}}" -r 10

Debugging WebHID Issues

Try using nondebug's WebHID Explorer to connect to the device. If the connection fails, take a look at chrome://device-log/ to see why.

Citation

If you use this work, please cite:

@inproceedings{dhat2024mice,
  author = {Dhat, Varad and Walker, Nick and Cakmak, Maya},
  title = {Using 3D Mice to Control Robot Manipulators},
  year = {2024},
  month = mar,
  booktitle = {ACM/IEEE International Conference on Human-Robot Interaction (HRI)},
  location = {Boulder, CO, USA},
  wwwtype = {conference},
  wwwpdf = {https://hcrlab.cs.washington.edu/assets/pdfs/2024/dhat2024using.pdf},
  wwwcode = {https://github.com/hcrlab/3dmouse-hid},
  doi = {10.1145/3610977.3637486}
}