{"id":22836005,"url":"https://github.com/ysoldak/HeadTracker","last_synced_at":"2025-08-10T21:31:39.540Z","repository":{"id":44628844,"uuid":"331943734","full_name":"ysoldak/HeadTracker","owner":"ysoldak","description":"Zero configuration, auto-calibrating wireless DIY Head Tracker, for Nano 33 BLE and XIAO BLE Sense boards","archived":false,"fork":false,"pushed_at":"2024-05-20T14:11:24.000Z","size":11637,"stargazers_count":55,"open_issues_count":4,"forks_count":8,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-06-19T02:09:09.190Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ysoldak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ysoldak"}},"created_at":"2021-01-22T12:45:28.000Z","updated_at":"2024-05-20T14:11:27.000Z","dependencies_parsed_at":"2024-01-21T00:30:27.431Z","dependency_job_id":"e1677b62-37cf-4811-91d4-83856722304f","html_url":"https://github.com/ysoldak/HeadTracker","commit_stats":{"total_commits":154,"total_committers":2,"mean_commits":77.0,"dds":0.07792207792207795,"last_synced_commit":"451bc30281513fce07adacbf524015ec9bdcea24"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ysoldak%2FHeadTracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ysoldak%2FHeadTracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ysoldak%2FHeadTracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ysoldak%2FHeadTracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ysoldak","download_url":"https://codeload.github.com/ysoldak/HeadTracker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229464309,"owners_count":18077035,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-12T23:00:50.310Z","updated_at":"2025-08-10T21:31:39.521Z","avatar_url":"https://github.com/ysoldak.png","language":"C","funding_links":["https://github.com/sponsors/ysoldak"],"categories":["Wireless Communication"],"sub_categories":["WASI and WASM Unknown"],"readme":"# Zero configuration auto-calibrating DIY head tracker\n\nHead Tracker runs on [Seeeduino XIAO BLE Sense](https://www.seeedstudio.com/Seeed-XIAO-BLE-Sense-nRF52840-p-5253.html) and [Arduino Nano 33 BLE](https://store.arduino.cc/arduino-nano-33-ble) boards and connects to [OpenTX](https://github.com/opentx/opentx), [EdgeTX](https://edgetx.org) and [ETHOS](https://ethos.frsky-rc.com) radios via either wired (PPM) or wireless (Bluetooth) trainer link.\n\nThis project would not exist without [awesome work](https://github.com/tinygo-org/awesome-tinygo) by [TinyGo](https://tinygo.org) community that made [codding in Go for embedded systems](https://github.com/tinygo-org/tinygo) possible!\n\n## Quick Setup\n\n- **Buy** [Seeeduino XIAO BLE Sense](https://www.seeedstudio.com/Seeed-XIAO-BLE-Sense-nRF52840-p-5253.html) board\n- **Flash firmware**\n  - Plug-in the board to your computer\n  - Double tap on `RST` button on the board (little one, near USB-C plug), `XIAO-SENSE` USB drive pops up\n  - Download `ht_xiao-ble_x.x.x.uf2` from latest [release](https://github.com/ysoldak/HeadTracker/releases)\n  - Copy the file to `XIAO-SENSE` USB drive\n  - USB drive disconnects itself and reboots (congrats! now you have your head tracker!)\n- **Connect to your radio**\n  - Pick up your radio with wireless trainer link (PARA, Bluetooth)  \n    _all recent FrSky radios have wireless trainer that works; other radios may require [PARA Wireless module](https://www.horusrc.com/en/frsky-horus-x10-para-wireless-module.html) installed_\n  - Connect XIAO BLE Sense board as a wireless trainer  \n    _learn board's ID via [serial console](https://docs.arduino.cc/software/ide-v2/tutorials/ide-v2-serial-monitor) or by attaching little screen (see below) or by walking with your laptop, radio and board away from other bluetooth sources_\n  - [Define mixers in your radio](doc/EthOS.md) from Trainer 1,2 and 3 channels to your desired model outputs  \n    _you may want to [scale outputs to match rotation angels of the head tracker and your camera gimbal](doc/RadioConfiguration.md)_\n- **Attach Head Tracker to your FPV goggles**  \n  _see STL files in \"case\" folder, screen and button are optional_\n- **Calibrate and Setup**  \n  _nothing to do here, skip to the next item_\n- **HAVE FUN!**  \n    - _try our [fpv camera gimbal](https://cults3d.com/en/3d-model/gadget/micro-camera-gimbal-ysoldak) on your favourite model;_  \n    - _check out [our shop](https://skygadgets.shop) for other cool gadgets._\n\n## Video Tutorials\n- [Connect the head tracker wirelessly to your radio](https://youtu.be/b292hyC5Ctk?t=280)  \n  _watch full video to learn how to power the head tracker with a 1-cell lipo battery_\n\n---\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd\u003e\n\u003cimg src=\"case/DJI Integra Xiao Ble.jpg\" title=\"XIAO on DJI Integra\" style=\"float: right;\"/\u003e\n\u003c/td\u003e\u003ctd\u003e\n\u003cimg src=\"case/GogglesX Xiao Ble.jpg\" title=\"XIAO on Walksnail Googles X\" style=\"float: left;\"/\u003e\n\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\n\u003cimg src=\"case/BDI Adpater Xiao Ble Annotated.jpg\" title=\"XIAO + SSD1306 128x32 on DJI Goggles\" style=\"float: left;\"/\u003e\n\u003c/td\u003e\u003ctd\u003e\n\u003cimg src=\"case/BDI Adpater Xiao Ble Open.jpg\" title=\"XIAO + SSD1306 128x32 on DJI Goggles, wiring\" style=\"float: right;\"/\u003e\n\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n## Camera Gimbal\nCheck our DIY 3D printed [Micro Camera Gimbal](https://cults3d.com/en/3d-model/gadget/micro-camera-gimbal-ysoldak) and [Low Profile Mod](https://cults3d.com/en/3d-model/gadget/low-profile-mod-for-micro-camera-gimbal) for it!  \nJoin our dedicated [Facebook group](https://www.facebook.com/groups/242161055041994)  \n\nAlso available [fully assembled or as a kit on our shop](https://skygadgets.shop/products/fpv-camera-gimbal-for-micro-servos).\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd colspan=\"2\"\u003e\n\u003cimg src=\"media/MCG_Angle.jpg\" title=\"Micro Camera Gimbal, angle\" width=\"100%\" /\u003e\n\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\n\u003cimg src=\"media/MCG_Front.jpg\" title=\"Micro Camera Gimbal, front\" width=\"100%\" /\u003e\n\u003c/td\u003e\u003ctd\u003e\n\u003cimg src=\"media/MCG_Side.jpg\" title=\"Micro Camera Gimbal, side\" width=\"100%\" /\u003e\n\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n## Tested radios\n- FrSky X-Lite Pro (OpenTX)\n- FrSky X20S Tandem (EthOS)\n- [Radiomaster TX16S can be modified to have wireless trainer link](https://github.com/ysoldak/HeadTracker/discussions/31) and work with the head tracker\n\n## Wiring reference\n- **D2**: Orientation reset pin, use a button that connects this pin to **GND**\n- **D8**: PPM mode activation pin, solder it permanently to **GND** or use a positional switch\n- **D10**: PPM signal pin, connect it to an audio jack tip and **GND** to the jack body\n- **SDA\u0026SCL**: I2C communication pins, connect them to 128x32 SSD1306 screen\n\n\u003cimg src=\"doc/xiao-ble-wiring-battery.png\" title=\"XIAO with screen, button and battery wiring diagram\" width=\"100%\"/\u003e\n\u003cimg src=\"doc/xiao-ble-wiring-ext-power.png\" title=\"XIAO with screen and button wiring diagram\" width=\"100%\"/\u003e\n\n## Supported boards\n\nListed boards are perfect for a head tracker project, since they have both **IMU** for orientation and **Bluetooth** for connectivity.\n\n**XIAO BLE Sense** is a tiny board with UF2 bootloader and SoftDevice (bluetooth driver) pre-flashed that makes it very easy to use.\nThe board is relatively new and may be harder to find. Please pay attention and order \"Sense\" variant, it has IMU.  \n_Recommended for users w/o experience in embedded programming._\n\n**Nano 33 BLE** is a larger board from Arduino that shall be easier to source. There are two variants of this board: \"Nano 33 BLE\" and \"Nano 33 BLE Sense\" -- both will work for this project. This board has no UF2 bootloader pre-flashed and a debug probe is required to flash UF2 bootloader to it.  \n_Recommended for advanced users who have a debug probe (JLink or CMSIS-DAP compatible) and can use it._\n\nFor a long time, Nano 33 BLE was the only board supported. It has an additional sensor, magnetometer, that head trackers usually use to eliminate pan drift. In practice, however, magnetometer adds more problems than solves. Magnetometer is very sensitive to environment and tricky to calibrate properly. In this project we do not use magnetometer and have a good zero-configuration automatic continuous gyro calibration instead to solve the drift problem. Already after first 5 seconds the calibration is good enough to stop the drift.  \n\nAs of now, Nano 33 BLE board does not provide any benefit over XIAO BLE Sense. Instead, the later board is actually easier to use, thanks to pre-flashed UF2 bootloader and smaller size. In the future, just for fun, magnetometer support can be added but only if we can make calibration automatic and transparent for the user.\n\nYou have another nRF52840-based board with IMU and want to use it? File a feature request. Better yet, make a PR directly!\n\n\n## Flash binary\n\n### XIAO BLE Sense (Simple)\nConnect the board to your computer, double-tap on RST button and copy `ht_xiao-ble_xxx.uf2` file to XIAO-SENSE usb drive.\n\n### Nano 33 BLE (Advanced)\nFirst, you shall [flash UF2 bootloader to the board](./doc/Nano33BLE.md). You only need to do this once for each new board.\nThen connect the board to your computer, double-tap on button and copy `ht_nano-33-ble_xxx.uf2` file to NANO33BOOT usb drive.\n\n## Use head tracker\nAttach the head tracker to your FPV goggles.  \nPower the head tracker via USB, 1 cell lipo battery or 5v source.  \n\u003e Hint: I've been using analog adapter bay on my DJI V1 goggles to source 5v. Now, I source power via USB-C cable connected to DJI Integra.  \n\n### Bare\nThe head tracker is usable \"bare\", no extra accessories needed, not even a button.  \nTo reset the orientation without a button, simply **double-tap** the head tracker.  \n\u003e Hint: When the head tracker is mounted on your goggles directly, you can just double-tap your googles in any place to reset the orientation.\n\n### LEDs\nOn start, board shall blink continuously blue, red and green/orange leds.\n- Blue led indicates Bluetooth state and blinks while not connected, it switches to solid blue upon successful connection to your radio (see below);\n- Red led indicates initial gyroscope calibration, you shall wait until the red led is off before use, normally no more than several seconds;\n- Green/orange led indicates health of the head tracker and shall slowly blink during normal operation.\n\n### Buttons\nThe head tracker records initial orientation on power up, place your goggles accordingly or reset orientation later by double-tapping the head tracker or by using a **reset orientation** button that can be wired to **D2** and **GND** pins.  \nKeep **reset orientation** button pressed on power up to **discard calibration parameters** stored in flash memory.\n\n### Display\nIf you have a LED `128x32` display added you your board (via I2C), the board's bluetooth address is displayed on it. Blinking \":\" symbols indicate bluetooth connection status, like blue led. Upon start, while gyroscope is calibrating, you shall see head tracker version briefly on the screen. The version is then replaced by 3 horisonal bars, one for each axis: pan, tilt and roll.\n\n\n## Connect to radio\n\nHeadTracker can work either in wireless (Bluetooth) or wired (PPM) mode.  \nBluetooth mode is active by default.\n\n### Bluetooth\n- Flash your board with a [release file](https://github.com/ysoldak/HeadTracker/releases)\n- Connect to the board with a **Serial console** and make note of the board **address** (like: `7b:f5:1e:35:de:94`)\n- [SSD1306 LED display](https://www.amazon.com/s?k=ssd1306+128x32+oled+i2c) can be connected (via I2C) to the board; in such case board address displyed there too\n- In your radio, select Trainer mode **\"Master/BT\"**, wait a bit and click \"[Discover]\"\n- Search for your board by address you noted earlier and **Connect** to it\n- **Blue led** on the board shall turn **on** indicating successful connection\n- Do not forget to configure **Trainer function** in your radio either on \"Special Functions\" screen of your model or on \"Global Functions\" of your radio setup.\n\n### Wire\n- Activate PPM trainer output by connecting **D8** and **GND** pins.\n- Collect PPM signal from **D10** pin. (Audio jack tip shall be connected to **D10** and rest to **GND**)\n\n## Related links\n- [DIY-Head-Tracker](https://github.com/kniuk/DIY-Head-Tracker)  \n  Original DIY head tracker for Arduino Nano with separate IMU board and PPM over cable\n- [RC HeadTracker by Cliff](https://github.com/dlktdr/HeadTracker)  \n  Another version of head tracker, based on Arduino Nano 33 BLE board.\n- [Bluetooth Smart/BLE Crash Course](https://inductive-kickback.com/projects/bluetooth-low-energy/bluetooth-smartble-crash-course/)\n- [Bluetooth low energy Characteristics, a beginner's tutorial](https://devzone.nordicsemi.com/nordic/short-range-guides/b/bluetooth-low-energy/posts/ble-characteristics-a-beginners-tutorial)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fysoldak%2FHeadTracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fysoldak%2FHeadTracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fysoldak%2FHeadTracker/lists"}