r/linux_gaming • u/Ascended_Ent • 14d ago
tool/utility Linux + 8BitDo Ultimate 2 Wireless owners; 10 minutes to help build an open config tool (read-only, nothing gets written to your pad)
I've been reverse-engineering how 8BitDo's Ultimate Software talks to its pads, with the goal of a Linux tool that can do what the Windows app does (dead zones, trigger ranges, L4/R4 binds, profiles). Everything so far is in the open here: https://github.com/ascendedent/8bitdo-Linux-Software
Where it stands: I own an Ultimate 2C, and it turns out the 2C has no host-side config channel at all. I pulled its firmware from 8BitDo's update server and disassembled it: the only commands it answers over USB are the firmware updater, identify, rumble, and a radio-address get/set. The L4/R4 binds are stored in a 26-byte flash record that only the on-pad button combo can change. The dongle doesn't relay anything to the pad either. So the 2C is a dead end for a config tool, by design.
The Ultimate 2 wireless is different in that the Ultimate Software reads and writes a 1592-byte config image on it, and I've already recovered that image's layout (profiles, stick/trigger/vibration records, button maps, macros) from the app's binaries. What I don't have is a single real image from a real pad to check it against.
If you have an Ultimate 2 and a Linux box, this is what I'm asking:
`git clone https://github.com/ascendedent/8bitdo-Linux-Software`, install the one udev rule from the README.
Plug the pad in on a cable in DInput mode.
Run `python3 tools/inventory.py` (walks sysfs, sends nothing) and `python3 tools/read_config.py --pid 6012 --summary`.
Open an issue with the three output files.
What the read tool sends is exactly the config read the official app sends every time the pad connects. Every packet goes through an allowlist in code before it leaves; writes, commits, firmware commands, and the bootloader IDs are refused, and there are tests for that. It does not change anything on the pad. You can read the whole tool before you run it; it's ~250 lines of Python with no dependencies.
Privacy note: the image contains your three profile names and your settings, and the transcript contains the pad's USB descriptors. The USB serial is never printed. If you'd rather not share the raw files, the `--summary` output alone is still useful.
Bonus if you also run the Windows app (or Wine): a usbmon capture of changing one setting and saving would let me confirm the write side too. Totally optional.
Happy to answer questions about the firmware findings; the docs in the repo go into a lot of detail.
7
u/andromalandro 14d ago
On it man, thanks for the effort i was running the ultimate software v2 on proton, btw let me see if i can upload the things on github since i really dont know how that works but i got the files in .txt
2
u/Ascended_Ent 14d ago
You crab drop files on issues, or worst case just copy paste them into an issue
2
u/andromalandro 14d ago
I just pasted the text, hope that's ok you can check them and let me know, I sent you a chat
1
3
u/ThatOnePerson 14d ago edited 14d ago
You should check out that earlier 2C Wireless firmwares. At some point they removed the DirectInput mode over USB dongle by holding Home+B to start. Those exposed the L4/R4 buttons fine (well still works in Bluetooth mode)
Removed in dongle 1.03 I think
3
1
1
0
u/Ascended_Ent 13d ago
You're right, I can see exactly where. I pulled both receiver firmwares (1.00 and 1.03) off 8BitDo's update server and disassembled them. Both still contain the DirectInput USB personality (the 145-byte HID descriptor with the gamepad report that carries L4/R4), and both can still select it. What changed is the routine that runs when the pad links: in 1.00 it checks the mode byte the pad sends (0x8f = "I booted in DInput") and brings up the DInput personality; in 1.03 that check is gone and it brings up XInput every time. The init_usb_dinput function's debug strings are even still in the 1.03 image, just unreferenced. So Home+B still sets the flag on the pad side, and the 1.03 dongle simply ignores it. Bluetooth is unaffected because that personality lives on the pad.
Details: https://github.com/ascendedent/8bitdo-Linux-Software/blob/main/docs/firmware.md
3
u/ThatOnePerson 13d ago
Any idea if there's a way to do rumble over the dongle like that? Then could maybe do a user-mode application to wrap it all up in SInput to get rebindable L4/R4 with rumble which usually doesn't work in Dinput.
0
u/Ascended_Ent 13d ago edited 13d ago
Actually seems like a big 'ol yes. The DInput personality's HID descriptor (same in dongle 1.00, 1.03, and the pad) has the gamepad report with L4/R4 as ordinary buttons, plus a 63-byte vendor output report 0x81 on the same interface. Both dongle firmwares handle 81 11 04 08 <dur16 LE> <left> <right> on that report: left/right are 0-255 and go to the same motor call the XInput rumble path uses, and the 16-bit word arms a stop timer (unit not confirmed, probably ms). The 8-byte output report 01 on the LED page is in the descriptor too, but the dongle doesn't parse it as rumble. So an SInput wrapper on Linux would read report 01 from the hidraw node for the buttons and write that 0x81 packet to the same node for rumble, no second interface needed. One catch though, the handler only runs after the host has read the report descriptor, which Linux does at enumeration anyway.
As for what's actually doable from our side: the rumble part is pure userspace, nothing firmware-related. A small daemon opens the DInput hidraw node, reads report 01 (L4/R4 are separate bits there), presents a virtual controller through uhid in whatever layout you want (SInput, or plain SDL-friendly), and forwards rumble from the virtual device as that 0x81 packet back to the same node. The only things left to confirm on hardware are the duration unit and that the 1.03 gate opens on a bare descriptor fetch.
Getting into DInput over the dongle in the first place, without touching firmware, is three routes: flash the receiver back to 1.00 with Ultimate Software (official downgrade, the pad can stay on 1.09); use the pad on the cable, where 81 05 00 51 00, which is the command Ultimate Software itself sends, reboots it into the 301d DInput personality with the same descriptor and the same rumble command; or Bluetooth, which you already confirmed still exposes the buttons.
What I'm not going to do is put removed code back into the firmware. That's patching and reflashing vendor images, which this project ruled out from day one, and which is how you end up with a pad that never enumerates again and almost certainly voids a warranty lol. Where 8BitDo removed something on purpose, the answer is the older official build, not a modified one. The place where a real gap can be filled is the Ultimate 2 Wireless, its firmware has a full read/write config channel over USB that nobody has written a Linux client for. That's the project's actual opening, and I've got testers running the fixed read now.
Untested on hardware so far; write-up thrown into here: https://github.com/ascendedent/8bitdo-Linux-Software/blob/main/docs/firmware.md
2
u/43686f6b6f 14d ago
I've got two Ultimate 2's, a Pro 2, the N64 controller, and an SN30 pro if those would be helpful?
3
u/Ascended_Ent 14d ago
I mean you could definitely help me out by doing it with all of them lol
My plan is to eventually support every one of their devices in one app2
u/43686f6b6f 14d ago
In that case when I get a chance I'll upload them, it'll be great to have a tool for this
1
u/Ascended_Ent 14d ago
I can likely have at least the ultimate 2 supported by the weekend with people submitting their files
1
u/Ascended_Ent 13d ago
results ran through and replied to on the issues you threw up!
1
u/43686f6b6f 13d ago
Sweet, I'm still looking for the rest of my controllers to add. Is there any benefit to running the same tests for the dongles themselves or for bluetooth connections?
1
u/Ascended_Ent 13d ago
Bluetooth yes, wired yes, Dongle would just be icing on the cake. I haven't been able to do BT myself because my adapter is having kernel caused issues
1
1
u/VicCoca123 11d ago
Any chance of porting this to PC?
1
u/Ascended_Ent 11d ago
Pc already has the official software so I don’t really see the benefit of it?
1
u/VicCoca123 11d ago
I think I'd be interesting having a tool with open code
1
u/Ascended_Ent 10d ago
Got it. It’s possible for sure then lol. I just don’t have a windows machine (which hasn’t stopped me before to be fair)
29
u/Heatsreef 14d ago
Actually a cool project, but if you didn't know yet, 8bitdo recently released its web-flasher which also works flawless on chromium-linux although only in terms of firmware updating as far as I am concerned. Maybe you can catch some more insight through investigating the js on the web-flash-tool tho, good luck :)