USB Gecko
| USB Gecko | |
| General | |
|---|---|
| Author(s) | Ian Callaghan |
| Type | Hardware tool |
The USB Gecko is a Wii/Gamecube development and hacking tool by Ian Callaghan which connects to the USB port of the computer, and to the GameCube memory slot of the Wii. It can be used to upload homebrew, to use your computer as a remote terminal under Wii Linux and as a remote debugging tool.
See Gecko OS for the homebrew application to launch a game and be able to debug it remotely using this device.
In 2010, Ian released the USB Gecko Special Edition, an updated version that drops the flash chip and adds a user-controllable LED.
From March 2015 until February 2018, happy_bunny sold the Shuriken USB, a hand-soldered USB Gecko SE clone in a 3D-printed case.
None of these devices are available for purchase anymore, however PCB designs and schematics for the Shuriken USB clone are available for download.
Windows Side Application Programming
Drivers and documentation for the FTDI chip used in the USB Gecko can be found on FTDI's website: Drivers and API downloads, API Documentation
The device will also be recognised as a COM serial port if drivers have been installed, reading and writing to this port will transfer the data across the Gecko. (Using the above D2XX API to transfer data is functionally equivalent)
Linux Side Application Programming
The USB Gecko will usually be recognized as a USB to serial port converter and a device file of the form /dev/ttyUSB0 will appear. Simply writing to and reading from this device file will send data across the USBGecko link.
Failing that, userspace tools could use the libusb library and usb_bulk_write and usb_bulk_read functions. The USBGecko will appear as 0403:6001 in the lsusb output.
Hardware
The USB Gecko is a two step converter to convert EXI<->serial<->usb. It is a fancy serial port. All the fun is provided by software. The EXI interrupt cannot be triggered from the PC because the pin on the Wii side is left unconnected. In theory one could open up the USB Gecko and run a trace from that pin to one of the many unused pins on the CPLD, reprogram the CPLD, and be able to trigger the EXI interrupt from the PC side. This can be seen in the image at right.
The pins on the bottom connector are numbered from left to right 12 down to 1, even numbers being on the bottom row, odd numbers being on the top row. Pin 3 is the EXI interrupt pin, which is unconnected for some unknown reason.
The pins on the front side are what connect to the Wii EXI port. The pins on the back side connect to the Altera CPLD's JTAG pins for programming. The pins are, in order from left to right (matching the bottom picture at right):
TDO, 3.3V, TMS, TDI, TCK, GND.
The Gecko has 3 chips:
- The USB interface is provided by the FT245RL which converts USB to two 8 bit bidirectional FIFOs. One sends data to the Wii (128 byte capacity), the other receives data from the Wii (256 byte capacity).
- The FIFOs are connected to an ALTERA CPLD (Complex Programmable Logic Device) EPM570T100C5N which converts the parallel data to the serial datastream needed for the Wii's EXI port.
- There is a 512K byte flashrom, the SST39VF040 which is accessable only on the Wii side through the Altera CPLD. This is not strictly necessary for the USB Gecko's main functionality.
Codehandler Command Protocol
The PC side sends bytes over to the Wii to control the installed code handler. The code handler takes care of interpreting the cheat code virtual machine which can be used to play games with infinite lives, health or whatever hack a person might desire. The code handler also has functionality to support debugging functions, such as setting breakpoints, viewing or writing memory, or pausing a program in progress.
The codehandler on the Wii side is inserted in some commonly called function like the function to wait for vertical blank. When it gets a chance to run, it performs the virtual machine functions of interpreting the gecko codes, and services the debug commands pending on the EXI port if any are ready.
The debug command codes all start with a byte to indicate what the command is, and the command byte is followed by zero or more bytes of associated data. Here is a list of codes. The byte values are in hex (base 16), so if "10" appears it isn't ten, it's sixteen. The codes seem to be loosely organized in binary coded decimal.
01 [4 bytes address] [4 bytes data] = Write a byte to memory 02 [4 bytes address] [4 bytes data] = Write a word (16 bits) to memory 03 [4 bytes address] [4 bytes data] = Write a double word (32 bits) to memory 04 [4 bytes high addr] [4 bytes low addr] = Read bytes from memory 06 = Freeze program 07 = Unfreeze program 08 = Resume program, but remain frozen (single frame advance) NOTE THIS IS A WORK IN PROGRESS 09 [data] = Breakpoints (ibp) 10 [data] = Breakpoints (dbp) 2f [data] = upbpdata 30 [data?] = getbpdata 38 [data] = cancelbreakpoints 40 [data] = sendcheats 41 [data] = uploadcode 44 [data] = breakpoints (step) 50 [data] = pausestatus 60 [data] = executecodes 89 [data] = breakpoints (aligned dbp) 99 [data] = versionnumber
Homebrew Channel
The Homebrew Channel supports booting homebrew programs from a USB Gecko via wiiload (as an alternative to using Wi-Fi or a USB network adapter). The grayed-out gecko icon will turn white when a compatible device is detected.
Files
- Complete archive. This is a snapshot of a more complete archive. It also doesn't contain schematics, but it does contain the same PCB manufacturing files as the archive below and the VHDL source. It also has source code to the Gecko codehandler loaded on the Wii, which handles the cheat codes and remote debugging functions for retail software.
- USB Gecko schematics (BSD licensed). This archive doesn't actually contain a schematic of the circuit, but rather the files needed for producing the circuit boards and some source code. The VHDL source for the CPLD itself is included.