steam-frame/H4zeyaf--Ghostcontrol-PS5-USB-Controller-Patcher-Cyclone2
1
0 Fork 0
mirror of https://github.com/H4zeyaf/Ghostcontrol-PS5-USB-Controller-Patcher-Cyclone2.git synced 2026-10-06 07:00:21 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update README with fork documentation, features, and credits

Browse Source
This commit is contained in:
Hamza committed 2026-09-12 06:57:24 +01:00
1 parent c374f1aa66
commit b76e32f69e
1 file changed
+70 -59
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+70 -59
View File
@@ -1,102 +1,113 @@
# Ghostcontrol — by StonedModder
# Ghostcontrol (PS5 USB Controller Patcher)
If you enjoy my work - please consider donating to my BTC address:
A PlayStation 5 payload that enables third-party USB and 2.4GHz wireless dongle controllers on jailbroken PS5 consoles. It reads raw USB HID / XInput reports from connected controllers and injects them into a virtual DualSense controller via the PS5's `scePadVirtualDeviceInsertData` (VDI) subsystem.
`bc1qa9zfgnccajsw8vg7k287qz5a7apf8pefj5jjx5`
Use third-party USB controllers on PS5. Reads USB HID input from a plugged-in controller and injects it into a virtual DualSense via the PS5's `scePadVirtualDeviceInsertData` path (Ghostpad VDI path).
**Tested controller:** 8BitDo Ultimate 2 in Nintendo Switch Pro Controller mode (VID=0x057e PID=0x2009)
---
https://github.com/user-attachments/assets/6583b1c2-3d3d-4f2e-9e79-689121fea4a3
## Features
- 60Hz input streaming from USB HID controller → virtual DualSense
- PS5 notifications: startup, controller connect/disconnect, detected controller type
- User assignment: virtual DualSense is bound to the foreground user on startup
- Full button mapping: face buttons, triggers, sticks, dpad, L3/R3, PS button
- Auto-reconnect on controller unplug/replug
---
## Requirements
- PS5 with kernel exploit (tested on jailbroken PS5)
- [ps5-payload-sdk](https://github.com/ps5-payload-dev/sdk)
- USB controller — see supported list below
This repository is a fork of [StonedModder's Ghostcontrol](https://github.com/StonedModder/Ghostcontrol---PS5-USB-Controller-Patcher), extending compatibility to **GameSir Cyclone 2** (and standard XInput / Xbox 360 wireless controllers) with improved 125Hz continuous input injection.
---
## Supported Controllers
| Controller | Mode | VID:PID | Status |
|-----------|------|---------|--------|
| 8BitDo Ultimate 2 | Nintendo Switch Pro | 057e:2009 | ✅ Working |
| 8BitDo Ultimate 2 | Native | 2dc8:310b | Untested |
| GameSir Cyclone 2 | XInput / Xbox 360 | 3537:100b | ✅ Added Support |
| Controller | Connection / Mode | VID:PID | Status |
|---|---|---|---|
| **GameSir Cyclone 2** | 2.4GHz Wireless Dongle (PC / XInput mode) | `3537:100b` | ✅ Fully Working (Sticks, Triggers, D-Pad, Buttons, Home) |
| **8BitDo Ultimate 2** | Nintendo Switch Pro mode | `057e:2009` | ✅ Working |
| **8BitDo Ultimate 2** | Native mode | `2dc8:310b` | Untested |
| **Xbox One S / Series** | Wired USB | `045e:02ea` / `045e:0b12` | ✅ Supported |
See `othercontrollersGuide.md` for adding new controllers.
---
## Build
## Features
- **High-Frequency Continuous Injection**: 125Hz dedicated injection thread ensuring zero dropped inputs, responsive navigation, and smooth analog stick control across games and system menus.
- **XInput & Xbox 360 Wireless Protocol**: Native packet parsing with deadzone calibration, analog trigger mapping, and Guide/Home button handling.
- **PS5 On-Screen Notifications**: Informative notifications on controller detection, user assignment, and disconnect.
- **User Assignment Dialog**: Virtual DualSense binds cleanly to the foreground profile on startup or interactive user assignment.
- **Auto-Reconnect**: Seamless re-initialization upon controller or dongle unplug/replug.
---
## Requirements
- PS5 on a compatible jailbreakable firmware (with kernel exploit / elf loader support).
- [ps5-payload-sdk](https://github.com/ps5-payload-dev/sdk) to compile from source.
- Compatible USB controller or wireless dongle.
> **Note:** In compliance with copyright guidelines, pre-compiled payload binaries (`.elf`) are not distributed in this repository. You can compile the payload using the PS5 Payload SDK.
---
## Building from Source
Ensure you have installed the [PS5 Payload SDK](https://github.com/ps5-payload-dev/sdk) and have the environment configured:
```sh
cd payload
export PS5_PAYLOAD_SDK=/path/to/ps5-payload-sdk
make clean all
```
Output: `ghost-control-ps5.elf`
This will produce the compiled payload: `ghost-control-xbox-ps5.elf`.
## Deploy
---
## Deployment
Send the compiled ELF to your PS5 running an ELF loader (e.g. on port 9021 or 9020):
```sh
# Deploy to PS5 (replace IP)
nc -w 5 192.168.1.xxx 9021 < ghost-control-ps5.elf
# Replace with your PS5's IP address
nc -w 5 192.168.1.xxx 9021 < payload/ghost-control-xbox-ps5.elf
```
Or set `PS5_HOST` in your environment:
Or deploy directly via Makefile:
```sh
make deploy PS5_HOST=192.168.1.xxx
cd payload
make deploy PS5_HOST=192.168.1.xxx PORT=9021
```
---
## How It Works
1. **VDA**: Creates a virtual DualSense via `scePadVirtualDeviceAddDevice(type=3)`
2. **klog capture**: Monitors klogsrv TCP to detect the `DEVICE_ADDED` event and get the device handle
3. **force_bind**: Binds the virtual device to the foreground user via ShellUI MBus IPC
4. **USB HID thread**: Detaches `usb_hid0` from the controller, opens raw USB FS endpoints, runs the Nintendo Switch Pro Controller USB handshake, then reads 60Hz input reports
5. **VDI inject**: Parses HID reports into `ScePadData` and calls `scePadVirtualDeviceInsertData` at 60Hz
1. **Virtual Device Creation (VDA)**: Creates a virtual DualSense pad via `scePadVirtualDeviceAddDevice(type=3)`.
2. **Handle Acquisition**: Captures kernel logging events (`klog`) to obtain the virtual device handle.
3. **User Binding**: Associates the virtual controller with the foreground user session via ShellUI MBus IPC (`shellui_pad.c`).
4. **USB HID / XInput Engine**: Detaches the console's default kernel HID driver from the device endpoint, opens raw USB FS endpoints, runs any required initialization handshakes, and reads controller reports.
5. **Continuous Injection (VDI)**: Decodes controller packets into native `ScePadData` structures and feeds them continuously at 125Hz through `scePadVirtualDeviceInsertData`.
See `ProControllerResearch.md` for the full research documentation on the USB HID protocol.
See `ProControllerResearch.md` for research documentation on the USB HID protocol.
---
## Files
## File Structure
| File | Description |
|------|-------------|
| `gc_main.c` | Main payload — VDA, VDI, USB HID thread, button parsing |
| `shellui_pad.c` | ShellUI PT_ATTACH helper for force_bind via MBus |
| `shellui_pad.h` | Header for shellui_pad |
| `controller_xbox360.c` | Driver for Xbox 360 / XInput wireless controllers (GameSir Cyclone 2, etc.) |
| `controller_xbox360.h` | Header for Xbox 360 driver |
| `Makefile` | Build system |
| File / Directory | Description |
|---|---|
| `payload/gc_main.c` | Core payload: virtual device lifecycle, USB FS listener, continuous injection thread |
| `payload/controller_xbox360.c` | Xbox 360 / XInput driver (GameSir Cyclone 2, wireless dongles) |
| `payload/controller_xbox360.h` | Header for Xbox 360 / XInput driver |
| `payload/controller_xbox.c` | Xbox One / Series S wired driver |
| `payload/controller_nintendo.c` | Nintendo Switch Pro / 8BitDo driver |
| `payload/shellui_pad.c` | ShellUI PT_ATTACH helper for user binding |
| `payload/usb_helpers.c` | USB FS transfer helpers |
| `payload/Makefile` | Compilation and deployment recipes |
| `ProControllerResearch.md` | Full USB protocol research for Nintendo Switch Pro Controller |
| `othercontrollersGuide.md` | Guide for adding other USB HID controllers |
---
## Credits & Acknowledgements
- **[StonedModder](https://github.com/StonedModder)** — Creator of the original [Ghostcontrol](https://github.com/StonedModder/Ghostcontrol---PS5-USB-Controller-Patcher) project and research into the PS5 Virtual Device Interface.
- **[H4zeyaf](https://github.com/H4zeyaf)** — GameSir Cyclone 2 support, continuous 125Hz injection implementation, and XInput driver integration.
- Contributors and developers of the [ps5-payload-sdk](https://github.com/ps5-payload-dev/sdk).
---
## License
GPL-3.0-or-later