Welcome to QUsb2Snes documentation.
QUsb2Snes is a reimplementation of the Usb2Snes websocket server using a more multi plateform framework (Qt, ench the Q in the name) than the original one.
You should look at http://usb2snes.com/ if you are regular user.
To make more thing more clear of what is exactly QUsb2Snes, let’s get back to the origin of the Usb2Snes project.
Usb2Snes is a firmware for the Sd2snes cartridge written by Redguyy that allows to use the USB port on the Sd2Snes to access various fonctionnality of the Sd2Snes. Most notable are uploading ROM, read and write various memories of the console.
The issue with this approche, when writing application that use this techology only one application can have access to the Sd2snes. So for example you cannot run an Item tracker for alttp randomizer at the same time than the fileviewer to upload a new ROM.
To avoid this issue, Redguyy wrote an intermediary application also called Usb2Snes (enjoy your name confusion) that other application use to talk to the Sd2Snes.
So a basic usage look like that:
Emulators, SNES Classic…
QUsb2Snes is a replacement for the middle part of the previous diagram. Since now the application does not access directly the Sd2Snes through the Usb connection. Nothing prevent this intermediate part to trick the applications to make them access something else, like a Snes Emulator or a SNES Classic
For example Snes9x
QUsb2Snes currently support:
- SD2Snes with the usb2snes firmware.
- Snes9x multitroid with Lua support
- SNES classic moded with Hakchi2 CE
- RetroArch support with Snes9x and bsnes-mercury cores
A list of applications and what they do is available on the application page
Magic2Snes is a special application that make writing applications for Usb2Snes easier for non developpers. You will find more informations on Magic2Snes
By default QUsb2Snes comes with various Magic2Snes scripts.
- Download the lastest release on the release page
- Uncompress the 7zip file and start the QUsb2Snes executable
Mac os X
- Download the lastest release (dmg file) on the release page
SD2Snes devices may have issue on mac ox X
For now you will have to compile the source yourself, see the
LinuxREADME.md file to how to do it.
There now exists a PKGBUILD for the upstream version of QUsb2Snes which also provides QFile2Snes (https://aur.archlinux.org/packages/qusb2snes-git/)
If you don’t use a SD2Snes, you will have to activate the support for your way to play SNES in the
If you came from usb2snes.com, the firmware should be provided directly on the bundle.
You need to install the last Usb2Snes firmware by Redguy (https://github.com/RedGuyyyy/sd2snes/releases/tag/usb2snes_v11) . Just follows the instruction provided. Don’t start usb2snes.exe since QUsb2snes do the same thing that the original software. Your sd2snes device should show up on the Devices menu when connected.
Snes9x-rr allows to run Lua scripts in the emulator, that allows use to connect to QUsb2snes. You can use the Multitroid version of Snes9x-rr (http://multitroid.com/) or use Snes9x-rr 1.60 https://github.com/gocha/snes9x-rr/releases. Older version of Snes9x-rr does not allow to write to ROM from Lua so some application will not work.
Lua bridge on the device menu of QUsb2Snes.
Then run the luabridge.lua script from the LuaBridge folder from the Lua console window in Snes9x
BizHawk 2.3.1 (bsnes core recommanded)
In the device menu of QUsb2Snes activate the
You will need to change the Lua support on the emulator. Go into the
Config -> Customize menu then goes into the Advanced tab and select
Lua+LuaInterface at the bottom in the Lua core part. Restart the emulator.
In the Lua directory of BizHawk create a
lua_bridge directory (or a similar name) then copy the content of the BizHawk directory from QUsb2Snes (the lua file and the dll file).
Run your game and then in the
Tools menu start the
Lua console click on the folder icon to load the
multibridge.lua file. You need to close the Lua console if you want to disconnect properly.
You can use Snex9x (not recommanded) or bsnes-mercury cores. You need to activate the network command support, etheir in the configuration menu of RetroArch or editing your retroarch.cfg file (can be found in %appData%\RetroArch) to set network_cmd_enable = “true” (default is false). Then you need to activate the RetroArch virtual device on the devices menu. Any flavor of bsnes-mercury is prefered as we can access the ROM data.
Snex9x core : For software needing to the patch the ROM (multitroid for example) you etheir need to patch the rom manually with the IPS file or put the IPS file along side the rom with the same name for retroarch to auto patch it.
You can connect to a remote RetroArch by adding a
RetroArchHosts="remoteName=ip" (note the s in Host) in the config file. If you want to add multiple hosts, just add ; between each host definition.
SNES classic (called also SNES mini)
If for some reason your SNES classic does not have the expected IP address (connected via wifi or something) you can add a
SNESClassicIP=myip in the config.ini file.
Native emulator (canoe)
Mostly tested with Super Metroid.
Enable the SNES classic support on the device menu.
You need to ‘hack’ your SNES classic with the Hakchi2 CE version (https://github.com/TeamShinkansen/hakchi2/releases/) then remove the covershell mod if needed (as explained in https://github.com/TeamShinkansen/hakchi2/releases/tag/v3.4.0).
serverstuff mod provided by QUsb2snes: copy the
serverstuff.hmod to the
user_mods directory on Hakchi2, then install the mod with Hakchi2
Start the game and check if the SNES classic appear on the Devices menu, it should display something like
SNES classic : no client connected. If not, try restarting the game.
It will not work with the ‘normal’ Hakchi2 version as the Hakchi2 CE provide a more stable way to access the SNES Classic.
Enable the RetroArch support. Open Hakchi2 CE and in the menu go to ‘tools -> open ftp client’ it should open your default browser, copy paste the url it should look like
ftp://169.254.13.37/ for the default ip, and paste in the file explorer to go to it (if it ask you for user/password, just put root as user, there is no password). Go into the
/etc/libretro/ folder and copy the retroarch.cgf file somewhere. Open the copy with a text editor and search for the
network_cmd_enable entry, replace
true, save. Then now put your copy in place of the original one.