# torvalds/scrollwheel architecture

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

- Interactive diagram: https://gitdiagram.com/torvalds/scrollwheel
- Repository: https://github.com/torvalds/scrollwheel

## Overview

This is RP2350 firmware for a DIY rotary control: an AS5600 magnetic angle sensor and switches become USB HID scroll, volume, and keyboard events, with a WS2812 LED providing visual feedback. The main loop initializes hardware and USB, samples the angle, updates the LED, services TinyUSB, and periodically processes switches and angle changes. The README documents board-dependent GPIOs and the optional LED. PIO implementation details were not sampled, so their specific behavior is based on the firmware’s use and README descriptions.

Main entry points: [`blink.c`](https://github.com/torvalds/scrollwheel/blob/main/blink.c) (Main loop), [`hid-device.c`](https://github.com/torvalds/scrollwheel/blob/main/hid-device.c) (USB HID device), [`ws2812.pio`](https://github.com/torvalds/scrollwheel/blob/main/ws2812.pio) (WS2812 PIO), [`tinyusb`](https://github.com/torvalds/scrollwheel/tree/main/tinyusb) (TinyUSB stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Physical inputs"]
  node_i2c["I2C setup<br/>[blink.c]"]
  node_angle_read["Angle acquisition<br/>[blink.c]"]
  node_switch_setup["Switch setup<br/>[blink.c]"]
  node_debounce["PIO debounce<br/>[debounce.pio]"]
end

subgraph group_firmware["Control firmware"]
  node_main["Main loop<br/>[blink.c]"]
  node_angle_track["Angle tracking<br/>[blink.c]"]
  node_switch_read["Switch events<br/>[blink.c]"]
  node_button_map["Button mapping<br/>[blink.c]"]
  node_angle_map["Rotation mapping<br/>[blink.c]"]
  node_led_map["LED color mapping<br/>[blink.c]"]
end

subgraph group_outputs["USB and feedback"]
  node_led_program["WS2812 PIO<br/>[ws2812.pio]"]
  node_usb_hid["USB HID device<br/>[hid-device.c]"]
  node_hid_api["HID send API<br/>[hid-device.c]"]
  node_tusb["TinyUSB stack"]
end

node_controls(("Knob and switches"))
node_sensor["AS5600 sensor"]
node_led_hw["WS2812 LED"]
node_host(("USB host"))

node_controls -->|"rotates magnet"| node_sensor
node_main -->|"initializes"| node_i2c
node_i2c -->|"configures bus"| node_sensor
node_main -->|"samples"| node_angle_read
node_angle_read -->|"reads angle"| node_sensor
node_angle_read -->|"unwraps readings"| node_angle_track
node_main -->|"initializes"| node_switch_setup
node_switch_setup -->|"starts program"| node_debounce
node_controls -->|"presses switches"| node_switch_read
node_main -->|"polls"| node_switch_read
node_switch_read -->|"returns states"| node_button_map
node_main -->|"processes"| node_button_map
node_main -->|"processes angle"| node_angle_map
node_angle_map -->|"sends scroll or volume"| node_hid_api
node_button_map -->|"sends keycodes"| node_hid_api
node_main -->|"updates periodically"| node_led_map
node_led_map -->|"encodes color"| node_led_program
node_led_program -->|"drives LED"| node_led_hw
node_main -->|"initializes USB"| node_usb_hid
node_main -->|"services tasks"| node_tusb
node_usb_hid -->|"initializes stack"| node_tusb
node_hid_api -->|"submits reports"| node_usb_hid
node_usb_hid -->|"provides HID reports"| node_host

click node_main "https://github.com/torvalds/scrollwheel/blob/main/blink.c"
click node_i2c "https://github.com/torvalds/scrollwheel/blob/main/blink.c"
click node_angle_read "https://github.com/torvalds/scrollwheel/blob/main/blink.c"
click node_angle_track "https://github.com/torvalds/scrollwheel/blob/main/blink.c"
click node_switch_setup "https://github.com/torvalds/scrollwheel/blob/main/blink.c"
click node_debounce "https://github.com/torvalds/scrollwheel/blob/main/debounce.pio"
click node_switch_read "https://github.com/torvalds/scrollwheel/blob/main/blink.c"
click node_button_map "https://github.com/torvalds/scrollwheel/blob/main/blink.c"
click node_angle_map "https://github.com/torvalds/scrollwheel/blob/main/blink.c"
click node_led_map "https://github.com/torvalds/scrollwheel/blob/main/blink.c"
click node_led_program "https://github.com/torvalds/scrollwheel/blob/main/ws2812.pio"
click node_usb_hid "https://github.com/torvalds/scrollwheel/blob/main/hid-device.c"
click node_hid_api "https://github.com/torvalds/scrollwheel/blob/main/hid-device.c"
click node_tusb "https://github.com/torvalds/scrollwheel/tree/main/tinyusb"

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_i2c,node_angle_read,node_switch_setup,node_debounce toneBlue
class node_main,node_angle_track,node_switch_read,node_button_map,node_angle_map,node_led_map toneAmber
class node_led_program,node_usb_hid,node_hid_api,node_tusb toneMint
class node_controls,node_sensor,node_led_hw,node_host toneIndigo
```

## Components

### Physical inputs

- [I2C setup](https://github.com/torvalds/scrollwheel/blob/main/blink.c): `blink.c`
- [Angle acquisition](https://github.com/torvalds/scrollwheel/blob/main/blink.c): `blink.c`
- [Switch setup](https://github.com/torvalds/scrollwheel/blob/main/blink.c): `blink.c`
- [PIO debounce](https://github.com/torvalds/scrollwheel/blob/main/debounce.pio): `debounce.pio`

### Control firmware

- [Main loop](https://github.com/torvalds/scrollwheel/blob/main/blink.c): `blink.c`
- [Angle tracking](https://github.com/torvalds/scrollwheel/blob/main/blink.c): `blink.c`
- [Switch events](https://github.com/torvalds/scrollwheel/blob/main/blink.c): `blink.c`
- [Button mapping](https://github.com/torvalds/scrollwheel/blob/main/blink.c): `blink.c`
- [Rotation mapping](https://github.com/torvalds/scrollwheel/blob/main/blink.c): `blink.c`
- [LED color mapping](https://github.com/torvalds/scrollwheel/blob/main/blink.c): `blink.c`

### USB and feedback

- [WS2812 PIO](https://github.com/torvalds/scrollwheel/blob/main/ws2812.pio): `ws2812.pio`
- [USB HID device](https://github.com/torvalds/scrollwheel/blob/main/hid-device.c): `hid-device.c`
- [HID send API](https://github.com/torvalds/scrollwheel/blob/main/hid-device.c): `hid-device.c`
- [TinyUSB stack](https://github.com/torvalds/scrollwheel/tree/main/tinyusb): `tinyusb`

### Other components

- **Knob and switches**
- **AS5600 sensor**
- **WS2812 LED**
- **USB host**

## Connections

- Knob and switches → AS5600 sensor: rotates magnet (evidence: `README.md`)
- Main loop → I2C setup: initializes (evidence: `blink.c`)
- I2C setup → AS5600 sensor: configures bus (evidence: `blink.c`)
- Main loop → Angle acquisition: samples (evidence: `blink.c`)
- Angle acquisition → AS5600 sensor: reads angle (evidence: `blink.c`)
- Angle acquisition → Angle tracking: unwraps readings (evidence: `blink.c`)
- Main loop → Switch setup: initializes (evidence: `blink.c`)
- Switch setup → PIO debounce: starts program (evidence: `blink.c`)
- Knob and switches → Switch events: presses switches (evidence: `README.md`)
- Main loop → Switch events: polls (evidence: `blink.c`)
- Switch events → Button mapping: returns states (evidence: `blink.c`)
- Main loop → Button mapping: processes (evidence: `blink.c`)
- Main loop → Rotation mapping: processes angle (evidence: `blink.c`)
- Rotation mapping → HID send API: sends scroll or volume (evidence: `blink.c`)
- Button mapping → HID send API: sends keycodes (evidence: `blink.c`)
- Main loop → LED color mapping: updates periodically (evidence: `blink.c`)
- LED color mapping → WS2812 PIO: encodes color (evidence: `blink.c`)
- WS2812 PIO → WS2812 LED: drives LED (evidence: `README.md`)
- Main loop → USB HID device: initializes USB (evidence: `blink.c`)
- Main loop → TinyUSB stack: services tasks (evidence: `blink.c`)
- USB HID device → TinyUSB stack: initializes stack (evidence: `hid-device.c`)
- HID send API → USB HID device: submits reports (evidence: `hid-device.c`)
- USB HID device → USB host: provides HID reports (evidence: `hid-device.c`)
