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.



Usb2Snes firmware

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.

Direct access

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:

Websocket access

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

Lua connection


QUsb2Snes currently support:


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.



Mac os X

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.

Arch Linux

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 devices menu.


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 Rerecording

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.

Activate the 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 lua bridge

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

Install the 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 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 false with true, save. Then now put your copy in place of the original one.