# darkwingtori/xbox-series-wiiu-relay architecture

> Architecture diagram of the GitHub repository darkwingtori/xbox-series-wiiu-relay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/darkwingtori/xbox-series-wiiu-relay
- Repository: https://github.com/darkwingtori/xbox-series-wiiu-relay

## Overview

This ESP32 firmware relays Xbox Series X|S input to a Wii U running Bloopair by bridging BLE HID-over-GATT to Classic Bluetooth HID, impersonating an Xbox One S controller. At startup, it connects to the Xbox before advertising to the Wii U; input reports travel toward the console, while rumble reports return to the controller. The report layout and advertised HID descriptor support the bridge. The README documents the end-to-end workflow; source excerpts show callback wiring and protocol handling, though some hardware-specific behavior remains an acknowledged assumption.

Main entry points: [`main/main.c`](https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/main.c) (Relay startup and callbacks), [`main/ble_central.c`](https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/ble_central.c) (BLE central), [`main/hid_peripheral.c`](https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/hid_peripheral.c) (Classic HID peripheral), [`main/relay_report.h`](https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/relay_report.h) (Shared report layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Relay orchestration"]
  node_app["Relay startup and callbacks<br/>[main.c]"]
end

subgraph group_ble["Xbox BLE link"]
  node_blelink["BLE central<br/>[ble_central.c]"]
end

subgraph group_protocol["HID report formats"]
  node_reports["Shared report layout<br/>[relay_report.h]"]
  node_descriptor["HID descriptor<br/>[hid_descriptor.h]"]
end

subgraph group_classic["Wii U Classic HID"]
  node_hiddevice["Classic HID peripheral<br/>[hid_peripheral.c]"]
end

node_xbox(("Xbox controller"))
node_wiiu(("Wii U / Bloopair"))

node_app -->|"starts connection"| node_blelink
node_blelink -->|"scans and connects"| node_xbox
node_xbox -->|"notifies input"| node_blelink
node_blelink -->|"calls input callback"| node_app
node_app -->|"forwards input"| node_hiddevice
node_hiddevice -->|"advertises and sends HID"| node_wiiu
node_wiiu -->|"sends rumble report"| node_hiddevice
node_hiddevice -->|"calls output callback"| node_app
node_app -->|"forwards rumble"| node_blelink
node_blelink -->|"writes output report"| node_xbox
node_app -->|"checks report IDs"| node_reports
node_hiddevice -->|"registers descriptor"| node_descriptor
node_reports -->|"matches Bloopair layout"| node_wiiu

click node_app "https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/main.c"
click node_blelink "https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/ble_central.c"
click node_reports "https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/relay_report.h"
click node_descriptor "https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/hid_descriptor.h"
click node_hiddevice "https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/hid_peripheral.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app toneBlue
class node_blelink toneAmber
class node_reports,node_descriptor toneMint
class node_hiddevice toneRose
class node_xbox,node_wiiu toneIndigo
```

## Components

### Relay orchestration

- [Relay startup and callbacks](https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/main.c): `main/main.c`

### Xbox BLE link

- [BLE central](https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/ble_central.c): `main/ble_central.c`

### HID report formats

- [Shared report layout](https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/relay_report.h): `main/relay_report.h`
- [HID descriptor](https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/hid_descriptor.h): `main/hid_descriptor.h`

### Wii U Classic HID

- [Classic HID peripheral](https://github.com/darkwingtori/xbox-series-wiiu-relay/blob/main/main/hid_peripheral.c): `main/hid_peripheral.c`

### Other components

- **Xbox controller**
- **Wii U / Bloopair**

## Connections

- Relay startup and callbacks → BLE central: starts connection (evidence: `main/main.c`)
- BLE central → Xbox controller: scans and connects (evidence: `README.md`)
- Xbox controller → BLE central: notifies input (evidence: `main/ble_central.c`)
- BLE central → Relay startup and callbacks: calls input callback (evidence: `main/ble_central.c`)
- Relay startup and callbacks → Classic HID peripheral: forwards input (evidence: `main/main.c`)
- Classic HID peripheral → Wii U / Bloopair: advertises and sends HID (evidence: `README.md`)
- Wii U / Bloopair → Classic HID peripheral: sends rumble report (evidence: `main/hid_peripheral.c`)
- Classic HID peripheral → Relay startup and callbacks: calls output callback (evidence: `main/hid_peripheral.c`)
- Relay startup and callbacks → BLE central: forwards rumble (evidence: `main/main.c`)
- BLE central → Xbox controller: writes output report (evidence: `main/ble_central.c`)
- Relay startup and callbacks → Shared report layout: checks report IDs (evidence: `main/main.c`)
- Classic HID peripheral → HID descriptor: registers descriptor (evidence: `main/hid_peripheral.c`)
- Shared report layout → Wii U / Bloopair: matches Bloopair layout (evidence: `README.md`)
