nRF-based KatVR C2/C2+ Receiver -- 133 Hz version

This app aims to implement bluetooth receiver compatible with KatVR's C2/C2+ treadmill sensors.

Project address: https://github.com/datacompboy/nrf-katvr-receiver/

Read article about it at Medium or LinkedIn or Habr.

Tested on

• Seeed Studio XIAO nRF52840

READ ME!

The receiver can provide lower latency by working at up to 133Hz, but that requires patching firmware of all 3 sensors.

Run set-freq-88hz.cmd script for maximum compatibility, set-freq-100hz to change receiver frequency to compatibly but faster.

The set-freq-133hz.cmd allows to run at maximum speed, but it requires to use a fixed firmware for all sensors you use.

Installation on Seeed Studio XIAO nRF52840 dongle by cloning existing receiver

• Download binary release package
• Unpack
• Exit from the KAT Gateway
• Disconnect your KAT Walk USB cable
• Attach your Seeed Studio XIAO nRF52840 dongle to usb port and double-press the reset button (left from usb port), so that new drive explorer window pops up.
• Double-click "install.cmd" script to install firmware and write pairing with your sensors.
• The get stable connection, please update sensors firmware!

To update a sensor firmware:

• Take the sensor out of a shoe or a backplate
• Connect it to the PC
• Press with a toothpick button inside of a "Firmware update" hole
• Click with another toothpick the "Reset" button
• Release the "Firmware update" button
• From "Sensors" folder run "update-feet-firmware.cmd" or "update-direction-firmware.cmd"

If you want to restore sensor firmware back to stock: do the same, but run "restore-*" script.

You need an updated firmware to enjoy lower latencies with this receiver, but the use of fixed firmware with the official receiver will lead to very-very fast movement in games... I'm working on a better solution.

Installation on Seeed Studio XIAO nRF52840 dongle when you don't have working receiver

If your existing receiver is not working and you don't have configuration in your gateway, you still need to install KAT gateway, but then do this:

• Download binary release package
• Unpack
• Exit from the KAT Gateway
• Connect your Seeed Studio XIAO nRF52840 dongle to usb port and double-press the reset button (left from the usb port), so that new drive explorer window pops ups.
• Manually copy version of the firmware that matches your original receiver:
  • nrf_receiver_walk_c2.uf2 for C2 or C2+
  • nrf_receiver_walk_c2_core.uf2 for C2Core
  • nrf_receiver_walk_c2_plus_enhanced.uf2 for C2+ Enhanced.
• Once you copy it, soon the driver will disappear -- the dongle will enter the receiver mode.
• Run the write-serial.cmd script and enter the original serial number from you old receiver (it is written on your treadmill, and looks like "CRA2xxxxxxx"), confirm with enter, and the receiver will get the updated serial number.
• Run the gateway and pair your new receiver with your sensors like you would do for the new treadmill.

You may skip write-serial step, then receiver will have some random serial number that is more-or-less unique for each of the dongles.

You may switch frequency and update sensors firmware same as in the description above.

Features

• KatVR Sensors BT protocol
  • Connect to multiple devices (static list: Direction, Left Feet, Right Feet)
  • Capture notifications sent by devices and know who sent them.
  • Parse BT notification from feet sensors
  • Parse BT notification from direction sensor
  • Achieved 133Hz/sensor frequency!
    • Default receiver has ~80Hz/sensor
    • Single sensor has 250Hz limit;
    • BLE4 has limit of 400Hz for all connections with single central.
• KatVR Gateway USB protocol
  • Devices
    • Expose "Kat Receiver" HID device
  • Protocol
    • Enable / disable stream command
    • Sensor position notification
    • Fake LED / Vibration commands
    • Pair with sensors
    • Allow to set SerialNumber for cloning (use device-uniq serial otherwise)
• KatVr Gateway Compatibility
  • Device can be used as separate receiver, by following standard pairing procedure
  • Device can clone settings from existing KAT receiver using provided clone-kat-device.ps1 powershell script.

How to build

• Prerequisites
  • Install nRF Connect for Desktop
    • Install Toolchain Manager
      • Install the nRF SDK (as of today, v2.5.2)
      • Install the Serial Terminal (convenient to peek at live-over-usbcom debug stream)
    • If you use nRF52840 Dongle -- also install "Programmer"
  • Install VS Code
    • Install "nRF Connect vor VS Code Extension Pack" thru extensions marketplace
• Checkout the project from github, open in VS Code
• Create build config:

  • Go to nRF Connect tab

  • Go to Applications pane

  • Click Create new build configuration

  • Choose your dongle type from dropdown, the rest can be left as is

    • If you wish to enable debuggign (Enables USB console and logging), add an extra CMake option:

      -DOVERLAY_CONFIG=prj_debug.conf

  • Now use "Build" action from Actions pane under the chosen build.

• Flashing to the dongle:
  • First, find the output directory
    • under the NRF-KATVR-RECEIVER pane there are Output files section
    • right-click on any file here, and click "Copy path to file"
    • open system explorer, paste the path into address bar, remove filename, enter
  • If you use XIAO nRF52840:
    • Double-click the tiny "reset" button left from USB-C port
    • The new disk will appear in the system
    • From the output files folder (see above), copy zephyr.uf2 file into the new disk
    • Once copy finishes, disk disappears and dongle reboot into app
  • If you use nRF52840 Dongle:
    • Dongle has an easy-accessible white button (not the right one) and right near it another one, that can be pressed along the PCB in horizontal motion -- that's the flashing button. Click it.
    • Open Programmer from nRF Connect Desktop
    • Select dongle in top-left corner (it's handy to keep auto-connect for multiple iterations, it reconnects if device is in flasher mode)
    • "Add file" to add from the Output files the "zephyr.hex".
      • If you change the code and want to re-flash, you can just click "Reload files" to reload latest copy from disk
    • Press "Write" to actually flash the device.
    • Once it finishes, device will reboot into device mode
• Connecting to debug console
  • Run the "Serial Terminal" from the nRF Desktop
  • Select "nRF KAT-VR Receiver" from the left-top corner of terminal, (hint: "autoconnect")
  • Enjoy the logs!

TODO

• KatVR Sensors BT protocol
  • Connect & receive events from seat
• KatVR Gateway USB protocol
  • Devices
    • Expose "Kat Seat Receiver" HID device
    • Let to choose mimic C2/C2+ or C2Core receivers
  • USB Host / BT Hid
    • Create child device to control vibration/LED wirelessy
• BT Peripheral mode (doesn't seems like worth it)
  • Export connected sensors MACs over BLE in R/W mode
  • Export sensors data over BLE in standard way
    • unlikely with standard sensors.
    • it could be possible to reexport over BLE, but in 1 packet that contains all 3 sensors data without gaps, increased MTU and packets frequency decreased down to ~80hz...
    • or should be possible to update firmware to enable 2Mbit PHY, then it may fit. more digging needed.
• Moonshots
  • Support on-chip 6-axis IMU (e.g. from Seeed Studio XIAO nRF52840 Sense) for "head" direction
  • on-chip gateway, mixing IMU & sensors and export data over HID