# tommywabg/switch2connect architecture

> Architecture diagram of the GitHub repository tommywabg/switch2connect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tommywabg/switch2connect
- Repository: https://github.com/tommywabg/switch2connect

## Overview

Switch 2 Connect is a Windows controller-connection and emulation application, with companion ESP32-S3 BLE-bridge firmware. The main workflow is to discover a Switch controller over Bluetooth, USB, or the bridge; process its input and motion; then expose it through a selected virtual-controller backend. The README also documents driver management, wired-controller handling, keyboard and gyro mappings, and DualSense haptics. Source excerpts and the index support the core orchestration and selected calls; broader capability links use README evidence, while unsampled implementation details are not inferred.

Main entry points: [`src/controller.py`](https://github.com/tommywabg/switch2connect/blob/main/src/controller.py) (Controller runtime), [`src/discoverer.py`](https://github.com/tommywabg/switch2connect/blob/main/src/discoverer.py) (Controller discovery), [`src/virtual_controller.py`](https://github.com/tommywabg/switch2connect/blob/main/src/virtual_controller.py) (Virtual controller), [`src/usb_serial_bridge.py`](https://github.com/tommywabg/switch2connect/blob/main/src/usb_serial_bridge.py) (Bridge serial client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connection["Connection and discovery"]
  node_app["Application UI<br/>[gui.py]"]
  node_discovery["Controller discovery<br/>[discoverer.py]"]
  node_wired["Wired HID controller"]
end

subgraph group_input["Input processing"]
  node_controller["Controller runtime<br/>[controller.py]"]
  node_config["Profiles and mappings<br/>[config.py]"]
  node_gyro["Gyro processing<br/>[gyro.py]"]
  node_keyboard["Keyboard output<br/>[keyboard_output.py]"]
end

subgraph group_outputs["Emulation and feedback"]
  node_virtual["Virtual controller"]
  node_winuhid["WinUHid backend<br/>[winuhid_client.py]"]
  node_usbip["USBIP server<br/>[usbip_server.py]"]
  node_dualsenseusbip["DualSense USBIP"]
  node_haptics["DualSense haptics"]
  node_structs["DualSense reports"]
end

subgraph group_platform["Windows integration"]
  node_driver["Driver management"]
  node_hidhide["HidHide management<br/>[hidhide.py]"]
  node_pnp["PnP configuration<br/>[pnp_cfgmgr.py]"]
  node_power["Power policy<br/>[power_saving.py]"]
  node_timer["Timer resolution"]
end

subgraph group_bridge["ESP32 bridge"]
  node_bridgeclient["Bridge serial client"]
  node_firmware["ESP32-S3 firmware<br/>[main.c]"]
  node_firmwareblue["Bluedroid firmware<br/>[main.c]"]
end

node_user(("Player"))
node_bluetooth["Bluetooth controller"]

node_user -->|"configures"| node_app
node_app -.->|"starts discovery"| node_discovery
node_discovery -->|"creates controllers"| node_controller
node_discovery -->|"scans USB"| node_wired
node_bluetooth -->|"advertises"| node_discovery
node_discovery -->|"detects bridge"| node_bridgeclient
node_bridgeclient -.->|"sends commands"| node_firmware
node_bridgeclient -.->|"sends commands"| node_firmwareblue
node_controller -->|"reads mappings"| node_config
node_controller -->|"uses motion processing"| node_gyro
node_controller -->|"emits key input"| node_keyboard
node_wired -->|"provides input"| node_controller
node_bridgeclient -->|"provides input"| node_controller
node_controller -->|"routes input"| node_virtual
node_virtual -->|"uses backend"| node_winuhid
node_virtual -->|"uses backend"| node_usbip
node_virtual -->|"starts PS5 server"| node_dualsenseusbip
node_dualsenseusbip -->|"uses reports"| node_structs
node_dualsenseusbip -->|"uses haptic processing"| node_haptics
node_app -->|"manages drivers"| node_driver
node_driver -->|"checks devices"| node_pnp
node_driver -->|"checks HidHide"| node_hidhide
node_wired -->|"supports hiding"| node_hidhide
node_power -->|"sets timer policy"| node_timer
node_controller -->|"observes policy"| node_power
node_user -->|"pairs by sync"| node_bluetooth

click node_app "https://github.com/tommywabg/switch2connect/blob/main/src/gui.py"
click node_discovery "https://github.com/tommywabg/switch2connect/blob/main/src/discoverer.py"
click node_wired "https://github.com/tommywabg/switch2connect/blob/main/src/usb_hid_controller.py"
click node_bridgeclient "https://github.com/tommywabg/switch2connect/blob/main/src/usb_serial_bridge.py"
click node_firmware "https://github.com/tommywabg/switch2connect/blob/main/ESP32-S3%20firmware/esp32s3_usb_bridge/main/main.c"
click node_firmwareblue "https://github.com/tommywabg/switch2connect/blob/main/ESP32-S3%20firmware/esp32s3_usb_bridge_bluedroid/main/main.c"
click node_controller "https://github.com/tommywabg/switch2connect/blob/main/src/controller.py"
click node_config "https://github.com/tommywabg/switch2connect/blob/main/src/config.py"
click node_gyro "https://github.com/tommywabg/switch2connect/blob/main/src/gyro.py"
click node_keyboard "https://github.com/tommywabg/switch2connect/blob/main/src/keyboard_output.py"
click node_virtual "https://github.com/tommywabg/switch2connect/blob/main/src/virtual_controller.py"
click node_winuhid "https://github.com/tommywabg/switch2connect/blob/main/src/winuhid_client.py"
click node_usbip "https://github.com/tommywabg/switch2connect/blob/main/src/usbip_server.py"
click node_dualsenseusbip "https://github.com/tommywabg/switch2connect/blob/main/src/usbip_dualsense_server.py"
click node_haptics "https://github.com/tommywabg/switch2connect/blob/main/src/dualsense_haptic.py"
click node_structs "https://github.com/tommywabg/switch2connect/blob/main/src/dualsense_structs.py"
click node_driver "https://github.com/tommywabg/switch2connect/blob/main/src/driver_install_helper.py"
click node_hidhide "https://github.com/tommywabg/switch2connect/blob/main/src/hidhide.py"
click node_pnp "https://github.com/tommywabg/switch2connect/blob/main/src/pnp_cfgmgr.py"
click node_power "https://github.com/tommywabg/switch2connect/blob/main/src/power_saving.py"
click node_timer "https://github.com/tommywabg/switch2connect/blob/main/src/timer_resolution.py"

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,node_discovery,node_wired toneBlue
class node_controller,node_config,node_gyro,node_keyboard toneAmber
class node_virtual,node_winuhid,node_usbip,node_dualsenseusbip,node_haptics,node_structs toneMint
class node_driver,node_hidhide,node_pnp,node_power,node_timer toneRose
class node_bridgeclient,node_firmware,node_firmwareblue,node_user,node_bluetooth toneIndigo
```

## Components

### Connection and discovery

- [Application UI](https://github.com/tommywabg/switch2connect/blob/main/src/gui.py): `src/gui.py`
- [Controller discovery](https://github.com/tommywabg/switch2connect/blob/main/src/discoverer.py): `src/discoverer.py`
- [Wired HID controller](https://github.com/tommywabg/switch2connect/blob/main/src/usb_hid_controller.py): `src/usb_hid_controller.py`

### Input processing

- [Controller runtime](https://github.com/tommywabg/switch2connect/blob/main/src/controller.py): `src/controller.py`
- [Profiles and mappings](https://github.com/tommywabg/switch2connect/blob/main/src/config.py): `src/config.py`
- [Gyro processing](https://github.com/tommywabg/switch2connect/blob/main/src/gyro.py): `src/gyro.py`
- [Keyboard output](https://github.com/tommywabg/switch2connect/blob/main/src/keyboard_output.py): `src/keyboard_output.py`

### Emulation and feedback

- [Virtual controller](https://github.com/tommywabg/switch2connect/blob/main/src/virtual_controller.py): `src/virtual_controller.py`
- [WinUHid backend](https://github.com/tommywabg/switch2connect/blob/main/src/winuhid_client.py): `src/winuhid_client.py`
- [USBIP server](https://github.com/tommywabg/switch2connect/blob/main/src/usbip_server.py): `src/usbip_server.py`
- [DualSense USBIP](https://github.com/tommywabg/switch2connect/blob/main/src/usbip_dualsense_server.py): `src/usbip_dualsense_server.py`
- [DualSense haptics](https://github.com/tommywabg/switch2connect/blob/main/src/dualsense_haptic.py): `src/dualsense_haptic.py`
- [DualSense reports](https://github.com/tommywabg/switch2connect/blob/main/src/dualsense_structs.py): `src/dualsense_structs.py`

### Windows integration

- [Driver management](https://github.com/tommywabg/switch2connect/blob/main/src/driver_install_helper.py): `src/driver_install_helper.py`
- [HidHide management](https://github.com/tommywabg/switch2connect/blob/main/src/hidhide.py): `src/hidhide.py`
- [PnP configuration](https://github.com/tommywabg/switch2connect/blob/main/src/pnp_cfgmgr.py): `src/pnp_cfgmgr.py`
- [Power policy](https://github.com/tommywabg/switch2connect/blob/main/src/power_saving.py): `src/power_saving.py`
- [Timer resolution](https://github.com/tommywabg/switch2connect/blob/main/src/timer_resolution.py): `src/timer_resolution.py`

### ESP32 bridge

- [Bridge serial client](https://github.com/tommywabg/switch2connect/blob/main/src/usb_serial_bridge.py): `src/usb_serial_bridge.py`
- [ESP32-S3 firmware](https://github.com/tommywabg/switch2connect/blob/main/ESP32-S3%20firmware/esp32s3_usb_bridge/main/main.c): `ESP32-S3 firmware/esp32s3_usb_bridge/main/main.c`
- [Bluedroid firmware](https://github.com/tommywabg/switch2connect/blob/main/ESP32-S3%20firmware/esp32s3_usb_bridge_bluedroid/main/main.c): `ESP32-S3 firmware/esp32s3_usb_bridge_bluedroid/main/main.c`

### Other components

- **Player**
- **Bluetooth controller**

## Connections

- Player → Application UI: configures (evidence: `README.md`)
- Application UI → Controller discovery: starts discovery
- Controller discovery → Controller runtime: creates controllers (evidence: `src/discoverer.py`)
- Controller discovery → Wired HID controller: scans USB (evidence: `src/discoverer.py`)
- Bluetooth controller → Controller discovery: advertises (evidence: `README.md`)
- Controller discovery → Bridge serial client: detects bridge (evidence: `src/discoverer.py`)
- Bridge serial client → ESP32-S3 firmware: sends commands
- Bridge serial client → Bluedroid firmware: sends commands
- Controller runtime → Profiles and mappings: reads mappings (evidence: `src/controller.py`)
- Controller runtime → Gyro processing: uses motion processing (evidence: `src/controller.py`)
- Controller runtime → Keyboard output: emits key input (evidence: `src/controller.py`)
- Wired HID controller → Controller runtime: provides input (evidence: `src/usb_hid_controller.py`)
- Bridge serial client → Controller runtime: provides input (evidence: `src/usb_serial_bridge.py`)
- Controller runtime → Virtual controller: routes input (evidence: `README.md`)
- Virtual controller → WinUHid backend: uses backend (evidence: `src/virtual_controller.py`)
- Virtual controller → USBIP server: uses backend (evidence: `src/virtual_controller.py`)
- Virtual controller → DualSense USBIP: starts PS5 server (evidence: `src/virtual_controller.py`)
- DualSense USBIP → DualSense reports: uses reports (evidence: `src/usbip_dualsense_server.py`)
- DualSense USBIP → DualSense haptics: uses haptic processing (evidence: `src/usbip_dualsense_server.py`)
- Application UI → Driver management: manages drivers (evidence: `README.md`)
- Driver management → PnP configuration: checks devices (evidence: `src/driver_install_helper.py`)
- Driver management → HidHide management: checks HidHide (evidence: `src/driver_install_helper.py`)
- Wired HID controller → HidHide management: supports hiding (evidence: `src/usb_hid_controller.py`)
- Power policy → Timer resolution: sets timer policy (evidence: `src/power_saving.py`)
- Controller runtime → Power policy: observes policy (evidence: `src/controller.py`)
- Player → Bluetooth controller: pairs by sync (evidence: `README.md`)
