diff --git a/README.md b/README.md index af1f456..6d57296 100644 --- a/README.md +++ b/README.md @@ -1,93 +1,126 @@ # OSC-based JoyCon (Haptics) for ChilloutVR/VRChat -Link Nintendo Switch Joy-Cons to [Chillout VR](https://store.steampowered.com/app/661130/ChilloutVR/)/VRChat! Uses [OSC Mod](https://github.com/kafeijao/Kafe_CVR_Mods/tree/master/OSC) in ChilloutVR and the [OSC system](https://docs.vrchat.com/docs/osc-overview) in VRChat. +Link Nintendo Switch Joy-Cons to ChilloutVR/VRChat! Uses OSC Mod in ChilloutVR and the OSC system in VRChat. For now, only simple on/off rumble haptics are supported! # Requirements - - Nintendo Switch Joy-Con controller(s). **Only tested with knockoffs from Aliexpress.** - - A customisable avatar or a compatible avatar - - Bluetooth Dongle or similar. [You can use another Windows device as relay](#relay) - - Something to attach controller to body/headset straps, for example ["Exercise Patch Self Adhesive Tape Sports Gym Fitness"](https://www.google.com/search?q=Exercise+Patch+Self+Adhesive+Tape+Sports+Gym+Fitness) - - Unity editor - - `vrcjoycon.exe` from this repository's [Releases](https://github.com/Python1320/vrcjoycon/releases/tag/vrcjoycon) - - **ChilloutVR** - - [OSC Mod](https://github.com/kafeijao/Kafe_CVR_Mods/tree/master/OSC) (Recommended to install via [CVR Assistant](https://github.com/knah/CVRMelonAssistant)) - - Other avatars need [CVR Pointer]( https://documentation.abinteractive.net/cck/components/pointer/?h=pointer#cvr-pointer) on at least one index finger. - - Your avatar needs [CVR Advanced Avatar Trigger](https://documentation.abinteractive.net/cck/components/aas-trigger/) boxes and parameters +- Nintendo Switch Joy-Con controller(s). + Official Nintendo Joy-Cons ARE supported. + Third-party / knockoff Joy-Cons are also supported. +- A customisable avatar or a compatible avatar +- Bluetooth dongle or similar (a separate Windows device can be used as a relay) +- Something to attach controllers to your body/headset straps +- Unity editor +- vrcjoycon.exe from this repository’s Releases +- ChilloutVR + - OSC Mod (recommended via CVR Assistant) + - CVR Pointer on at least one index finger if using other avatars + - CVR Advanced Avatar Trigger boxes and parameters on your avatar + +# Notes on Official Nintendo Joy-Cons + +Official Nintendo Joy-Cons work with this project. + +However, Bluetooth pairing on Windows can be unreliable depending on: +- Bluetooth chipset and drivers +- Windows version +- Interference from Steam Input or other controller software + +If you have trouble pairing or maintaining a stable connection with real Joy-Cons, using BetterJoy is strongly recommended. + +BetterJoy can: +- Improve Joy-Con Bluetooth stability on Windows +- Handle reconnections more reliably +- Prevent Steam Input from hijacking the controllers + +Recommended setup for official Joy-Cons: +- Install [BetterJoy](github.com/Davidobot/BetterJoy/releases/latest) +- Disable Steam Input for Joy-Cons +- Pair Joy-Cons normally via Windows Bluetooth +- Let BetterJoy manage the connection +- Launch vrcjoycon.exe after controllers are connected + +Third-party / knockoff Joy-Cons may not require BetterJoy, but it can still help in some cases. # HELP WANTED -Only tested with knockoff joycons. Does it work with real joycons? Apparently not. We need to fix this! -# Linux +This project has been confirmed to work with both official Nintendo Joy-Cons and third-party / knockoff Joy-Cons. + +Additional testing across different: +- Windows versions +- Bluetooth adapters +- Joy-Con hardware revisions +is still very welcome. +Documentation improvements and pairing tips are especially appreciated. + +# Linux -### **1. Installation** +### 1. Installation -Only tested on Debian 12 (bookworm) and python 3.11 +Only tested on Debian 12 (bookworm) and Python 3.11. -Steps -```bash +Steps: -# Our dependencies sudo apt install libhidapi-dev -# https://innovativeinnovation.github.io/ubuntu-setup/python/pyenv.html -# Pyenv dependencies +Install pyenv dependencies: + sudo apt install make build-essential libssl-dev zlib1g-dev libbz2-dev \ libreadline-dev libsqlite3-dev wget curl llvm libncursesw5-dev \ xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev -# Get pyenv so we can get python 3.11 exactly +Install pyenv: + curl https://pyenv.run | bash -# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -# ^^^ Follow comments above to install pyenv lines in .bashrc ^^^ -# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Follow the instructions printed by the installer to update your shell configuration. -pyenv install 3.11 # build 3.11 python -pyenv virtualenv 3.11 joycon # create joycon virtualenv +Install Python and virtualenv: -. .bashrc # reload .bashrc (or restart shell here) +pyenv install 3.11 +pyenv virtualenv 3.11 joycon -git clone "https://github.com/Python1320/vrcjoycon.git" && \ -cd vrcjoycon && \ -pyenv local joycon +Reload your shell or restart. -# Make sure you see (joycon) prefix on your shell now +Clone the repository and set environment: - # install poetry dependency manager -pip install poetry # OR: curl -sSL https://install.python-poetry.org | python3 +git clone https://github.com/Python1320/vrcjoycon.git +cd vrcjoycon +pyenv local joycon + +Install Poetry and dependencies: -poetry install # install python dependencies with poetry +pip install poetry +poetry install -####### Do steps 2 and 3 below and (*) ########## +Run: cd src ./main.py -# Start controllers for discovery +Modify config: -# Modify config +nano config.ini -${EDITOR:-nano} config.ini +You may need to try: +poetry add hid +or +poetry add hidapi +Remove whichever does not work. -``` -(*) you may need to try `poetry add hid` and `poetry add hidapi` to find a working one (remove the other one). +### 2. hid_nintendo kernel module must not be loaded -### **2. hid_nintendo kernel module must not be loaded** -```bash echo "blacklist hid_nintendo" > /etc/modprobe.d/blacklist_hid_nintendo.conf rmmod hid_nintendo -``` -### **3. Install udev rules** +### 3. Install udev rules -See: https://www.reddit.com/r/Stadia/comments/egcvpq/comment/fc5s7qm/ +Create udev rules: -```bash cat << 'EOF' > /etc/udev/rules.d/50-nintendo-switch.rules # Switch Joy-con (L) (Bluetooth only) KERNEL=="hidraw*", SUBSYSTEM=="hidraw", KERNELS=="0005:057E:2006.*", MODE="0666" @@ -98,74 +131,68 @@ KERNEL=="hidraw*", SUBSYSTEM=="hidraw", KERNELS=="0005:057E:2007.*", MODE="0666" # Switch Pro controller (USB and Bluetooth) KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="057e", ATTRS{idProduct}=="2009", MODE="0666" KERNEL=="hidraw*", SUBSYSTEM=="hidraw", KERNELS=="0005:057E:2009.*", MODE="0666" - EOF -``` +Reload rules: -Run `udevadm control --reload-rules` +udevadm control --reload-rules # TODO - - Example haptics avatar + world (please submit in PR!) - - Button input possibility - - Gyroscope? - - Switch joy-con to poll only to reduce wireless interference (partially done) + +- Example haptics avatar + world +- Button input possibility +- Gyroscope support +- Reduce wireless interference by polling-only mode # Haptics: Setting Up / Usage -### **Unity** (For Chillout VR) - -Rather simple. Just add a few components with right parameter name and it should just work. - - 1. Add joyconrumble1 to avatar parameters - - ![Add joyconrumble1 to avatar parameters](https://user-images.githubusercontent.com/207340/188220202-71f9448d-4c50-4405-a0eb-7d022e5a590a.png) - 2. Add [CVR Advanced Avatar Trigger](https://documentation.abinteractive.net/cck/components/aas-trigger/) to your head - - ![Add CVR Advanced Avatar Trigger](https://user-images.githubusercontent.com/207340/188219981-bdeecdf4-a738-4fd1-9dfd-59fb5beacae5.png) - 3. Add [CVR Pointer]( https://documentation.abinteractive.net/cck/components/pointer/?h=pointer#cvr-pointer) on at least one finger - - ![Add CVR Pointer](https://user-images.githubusercontent.com/207340/188220053-e38ae570-91c1-41c0-a9de-9ac943f99a3f.png) - -### **Unity** (for VRCHat) - 1. Position one or multiple [Contact Receivers](https://docs.vrchat.com/docs/contacts#vrccontactreceiver) components to your chosen avatar bone - 1. Choose at least some collision tags or you will receive no contacts - 2. Haptics can be set to `local only`. `Allow Self` is recommended for testing. - 3. Select `Proximity` from `Receiver Type`. - 4. Set target parameter to `joyconrumble1`. For right controller choose `joyconrumble2`. - - ![componentdetails](images/help2.png) - 5. Add the above parameters to your [animator parameters](https://docs.vrchat.com/docs/animator-parameters) with default float value of 0.0. This is used by OSC to relay the status to VRCJoyCon. - - ![animator](images/help1.png) - -### **VRChat** - 1. Put controllers into pairing mode by pressing the pairing button. - 2. Pair controllers manually over Bluetooth with Windows. - 3. Launch [vrcjoycon.exe](https://github.com/Python1320/vrcjoycon/releases/tag/vrcjoycon) - 4. When pairing is successful, the controller should vibrate. You may need to press the pair button in the controllers a few times before Windows notices the controllers. They should say "connected" in the windows settings when this is so. - 5. In case of trouble, test with other joycon software first - 6. Launch **VRChat** if not already launched - 1. From the VRChat's **circular menu**, inside **settings**, inside **OSC**, choose **Enable** OSC. Additional help [here](https://docs.vrchat.com/docs/osc-overview#enabling-it). - (*If the haptics do not work, try reset configuration option in the same menu* **ATTN.** The OSC Debug menu does not help you with debugging haptics, only output) + +### Unity (ChilloutVR) + +1. Add joyconrumble1 to avatar parameters +2. Add CVR Advanced Avatar Trigger to your head +3. Add CVR Pointer on at least one finger + +### Unity (VRChat) + +1. Add Contact Receivers to chosen avatar bones +2. Choose collision tags +3. Set haptics to local only (Allow Self recommended) +4. Receiver type: Proximity +5. Target parameter: joyconrumble1 + Use joyconrumble2 for the second Joy-Con +6. Add parameters to animator parameters with default float value 0.0 + +### VRChat + +1. Put Joy-Cons into pairing mode +2. Pair Joy-Cons manually via Windows Bluetooth +3. If using official Joy-Cons and experiencing issues, start BetterJoy first +4. Launch vrcjoycon.exe +5. Controllers should vibrate when successfully connected +6. Enable OSC in VRChat settings +7. If haptics do not work, try resetting OSC configuration # Relay -If you have no bluetooth on your VR PC or are experiencing interference it should also be possible to use `vrcjoycon.exe` on a different Windows Laptop, for example. - 1. You will need to configure VRChat to relay the OSC output data to your target computer: https://docs.vrchat.com/docs/osc-overview#vrchat-ports - 2. Start `vrcjoycon` with command line arguments `vrcjoycon.exe --listen=any --port=9001` - - You can replace `any` with an IP address. Any is an alias for `0.0.0.0` - - The default port is 9001 - - Make sure your firewall allows listening on `UDP` protocol port `9001` for `vrcjoycon.exe` +If your VR PC has no Bluetooth or suffers from interference, vrcjoycon.exe can be run on another Windows machine. -# Troubleshooting +1. Configure VRChat OSC output to target the relay machine +2. Start vrcjoycon.exe with: + vrcjoycon.exe --listen=any --port=9001 +3. Allow UDP port 9001 through firewall -Test with OSC receiver to see if your avatar is transmitting. Try transmitting `1` to `/avatar/parameters/joyconrumble1` with OSC sender to see if `vrcjoycon.exe` works. +# Troubleshooting +- Disable Steam Input for Joy-Cons +- Close DS4Windows unless needed +- Use BetterJoy for official Nintendo Joy-Cons if pairing is unstable +- Test OSC output by sending value 1 to: + /avatar/parameters/joyconrumble1 # Credits / components used - - [joycon-python](https://github.com/tocoteron/joycon-python) library + +- joycon-python library # License PENDING MISSING LICENSE ON: https://github.com/tocoteron/joycon-python -