thp/psmoveapi: 6DoF tracking for the PS Move controller on Linux, macOS and Windows

What problem thp/psmoveapi solves, and for whom

A Move Motion Controller is a Bluetooth HID device with a magnetometer, an accelerometer, a gyroscope, a sphere LED and a rumble motor. Sony never shipped a general-purpose desktop driver for it. The PS Move API fills that gap: the README describes it as an open source library for Linux, macOS and Windows that accesses the controller "via Bluetooth and USB directly from your PC without the need for a PS3".

The audience is narrow and specific. This is for people who want the raw device: pair it, drive the LED, read the inertial sensors and buttons, and feed a camera into a tracker. The README lists sensor fusion for augmented and virtual reality applications among the core features. It is not for someone who wants a finished VR runtime; there is no headset integration in the README, no game engine plugin, and no graphical configuration tool described.

The feature list is honest about scope. Pairing happens over USB. LED and rumble work over both USB and Bluetooth. Inertial sensors and buttons are read over Bluetooth. Extension devices such as the Sharp Shooter and the Racing Wheel are supported. Tracking reaches up to five controllers in 3D space through OpenCV, and orientation comes from an open source AHRS algorithm. Each of those is a separate subsystem with its own failure modes.

The architecture: C core, C++ headers, ctypes Python bindings

The library splits into a C core, additional C++ headers for interoperability, and Python 3 bindings built on ctypes. The README gives the reason for the C core directly: portability and performance. That choice shapes everything downstream. The ctypes bindings mean Python callers load the compiled shared library at runtime rather than building an extension module, so the Python layer is only as available as the C library on the same machine.

The repository layout mirrors the split. Source lives under src/, public headers under include/, the bindings under bindings/, and example programs under examples/, with separate c/, python/ and labs/ directories. Third-party code sits in external/, which is where the licensing question starts.

Tracking is the part with real moving parts. A camera captures frames, OpenCV finds the sphere, and the AHRS algorithm fuses that with the inertial readings. The README names the PS Eye as the camera that works on all three platforms, and allows "any other suitable camera source". That phrasing hides the calibration work: the camera has to be positioned, and the sphere has to be visible, for the vision half to contribute anything. Orientation tracking from the inertial sensors alone is a different path from full 3D position tracking, and the README does not present them as interchangeable.

Installing PS Move API and running a first program

The README does not carry install commands. It points to the documentation at psmoveapi.readthedocs.io and to the repository's CMakeLists.txt, and the top-level tree contains a CMakeLists.txt, a cmake/ directory and a scripts/ directory, so the build is CMake-driven. The exact configure and build invocation is not reproduced here because the README does not give one; read the Read the Docs build page before you start.

What the README does state is that some third-party modules are optional and selected with CMake options, and that CMake prints a hint about the library licensing for your configuration at configure time. The one option named in the README is PSMOVE_USE_PS3EYE_DRIVER, disabled by default, which controls the PSEye camera driver used by the tracker on macOS.

Once the library is built and installed, the Python bindings are the shortest path to a working session. The bindings directory holds a ctypes-based binding for Python 3, and examples/python/ holds runnable examples. The README does not reproduce a sample program, so the honest starting point is the code under examples/python/ rather than a snippet from elsewhere.

The first thing to get right is the pairing step, because the README lists pairing of Bluetooth controllers via USB as the entry point. Plug the controller in, pair it, then unplug and work over Bluetooth. After that, the examples show how to set the LED and read sensor frames. If a program cannot find the controller, the pairing is the first thing to check, not the tracking code.

For a C program, examples/c/ contains the equivalent code against the headers in include/. Build against the installed library the same way the example's CMakeLists.txt does, rather than copying flags from a blog post.

Where the library stops being the right tool

The most concrete limitation is the release cadence. The most recent release listed is 4.0.12 from December 2020, and the two before it are 4.0.11 from September 2020 and 4.0.10 from May 2020. The repository's last push was on 2026-08-05, so commits continue, but the tagged releases are years behind that activity. Anyone who needs a versioned artifact with a changelog entry for a recent fix will not find one.

The second limitation is the camera. Position tracking depends on a camera seeing the sphere, and the README only names the PS Eye as the camera that works across Linux, Windows and macOS. On macOS the PSEye path is exactly the one behind PSMOVE_USE_PS3EYE_DRIVER, which is disabled by default. So the platform where the named camera needs an opt-in CMake flag is also the platform where you cannot assume the tracker works out of the box.

The third is scope of hardware. Nothing in the README mentions the PS4 or PS5 controllers, even though searches around this project pair its name with those consoles. The library is documented against the Move Motion Controller and its extension devices. If your hardware is a DualSense or a PS VR aim controller, the README gives you no reason to expect support.

Finally, the library is a building block, not an application. There is no described GUI, no service that survives reboots, and no configuration file. You are writing the program that uses it.

How this differs from PSMoveService and PSMoveServiceEx

PSMoveService and PSMoveServiceEx appear in the related searches for this project, and the difference in approach is the useful comparison. thp/psmoveapi is a library: you link against it or import its Python bindings, and your program owns the process, the camera loop and the calibration. PSMoveService is a service: it runs as a separate process that owns the controllers and the cameras, and client applications connect to it rather than to the hardware.

That distinction decides your architecture before you write any code. If two programs on the same machine both need the controller, a library approach means arbitration is your problem; a service approach centralises it. If you want to embed tracking in a single application and control the timing of every frame, a service adds a process boundary and an IPC layer you did not ask for.

There is a licensing angle too. The README states that all dependencies are MIT- or BSD-style with one exception: PS3EYEDriver, which is MIT-licensed with parts based on GPL code, used for PSEye interfacing on macOS and gated behind PSMOVE_USE_PS3EYE_DRIVER. A service that bundles camera drivers makes that choice for you; this library leaves the flag in your hands, which is more work and more control.

Licence terms and what upgrading costs

The README says the source is released under a Simplified BSD-style licence, with the exact text in the COPYING file. That is permissive and, for most uses, unremarkable. The complication is external/, which the README says may carry different licences, and which is optional: CMake options decide which modules are compiled in, and CMake reports the resulting licensing at configure time.

The one named exception is PS3EYEDriver, described as MIT with parts based on GPL code, used for PSEye interfacing on macOS and controlled by PSMOVE_USE_PS3EYE_DRIVER, disabled by default. If you enable it, you are combining GPL-derived code into your build, and that is a question for your own legal review, not something this article can settle. The README also points to pages 51 to 53 of the author's master's thesis and to external/README for the full third-party picture.

Upgrade cost is low in the sense that there is little to upgrade: the newest release is 4.0.12 from December 2020. If you track master instead of a tag, you inherit whatever lands there, and the repository's last push was on 2026-08-05. The practical cost is not migration effort, it is the absence of a release that packages recent work. Plan for building from a specific commit and recording which one.

Editorial conclusion

Adopt thp/psmoveapi if you are comfortable in C or Python and want direct control of the Move controller's Bluetooth, LED, rumble and camera tracking behaviour on a desktop OS. Do not adopt it if you need a maintained, packaged product, a PS4 or PS5 controller, or a setup that works without a camera and a calibration step. Before committing, verify three things: that your camera is supported by the OpenCV capture path on your platform, that the CMake configuration you need does not pull in the PS3EYEDriver option and its GPL-derived parts, and that the last release, 4.0.12 from December 2020, covers the API you plan to build on.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. thp/psmoveapi on GitHub