Skip to content

Update README.md #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
schnoplet wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update README.md #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
223 changes: 125 additions & 98 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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