PS Move API Documentation

Building PS Move API from source

Note that the PS Move API Github Releases page contains prebuilt library downloads, you might prefer to use those.

Requirements for all platforms:

  • CMake 3.16 or newer (tested with 3.25.1)

Building on macOS 13

You need to install the following requirements:

Install the dependencies:

bash -e -x scripts/install_dependencies.sh

To build from source, you can use the build script:

bash -e -x scripts/macos/build-macos

The build script builds for the CPU architecture of the current build machine (using uname -m for detection). By default, on an Apple Silicon machine, this builds for arm64, and for Intel machines, x86_64 is the build target.

The build script assumes Homebrew is installed in the system-wide default folder. For Intel, this is /usr/local and for Apple Silicon, this is /opt/homebrew. If your local installation differs, you might have to adjust MACOS_HOMEBREW_LIB and MACOS_HOMEBREW_INCLUDE in scripts/macos/build-macos, so that the build script and CMake can find headers and libraries.

Building on Ubuntu 22.04

Install the dependencies:

bash -e -x scripts/install_dependencies.sh

To build from source, you can use the build script:

bash -e -x scripts/linux/build-debian

Building on Windows (Visual Studio)

You need to install the following requirements:

Automatic build

A build script is provided which will take care of the build for you. The script will generate the Visual Studio solution and build everything in Debug and Release.

Run the batch files in a “Developer Command Prompt for VS 2022” (you will find this in the start menu) from the PS Move API checkout folder.

For Visual Studio 2022 and 64-bit use:

call scripts/visualc/build_msvc.bat 2022 x64

For Visual Studio 2022 and 32-bit use:

call scripts/visualc/build_msvc.bat 2022 x86

The resulting binaries will be placed in build-x86/ (for the 32-bit build) and build-x64/ (for the 64-bit build).

Python bindings

For Python 3, use the ctypes-based psmoveapi.py bindings. The old SWIG-based bindings are not supported anymore.

Testing the build

A lot of Python example scripts are provided in the examples/python/ directory. They are laid out so that when you build the library (and its Python bindings) in the customary build folder in the PSMove API checkout, the Python examples should find the modules without needing to install anything. We suggest you start with always.py which you can directly call from within the build directory like so:

python ../examples/python/always.py

This script does not require Bluetooth and should thus provide an easy way to test the Python bindings. Simply connect your Move controller via USB and run the script as shown above. If that is working, continue with pair.py to set everything up for using Bluetooth.

Pairing the Controller to your PC

The PS Move connects via two methods:

  • USB: Used for Bluetooth pairing; can set rumble and LEDs, cannot read sensors
  • Bluetooth: Used for wireless connectivity; can set rumble, LEDs and read sensors

Bluetooth pairing

The psmove pair utility is used for Bluetooth pairing – it will write the Bluetooth host address of the computer it’s running on to PS Move controllers connected via USB.

It optionally takes a single command-line parameter that is an alternative Bluetooth host address. For example, if you want to pair your PS Move controller to your phone, but it does not have USB Host Mode, you can use this on your PC:

./psmove pair aa:bb:cc:dd:ee:ff

Where aa:bb:cc:dd:ee:ff is the Bluetooth host address of your phone. Note that depending on the phone, you also need to run pairing code there.

Depending on the operating system, you might need to run the utility as Administrator (Windows), enter your password (OS X) or run using sudo (Linux) to let the utility modify the system Bluetooth settings and whitelist the PS Move for connection.

Note

You only need to pair the controller to your PC once, from then on it will always try to connect to your PC. Only when you connect your controller to a PS3 or pair with another PC will you have to re-do the pairing process on your computer.

Connecting via Bluetooth

Unplug the USB cable and press the PS button on the controller. The red status LED will start blinking and should eventually remain lit to indicate a working Bluetooth connection. If it continues blinking, it might not be paired via Bluetooth, or - if you can see the connection on your computer - the battery is low and needs charging via USB or a charger. To verify the connection, check the Bluetooth devices list of your computer and see if there is an entry for “Motion Controller”.

On recent versions of OS X, a dialog might pop up asking for a PIN. Close it and pair the controller again using psmove pair. After that, it should connect successfully.

Troubleshooting

Here are some advanced tips if you can’t get pairing working out of the box:

Mac OS X

If psmove pair doesn’t work or you get a PIN prompt when you press the PS button on your controller, follow these steps:

  • Right after you run psmove pair write down the adress you find after “controller address:” in the form “aa:bb:cc:dd:ee:ff”
  • Disable Bluetooth (or the modifications that follow won’t work)
  • Wait for the Bluetooth process to quit (pgrep blued); repeat until nothing prints anymore (e.g. the process “blued” has quit) - this can take up to a minute
  • Authorize the controller’s MAC address: sudo defaults write /Library/Preferences/com.apple.Bluetooth HIDDevices -array-add "<aa-bb-cc-dd-ee-ff>" (where <aa-bb-cc-dd-ee-ff> is the MAC address you wrote down at 8.2 but with hyphens for separators)
  • Enable Bluetooth again then press the PS button on the controller. The PIN request should not pop up this time and the Move should now appear in the bluetooth devices as “Motion Controller”.

Starting with macOS Sierra, at most 2 Move controllers can be connected via Bluetooth at the same time when using the built-in Bluetooth adapter. This is due to some internal changes Apple made and did work on the same hardware prior to updating to Sierra. If you need more controllers at the same time, you can use an external Bluetooth adapter.

Ubuntu Linux

If you wish to access the PSMove controller via USB or Bluetooth without requiring root-level permissions then it is necessary to copy the contrib/99-psmove.rules file to /etc/udev/rules.d/:

sudo cp contrib/99-psmove.rules /etc/udev/rules.d/
sudo udevadm trigger

Windows

You might have to try pairing multiple times for the Bluetooth connection to work on Windows. Also, be sure to use the Microsoft Bluetooth Stack and do not install any third party drivers (e.g. MotionInJoy) that would interfere with proper operation of PS Move API on Windows.

Tracking and Camera

This page contains information about the camera integration, especially as it relates to tracking and the different variants for different OSes.

PS3 Camera

This camera is always supported on Linux, and supported on macOS and Windows when using the PS3EYEDriver camera control driver.

On Linux, the kernel includes built-in support for the camera using the ov534 driver, so the V4L2 camera control driver also support the PS3 Eye.

The camera needs a USB 2.0 port.

On Windows, you need to install Zadig (WinUSB driver) for the “USBCamera-B4.09.24.1” (or similar) device so that the PS3EYEDriver can access the camera using libusb. This has been tested with the “WinUSB (v6.1.7600.16385)” driver and Zadig 2.7.

  • Tested models: SLEH-00448
  • No firmware upload necessary

Supported resolutions:

  • 640x480 @ 60 Hz (default)
  • 320x240 @ 187 Hz

PS4 Camera

This camera is currently supported on Linux when using the V4L2 camera control driver, and macOS when using the AVFoundation camera control driver.

You need to upload a firmware binary blob using the psmove camera-firmware command.

The camera needs a USB 3.0 port.

If you have a PSVR kit, you can order the Camera Adaptor (to convert PS4 AUX to USB 3.0) from Sony for free. You only need to enter the serial number of your PSVR kit during the ordering process, no need for a PS5. If you only have the camera but no PSVR, you can look to buy the adaptor online. The official Sony one is CFI-ZAA1.

The official PSVR camera adaptor for PS5 (CFI-ZAA1) will be detected automatically. If you are using a homemade PS4 AUX-to-USB adapter, use psmove camera-firmware --force-ps4 to detect any OV580 in boot mode as PS4 (otherwise it’s assumed that the camera is a PS5 camera, as there is no way yet to distinguish the PS4 and PS5 cameras from the USB descriptor in boot mode only, which is probably why the CFI-ZAA1 appears as USB parent device during enumeration).

After the firmware upload the camera is supported using the uvcvideo kernel driver in OpenCV/V4L2 (Linux) and UVCService on OpenCV/AVFoundation (macOS).

  • Tested models: CUH-ZEY2 (“round model v2”)
  • Tested firmware SHA-1: fe86162309518a0ffe267075a2fcf728c5856b3e
  • Firmware search path: /etc/psmoveapi/camera-firmware-ps4.bin, $HOME/.psmoveapi/camera-firmware-ps4.bin

Supported resolutions:

  • 1280x800 @ 60 Hz (default)
  • 640x400 @ 120 Hz
  • 320x192 @ 240 Hz

PS5 Camera

This camera is currently supported on Linux when using the V4L2 camera control driver, and macOS when using the AVFoundation camera control driver.

You need to upload a firmware binary blob using the psmove camera-firmware command.

The camera needs a USB 3.0 port.

After the firmware upload the camera is supported using the uvcvideo kernel driver in OpenCV/V4L2 (Linux) and UVCService on OpenCV/AVFoundation (macOS).

  • Tested models: CFI-ZEY1
  • Tested firmware SHA-1: 0fa4da31a12b662a9a80abc8b84932770df8f7e1
  • Firmware search path: /etc/psmoveapi/camera-firmware-ps5.bin, $HOME/.psmoveapi/camera-firmware-ps5.bin

Supported resolutions:

  • 1920x1080 @ 30 Hz
  • 1280x800 @ 60 Hz (default)
  • 960x520 @ 60 Hz
  • 640x376 @ 120 Hz
  • 448x256 @ 120 Hz
  • 320x184 @ 240 Hz

Networking (Move Daemon)

PS Move API contains a feature that allows you to connect more than 7 PS Move controllers to a single instance, even on systems that do not allow multiple Bluetooth adapters. The way this works is by exposing the connected controllers via IP (UDP).

This feature has been used by e.g. Edgar Rice Soiree to run a game with 20 move controllers distributed over 3 PCs.

moved2_hosts.txt

You need to place a file “moved2_hosts.txt” into the data directory of PS Move API (usually ~/.psmoveapi/, in Windows %APPDATA%/.psmoveapi/) with one IP address per line that points to a moved instance.

Example moved2_hosts.txt contents:

192.168.0.2

This would try to use the moved running on 192.168.0.2. You can have multiple IPs listed there (one per line), the servers will be tried in order.

If you add * on a single line, this will enable local network auto-discovery, meaning that any running Move Daemon instances can be auto-discovered via UDP broadcast.

API Usage

After that, you can use the PS Move API just as you normally would, and after your locally-connected controllers, controllers connected to remote machines will be used (psmove_count_connected() and psmove_connect_by_id() will take the remote controllers into account).

If you want to only use remotely-connected controllers (ignoring any controllers that are connected locally), or if you want to use moved running on localhost (where it will already provide the connected controllers to you), you should add the following API call at the beginning of your application to ensure that locally-connected devices are not used via hidapi:

psmove_set_remote_config(PSMove_OnlyRemote);

Similarly, you can disable remote controllers via the following API call (in that case, no connections to moved are carred out, only hidapi is used):

psmove_set_remote_config(PSMove_OnlyLocal);

Configuration

Environment Variables

Some aspects of the tracker can be configured at runtime using environment variables. The following environment variables are currently recognized by the tracker (with examples for the Linux/Unix bash):

PSMOVE_TRACKER_CAMERA

If set, this is the camera that will be used when using psmove_tracker_new() instead of using auto-detection.

Example:

export PSMOVE_TRACKER_CAMERA=2  # Will use the 3rd camera
PSMOVE_TRACKER_FILENAME

If set, this will use a video file to playback instead of capturing from a camera. Any camera settings are ignored.

Example:

export PSMOVE_TRACKER_FILENAME=demo.avi # Will play demo.avi
PSMOVE_TRACKER_WIDTH, PSMOVE_TRACKER_HEIGHT

If set, these variables control the desired size of the camera picture.

Example:

export PSMOVE_TRACKER_WIDTH=1280
export PSMOVE_TRACKER_HEIGHT=720
PSMOVE_TRACKER_CAMERA_CALIBRATION

If set, this points to an XML file created by psmove calibrate-camera.

Example:

export PSMOVE_TRACKER_CAMERA_CALIBRATION=pseye.xml

Mailing List

For questions, please read the archives of the PS Move Mailing List. If you cannot find an answer to your question in the archives, send an e-mail: