Smol Slime

Smol Slimes, also known as nRF Trackers, uses a protocol called Enhanced ShockBurst (ESB) on Nordic Semiconductor nRF52 and nRF54L series System-on-Chip (SoC). These are very power-efficient trackers, requiring a much smaller battery that can last for days to weeks compared to traditional ESP (WiFi) SlimeVR Trackers. A Receiver, or dongle, is required to bridge communication between trackers and the SlimeVR Server. This method does not work with Quest Standalone without using a computer for OSC.

Interested, have questions, or issues with this project? Chat with us in #smol-slimes on SlimeVR Discord!

Table of Contents

• 📡 Receiver Hardware
  • USB Dongles
  • Microcontroller Boards
• 🏃 Tracker Hardware
  • Microcontroller Boards
  • Inertial Measurement Units
  • Magnetometers
  • Sensor Modules
    • IMU Modules
    • IMU + Magnetometer Modules
  • Buttons
  • Switches
  • Batteries
• Schematics
• Software
• Firmware
  • Cloning Repositories
  • Building firmware
    • Changing board defines
    • Adjusting settings in the Kconfig
  • Pre-Compiled firmware for default pins
    • Latest builds (Automated)
  • Updating Adafruit Bootloader (SuperMini / XIAO)
  • Flashing firmware to device
    • Dongles (eByte/Nordic)
    • SuperMini and other Devices with Adafruit Bootloader as Receiver/Tracker:
  • Pairing Mode
    • Tracker
    • Receiver
  • Calibration
    • Basic
    • 6-Side
  • Updating firmware
  • Console Commands
    • Receiver
    • Tracker
  • Button
  • LED Codes
• Protocols
  • Tracker -> Server
  • Tracker <-> Receiver
  • Tracker <-> Server
  • Receiver <-> Server
• Troubleshooting
  • Check Console Logs
    • SWD Debugging
• Links
  • Discord
  • Firmware Source Code
• Community projects
  • Firmware
  • Hardware

📡 Receiver Hardware

It is important to use boards with a good antenna to maintain signal integrity and range. Hardware with PCB antennas are generally the best option to use as a receiver.

USB Dongles

These dongles have a fairly optimized PCB antenna. If you have issues with signal integrity, it is recommended to use a USB extension cable.

Microcontroller Boards

These boards use antenna designs that are not optimized for range. If you are using the same boards for both trackers and receiver, they will likely perform poorly without modification.

🏃 Tracker Hardware

Before you start, decide on how many trackers you may need.

Trackers are required to have a battery and an inertial measurement unit (IMU). A magnetometer is optional.

Buttons and slide switches are recommended but not required. Buttons can be added to control the tracker, and a slide switch can be used to physically disconnect a tracker's battery.

Microcontroller Boards

Inertial Measurement Units

• BMI270
• ICM-42688-P
• ICM-42688-V
• ICM-45686
• ISM330BX
• ISM330DHCX
• LSM6DSO
• LSM6DSR
• LSM6DSV
• LSM6DSV16B

Magnetometers

• AK09940
• BMM150*
• BMM350*
• IIS2MDC
• IST8306
• IST8308
• LIS2MDL
• LIS3MDL*
• MMC5983MA

*Sensor driver has not been tested.

Sensor Modules

IMU Modules

Some of the supported sensor modules are described on the IMU Comparison page. Note that most common sensor modules are not supported.

IMU + Magnetometer Modules

Meia, a member of the SlimeVR Discord, produces and sells sensor modules with an onboard magnetometer. They are compatible with common sensor modules, and the form factor is suitable for stacked builds.

Buttons

Push buttons/momentary switches are used to control the tracker. Multiple button configurations are supported. A tracker can have either a reset button, a user button, or both.

The reset button is suitable for all functionality. If a user button is available, it will be used instead.

If a button is not available, tweezers can be used to short the pins for initial tracker setup.

Switches

A slide switch can be used to physically disconnect a battery. Some boards have a high standby power draw and will require a switch.

If a switch is not used, a tracker can enter deep sleep by holding down the user button.

Batteries

Most boards will support a 3.7V Li-ion/LiPo battery. Usually, batteries have a maximum charge rate of 1C, or a 1 hour charge rate. Do not use a battery if the charge rating will be exceeded.

To extend the lifespan of the battery, a much lower charge rate close to 0.5C is recommended.

Schematics

Default SuperMini Build	Stacked 🥪 SuperMini Build1

Software

• Git Client
• nRF Connect for Desktop
  • Programmer (Inside nRF Connect; needed for Nordic and eByte Dongles only)
  • Serial Terminal (Inside nRF Connect; recommended to send commands to your Receiver/Trackers)
  • Toolchain Manager (Inside nRF Connect; needed for building firmware for receiver and tracker)
    • 2.9.0 (Inside Toolchain Manager) Don't use a newer version!
• Visual Studio Code
  • nRF Connect for VS (Install within VS Code Extension tab)
• SlimeVR Server
  • 0.13.2 or later version

Firmware

Cloning Repositories

1. Open Command Prompt (Type cmd in Start Menu).
2. Change to a directory you want the repositories to clone to. (Use "cd" followed by space and then a full path to a folder or drive.)
3. Cloning SlimeNRF Receiver Repository.

git clone --single-branch --recurse-submodules -b master https://github.com/SlimeVR/SlimeVR-Tracker-nRF-Receiver.git

4. Cloning SlimeNRF Tracker Repository.

git clone --single-branch --recurse-submodules -b master https://github.com/SlimeVR/SlimeVR-Tracker-nRF.git

Note: It is recommended to clone to a filepath without whitespaces and/or unicode characters. You may encounters errors when building the firmware.

Building firmware

1. Launch VS Code using nRF Connect's Toolchain Manager.
2. Open the folder to one of the repositories.
3. Make any pin changes or necessary adjustments to boards\MANUFACTURER\BOARD_NAME.dts.
4. Click on the nRF Connect tab on the left side of your screen (about half way down).
5. Under "Applications" , click on "+ Add build configuration."
6. Select preset from "Board Target".
7. Scroll down and click on the "Build Configuration" button.

Note: For trackers, settings are found in "nRF Kconfig GUI" under "Actions" and expand the "SlimeNRF" section.

Changing board defines

Board defines can be found in \boards\ for overlays (Boards within the Zephyr library) and custom boards are found in boards\MANUFACTURER\BOARD_NAME.dts.

1. Navigate to the board's .dts file.
2. I2C (SCL/SDA) can be changed to other pins. Make sure you are using "High Frequency" pins and that you change the pins for both lines.
3. SW0 can be enabled by uncommenting (removing the // ) from lines below the description commment. You can select the lines and press Ctrl / if you are using VS Code. Re-define the gpio pin if necessary.
4. INT (int0-gpios) can be re-defined under the Zephyr user section.
5. CLK (clk-gpios) can be uncommented and re-defined if you are using an IMU with an external clock/crystal oscillator such as the ICM-42688 or ICM-45686.

Adjusting settings in the Kconfig

1. Go to the nRF Connect tab of VS Code.
2. Build the desired board once.
3. A section called Actions should appear on the left navigation board.
4. Select your built board under Applications, then scroll down to the Actions.
5. Double click nRF Kconfig GUI.
6. Scroll down to the SlimeNRF section.
7. Enable/Disable or adjust any configs needed.
8. Click the "Apply" button", then click the "Save to file" button.
9. If prompted which file to save to, select prj.conf.
10. Click on the "Pristine Build" button next to Build in the Actions section.

Pre-Compiled firmware for default pins

Latest builds (Automated)

Updating Adafruit Bootloader (SuperMini / XIAO)

1. You can download them here. https://github.com/adafruit/Adafruit_nRF52_Bootloader/releases
2. For SuperMini, download update-nice_nano_bootloader-x.x.x_nosd.uf2. For XIAO, download update-xiao_nrf52840_ble_sense_bootloader-x.x.x_nosd.uf2. (The proper non-Sense version doesn't update the bootloader.)
3. Plug the device into your computer via data USB cable.
4. The device should start off in DFU mode when new without a bootloader. The LED should be fading on and off.
5. If device's LED is not fading on and off, press the reset button twice (or short RST/GND pins) twice within 0.5s. If device with existing SlimeNRF firmware, reset 4 times.
6. Navigate to your Downloads folder and copy the uf2 file.
7. Navigate to the Mass Storage Drive (ex. NICENANO/XIAO-SENSE) from ThisPC.
8. Paste the file into there, and the window should close and the device will reboot.

Flashing firmware to device

Dongles (eByte/Nordic)

1. Open "Programmer" in nRF Connect.
2. Press the reset button, and the LED should start fading on and off, putting the device in DFU Mode. For eByte, it is the right button. For Nordic, it is a side button (not the round white button).
3. On the top left corner, select your Device.
4. Click on "Add File".
5. Navigate to your local Receiver repository, then select file in build\REPOSITORY_NAME\zephyr\zephyr.hex.
6. Click the "Write button".

SuperMini and other Devices with Adafruit Bootloader as Receiver/Tracker:

1. Plug the device into your computer via data USB cable.
2. The device should start off in DFU mode when new without a bootloader. The LED should be fading on and off.
3. If device's LED is not fading on and off, press the reset button twice (or short RST/GND pins) twice within 0.5s. If device with existing SlimeNRF firmware, reset 4 times.
4. Navigate to your local Receiver or Tracker repository, then go to build\REPOSITORY_NAME\zephyr\.
5. Copy zephyr.uf2 file.
6. Navigate to the Mass Storage Drive (ex. NICENANO/XIAO-SENSE) from ThisPC.
7. Paste the file into there and the window should close and device will reboot.

Pairing Mode

Tracker

Method 1: Console

1. Open nRF Connect for Desktop.
2. Open Serial Terminal from nRF Connect.
3. Ensure your tracker is connected to your computer via cable.
4. On the top left corner, select your tracker under Devices.
5. Click the "Connect to Port" button.
6. Type pair into the console.

Method 2: Button

1. Press the Reset (or short RST/GND pins) or Function button (if you have SW0 defined) 3 times.

Device's LED should blink once every sec.

Receiver

1. Open nRF Connect for Desktop.
2. Open Serial Terminal from nRF Connect.
3. Ensure your tracker is connected to your computer via cable.
4. On the top left corner, select your dongle under Devices.
5. Click the "Connect to Port" button.
6. Type pair into the console.

Device's LED should blink once every sec.

Once trackers are paired, the LED should stop blinking once per sec. To exit pairing mode on Receiver, type reboot in the console or press the left button once on eByte Dongle or the white button once on Nordic Dongle.

Calibration

Basic

Method 1: Console

1. Open nRF Connect for Desktop.
2. Open Serial Terminal from nRF Connect.
3. Ensure your tracker is connected to your computer via cable.
4. On the top left corner, select your tracker under Devices.
5. Click the "Connect to Port" button.
6. Type calibrate into the console while tracker is on a flat surface.
7. Wait for the logs to reboot and print out again.

Method 2: Button

1. Press your Reset or SW0 (Functional) button twice and leave the tracker still on a flat surface for a few seconds.

6-Side

1. Make sure the power switch is on. (So the tracker can run on battery when unplugged.)
2. Open nRF Connect for Desktop.
3. Open Serial Terminal from nRF Connect.
4. Ensure your tracker is connected to your computer via cable.
5. On the top left corner, select your tracker under Devices.
6. Click the "Connect to Port" button.
7. Enter 6-side command in console. (At the moment, there is no button press combination to start this calibration.)
8. Follow the console log on rotating sides on a flat surface. Leave the cable side for last.
9. When prompted for the last side, unplug your USB cable and place the side with the USB port onto the flat surface.
10. Wait a bit until calibration is complete.

Updating firmware

1. If your Receiver needs firmware updated, do this first.
2. Open nRF Connect's Serial Terminal.
3. Select your Receiver from the Device list.
4. Click the "Connect to Port" button.
5. Enter clear to unpair all of your trackers from the Receiver. The Receiver will automatically enter pairing mode.
6. Connect a tracker to your computer via USB cable and make sure the power switch is on. (So the tracker can run on battery when unplugged for 6-Side calibration.)
7. Select your tracker from the Device List.
8. Click the "Connect to Port" button.
9. Enter dfu to go into DFU Mode.
10. Copy the UF2 file onto your tracker.
11. Enter 6-side to start 6-Side calibration.
12. After 6-Side calibration, enter calibrate to calibrate the ZRO.
13. Enter pair to enter pairing mode.
14. Wait for the tracker to pair to the Receiver, and then disconnect.
15. Repeat process for all trackers.
16. Select your Receiver from the Device list.
17. Click the "Connect to Port" button.
18. Enter reboot to exit pairing mode.

Console Commands

Receiver

• info - Get device information
• list - Get paired devices
• reboot - Soft reset the device
• pair - Enter pairing mode
• clear - Clear stored devices
• dfu - Enter DFU bootloader (only available if your device has one)
• uptime - Get device uptime
• meow - Meow!

Tracker

• info - Get device information
• reboot - Soft reset the device
• calibrate - Calibrate sensor ZRO
• 6-side - Calibrate 6-side accelerometer
• pair - Enter pairing mode
• dfu - Enter DFU bootloader (only available if your device has one)
• uptime - Get device uptime
• meow - Meow!

Button

• Reset - 1 Press
• Calibration - 2 Presses
• Pairing Mode - 3 Presses
• DFU Bootloader - 4 Presses
• Deep Sleep - Press and Hold

LED Codes

• 1 short blink per second - Pairing mode.
• 1 long blink per second - Low battery.
• 2, 3, 4 long blinks every 5 seconds - Error.
  • 2 blinks - Sensor error.
  • 3 blinks - Connection error.
  • 4 blinks - Hardware error.
• Fade on and off - DFU mode.
• Very short blink - Normal operation or wake on motion.
• While plugged in: Pulsing - Charging.
• While plugged in: Solid - Fully charged.

Protocols

type    |id      |packet data                                                                                                                  |
0       |id      |proto   |batt    |batt_v  |temp    |brd_id  |mcu_id  |imu_id  |mag_id  |fw_date          |major   |minor   |patch   |rssi    | info
1       |id      |q0               |q1               |q2               |q3               |a0               |a1               |a2               | full precision quat
2       |id      |batt    |batt_v  |temp    |q_buf                              |a0               |a1               |a2               |rssi    | reduced precision quat
3       |id      |svr_stat|status  |resv                                                                                              |rssi    | status

type    |id      |packet data                                                                                                                  |
64      |id      |addr                                                 |resv                                                                   | pairing data from tracker
65      |id      |addr                                                 |addr_rcv                                             |channel |resv    | pairing data to tracker
66      |id      |addr                                                 |time                                                                   | timing data to tracker (why addr?)
67      |id      |addr                                                 |cmd_data                                                               | some command to tracker? (need to be part of timing?)

type    |id      |packet data                                                                                                                  |
128     |id      |addr                                                 |cmd_data                                                               | some command to tracker? (field too large?)
128     |id      |addr                                                 |ack                                                                    | acknowledge?

type    |id      |packet data                                                                                                                  |
192     |id      |resv                                                                                                                         | 192+ should be some interaction b/w receiver and server
254     |resv                                                                                                                                  | filler, this packet is ignored by the server
255     |id      |addr                                                 |resv                                                                   | tracker id association

Troubleshooting

Check Console Logs

1. Open nRF Connect for Desktop.
2. Open Serial Terminal from nRF Connect.
3. Ensure your tracker is connected to your computer via cable.
4. On the top left corner, select your tracker under Devices.
5. Click the "Connect to Port" button.

SWD Debugging

• Instructions for the Raspberry Pi, Raspberry Pi Pico, ST-Link V2, and other debuggers will be added in the future. Resource: https://github.com/joric/nrfmicro/wiki/Bootloader

J-Link, nRF52/nRF52840 Development Kit, and OB-ARM Debugger

1. Install J-Link Software and Documentation Pack: https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack
2. Download Bootloader HEX File for your device (SuperMini - nice_nano_bootloader-x.x.x_sxxx_x.x.x.hex, XIAO - xiao_nrf52840_ble_sense_bootloader-x.x.x_sxxx_x.x.x.hex): https://github.com/adafruit/Adafruit_nRF52_Bootloader/releases
3. Connect Debugger to SWD IO, CLK, and GND Pins. (It is safer to power up your device by plugging into USB instead of using the VDD pin)

Flashing/Fixing bricked bootloader

1. Open "J-Flash Lite."
   • Target Device: NRF52840_XXAA
   • Target Interface: SWD
   • Speed: 4000
2. Click the "OK" button.
3. Click on the "..." button and select downloaded HEX file.
4. Click the "Program Device" button.

RTT/Debugging

1. Open "RTT Viewer."
   • Connection to J-Link: USB
   • Specify Target Device: NRF52840_XXAA
   • Force go on connect: Checked
   • Target Interface & Speed: SWD / 4000 hKz
   • RTT Control Block: Auto Detect
2. Click the "OK" button.

Recommended Hardware/Tools

OB-ARM Debugger: https://www.aliexpress.us/item/3256806507382540.html

Pogo Pin Test Clip (1.5mm Pitch, 4P, Single Row): https://www.aliexpress.us/item/3256805646654844.html

Note: The clip is for SuperMini only. There are cheaper clips out there, but they don't break out the pins from 1.5mm pitch to 2.54mm pitch for dupont wires.

Links

Discord

SlimeVR Discord: https://discord.gg/SlimeVR

Firmware Source Code

Community projects

Firmware

Hardware

Created by Shine Bright ✨ and Depact