Ayaneo 3 Magic Modules

[Gweeds9]

Since bazzite phased out handheld daemon, the magic modules for the Ayaneo 3 are no longer supported. There needs to be a modern solution for this

[pastaq]

Part of the code is already in the kernel, ayaneo-ec driver handles part of the two part handshake. The second part needs an hid driver added to the kernel. When both of those pieces are in place and OpenGamepadUI plug-in for the pop out can be made.

Moving this to OpenGamepadUI as this isn't something that InputPlumber is designed to handle.

[matmartinez]

Hi there! Good news—the missing kernel piece is now ready and has been tested on hardware.

I've written hid-ayaneo, a HID driver for the AYANEO 3's detachable controller, porting the protocol that Handheld Daemon implemented in userspace (credit @antheas — the hhd Ayaneo3Hidraw code was the reference) onto the ayaneo-ec foundation. Code: https://github.com/matmartinez/ayaneo-3-bazzite-compat/tree/main/hid-ayaneo

It binds the controller's vendor HID interface (1c4f:0002, application usage 0xff000001, DMI-gated to the AYANEO 3 since that VID/PID is a generic SigmaMicro ID) and exposes:

• Module identification — sysfs module_left / module_right (the raw module-type IDs, e.g. 0x04 Cross/Joystick, 0x50 Joystick\ABXY; 16 known types)
• Software eject — sysfs eject, accepts left/right/both, blocks until the firmware confirms the release handshake (~4s)
• RGB — a multicolor LED class device named ayaneo:rgb:joystick_rings (the name InputPlumber's 50-ayaneo_3.yaml already expects)

EC power-off is deliberately not done by the driver — the full pop-out flow is eject → wait for the write to return → write 0 to ayaneo-ec's controller_power, i.e. exactly the orchestration a plugin/userspace layer should own, per the two-part-handshake layering described here.

Verified end-to-end on an AYANEO 3 running Bazzite 44 (OGC kernel 7.2.0-ogc4.1): a physical eject → module released → reinsert → controller_modules back to both → power on → controller re-enumerates (custom mode persists in flash) → driver rebinds and reads module IDs again. RGB and identification also confirmed.

--

So before I submit this to LKML (and to OGC kernel-packages so Bazzite can carry it), I'd love feedback on the sysfs interface from @pastaq / @antheas — attribute names, whether eject should be synchronous, whether module IDs should be decoded to strings in-kernel or left raw for userspace, anything that would make the OpenGamepadUI plugin's life easier. I'm planning to work on that plugin next, so if there's existing WIP or preferred plugin structure for it, pointers welcome.

[Gweeds9]

Hi there! Good news—the missing kernel piece is now ready and has been tested on hardware.

I've written hid-ayaneo, a HID driver for the AYANEO 3's detachable controller, porting the protocol that Handheld Daemon implemented in userspace (credit @antheas — the hhd Ayaneo3Hidraw code was the reference) onto the ayaneo-ec foundation. Code: https://github.com/matmartinez/ayaneo-3-bazzite-compat/tree/main/hid-ayaneo

It binds the controller's vendor HID interface (1c4f:0002, application usage 0xff000001, DMI-gated to the AYANEO 3 since that VID/PID is a generic SigmaMicro ID) and exposes:

• Module identification — sysfs module_left / module_right (the raw module-type IDs, e.g. 0x04 Cross/Joystick, 0x50 Joystick\ABXY; 16 known types)
• Software eject — sysfs eject, accepts left/right/both, blocks until the firmware confirms the release handshake (~4s)
• RGB — a multicolor LED class device named ayaneo:rgb:joystick_rings (the name InputPlumber's 50-ayaneo_3.yaml already expects)

EC power-off is deliberately not done by the driver — the full pop-out flow is eject → wait for the write to return → write 0 to ayaneo-ec's controller_power, i.e. exactly the orchestration a plugin/userspace layer should own, per the two-part-handshake layering described here.

Verified end-to-end on an AYANEO 3 running Bazzite 44 (OGC kernel 7.2.0-ogc4.1): a physical eject → module released → reinsert → controller_modules back to both → power on → controller re-enumerates (custom mode persists in flash) → driver rebinds and reads module IDs again. RGB and identification also confirmed.

--

So before I submit this to LKML (and to OGC kernel-packages so Bazzite can carry it), I'd love feedback on the sysfs interface from @pastaq / @antheas — attribute names, whether eject should be synchronous, whether module IDs should be decoded to strings in-kernel or left raw for userspace, anything that would make the OpenGamepadUI plugin's life easier. I'm planning to work on that plugin next, so if there's existing WIP or preferred plugin structure for it, pointers welcome.

I’m open to testing this. How can I? Is it built into the 44 kernel or do I have to do anything else?

[pastaq]

That's amazing. If you want a review of the driver prior to submitting to LKML please submit it to the OGC unstable kernel. That isn't strictly necessary though.

The EC portion of the interface is already present in the ayaneo-ec driver, so that just needs to be hooked up in userspace to this sysfs interface.

Be aware that Antheas won't be able to see your tags here or respond, he's banned from all ShadowBlip projects.

[matmartinez]

Thanks @pastaq! A few updates since that comment:

Driver review: already submitted to OGC — OpenGamingCollective/linux#101 (targeting features/ayaneo, checkpatch-clean with MAINTAINERS + Documentation/ABI/ entries) plus OpenGamingCollective/kernel-packages#35 for CONFIG_HID_AYANEO=m. If "unstable kernel" means a different target than the features/* branch flow, happy to redirect. And thanks for the heads-up about Antheas — I'll CC him directly on the LKML series so he can weigh in there.

The OGUI plugin already exists and works. Quick Bar card in overlay mode on Bazzite 44, layout modeled on AYANEO's native MagicModule panel (state-carrying pop buttons + Pop Both + the L/R-not-interchangeable footer hint), talking to the two drivers exactly as you describe — eject on hid-ayaneo, then controller_power on ayaneo-ec, with auto-repower on reinsert. Verified through full physical pop/reinsert cycles driven from the UI. Code: https://github.com/matmartinez/ayaneo-3-bazzite-compat/tree/main/ogui-plugin

Two things from building it that need your input:

1. Overlay mode: plugins initialize under an orphaned PluginManager and never enter the scene tree (_ready never fires) #535 — in overlay mode, plugins initialize under an orphaned PluginManager and _ready never fires (silently, since release builds suppress script errors). The plugin carries a reparenting workaround; details and suggested fixes in the issue.
2. Where should this live? I can do a proper release zip + PR to the OpenGamepadUI-plugins registry — but since plugin zips can't ship the udev rule needed for unprivileged sysfs access, in-tree platform code (with your pkexec pattern) might be the better fit. Your call; the backend/card code ports to either.

@Gweeds9 — yes please! Testing guide: https://github.com/matmartinez/ayaneo-3-bazzite-compat/blob/main/TESTING.md. It's not in the Bazzite 44 kernel yet, so there's a one-time driver build (Bazzite ships everything needed — it's make + insmod, ~5 min total), a udev rule, and a plugin zip from the repo's releases page. The driver needs re-insmod after each reboot until the OGC kernel PR lands. Module IDs from dmesg + what works/doesn't here would be super helpful.

[pastaq]

The udev rule can be PR to live in OpenGamepadUI as a prerequisite for the plug-in being added to the plugin store.

[pastaq]

unstable is a separate repo used for development, testing, and review prior to submitting upstream.

https://github.com/OpenGamingCollective/linux-unstable

[matmartinez]

@pastaq both done, thanks for the direction!

• Driver review: HID: ayaneo: Add AYANEO 3 detachable controller driver OpenGamingCollective/linux-unstable#3 (same commit rebased onto its master; also cross-linked from [FOR-UPSTREAM] HID: ayaneo: Add AYANEO 3 detachable controller driver OpenGamingCollective/linux#101 — happy to close whichever is redundant).
• Udev rule: rootfs: Add udev rule for AYANEO 3 magic module controls #536 — grants unprivileged access to eject/reset (hid-ayaneo) and controller_power (ayaneo-ec). Once that lands I'll do the release zip + registry PR to OpenGamepadUI-plugins for the plugin itself.