py-oculus-touch 0.1.0

An API to interface with your Oculus Touch controllers.

What is it?

This is a python library that allows you to interface with your Oculus Touch controllers and headset. It is a wrapper for the auto_oculus_touch project.

With it, you can read the current state of the controllers and headset, send button presses to the controller, or move the thumbsticks.

Installation

pip install py_oculus_touch

Example Usage

Below is a short program that will vibrate both controllers for 1 second whenever the X button is pressed while the headset is being worn.

from py_oculus_touch import OculusTouch, OculusTouchControllerEnum

oculus = OculusTouch()

while True:
    print("\n")

    wearing = oculus.Wearing()
    print(f"Headset is {'ON' if wearing else 'OFF'} your head")

    x = oculus.GetPositionX(OculusTouchControllerEnum.Head)
    y = oculus.GetPositionY(OculusTouchControllerEnum.Head)
    z = oculus.GetPositionZ(OculusTouchControllerEnum.Head)
    yaw = oculus.GetYaw(OculusTouchControllerEnum.Head)
    pitch = oculus.GetPitch(OculusTouchControllerEnum.Head)
    roll = oculus.GetRoll(OculusTouchControllerEnum.Head)
    print(
        f"Headset Position: ({x}, {y}, {z}), Yaw: {yaw}, Pitch: {pitch}, Roll: {roll}"
    )

    buttons_down: list = oculus.GetButtonsDownList() # Get a list of buttons that are currently held down
    sensors_touched: list = oculus.GetTouchDownList() # Get a list of capacitive sensors that are currently being touched
    print(f"These buttons are down: {buttons_down}")
    print(f"These sensors are touched: {sensors_touched}")

    print("Here's a vibration for fun")
    oculus.Vibrate(OculusTouchControllerEnum.Left) # Vibrate the left controller
    oculus.Vibrate(OculusTouchControllerEnum.Right) # Vibrate the right controller

    oculus.PollAndSleep(1.0) # Poll and wait for 1 second

This is a smaple output from the above program:

Headset is ON your head
Headset Position: (0.002324591390788555, 0.0881958156824112, -0.02958393096923828), Yaw: 0.26628559827804565, Pitch: 32.98610305786133, Roll: -2.244016647338867
These buttons are down: []
These sensors are touched: []
Here's a vibration for fun


Headset is ON your head
Headset Position: (0.0005310606211423874, 0.09536674618721008, 0.0015068724751472473), Yaw: -0.9234217405319214, Pitch: 35.654449462890625, Roll: -3.4883065223693848
These buttons are down: []
These sensors are touched: [<OculusTouchButtonEnum.RThumb: 4>, <OculusTouchButtonEnum.LThumb: 1024>]
Here's a vibration for fun


Headset is ON your head
Headset Position: (3.6899931728839874e-05, 0.09039056301116943, -0.018536627292633057), Yaw: 3.5531980991363525, Pitch: 33.512542724609375, Roll: -5.120441913604736
These buttons are down: [<OculusTouchButtonEnum.RThumb: 4>, <OculusTouchButtonEnum.LThumb: 1024>]
These sensors are touched: [<OculusTouchButtonEnum.RThumb: 4>, <OculusTouchButtonEnum.LThumb: 1024>]
Here's a vibration for fun


Headset is ON your head
Headset Position: (0.009187383577227592, 0.0899086445569992, -0.02320261299610138), Yaw: 5.528964042663574, Pitch: 33.527103424072266, Roll: -5.911553382873535
These buttons are down: []
These sensors are touched: [<OculusTouchButtonEnum.A: 1>, <OculusTouchButtonEnum.B: 2>, <OculusTouchButtonEnum.X: 256>, <OculusTouchButtonEnum.Y: 512>, <OculusTouchButtonEnum.LThumb: 1024>]
Here's a vibration for fun

API Reference

InitOculus

Initialize the Oculus API.

Parameters

• poll: boolean (Optional): If true, polls the Oculus API after initializing. Defaults to true.

Returns

• number: Return code from the initialization process.

Poll

Polls the Oculus Touch API for state updates.

Parameters

None

Returns

None

Sleep

Blocks the runtime and waits for the specified length. Useful for sleeping between polls.

Parameters

• length: number (Optional): Length of time to sleep in seconds. Defaults to 0.1.

Returns

• Promise<void>: A Promise that resolves after the specified length of time.

PollAndSleep

Combines the Poll() and Sleep() functions.

Parameters

• length: number (Optional): Length of time to sleep in seconds. Defaults to 0.1.

Returns

• Promise<void>: A Promise that resolves after the specified length of time.

Wearing

Checks if the user is wearing the headset.

Parameters

None

Returns

• boolean: True if the user is wearing the headset, false otherwise.

IsPressed

Checks if the specified button was pressed in the current poll. "Pressed" and "Down" are not the same thing.

Parameters

• button: OculusTouchButtonEnum: The button to check.

Returns

• boolean: True if the button was pressed, false otherwise.

IsReleased

Checks if the specified button was released in the current poll.

Parameters

• button: OculusTouchButtonEnum: The button to check.

Returns

• boolean: True if the button was released, false otherwise.

IsDown

Checks if the specified button is currently held down. "Pressed" and "Down" are not the same thing.

Parameters

• button: OculusTouchButtonEnum: The button to check.

Returns

• boolean: True if the button is held down, false otherwise.

IsTouchPressed

Checks if the specified button's capacitor was touched in the current poll. "Pressed" and "Down" are not the same thing.

Parameters

• sensor: OculusTouchSensorEnum: The sensor to check.

Returns

• boolean: True if the button's capacitor was touched, false otherwise.

IsTouchReleased

Checks if the specified button's capacitor was released in the current poll.

Parameters

• sensor: OculusTouchSensorEnum: The sensor to check.

Returns

• boolean: True if the button's capacitor was released, false otherwise.

IsTouchDown

Checks if the specified button's capacitor is currently being touched. "Pressed" and "Down" are not the same thing.

Parameters

• sensor: OculusTouchSensorEnum: The sensor to check.

Returns

• boolean: True if the button's capacitor is being touched, false otherwise.

Reached

Checks whether a specified axis has reached a specified threshold value in between the last poll.

Parameters

• axis: OculusTouchAxisEnum: The axis to check.
• value: number: The threshold value to check against.

Returns

• number: Return code indicating if the axis has reached the threshold. 0 if the threshold wasn't crossed. 1 if the threshold was crossed in the positive direction. -1 if it was crossed in the negative direction.

GetAxis

Returns the value of the specified axis.

Parameters

• axis: OculusTouchAxisEnum: The axis to query.

Returns

• number: The current value of the specified axis.

GetButtonsDown

Returns a bitmask of all buttons currently held down. "Pressed" and "Down" are not the same thing.

Parameters

None

Returns

• number: Bitmask representing buttons currently held down.

GetButtonsDownList

Returns a list of all buttons currently held down. "Pressed" and "Down" are not the same thing.

Parameters

None

Returns

• OculusTouchButtonEnum[]: List of buttons currently held down.

GetButtonsReleased

Returns a bitmask of all buttons released in the current poll.

Parameters

None

Returns

• number: Bitmask representing buttons released in the current poll.

GetButtonsReleasedList

Returns a list of all buttons released in the current poll.

Parameters

None

Returns

• OculusTouchButtonEnum[]: List of buttons released in the current poll.

GetButtonsPressed

Returns a bitmask of all buttons pressed in the current poll. "Pressed" and "Down" are not the same thing.

Parameters

None

Returns

• number: Bitmask representing buttons pressed in the current poll.

GetButtonsPressedList

Returns a list of all buttons pressed in the current poll. "Pressed" and "Down" are not the same thing.

Parameters

None

Returns

• OculusTouchButtonEnum[]: List of buttons pressed in the current poll.

GetTouchDown

Returns a bitmask of all buttons whose capacitors are currently being touched. "Pressed" and "Down" are not the same thing.

Parameters

None

Returns

• number: Bitmask representing buttons whose capacitors are currently being touched.

GetTouchDownList

Returns a list of all buttons whose capacitors are currently being touched. "Pressed" and "Down" are not the same thing.

Parameters

None

Returns

• OculusTouchSensorEnum[]: List of buttons whose capacitors are currently being touched.

GetTouchPressed

Returns a bitmask of all buttons whose capacitors were touched in the current poll. "Pressed" and "Down" are not the same thing.

Parameters

None

Returns

• number: Bitmask representing buttons whose capacitors were touched in the current poll.

GetTouchPressedList

Returns a list of all buttons whose capacitors were touched in the current poll. "Pressed" and "Down" are not the same thing.

Parameters

None

Returns

• OculusTouchSensorEnum[]: List of buttons whose capacitors were touched in the current poll.

GetTouchReleased

Returns a bitmask of all buttons whose capacitors were released in the current poll.

Parameters

None

Returns

• number: Bitmask representing buttons whose capacitors were released in the current poll.

GetTouchReleasedList

Returns a list of all buttons whose capacitors were released in the current poll.

Parameters

None

Returns

• OculusTouchSensorEnum[]: List of buttons whose capacitors were released in the current poll.

GetTrigger

Returns the value of a specified trigger.

Parameters

• hand: OculusTouchHandEnum: The hand (left or right) of the trigger.
• trigger: OculusTouchTriggerEnum: The trigger (index or hand) to query.

Returns

• number: The value of the specified trigger.

GetThumbStick

Returns the value of a specified thumbstick's axis.

Parameters

• hand: OculusTouchHandEnum: The hand (left or right) of the thumbstick.
• axis: OculusTouchAxisEnum: The axis (x or y) of the thumbstick to query.

Returns

• number: The value of the specified thumbstick's axis.

Vibrate

Vibrates a specified controller.

Parameters

• controller: OculusTouchControllerEnum: The controller to vibrate.
• frequency: OculusTouchVibrationFrequencyEnum (Optional): The vibration frequency. Default is OculusTouchVibrationFrequencyEnum.Medium.
• amplitude: number (Optional): The amplitude of the vibration, range [0, 255]. Default is 128.
• length: number (Optional): The length of the vibration in seconds, 0 for infinite. Default is 1.0.

Throws

• Error: If the amplitude is not in the range [0, 255].

Returns

None

GetYaw

Returns the yaw of a specified controller. Yaw is rotation around the y-axis.

Parameters

• controller: OculusTouchControllerEnum: The controller to query.

Returns

• number: The yaw (rotation around the y-axis) of the specified controller.

GetPitch

Returns the pitch of a specified controller. Pitch is rotation around the x-axis.

Parameters

• controller: OculusTouchControllerEnum: The controller to query.

Returns

• number: The pitch (rotation around the x-axis) of the specified controller.

GetRoll

Returns the roll of a specified controller. Roll is rotation around the z-axis.

Parameters

• controller: OculusTouchControllerEnum: The controller to query.

Returns

• number: The roll (rotation around the z-axis) of the specified controller.

GetPositionX

Returns the x position of a specified controller.

Parameters

• controller: OculusTouchControllerEnum: The controller to query.

Returns

• number: The x position of the specified controller.

GetPositionY

Returns the y position of a specified controller.

Parameters

• controller: OculusTouchControllerEnum: The controller to query.

Returns

• number: The y position of the specified controller.

GetPositionZ

Returns the z position of a specified controller.

Parameters

• controller: OculusTouchControllerEnum: The controller to query.

Returns

• number: The z position of the specified controller.

SetTrackingOrigin

Sets the tracking origin of the headset. This is the point in space that the headset will consider to be the origin (0, 0, 0).

Parameters

• origin: OculusTouchTrackingOriginEnum: The tracking origin to set.

Returns

None

ResetFacing

Resets the yaw of a specified controller. Yaw is rotation around the y-axis.

Parameters

• controller: OculusTouchControllerEnum: The controller for which to reset the yaw.

Returns

None

InitvJoy

Initializes the vJoy driver. This must be called before any vJoy functions can be used.

Parameters

• device: number: The vJoy device number to initialize.

Throws

• Error: If there is an error during initialization.

Returns

None

SetvJoyAxis

Sets the value of a specified vJoy axis.

Parameters

• axis: OculusTouchvJoyDeviceEnum: The vJoy axis to set.
• value: number: The value to set, range [0.0, 1.0].

Returns

None

SetvJoyAxisU

Sets the value of a specified vJoy axis using a different range.

Parameters

• axis: OculusTouchvJoyDeviceEnum: The vJoy axis to set.
• value: number: The value to set, range [0.0, 1.0], mapped to [-1.0, 1.0].

Returns

None

SetvJoyButton

Sets the value of a specified vJoy button.

Parameters

• button: OculusTouchButtonEnum: The vJoy button to set.
• value: number: The value to set, range [0, 1].

Returns

None

SendRawMouseMove

Sends a raw mouse move event to the host computer.

Parameters

• x: number: The relative movement in the x direction.
• y: number: The relative movement in the y direction.
• z: number: The relative movement in the z direction.

Returns

None

SendRawMouseButtonDown

Sends a raw mouse button down event to the host computer.

Parameters

• button: OculusTouchRawMouseButtonEnum: The button to press.

Returns

None

SendRawMouseButtonUp

Sends a raw mouse button up event to the host computer.

Parameters

• button: OculusTouchRawMouseButtonEnum: The button to release.

Returns

None