Difference between revisions of "USB Gecko"

From WiiBrew
Jump to navigation Jump to search
(43 intermediate revisions by 18 users not shown)
Line 1: Line 1:
To code computer side usbgecko application you need :
+
{{Infobox homebrew
 +
| type = hardware tool
 +
| author = Ian Callaghan
 +
}}
  
* For Win32 : [http://www.ftdichip.com/Drivers/D2XX.htm API] [http://www.ftdichip.com/Documents/ProgramGuides/D2XXPG34.pdf DOC]
+
[[File:Usbgecko.jpg|thumb|A USB Gecko is an adapter to connect a Wii to a PC through a Gamecube memory slot]]
  
* For Linux : [http://www.intra2net.com/de/produkte/opensource/ftdi/ API] [http://www.intra2net.com/de/produkte/opensource/ftdi/documentation/group__libftdi.html DOC]
+
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 [[Homebrew apps/Wii Linux|Wii Linux]] and as a [[Debugging|remote debugging]] tool.
  
 +
See [[Gecko OS]] for the Hombrew 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.
  
I have started a linux application, all seems ok, except the ftdi_read_data that always return 0 :/
+
From March 2015 until February 2018, happy_bunny sold the Shuriken USB, a hand-soldered USB Gecko SE clone in a 3D-printed case.
For those who interrested this page can be a base to make a usable application.
 
  
#include <stdio.h>
+
None of these devices are available for purchase anymore.
#include <sys/types.h>
+
 
#include <ftdi.h>
+
== Windows Side Application Programming ==
+
For Win32 : [http://www.ftdichip.com/Drivers/D2XX.htm API] [http://www.ftdichip.com/Documents/ProgramGuides/D2XXPG34.pdf DOC]
//--------------------------  Globals ----------------------------------
+
 
int32_t status;
+
== Linux Side Application Programming ==
int ret;
+
The USB Gecko will usually be recognized as a USB to serial port converter and a device file of the form
int32_t TxSent;
+
/dev/ttyUSB0
int32_t RxSent;
+
will appear. Simply writing to and reading from this device file will send data across the USBGecko link.
+
 
struct ftdi_context ftdic;
+
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.
+
 
int cmd_readmem = 0x04;
+
== Hardware ==
//--------------------------  Function Prototypes ----------------------------------
+
[[file:USBGecko.jpg|thumb|Front side]]
void gecko_opendevice();
+
[[file:USBGecko-2.jpg|thumb|Back side]]
+
 
+
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.
int main(int argc, char **argv)
+
 
{
+
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):
void* plop;
+
 
unsigned char responseback = 0;
+
TDO, 3.3V, TMS, TDI, TCK, GND.
+
 
ftdi_init(&ftdic);
+
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.
printf("-----------------------------------\n");
+
* 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.
printf("- NoNameNo's UsbGecko Linux Tools -\n");
+
 
printf("-----------------------------------\n\n");
+
== Command Protocol ==
+
 
gecko_opendevice();
+
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.
printf("Connecting to Wii.\n");
+
 
printf("%x\n",gecko_writebyte(&cmd_readmem,1));
+
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.
printf("%x\n",gecko_readbyte(&responseback, 1));
+
 
ftdi_usb_close(&ftdic);
+
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.
ftdi_deinit(&ftdic);
+
 
+
<pre>
return EXIT_SUCCESS;
+
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
int gecko_readbyte(unsigned char* lpBuffer, int dwBytesToRead)
+
07 = Unfreeze program
{
+
08 = Resume program, but remain frozen (single frame advance)
status = ftdi_read_data(&ftdic, lpBuffer, dwBytesToRead);
+
NOTE THIS IS A WORK IN PROGRESS
+
09 [data] = Breakpoints (ibp)
if (status > 0){
+
10 [data] = Breakpoints (dbp)
if(status != dwBytesToRead){
+
2f [data] = upbpdata
return 2;
+
30 [data?] = getbpdata
}
+
38 [data] = cancelbreakpoints
}
+
40 [data] = sendcheats
else{
+
41 [data] = uploadcode
printf("[Error] UsbGecko Reading Device\n");
+
44 [data] = breakpoints (step)
//ftdi_usb_close(&ftdic);
+
50 [data] = pausestatus
//ftdi_deinit(&ftdic);
+
60 [data] = executecodes
return status;
+
89 [data] = breakpoints (aligned dbp)
}
+
99 [data] = versionnumber
+
</pre>
return 1;
+
 
}
+
== Homebrew Channel ==
+
The Homebrew Channel + wiiload support booting homebrew programs from a USB Gecko (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 ==
//----------------------------------------------------------------------------------------------------
+
* [[Media:USBGecko-svn-r17.tar.gz‎|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 to the powerpc assembly language code that handles the gecko codes and the remote debugging functions.
int gecko_writebyte(unsigned char* lpBuffer, int dwBytesToWrite)
+
 
{
+
* [[Media:Usbgecko_schematics.zip|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.
status = ftdi_write_data(&ftdic, lpBuffer, dwBytesToWrite);
+
 
+
== External Links ==
if (status > 0){
+
* [http://web.archive.org/web/20101219125228/http://www.unrom.com:80/ Ian's blog]
if(status != dwBytesToWrite){
+
* [http://retro-system.com/shuriken_usb.htm Shuriken USB Website]
return 2;
+
* [http://retro-system.com/shuriken_usb_case.zip Shuriken USB - 3D Case Model]
}
+
* [https://oshpark.com/shared_projects/yRrFImey Shuriken USB - OSH Park PCB]
}
+
* [http://code.google.com/p/geckodownloads/ Software downloads on Google Code]
else{
+
* [https://www.gc-forever.com/forums/viewtopic.php?t=3089 Yet another USB Gecko clone]
printf("[Error] UsbGecko Writing Device\n");
 
ftdi_usb_close(&ftdic);
 
ftdi_deinit(&ftdic);
 
return 0;
 
}
 
 
return 1;
 
}
 
 
 
 
 
//----------------------------------------------------------------------------------------------------
 
//----------------------------------------------------------------------------------------------------
 
//----------------------------------------------------------------------------------------------------
 
void gecko_opendevice()
 
{
 
//---------------------------open device --------------------------------------
 
if((ret = ftdi_usb_open(&ftdic, 0x0403, 0x6001)) < 0) {
 
printf("[Error] UsbGecko NOT Detected\n");
 
exit(0);
 
}
 
else{ 
 
printf("[OK] UsbGecko Detected\n");
 
}
 
 
 
//---------------------------Reset device --------------------------------------
 
if((ret = ftdi_usb_reset(&ftdic)) < 0) {
 
printf("[Error] UsbGecko Reseting Device \n");
 
ftdi_usb_close(&ftdic);
 
ftdi_deinit(&ftdic);
 
exit(0);
 
}
 
else{ 
 
printf("[OK] UsbGecko Reseted\n");
 
}
 
 
 
//---------------------------SetTimeOut to 2000 --------------------------------------
 
ftdic.usb_read_timeout=2000;
 
ftdic.usb_write_timeout=2000;
 
printf("[OK] UsbGecko Setted 2 sec timout\n");
 
 
//---------------------------Purging RX/TX buffers --------------------------------------
 
if((ret = ftdi_usb_purge_buffers(&ftdic)) < 0) {
 
printf("[Error] UsbGecko Purging Buffer \n");
 
ftdi_usb_close(&ftdic);
 
ftdi_deinit(&ftdic);
 
exit(0);
 
}
 
else{ 
 
printf("[OK] UsbGecko Purged RX/TX buffers\n");
 
}
 
 
 
 
//--------------------------- Set RX/TX size buffer --------------------------------------
 
if((ret = ftdi_read_data_set_chunksize(&ftdic,65536)) < 0) {
 
printf("[Error] UsbGecko Setting RX buffer size\n");
 
ftdi_usb_close(&ftdic);
 
ftdi_deinit(&ftdic);
 
exit(0);
 
}
 
else{ 
 
printf("[OK] UsbGecko Setted RX Buffer Size\n");
 
}
 
if((ret = ftdi_write_data_set_chunksize(&ftdic,65536)) < 0) {
 
printf("[Error] UsbGecko Setting TX Buffer size\n");
 
ftdi_usb_close(&ftdic);
 
ftdi_deinit(&ftdic);
 
exit(0);
 
}
 
else{ 
 
printf("[OK] UsbGecko Setted TX Buffer Size\n");
 
}
 
 
 
//---------------------------Required ???  --------------------------------------
 
sleep(1);
 
 
}
 

Revision as of 19:28, 9 April 2021

USB Gecko
General
Author(s)Ian Callaghan
TypeHardware tool


A USB Gecko is an adapter to connect a Wii to a PC through a Gamecube memory slot

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 Hombrew 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.

Windows Side Application Programming

For Win32 : API DOC

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

Front side
Back side

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.

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 + wiiload support booting homebrew programs from a USB Gecko (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 to the powerpc assembly language code that handles the gecko codes and the remote debugging functions.
  • 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.

External Links