Recuperate the Razer Hydra: Two Magnetic 6-DoF Controllers Back to OSC, MIDI and Two-Player Games

Series: alt.ctrl activities; builds on Game controllers

The Razer Hydra (Sixense, 2011) tracks two wired handheld controllers magnetically, in position and orientation, from a base with a glowing orb. Its vendor SDK is a closed binary that stopped being maintained, but the base is a USB HID device, and an open driver in VRPN shows how to talk to it.

This recipe recuperates it in stages, each tried on the hardware before the next: research what may legally be used, read and record its streams, calibrate the tracking, replace the default gamepad mapping, build a skeuomorphic viewer with record and playback, and design bridges and maps to OSC, MIDI and game devices. Its two controllers make one more challenge: mapping each one on its own, for two players. It follows the way the Hydra was brought back on a Mac in October 2026, and most of the work is a staged prompt for a coding assistant, in the Coding Prompt Build Block below.

Materials

The Hydra and a computer
Item	Seeed Studio	Mouser	eBay
A Razer Hydra (RZ06-0063): the base and both controllers			search
A computer that runs hidapi (the version here used macOS)
For two-player game devices, a microcontroller that can present two USB HID interfaces, such as a Seeed Studio XIAO RP2040	102010428	713-102010428

Tools

A coding assistant, given the Coding Prompt Build Block below
hidapi, and Python, which the version here used through ctypes
A web browser, for the three.js viewer
Photos of the device, calipers and a ruler, or a 3D scanner, to model the base and controllers
An OSC-aware program (Max/MSP, Pd) and a MIDI monitor, to test the bridges

Skills

Reading USB HID reports
Weighing what a licence allows
Quaternions and coordinate frames
Programming with a coding assistant
Basic 3D modelling

Instructions

Research what may legally be used. VRPN's Razer Hydra driver is under the Boost Software License 1.0, so code derived from it can be published under that licence too; its quaternion library is public domain. Vrui's driver is GPL: read it to check the mode bytes, but don't copy it. The report layout is also written up in razer-hydra-hid-protocol, and Razer's master guide shows the setup.
Read the streams. Open the base (vendor 0x1532, product 0x0300) with hidapi; the version here is a Python bridge that reaches hidapi through ctypes and needs nothing else beyond Python's standard library: one interface is a gamepad, the other carries data. As found, the base is in gamepad mode, its default mapping, and the data interface is silent. VRPN's feature report switches it to motion mode: 52-byte reports, about 250 a second, with a frame counter that shows any lost. Put it back in gamepad mode on exit, if the bridge changed it.
Record every report to a file, and add a replay that plays a recording in place of the base, so that the rest can be built and tested without the hardware.
Calibrate. The base's magnetic field is symmetric through its centre, so a position cannot be told from its mirror. Set it up as the guide shows, facing forward with its cable toward you and both controllers resting on it, and calibrate from that pose: the hemisphere from the seated controllers, left and right from which side of the base each one rests on. Then follow each controller to whichever of the reported position and its mirror is nearer its last one. How the orientation's axes map onto the position frame was not settled by the first measurements: measure it with rotations against a square edge.
Model the base, its orb and both controllers, from photos and measurements or a scan. Their surfaces are sculpted and sloped, so place buttons and sticks on the surface, not on a flat projection of a photo.
Build the skeuomorphic viewer: a three.js page with both controllers at their tracked poses, their buttons, sticks and triggers moving, fed through a relay (here a small standard-library Python server), since a browser cannot receive UDP, and able to follow a replay. Until the controllers are labelled, draw them in two colours.
Design the bridges and maps: OSC with each controller's pose, buttons, stick and trigger, which the bridge here sends; then, not yet built here, MIDI from each controller on its own channel; and two game devices, one per controller, through a microcontroller presenting two USB HID interfaces, so two people can play. Let either controller go to either player.
Map them to sound, or play.

A web page drawing the Hydra in 3D: a round base with a green-lit orb, a blue controller lying on its left and an orange one on its right, cables to the base, cards below showing each controller's position, quaternion, buttons, trigger and stick, and a log of calibration events. — The skeuomorphic viewer replaying a bench recording: the left controller blue and the right orange, as in the steps.

Variations

One player, two hands: both controllers on one game device, the left on its left stick and the right on its right.
Head and hand: one controller fixed to the head and the other in the hand, as a cheap tracking pair.
Measure the latency: time the path from a report to the game device or the synthesizer, and compare with the 4 ms between reports.

Related resources

VRPN: the open driver this recipe builds on (Boost Software License 1.0)
razer-hydra-hid-protocol: the base's reports
Razer Hydra Master Guide (Razer): the setup
Replace the Gametrak's Electronics: another controller brought back by its own reports
Make a Wii Nunchuck a USB Controller: a microcontroller as a composite USB device
three.js: the 3D library for the viewer

Coding Prompt Build Block

A prompt to give a coding assistant, to start the code for this activity. Copy the box, answer its questions about your board and pins, and test what comes back on the bench before you rely on it.

I am building "Recuperate the Razer Hydra: Two Magnetic 6-DoF Controllers Back to OSC, MIDI and Two-Player Games", the activity at https://adrianfreed.com/recuperate-razer-hydra.html.

Help me bring a Razer Hydra (USB 1532:0300: a base and two wired controllers tracked magnetically in six degrees of freedom) back into use without Sixense's unmaintained SDK, in stages, each tried on the hardware before the next. Start from code whose licence allows reuse: VRPN's Razer Hydra driver (Boost Software License 1.0) and its quaternion library. Read others, such as Vrui's driver (GPL), without copying them. Start by listing each source you use and its terms.

Stage 1: with hidapi, find the base's data interface (the other interface is a gamepad). The base starts in gamepad mode, its default mapping; send VRPN's feature report to switch it to motion mode, wait for reports (52 bytes, about 250 a second), and put it back in gamepad mode on exit if the bridge changed it. Decode each controller's position, quaternion, buttons, stick and trigger, use the frame counter to count lost reports, record every report to a file, and add a replay mode that plays a recording in place of the hardware.

Stage 2, calibration: the magnetic field is symmetric through the base's centre, so a position cannot be told from its mirror image. Start with both controllers seated on the base, set up as Razer's guide shows; take the hemisphere from that, tell left from right by which side of the base each controller sits on, and then follow each controller to whichever of the reported position and its mirror is nearer its last one. Recalibrate on request. Measure, rather than assume, how the quaternion's axes map onto the position frame: rotations against a square edge, 0.5 to 1 m from the base.

Stage 3, a skeuomorphic viewer: a three.js page that draws the base, its orb and both controllers from measured photos or scans, at the tracked positions and orientations, with the buttons, sticks and triggers moving. A small relay passes the bridge's UDP stream to the page as Server-Sent Events, since a browser cannot receive UDP, and the page can follow a replay. Draw the two controllers in different colours until they are told apart.

Stage 4, bridges and maps for two players: send OSC with each controller's pose, buttons, stick and trigger; MIDI from each controller on its own channel; and two separate game devices, one per controller, so two people can play, by passing the readings to a microcontroller that presents two USB HID interfaces (Adafruit TinyUSB's hid_dual_interfaces example shows how). Let either controller be given to either player, keep the maps in editable tables, and time the path from report to output.

Libraries to explore:

hidapi: a small cross-platform C library for talking to HID devices: listing them, reading input reports, and getting and setting feature reports; Python can reach it through ctypes or cython-hidapi (https://github.com/libusb/hidapi)
VRPN: the Virtual Reality Peripheral Network; its vrpn_Tracker_RazerHydra driver (Boost Software License 1.0) holds the Hydra's mode switch, report layout and hemisphere tracking, and vrpn/quat its quaternion arithmetic (https://github.com/vrpn/vrpn)
three.js: a JavaScript 3D library (MIT) for drawing a device's model in a web page and moving it with the live stream (https://github.com/mrdoob/three.js)
python-osc: OSC clients and servers in pure Python, over UDP and TCP (https://github.com/attwad/python-osc)
Adafruit TinyUSB for Arduino: makes the board a USB device with several interfaces at once, among them Serial (CDC), MIDI and HID; TinyUSB's gamepad report has six 8-bit axes, a hat and 32 buttons, and its mouse report moves the pointer; setPollInterval sets, in milliseconds, how often the computer asks for HID reports; see the hid_composite, hid_gamepad and midi_test examples (https://github.com/adafruit/Adafruit_TinyUSB_Arduino)
Arduino MIDI Library: sends and receives MIDI over any serial port, and over USB, Bluetooth or a network through its transports (https://github.com/FortySevenEffects/arduino_midi_library)

Before writing anything, ask me what I am using: the board and its pins, or the software (such as Max, Pd or Python), and check its documentation for what this needs. Put the pin numbers, ranges and other settings in one block at the top, each with a comment. Say which of the libraries above you use, and why. Start with a test that shows the raw readings, so that I can check the wiring and the ranges before the rest.

This activity by Adrian Freed is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0): you may share and adapt it with attribution, for non-commercial purposes such as personal projects and teaching, and you must share adaptations under the same licence. Product names and links belong to their suppliers.