unshell

A toolkit for extracting and documenting the data that Nintendo Switch 2 accessories expose over USB, plus a community database of what has been found on each accessory.

Background

Switch 2 accessories carry data on the device and expose it over USB: a controller has an on-board SPI flash reachable through a vendor-specific interface, and a USB camera exposes its control surface through the USB Video Class. This project reads that data off the device, documents the formats, and collects sanitized findings per accessory in accessories/.

The work is black-box hardware security research performed on the author's own hardware. The tools are read-only: they do not write flash, do not change pairing state, and do not change camera control values.

Tools

controller_spi_dump.py

Dumps the on-board SPI flash of a Switch 2 controller over its vendor-specific interface and writes a raw image plus a region/strings analysis. Verified on the Pro Controller (057e:2069); use --vid/--pid to target another controller.

# auto-detect the controller, dump 0x0..0x200000 at 64 bytes per read
python controller_spi_dump.py

# dump a smaller range into a chosen directory
python controller_spi_dump.py --start 0x10000 --end 0x14000 --out-dir dumps

fw_carve.py

Carves the firmware images out of a controller dump, reports each header's size against the carved extent, and classifies each image by Shannon entropy (encrypted/compressed versus code-like).

python fw_carve.py spi_dump_057e2069_XXXXXXXXXXXXX.bin

Example output (redacted):

## MCU bank 1 @0x001000
  hash:  <redacted>
  size:  header=0x1a000 (106496)  carved=0x1a000 (106496)  MATCH
  const: <redacted>
  entropy=7.991 -> encrypted/compressed (opaque)
  -> mcu_bank1_0x001000.bin

## DSP image @0x180000
  size:  header=0x6800 (26624)  carved=0x6800 (26624)
  entropy=7.381 -> likely plain/code (RE-friendly)
  -> dsp_0x180000.bin

camera_uvc_probe.py

Probes a UVC camera's Extension Unit and terminal controls with read-only UVC GET requests, reporting each selector's capabilities, length, and current / min / max / default values. Verified on the HORI Piranha Plant Camera (0f0d:0203).

python camera_uvc_probe.py --unit 4 --selectors 1-16

Example output (redacted):

## selector 1 (0x01)
  INFO: 0x03 (GET|SET)
  LEN:  <redacted> bytes
  CUR:  <redacted>
  MIN:  <redacted>
  MAX:  <redacted>
  DEF:  <redacted>

A real dump or probe contains device-specific data. Do not publish your own dumps.

Supported accessories

Device	VID:PID	Extractable	Status
Pro Controller	057e:2069	SPI flash, firmware banks	verified
Joy-Con 2	n/a	SPI flash, firmware banks	expected, unverified
Wired GameCube controller	n/a	SPI flash, firmware banks	expected, unverified
HORI Piranha Plant Camera	0f0d:0203	UVC control surface	verified

The Joy-Con 2 and the wired GameCube controller use the same controller handshake family as the Pro Controller and are expected to work with controller_spi_dump.py, but this has not been verified. Target them with --vid/--pid.

The accessory database

accessories/ is a community-maintained database of what each Switch 2 accessory exposes over USB: interface and endpoint maps, storage region/offset maps, header and control-surface formats, and reverse-engineering notes. Each accessory is one markdown file.

Entries describe formats and offsets only. They never contain real per-device secrets: no serial numbers, Bluetooth MAC addresses, pairing or link keys, calibration bytes, firmware hash or const byte values, or firmware-version strings. This sanitization rule is mandatory.

See CONTRIBUTING.md for how to submit an entry and accessories/schema.md for the entry fields.

Requirements

• Python 3.8 or newer
• pyusb
• libusb 1.0 (the backend pyusb talks to)
• A USB cable to connect the accessory directly to the host

Install

git clone https://github.com/Jonaaaa/unshell.git
cd unshell
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Linux notes

• The interface may need to be detached from any kernel driver that has claimed it. The tools attempt this automatically.

• Accessing the device usually requires elevated privileges. Either run the tool with sudo, or install a udev rule so your user can open the device. A rule covering a single device looks like this (substitute the accessory's VID and PID):

  # /etc/udev/rules.d/99-switch2-accessory.rules
  SUBSYSTEM=="usb", ATTR{idVendor}=="057e", ATTR{idProduct}=="2069", MODE="0660", TAG+="uaccess"
  SUBSYSTEM=="usb", ATTR{idVendor}=="0f0d", ATTR{idProduct}=="0203", MODE="0660", TAG+="uaccess"
  

  Reload rules with sudo udevadm control --reload-rules && sudo udevadm trigger and reconnect the accessory.

Protocol

The controller SPI interface and the camera UVC control interface are documented field-by-field in docs/protocol.md.

Legal / authorized use

Use this only on hardware you own. The tools read data off your own accessory. They perform no writes and do not change device state, but the data they produce contains device-specific identifiers and key material. Keep dumps private and do not commit them (see .gitignore).

License

MIT. See LICENSE.