An open hardware and software project which tries to implement haptic head pat feedback to the player in VR. This project focuses mainly on VRChat's OSC support but might in the future also support other games. The project consists of a hardware part the "Headpat-Strap" or just "Patstrap", a Server running on the PC and the required edits on a VRChat-Avatar to support the communication over OSC. Keep in mind that this is only a hobby project, but feel free to experiment, edit the code or tweak the hardware to your liking.
Warning
This project is in the development phase. Please note that components of the project are subject to frequent changes.
To make this project you will need:
- ESP8266 WEMOS D1 Mini V4.0.0 If you use a different ESP, you may need to change the pins in the code.
- 2x 150KΩ Resistors
- 2x Transistors (I used BC547)
- 2x Vibrating motors
And optionally if you are using a battery:
An ESP8266 was used for this project, but can be switched with any other WLAN-capable IC. For the haptic feedback two Vibrating Mini Motor Disc from Adafruit were used for a 3D spaced feedback on the head. Both of them can be directly wired to the ESP but for higher performance it is recommended to switch them with two transistors like the BC547b.
The 3D-Model and the .scad file of the hausing, which includes some space for the Motor Discs and the ESP8266, is available under /model and can be 3D-Printed. Alternatively you can use a normal headband and simply hot glue the Motor Discs and the ESP on a headband.
Warning
The models in /model are not up to date and might not fit anymore.
For battery support please refer to the SlimeVR Docs. SlimeVR uses a TP4056 for charging and powering the device. If you want to measure the battery level you need to add the 180kOhm resistor at Pin A0 (enable Battery sense in slimevr docs for circuit diagram).
Optionally you can order a PCB for the Patstrap. The Gerber files required for ordering can be found here. Thanks to The-Prophet for making the PCB.
Warning
The PCB has not been tested yet and is still a Work In Progress!
To upload the firmware to the ESP we use Visual Studio Code and PlatformIO. Please refer to the SlimeVR Docs as a reference on how to install the IDE and the extension. After the installation you can download this repository and open the /firmware folder in Visual Studio Code.
Open the platformio.ini and change -DWIFI_CREDS_SSID and -DWIFI_CREDS_PASSWD to your local network's name and password. Keep in mind that it must be the same network your computer is running on in order for the device to communicate with the server program. If you are not using an ESP8266 you will need to change board = esp12e to your board and most likely also the PIN-Layout in the main.cpp file. If you want to measure battery level don't forget to uncomment -DUSE_BATTERY (remove ;). If you used a PNP transistor instead of the NPN like BC547b, uncomment -DUSE_PNP.
Your config file should look something like this:
[env]
monitor_speed = 9600
monitor_echo = yes
monitor_filters = colorize
framework = arduino
build_unflags = -Os
build_flags = -O2
; Set your wifi name and password here - Make sure it's within the same Network as the server software!
-DWIFI_CREDS_SSID='"WIFI_NAME"'
-DWIFI_CREDS_PASSWD='"WIFI_PASSWORD"'
; Uncomment below if you used a PNP transistor, if you followed the guide you proably want to leave it commented. => inverts the output of the haptic motors
; -DUSE_PNP
; Uncomment below if you use a battery
; -DUSE_BATTERY
; The port used to communicate to the patstrap server, if you change this you will also need to change the --esp-port in the server software
-DPORT='8080'
[env:esp12e]
platform = espressif8266
board = esp12e
framework = arduino
upload_speed = 921600After your edits you can plug-in your ESP, press build (✓) and flash (→) it. You can find the buttons in Visual Studio Code at the bottom on the left side.
Under releases you can find the binary files to run the server on your computer. The server is the middle man that allows communication between the device and VRChat. The server supports both Windows and Linux. The server opens up a window where the current connection status is displayed. If flashing the hardware worked and the device is running you should see the text connected. You can also verify the connection by looking at the ESP-LED.
- Fast blinking (~10 times per second): Not connected with WLAN.
- Slow blinking (~1 time per second): Connected to WLAN, not connected with server.
- Continues light: Connected.
- No light: Not turned on?
If connection was successful Patstrap connection should turn green. Furthermore you can now test the hardware by clicking Pat left and Pat right.
You can change the OSC Port as well as the Port to the ESP by adding a launch argument.
To change the OSC port start the server using the cmd and enter patstrap.exe --osc-port 1234.
To change the ESP port enter patstrap.exe --esp-port 1234 instead, but make sure that you also change the port in the platformio.ini file.
If you dont want to manually set the port everytime you start the server you can create a .bat file with the following content:
@echo off
patstrap.exe --osc-port 1234
Important
Make sure that the .bat file is in the same folder as the .exe file. Alternatively add the fullpath to the .exe in the .bat file.
If you are using VRCOSC you can add the .exe to the startup and (if needed) can add the launch arguments there.
For the Patstrap to work you will need to enable OSC Support in VRChat and edit your Avatar Model to include the required Colliders for detecting a head pat. For this you need to have a working avatar setup in unity.
-
Create Empties
First open up your Avatar in Unity, go to
armature -> Hips -> Spine -> Chest -> Neck -> Headand add twoEmptyobjects as a child of the head. It should look like the following image. Optionally you can rename them for better organization.
-
Add Contact Receivers
Open up the just added objects and click on
Add Componentand selectVRC Contact Receiver.
-
Positioning
Now move the contact receivers to your left and right of your avatar's head. Change the size and form if required. The position and size should resemble the following.
-
Configure Contact Receivers
Under the section
Collision Tagsclick onAddand selectHandand repeat this step forFinger. In the sectionReceiverchangeReceiver TypetoProximityand theParameterto one of the following fitting names.pat_rightfor the collider placed on the right sidepat_leftfor the collider placed on the left side
The end result should look similar to the following image. Repeat this step for the other two contact receivers.
-
Upload
Now you should be ready to test and upload your avatar.
After you uploaded your avatar and enabled osc support, the VRChat connection indicator should turn green as soon as the server software receives any avatar parameter including the head pat parameter. If this is not the case the following steps should help you finding the issue.
- Check if the parameters
pat_rightandpat_leftwere added to your uploaded avatar. You can find the json file at~\AppData\LocalLow\VRChat\VRChat\OSC\{userId}\Avatars\{avatarId}.json. If that is not the case, make sure the Avatar setup step was done correctly. For more information you can also check VRChat's docs. - Use Protokol for debugging and check if
pat_leftorpat_rightappear in the log. Make sure you set the port to the port used by VRChat (default 9001). - Start Patstrap Server in the CMD and look for error messages.
- If nothing worked feel free to file an issue or ask me on the Discord Server or write me directly at
DeanCode#3641.
I am grateful for any help, so if you like this project and want to help make it better feel free to make a pull request, share your opinions, ideas or problems in issues. If you want to help but have no idea what needs to be done, here some general details:
- Designing a hardware that is cheap and easy for others to replicate.
- Electronic components should idealy be available on stores like amazon.
- Documenting every step necessary to build the hardware and setup the software.
- Design casing for ESP
- Currently I am thinking of putting battery on one side and esp on the other, leaving a gap in between for VR headset's top strap.
- Put vibration motor more to the side for a more clear distinction between left and right
- Try isolating the motors from the strap to reduce noise - or - Find better alternative to the
Vibrating Mini Motor Disc, maybe one that can vibrate on lower frequencies (less noise?)
- Add setting for changing between "Vibrate on collision" and "Vibrate on motion"
- Add options to add more vibration motors - (more then just left / right)
- Add a list to the server gui to be able to add & remove new motors
- Change communication between server and hardware from 1 byte (4 bits per motor) to a more flexible system
- Update hardware software accordingly
- Video and update instructions in
README.md
Some related projects that I found interesting:
- BS_Patstrap_support by tapafon is a IPA mod that adds Patstrap support to Beatsaber
- SR_Patstrap_support by tapafon is a Melon mod that adds Patstrap support to Synth Riders
- HapticPatPat by kikookraft is a fork that adds Bluetooth support for lower latency
- Patstrap-Multi-Version-DE by LucyWolf is a german translated version of Patstrap
- Changed design of server app
- Hardware reconnecting to server should work now (also with different IP)
- Improved shutdown of server app
- Added support for battery measurement
- Added support in the firmware for both PNP and NPN transistor
- Improved PWM signal output (uses now builtin function from arduino)
- Updated README to match the new setup.
- Added
windows-debug.exebuilt (opens cmd for additional logs)
- Simplified background in server application
- Fixed test buttons
- Potentially fixed a div by zero crash
- Fixed VRChat status indicator not working
This project uses and refers to many parts from the SlimeVR project which is an open hardware, full body tracking solution and a great project that you definitely should checkout.