search

danielfvm / Patstrap

An Open-Hardware and Software project which tries to implement haptic head pat feedback to the player in VR. It focuses mainly on VRChat and their OSC support.
GNU General Public License v3.0
37 stars 5 forks source link
arduino esp8266 haptic-feedback osc python vrchat

readme

Patstrap

Repository size Last Commit GitHub commit activity (branch) GitHub License GitHub Repo stars

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.

Hardware

Parts

To make this project you will need:

And optionally if you are using a battery:

Electronics

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.

image

Hausing

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.

Battery

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).

PCB

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!

Software

Firmware

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 = 921600

After 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.

image

Server

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.

If connection was successful Patstrap connection should turn green. Furthermore you can now test the hardware by clicking Pat left and Pat right.

image

Port

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.

VRChat

Avatar - Unity

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.

  1. Create Empties

    First open up your Avatar in Unity, go to armature -> Hips -> Spine -> Chest -> Neck -> Head and add two Empty objects as a child of the head. It should look like the following image. Optionally you can rename them for better organization.

    image

  2. Add Contact Receivers

    Open up the just added objects and click on Add Component and select VRC Contact Receiver.

    image

  3. 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.

    image

  4. Configure Contact Receivers

    Under the section Collision Tags click on Add and select Hand and repeat this step for Finger. In the section Receiver change Receiver Type to Proximity and the Parameter to one of the following fitting names.

    • pat_right for the collider placed on the right side
    • pat_left for 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.

    image

  5. Upload

    Now you should be ready to test and upload your avatar.

Testing & Debugging

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.

  1. Check if the parameters pat_right and pat_left were 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.
  2. Use Protokol for debugging and check if pat_left or pat_right appear in the log. Make sure you set the port to the port used by VRChat (default 9001).
  3. Start Patstrap Server in the CMD and look for error messages.
  4. If nothing worked feel free to file an issue or ask me on the Discord Server or write me directly at DeanCode#3641.

Contribute

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:

Goals

TODO's and Issues

Related projects

Changelog

v0.3

Credits

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.