Linux support

[bojogon7]

Problem / motivation
Using it on linux

Proposed solution
Porting it to Linux maybe flatpak?

Alternatives considered
Adding it as element of some crossplatfor liblary

[ludrol]

Tried to run v2.1.0 under wine-ge-8-26 but crashed: wine: Call from 000000007B013AD7 to unimplemented function bluetoothapis.dll.BluetoothFindFirstDevice, aborting
sys-wine-11.0 and soda-9.0-1 did run fine but didn't detect the headphones

[melcodesdev]

Hello there! I am currently working on a Linux port; CLI is working for me and I will release a full version with GUI in around an hour or two.
I haven't tested on end the whole pipeline through a game but it definitely reports the head data through CLI well and opentrack's squid model was moving perfectly.
Please be patient!

[NicholasSlattery]

Awesome, that sounds great. I just made a new linux-support branch for the Linux port.

Could you open a pull request into linux-support instead of main? That way we can review and test the Linux work separately before merging anything into the main release.

[melcodesdev]

Awesome, that sounds great. I just made a new linux-support branch for the Linux port.

Could you open a pull request into linux-support instead of main? That way we can review and test the Linux work separately before merging anything into the main release.

Will do! I'm just finishing up on the scanning and general robustness of the GUI, start testing a bit and will do a PR.

[melcodesdev]

Due to some personal reasons I will be releasing the version tomorrow as well as doing the PR. Sorry for the bad estimation

[melcodesdev]

Hi @NicholasSlattery, the Linux port is done and working: https://github.com/melcodesdev/sony-head-tracker-linux (validated on a WH-1000XM5, streams to OpenTrack at ~25 packets/s, with a small GTK GUI).

I'd like to open a PR against your linux-support branch, but wanted to check your preferences first since it's your repo:

Do you want Linux added alongside Windows (cross-platform, your Windows code untouched), or is linux-support meant to be a Linux-only branch?
Any layout preference: keep the current flat include/ + src/ and let the build pick platform files, or split into core/ + windows/ + linux/ folders?
Anything else you'd want (tests, docs, style) to make it mergeable?

[ludrol]

@melcodesdev

1. The is no HID device shown when running the CLI (WH-1000XM5)
2. Coudn't understand documentation. It's unreadable.

[bojogon7]

For Linux there can be maybe also added support for airpods

https://github.com/librepods-org/librepods

[melcodesdev]

@melcodesdev

1. The is no HID device shown when running the CLI (WH-1000XM5)
2. Coudn't understand documentation. It's unreadable.

@ludrol Thanks for testing!

1. No HID device detected

The tracker only shows up as a /dev/hidraw* node once the headset is connected to your PC as a HID device. With Sony multipoint (connecting to multiple devices with one headset) it often stays on your phone and never attaches to the computer, which would explain seeing nothing.

Can you paste the output of:

bluetoothctl devices Connected is the WH-1000XM5 listed?
ls -l /dev/hidraw*
./build/sony-head-tracker probe
And let me know your distro + kernel (uname -r) and whether you built from the latest commit.

If probe lists the headset but says access denied, it's just permissions. Install the udev rule (or run once with sudo):

sudo cp extras/70-sony-head-tracker.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger
Then reconnect the headset. On my end an XM5 is detected and streams at ~25 Hz, so this is almost certainly connection or permissions, and the output above will tell us which.

2. Documentation

I've added a Troubleshooting section that covers this exact case. Past that, "unreadable" is hard to act on; the README has a Quick start, a per-distro install table, and a Usage list. If a specific part tripped you up, tell me which section and I'll fix it.

[ludrol]

2. Documentation

The 6k LOC commit did not help me reason where documentation would be placed. Existence of PORTING.md tripped me up.
do echo "devices Connected" | bluetoothctl instead of bluetoothctl devices Connected

1. troubleshooting

host for running:
OS: Bazzite x86_64
Host: 82JU (Legion 5 15ACH6H)
Kernel: Linux 7.0.9-ogc3.2.fc44.x86_64
Uptime: 26 mins
Packages: 2 (appimage), 4 (brew), 1 (brew-cask), 172 (flatpak), 3008 (rpm)
Shell: bash 5.3.9
Display (BOE08E8): 1920x1080 in 16", 120 Hz [Built-in]
DE: KDE Plasma 6.6.5
WM: KWin (Wayland)
WM Theme: leaf-dark-color
Theme: Fusion (LeafDark) [Qt], Vapor [GTK2/3]
Icons: breeze-dark [Qt], breeze-dark [GTK3/4]
Font: Noto Sans (10pt) [Qt], Noto Sans (10pt) [GTK3/4]
Cursor: Teto (30px)
Terminal: konsole 26.4.1
CPU: AMD Ryzen 5 5600H (12) @ 4.28 GHz
GPU 1: NVIDIA GeForce RTX 3060 Mobile / Max-Q [Discrete]
GPU 2: AMD Radeon Vega Series / Radeon Vega Mobile Series [Integrated]
Memory: 6.65 GiB / 13.49 GiB (49%)
Swap: 1.38 GiB / 35.59 GiB (4%)
Disk (/): 46.72 MiB / 46.72 MiB (100%) - overlay [Read-only]
Disk (/etc): 901.92 GiB / 929.93 GiB (97%) - btrfs
Locale: pl_PL.UTF-8

container for building:
OS: Arch Linux x86_64
Host: 82JU (Legion 5 15ACH6H)
Kernel: Linux 7.0.9-ogc3.2.fc44.x86_64
Uptime: 25 mins
Packages: 2 (appimage), 469 (pacman)
Shell: bash 5.3.15
Display (BOE08E8): 1920x1080 in 16", 120 Hz [Built-in]
DE: KDE Plasma
WM: KWin (Wayland)
WM Theme: leaf-dark-color
Theme: Fusion (LeafDark) [Qt]
Icons: breeze-dark [Qt], breeze-dark [GTK3/4]
Font: Noto Sans (10pt) [Qt], Noto Sans (10pt) [GTK3/4]
Cursor: Teto (30px)
Terminal: electron
CPU: AMD Ryzen 5 5600H (12) @ 4.28 GHz
GPU 1: NVIDIA GeForce RTX 3060 Mobile / Max-Q [Discrete]
GPU 2: AMD Radeon Vega Series / Radeon Vega Mobile Series [Integrated]
Memory: 6.64 GiB / 13.49 GiB (49%)
Swap: 1.38 GiB / 35.59 GiB (4%)
Disk (/): 901.92 GiB / 929.93 GiB (97%) - overlay
Disk (/etc/hostname): 901.92 GiB / 929.93 GiB (97%) - btrfs [Read-only]
Disk (/run/host/boot): 495.12 MiB / 973.42 MiB (51%) - ext4
Disk (/run/host/boot/efi): 13.12 MiB / 598.81 MiB (2%) - vfat
Locale: pl_PL.UTF-8

echo "devices Connected" | bluetoothctl
[NEW] Media /org/bluez/hci0 
        SupportedUUIDs: 0000110a-0000-1000-8000-00805f9b34fb
        SupportedUUIDs: 0000110b-0000-1000-8000-00805f9b34fb
[NEW] Endpoint /org/bluez/hci0/dev_88_C9_E8_1D_A3_FA/sep3 
[NEW] Transport /org/bluez/hci0/dev_88_C9_E8_1D_A3_FA/sep3/fd0 
[NEW] Endpoint /org/bluez/hci0/dev_88_C9_E8_1D_A3_FA/sep2 
[NEW] Endpoint /org/bluez/hci0/dev_88_C9_E8_1D_A3_FA/sep1 
Agent registered
[WH-1000XM5]> devices Connected
Device 88:C9:E8:1D:A3:FA WH-1000XM5

[WH-1000XM5]> info 88:C9:E8:1D:A3:FA 
Device 88:C9:E8:1D:A3:FA (public)
        Name: WH-1000XM5
        Alias: WH-1000XM5
        Class: 0x00240404 (2360324)
        Icon: audio-headset
        Paired: yes
        Bonded: yes
        Trusted: yes
        Blocked: no
        Connected: yes
        LegacyPairing: no
        CablePairing: no
        UUID: Vendor specific           (00000000-deca-fade-deca-deafdecacaff)
        UUID: Headset                   (00001108-0000-1000-8000-00805f9b34fb)
        UUID: Audio Sink                (0000110b-0000-1000-8000-00805f9b34fb)
        UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)
        UUID: Advanced Audio Distribu.. (0000110d-0000-1000-8000-00805f9b34fb)
        UUID: A/V Remote Control        (0000110e-0000-1000-8000-00805f9b34fb)
        UUID: A/V Remote Control Cont.. (0000110f-0000-1000-8000-00805f9b34fb)
        UUID: Handsfree                 (0000111e-0000-1000-8000-00805f9b34fb)
        UUID: Headset HS                (00001131-0000-1000-8000-00805f9b34fb)
        UUID: PnP Information           (00001200-0000-1000-8000-00805f9b34fb)
        UUID: Vendor specific           (45c93e07-d90d-4b93-a9db-91e5dd734e35)
        UUID: Vendor specific           (764cbf0d-bbcb-438f-a8bb-6b92759d6053)
        UUID: Vendor specific           (81c2e72a-0591-443e-a1ff-05f988593351)
        UUID: Vendor specific           (8901dfa8-5c7e-4d8f-9f0c-c2b70683f5f0)
        UUID: Vendor specific           (931c7e8a-540f-4686-b798-e8df0a2ad9f7)
        UUID: Vendor specific           (956c7b26-d49a-4ba8-b03f-b17d393cb6e2)
        UUID: Vendor specific           (9b26d8c0-a8ed-440b-95b0-c4714a518bcc)
        UUID: Vendor specific           (df21fe2c-2515-4fdb-8886-f12c4d67927c)
        UUID: Vendor specific           (f76acb00-7cab-495f-bb1a-e664598fd77f)
        UUID: Vendor specific           (f8d1fbe4-7966-4334-8024-ff96c9330e15)
        Modalias: usb:v054Cp0DF0d0113
        Battery Percentage: 0x1e (30)

ls  -l /dev/hidraw*
crw-rw-rw-+ 1 root root 241, 0 07-10 21:28 /dev/hidraw0  /dev/hidraw2  /dev/hidraw4  /dev/hidraw6  /dev/hidraw8
/dev/hidraw1  /dev/hidraw3  /dev/hidraw5  /dev/hidraw7

./build/sony-head-tracker probe[19:44:02.257478470] INFO  Scanned 9 hidraw node(s)
HID /dev/hidraw0
  Xtrfy Xtrfy M8W receiver
  usage 0x0001:0x0002  VID/PID 25A7:FA48  input=7 bytes
  verified Android tracker: no
HID /dev/hidraw1
  Xtrfy Xtrfy M8W receiver
  usage 0x0001:0x0006  VID/PID 25A7:FA48  input=8 bytes
  verified Android tracker: no
HID /dev/hidraw2
  ITE Tech. Inc. ITE Device(8910)
  usage 0xFF89:0x0010  VID/PID 048D:C101  input=37 bytes
  verified Android tracker: no
HID /dev/hidraw3
  SINO WEALTH Gaming KB 
  usage 0x0001:0x0006  VID/PID 258A:002A  input=8 bytes
  verified Android tracker: no
HID /dev/hidraw4
  SINO WEALTH Gaming KB 
  usage 0x0001:0x0080  VID/PID 258A:002A  input=2 bytes
  verified Android tracker: no
HID /dev/hidraw5
  HUION Huion Tablet_H640P
  usage 0xFF00:0x0001  VID/PID 256C:006D  input=12 bytes
  verified Android tracker: no
HID /dev/hidraw6
  HUION Huion Tablet_H640P
  usage 0x000D:0x0002  VID/PID 256C:006D  input=10 bytes
  verified Android tracker: no
HID /dev/hidraw7
  Trust GXT 242 Microphone
  usage 0x000C:0x0001  VID/PID 145F:0257  input=4 bytes
  verified Android tracker: no
HID /dev/hidraw8
  ELAN06FA:00 04F3:31DD
  usage 0x0001:0x0002  VID/PID 04F3:31DD  input=9 bytes
  verified Android tracker: no

No Android Head Tracker HID sensor was found.
Pair the headset over Bluetooth and make sure it is connected to this computer.

[melcodesdev]

@ludrol
Thanks, that output nails it, it's not a permissions thing or the tool missing it. Your headset just isn't exposing the head-tracker HID service.

Look at your info: the XM5's advertised UUIDs are all audio (Headset, Audio Sink, Handsfree…) plus Sony vendor ones; there's no Human Interface Device entry. And your probe shows 9 hidraw nodes with no Sony device among them. So the headphones are connected as audio only, and the sensor never attaches, which is why there's no /dev/hidraw* for it.

On my machine the same model does expose that HID service. The usual reason for the difference is that head tracking / spatial sound has to be turned on for the headphones to bring the sensor up. Could you try:

In Sony's Sound Connect app (phone), enable head tracking / spatial sound, then reconnect the XM5 to the PC and re-check ls /dev/hidraw* for a new node.
If no HID node appears after that, it's BlueZ not connecting the HID profile, not this tool; worth a bluetoothctl reconnect or checking dmesg for the HID device.
On the docs: fair, PORTING.md is an internal dev note, not user docs, and I get how it adds noise. I'll keep user-facing stuff in the README and mark PORTING.md dev-only. Thanks for the echo … | bluetoothctl tip too.

[melcodesdev]

@NicholasSlattery
The Linux port is ready; since you merged macOS into main for v2.2.0, I built it on top of main, fully additive (0 changes to Windows/macOS). To PR into linux-support as you asked, could you bring that branch up to date with main? It's a few commits behind, and right now a PR into it would show all the v2.2.0/macOS changes too. Or if you'd prefer, I'm happy to target main directly

[nar3n12]

Hey @melcodesdev, tried your linux branch and it works, thanks!!
built from source method. Haven't tested in any game yet, but can see the tracking data in the gui. also, the gui permission didnt worked, but running the python command as sudo worked.
Device: xm-6 earbuds
distro: pikaOS (debian based)

Update: tested on games too, Assetto Corsa, The Bus

[ludrol]

tested @melcodesdev fork and after firmware update of the headphones it works well enough in flighgear.

Sadly there is opentrack/opentrack#1204 that prevents playing for longer period of time.