psvr-protocol

Breakdown of the PlayStation VR communication protocols for programmers.

This Wiki is hosted on the web at dylanmckay.io/psvr-protocol/. This site automatically tracks the master branch.

It can be edited at github.com/dylanmckay/psvr-protocol

Foreword

This wiki is an attempt to collect all available and useful information for developing programs that interact with the PSVR.

As the protocol itself is not officially documented, all information collected is the result of reverse engineering.

This means that much of the terminology used will vary across sources, such as the names of commands and fields.

The goal of this project is to be the canonical reference for all things related to PSVR hacking.

Contributions and modifications to this repository are strongly encouraged! Information for contributors can be found here.

External projects and resources

In no particular order

• Libraries
  • PSVRFramework, a C# library for interfacing with the PSVR
  • libpsvr, A C library for interfacing with the PSVR
  • OpenHMD, A C library for interfacing with PSVR, Vive, and Oculus headsets, among others. The library extracts away details about the specific headset. Has bindings for many languages. The code for PSVR driver lives here.
  • OpenPSVR, an "Open Source Open VR driver for the Playstation VR"
  • PSVRMoveService, "A background service that communicates with the psmove and stores pose and button data"
• Example applications
  • PSVRTracker, "A sample app demonstrating position and orientation tracking for the PSVR headset"
  • MacMorpheus, a 360° PSVR video player for Mac. Does not have software USB support and requires the processing unit be plugged into both your computer and your PlayStation
  • thestr4ng3r/psvr, a "Cross-platform 3D 360/180 video player for Playstation VR"
  • PSVRTest, a small GUI program for viewing information queried from a PSVR headset
• Communities
  • /r/PSVRHack

The parts

The PSVR comes with two main components - the actual headset, and a small processing unit that handles most of the logic. These two parts are required - the headset cannot function without the box.

The processing unit

This device sits in-between the headset and the computer.

The processing unit has multiple IO connections

• On the back
  • A USB connection to a PlayStation or computer
    • This is used by the computer to control the headset, give orientation sensor readouts, send audio, read Mic data, and more
  • A HDMI video input that drives the video in the headset itself, labelled "HDMI PS4"
  • An optional HDMI video output that goes to an external TV, called the social screen as this is what the people around you see - labelled "HDMI TV"
• On the front
  • A HDMI video output that goes directly to the headset
  • A proprietary (AFAICT) connector that goes directly to the headset
    • This is used internally by the processing unit for things like retrieving inertia sensor readouts

The headset

Properties

Credit to Agustín Bernad on GitHub for calculating the lens properties here.

The basics

There are two connections that need to be established.

First, a USB connection must be made with the PSVR processing unit. The processing unit itself acts as a USB HID device to the host computer.

The PSVR will not display any video unless the correct initialisation commands are sent via USB.

Secondly, an HDMI connection must be established with the processing unit. Depending on the display mode, barrel distortion may need to be applied to the image in order to correct for the curvature of the lens.

A full explanation of the connection methods:

• The custom USB HID protocol
• The expected HDMI signal format

Note on projects that do not use USB

Some projects (such as the MacMorpheus video player) avoid all USB communication by having an powered-on, idle PS4 connected to the processing unit via USB. This sucks because it is a pain having a PlayStation hooked up to your system. This setup also can only be used in cinematic mode