Accurate Wiimote Light Gun for Raspberry PI (and Windows and Other Linux)
by arpruss in Circuits > Raspberry Pi
14995 Views, 27 Favorites, 0 Comments
Accurate Wiimote Light Gun for Raspberry PI (and Windows and Other Linux)
Normally, the Wii Remote used as a light gun isn't accurate enough for retro games like NES Duck Hunt, because the Wii Remote does not in fact select the point on the TV it's pointed at. It can't! The Wii Remote has an infrared camera in its front that sees the line of infrared LEDs in the sensor bar, but it can't know how far (or in what direction) the TV is from the bar or how big the TV is. Emulators and games work around this by showing cross-hairs or other targeting indicator, but that's not an accurate target-shooting experience.
To make the Wii Remote work as an accurate light gun that you can sight along to select a target on a TV requires four infrared LEDs arranged in a known quadrilateral pattern (not a straight line) in the same plane as the TV. The Wii Remote then sees the four LEDs and the camera image can be used to calculate a homography that allows us to figure out where the camera is pointing at.
The hardware for this project is simple. There are four infrared LEDs in simple 3D-printed housings that can be glued to the top and bottom of the TV housing and plug into a USB charger. Plus, in case you don't have Wii gun housing, I have a simple 3D printed handle and sights that you can attach to the Wii Remote (though to save plastic, I made mine a hybrid between wood and 3D printed plastic).
The python-based software was harder to make than the hardware and is currently Linux-only. It calibrates the LEDs and the Wii Remote and then uses homography calculations to emulate an absolute mouse that works quite well in Retroarch's fceumm NES emulator (and probably some other emulators) on my Raspberry PI 3B+.
Update (2026): This should work on other Linux systems (not tested) as well as on Windows (tested) as long as you run it in 1920x1080 display mode with your TV.
Supplies
- Wii Remote
- Four 940nm 5mm infrared LEDs (you can also replace each pair of them with a Wii sensor bar)
- Old USB cable with a working type A plug
- Raspberry PI 3 or other Linux computer with Bluetooth support
- 3D printer and filament (optional)
Infrared LED Chain
Get an old USB cable with a working type A male socket (usually my phone charging cables break on the micro USB end, so I have leftover cables with a working type A male socket).. Actually, it's even OK if the data cables are broken as long as the power lines work. Cut off the other end. In theory the red cable should be +5V and the black should be ground, but check it with a multimeter (plug it into a charger, and then check the voltage between the red and black wires).
Since infrared LEDs have around a 1.2-1.3V voltage drop, I just soldered four of them in series loop to the USB cable. Make sure the wires you solder are long enough that you can put LEDs at the bottom of the TV and two at the top, with a decent amount of horizontal space between LEDs (about 10 inches or so).
More precisely to make the LED loop:
- solder the minus side (cathode, shorter leg, with flat edge) of the first LED to the +5V USB wire
- join the plus side of the first LED (anode, longer leg, with round edge) to the minus side of the second LED
- repeat to join the second LED to the third and the third to the fourth
- then connect the plus side of the fourth LED with a wire to the ground USB wire.
To make things neater, you can use heat shrink tubing when you do the connections. Otherwise, use electrical tape to avoid shorts.
Make sure you have no short circuits. Then plug it into a USB charger and check that it's emitting infrared light by looking at the LEDs with a phone camera. (Many phone cameras are infrared sensitive.)
Attach to TV
Now, attach two of the LEDs to the underside of the TV and two to the upper side. The horizontal spacing should be about ten inches. If it's too much, you may have problems with the Wii Remote camera's field of view capturing them all. But if they're too close, then my geometric intuition says you'll have lower precision.
For testing, I taped the LEDs with electrical tape, and then for a permanent connection, I designed and printed four neat little LED clips (files are here) which I hot glued to the TV. You should make the LEDs be as close to the plane of the TV display as you can, without the bezel obscuring them from the location where you will be shooting.
If you choose to use a Wii sensor bar in place of a pair of these, you may need to find 12V power for it, since the Wii may attempt to hijack your Wii Remote if the Wii is on.
Install Software
The following setup is designed for the Raspberry PI 3 with Raspbian Stretch. Other Linux systems will require some changes. On earlier models you'll need a Bluetooth dongle and you'll need to run this from a commandline as well:
Step A: udev
Next, create a file in /etc/udev/rules.d/wiimote.rules that contains the single line:
You can do that, for instance, with a text editor or by typing the following on the commandline:
And then restart udev:
Step B: python libraries
Finally, get support stuff for my lightgun python script:
Step C: lightgun.py
Finally, get my lightgun python script package:
If all has gone well, you now have ~/lightgun/lightgun.py which you can use to calibrate the lightgun.
Measurement
Now you need to tell the software where the LEDs are located around the TV's edge as well as do some other settings.
Run:
(or python3 on some older Linux systems). Press 1+2 on the Wiimote when requested.
You now have a sequence of calibration screens which you can navigate with the Wiimote + and - buttons.
The first screen sets the screen size and the sight on your Wiimote. Press up/down on the Wiimote to change the screen measurement. You can measure that manually, or you can just press up/down until the white picture of the Wiimote on the screen is the same size as the real-life Wiimote. Then press left/right on the Wiimote to adjust the size of the sights to match those you have on your Wiimote (if you've printed mine, say).
The next four calibration screens are for the LED locations. Press + to go to the first one. You will see a calibration screen showing four arrows, one of them selected (bright) and three of them grayed out, around the edge of the TV.
For each of the four arrows around the edge, do this:
- press left/right on the Wiimote to move the arrows until they point as precisely as you can towards the corresponding LED;
- press up/down on the Wiimote to change the arrow's length until the length of the arrow matches the distance between the LED and the edge of the TV display; in other words, the length of the arrow needs to be equal to the distance from the tip of the arrow to the LED.
If you want to use a Wii sensor bar instead of a pair of LEDs, it may be a useful fact that on the OEM sensor bar the LED clusters are centered 21mm from each end. This can save you taking the bar apart to locate the LEDs.
Once your four arrows are correct (and maybe even earlier) you will see a red crosshair when you point the Wiimote at the screen. You can check that this is where it should be. (Remember that you need to be far enough away that the Wiimote can see all the LEDs. It's also important that there be no other sources of infrared in the field of view. I once had trouble because of sunlight reflecting off a screw head on the TV stand.)
Then press the + button to go to screen centering setting. This compensates for manufacturing deviations. In theory, these should be compensated for by calibration data in the Wiimote EEPROM, but in practice that seems to be off by a bit, especially vertically. For the centering adjustment, use the DPad to move the black center crosshair until the red crosshair aims where you want it to aim--namely, right where your sights are pointed.
My favorite way to do the centering adjustment is to attach the Wiimote to a tripod, and then use the sights to point directly at one of the infrared LEDs. If all goes well, the black crosshairs on the screen will be centered on the white dot indicating that LED. If they're not, then move them until they are.
Finally, if your LEDs are not in the same plane as the TV, press + to go the LED offset screen, and use the up/down buttons to adjust how far the LEDs are behind or in front of the TV. But if the difference is small, I recommend you don't bother and just live with slight inaccuracy, because LED offset can adversely affect performance.
Press the A button on the Wii Remote to exit calibration and save all data to the ~/.wiilightgun directory. (If you press HOME, you will exit and have to start over.)
Test and Use
You probably want to try your light gun now. Just run in a terminal emulator (or a script):
python3 ~/lightgun/lightgun.py -t
You will need to press the 1+2 buttons at the same time, and after that if all goes well, as long as lightgun.py is running, the lightgun will emulate a two-button absolute mouse. The trigger button is mouse button 1, and the A button is mouse button 2. Press ctrl-c to exit.
You now need only configure your emulators and/or games to work with an absolute mouse. Unfortunately, that's not always going to be that easy.
One fun thing you might try is my mod of iminurnamez's duck-duck-shoot:
cd ~
git clone https://github.com/arpruss/duck-duck-shoot
cd duck-duck-shoot
python play_game.py
For NES games, I use the libretro fceumm core in Retroarch. Go to the Options menu, and configure the Zapper to be a touchscreen. (Configuring it as a mouse doesn't actually work, as fceumm expects a relative-movement rather than absolute-position mouse.)
If you start your games with a script, you can edit the part that starts the game or emulator to say:
python3 ~/lightgun/lightgun.py -t -B 30 "command to start game"
Then during the first 30 seconds of the game's execution (hence the -B 30 option), you can connect your lightgun by holding down 1+2.
By the way, the lightgun.py script can also be used for general Wii Remote gaming with Retroarch. Just add the -o option and the lightgun functions will be turned off, and instead the Wii Remote will work horizontally, with the three buttons being 1, 2 and B respectively. There are other Retroarch-related functions in lightgun.py's mappings which you will discover by reading the code. For instance, the minus key acts as a shift, and together with the dpad controls saving and loading (up/down = change save number; left=restore; right=save).
Gun Handle and Aiming
You can use the Wii Remote by itself as a gun, sighting along the top. You can also buy one of the commercial gun casings for it. But because the original Wii Remote wasn't capable of use as a sightable gun, the casings tend not to come with iron sights, and iron sights greatly improve accuracy.
I designed a simple three-part 3D-printable system: a slide-on handle that sits just behind the trigger (so it looks a bit like a Star Trek Original Series phaser), and slide-on sights. Printable files are here. If you want to save on plastic at the expense of scrap wood, you can also do what I did and instead of printing the whole handle, print just the part that holds the Wiimote, and cut out a wooden piece and screw it on.
To sight, focus your eyes on the sights. Align the front sight's bump between the rear sight's bumps so that the air space on either is equal and all three bumps stick out equally high. Then align the middle of the target with the top of the bumps.
Windows
The current version of the python script should work on Windows, at least if you have a 1920x1080 display. I haven't tested it on higher resolution or other aspect ratios.
You should install the following python modules: numpy opencv-python hidapi
Appendix: the Algorithm
The mouse emulation code works roughly as follows.
- Process button presses.
- Get data from camera and adjust for camera centering calibration.
- If fewer than two LEDs are visible in the camera:
- Keep last mouse position.
- If four LEDs are visible:
- Use the Wiimote accelerometer data to get the Wiimote orientation and identify which LED camera image corresponds to which physical LED.
- Calculate homography between LED camera images and LED locations (in screen coordinates).
- Use homography to calculate what screen location corresponds to the center of the camera field of view.
- Do sightline parallax adjustment for the center of the virtual gun barrel below the sight-line.
- Set the mouse position to the adjusted screen location.
- If two or three LEDs are visible:
- Find two LEDs that are horizontal. Ignore the third (I have used P3P in earlier versions, but it turns out that the two LED method works more smoothly).
- Calculate the pointing on the assumption that the gun is located on the normal ray from the center of the screen. This turns out to be good enough in practice if you're sitting roughly in front of the TV.
- If no LEDs are visible:
- Keep last mouse position.