# jfedor2/wheel-adapter architecture

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

- Interactive diagram: https://gitdiagram.com/jfedor2/wheel-adapter
- Repository: https://github.com/jfedor2/wheel-adapter

## Overview

This firmware turns a Raspberry Pi Pico into a USB adapter: it reads a Logitech Driving Force-compatible wheel, presents a G29-style HID device to the PS5, and relays the console’s authentication exchange through a separate licensed controller. The principal flow is wheel input to a console-facing report; force-feedback output travels back to the wheel. Authentication proceeds through nonce reception, controller signing, and signature delivery. The sampled source shows these behaviors in `src/adapter.c` and the HID identity in `src/descriptors.c`; unsampled library internals are not mapped.

Main entry points: [`src/adapter.c`](https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c) (Controller signing exchange), [`src/descriptors.c`](https://github.com/jfedor2/wheel-adapter/blob/master/src/descriptors.c) (G29 HID identity), [`src/reports.h`](https://github.com/jfedor2/wheel-adapter/blob/master/src/reports.h) (Wheel report types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_wheel["Wheel handling"]
  node_wheel_mapping["Wheel input mapping<br/>[adapter.c]"]
  node_wheel_reports["Wheel report types<br/>[reports.h]"]
  node_force_feedback["Force feedback relay<br/>[adapter.c]"]
  node_wheel_setup["Wheel initialization<br/>[adapter.c]"]
end

subgraph group_auth["Authentication bridge"]
  node_nonce_intake["Nonce intake<br/>[adapter.c]"]
  node_controller_exchange["Controller signing exchange<br/>[adapter.c]"]
  node_signature_delivery["Signature delivery<br/>[adapter.c]"]
end

subgraph group_console["Console interface"]
  node_hid_reports["Console HID reports<br/>[adapter.c]"]
  node_hid_identity["G29 HID identity<br/>[descriptors.c]"]
end

subgraph group_runtime["Firmware runtime"]
  node_main_loop["Main loop<br/>[adapter.c]"]
end

node_ps5(("PS5 console"))
node_wheel_device(("Logitech wheel"))
node_auth_controller(("Licensed controller"))

node_main_loop -->|"runs callbacks"| node_wheel_mapping
node_main_loop -->|"runs task"| node_force_feedback
node_main_loop -->|"runs task"| node_wheel_setup
node_main_loop -->|"runs task"| node_controller_exchange
node_wheel_device -->|"sends reports"| node_wheel_mapping
node_wheel_mapping -->|"decodes as"| node_wheel_reports
node_wheel_mapping -->|"updates state"| node_hid_reports
node_ps5 -->|"requests reports"| node_hid_reports
node_hid_reports -->|"sends reports"| node_ps5
node_ps5 -->|"sends nonce"| node_nonce_intake
node_nonce_intake -->|"starts signing"| node_controller_exchange
node_controller_exchange -->|"requests signature"| node_auth_controller
node_auth_controller -->|"returns signature"| node_controller_exchange
node_controller_exchange -->|"stores signature"| node_signature_delivery
node_signature_delivery -->|"serves signature"| node_ps5
node_ps5 -->|"sends feedback"| node_force_feedback
node_force_feedback -->|"forwards feedback"| node_wheel_device
node_wheel_setup -->|"sends setup report"| node_wheel_device
node_hid_identity -->|"advertises identity"| node_ps5

click node_main_loop "https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c"
click node_wheel_mapping "https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c"
click node_wheel_reports "https://github.com/jfedor2/wheel-adapter/blob/master/src/reports.h"
click node_force_feedback "https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c"
click node_wheel_setup "https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c"
click node_nonce_intake "https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c"
click node_controller_exchange "https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c"
click node_signature_delivery "https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c"
click node_hid_reports "https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c"
click node_hid_identity "https://github.com/jfedor2/wheel-adapter/blob/master/src/descriptors.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_wheel_mapping,node_wheel_reports,node_force_feedback,node_wheel_setup toneBlue
class node_nonce_intake,node_controller_exchange,node_signature_delivery toneAmber
class node_hid_reports,node_hid_identity toneMint
class node_main_loop toneRose
class node_ps5,node_wheel_device,node_auth_controller toneIndigo
```

## Components

### Wheel handling

- [Wheel input mapping](https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c): `src/adapter.c`
- [Wheel report types](https://github.com/jfedor2/wheel-adapter/blob/master/src/reports.h): `src/reports.h`
- [Force feedback relay](https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c): `src/adapter.c`
- [Wheel initialization](https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c): `src/adapter.c`

### Authentication bridge

- [Nonce intake](https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c): `src/adapter.c`
- [Controller signing exchange](https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c): `src/adapter.c`
- [Signature delivery](https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c): `src/adapter.c`

### Console interface

- [Console HID reports](https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c): `src/adapter.c`
- [G29 HID identity](https://github.com/jfedor2/wheel-adapter/blob/master/src/descriptors.c): `src/descriptors.c`

### Firmware runtime

- [Main loop](https://github.com/jfedor2/wheel-adapter/blob/master/src/adapter.c): `src/adapter.c`

### Other components

- **PS5 console**
- **Logitech wheel**
- **Licensed controller**

## Connections

- Main loop → Wheel input mapping: runs callbacks
- Main loop → Force feedback relay: runs task
- Main loop → Wheel initialization: runs task
- Main loop → Controller signing exchange: runs task
- Logitech wheel → Wheel input mapping: sends reports
- Wheel input mapping → Wheel report types: decodes as
- Wheel input mapping → Console HID reports: updates state
- PS5 console → Console HID reports: requests reports
- Console HID reports → PS5 console: sends reports
- PS5 console → Nonce intake: sends nonce
- Nonce intake → Controller signing exchange: starts signing
- Controller signing exchange → Licensed controller: requests signature
- Licensed controller → Controller signing exchange: returns signature
- Controller signing exchange → Signature delivery: stores signature
- Signature delivery → PS5 console: serves signature
- PS5 console → Force feedback relay: sends feedback
- Force feedback relay → Logitech wheel: forwards feedback
- Wheel initialization → Logitech wheel: sends setup report
- G29 HID identity → PS5 console: advertises identity