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.

Full Simulation Installation (Advanced)

We include a ROS2 Humble robot simulation to enable testing without a robot. You will need to install various UR ROS2 packages to use it:

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

Our main launch file calls launch files created by Universal Robotics for placing their robot model in a Gazebo simulation, and also homes the robot and configures camera views:

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

This launch runs headless by default. MoveIt 2 Servo, the package which provides the end-effector twist controller, is initialized and activated in the final step of the launch file, after which you can confirm that servo is running:

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

Now you should be able to open http://localhost:8000/test/ and follow the interface instructions to teleoperate the simulated robot.

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}
}