Wii Nunchuk USB Gamepad and Mouse

This projects let's you use a Nintendo Nunchuk controller as an USB gamepad on your computer (a joystick, 2 buttons, and it also 3 axis of acceleration data). It also let's you use it as an USB mouse, but this function can be disabled by a jumper. Tilting the Nunchuk is the same as moving the mouse wheel.

Let me get some important and frequently mentioned web links out of the way:

• ATmega168 from Atmel
• V-USB by Objective Development. Download the files from there, and also go read their wiki.
• Project files I wrote. Download me!

This tutorial will show you how to make a USB gamepad and USB mouse device using an ATmega168 and a Nintendo Wii Nunchuk Controller.

Since the ATmega168 does not have any built-in USB functionality, I used V-USB by Objective Development to implement the USB functionality.

The amount of flash memory required by this project is actually less than what is available on an ATmega8 chip, so you can use an ATmega8 instead if you reconfigure the project. I used an ATmega168 because that's what I had.

Hardware

I will draw a series of circuit schematic diagrams, follow along (with a breadboard maybe? just build with me!). First, take care of some basic stuff.

• The ATmega168 must have a 5V power supply. This comes from the USB port.
• Decoupling capacitor is placed on the power bus.
• A reset switch is always wanted.
• A ISP programming header allows you to upload code to the ATmega168

From the above information, we start building something like this:

Now make the circuit suitable with V-USB. Take a look at the circuit diagram taken from V-USB's website:

That circuit is for a project that needs 3.3V (those two diodes have a voltage drop that drops the 5V down to about 3.3V), we'll change it to use 5V instead. Take a look at USBasp's schematic:

Notice the added 3.6V Zener diodes, and how the 1.5 kohm resistor changed into a 2.2 kohm resistor (I'm not sure why, but do it). The Zener diodes are there because the USB bus should still be 3.3V, so they make sure the bus is still safe for other 3.3V devices even when your 5V device is plugged in.

From this change, we come up with something like this:

Take note of where the D+ and D- lines are connected to the ATmega168, these will be defined in "usbconfig.h" (look for "USB_CFG_IOPORTNAME", "USB_CFG_DMINUS_BIT", "USB_CFG_DPLUS_BIT")

The Nunchuk controller communicates with the ATmega168 by the TWI bus. First take a few notes:

The first problem to solve: reading data from a Nintendo Nunchuk Controller.

The Nintendo Nunchuk Controller is a TWI device (also sometimes known as I2C). The ATmega168 has a built-in TWI module which we are going to use. There are a few things to note:

• The Nunchuk must run at 3.3V . Running it at 5V might work but you risk breaking the controller.
  • This means the TWI bus must use 3.3V and not 5V.
  • The internal pull-up resistors of the ATmega168 cannot be used since it will use 5V.
  • External pull-up resistors to 3.3V must be used on the TWI bus.

So we add to the circuit:

Here are some cheap cables that you can buy and cut up in order to connect the Nunchuk.

The pin-out of the extension port is shown below, the order from left to right is the same order looking at the back of the Wiimote.

Ground	No Connection	SCL
SDA	Device Detect (Ignore Me)	Vcc (3.3V)

Now at some point I realized that I would like to disable the mouse functionality somehow, since in a video game, I'd like to use a real mouse while the movement is controlled by the joystick. I added a jumper to the pin PC0 to enable the mouse.

That's pretty much the step-by-step of how to build the circuit. Here's the whole thing:

Firmware

Let's start coding! I'm using my own AVR Project IDE for this. You should download my project files from here (so you don't ACTUALLY have to follow me step by step). Start a new project (apply the template called "maximum optimization"), and start with a blank "main.c" file. The project should be configured with:

• ATmega168
• Clock speed of 12 MHz
• The AVRDUDE stuff depends on your programmer
• I think everything else should be left default (and might have been added by the "maximum optimization" template)

Go download the V-USB software from here. Copy the folder "usbdrv" into your project folder. Include these files into your project: "usbdrv.c", "usbdrvasm.S".

Now you need to configure V-USB by writing "usbconfig.h" by copying and modifying the provided "usbconfig-prototype.h" . Here's what I changed:

• The vendor string and device name was changed to "circleofcurrent.com" and "Nunchuk Joystick", the length of these strings needs to be set. Look for "USB_CFG_VENDOR_NAME" and "USB_CFG_DEVICE_NAME".
• The device power (look for "USB_CFG_MAX_BUS_POWER") was set to 500.
• "USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH" must be changed to match the size of your USB HID report descriptor array.
• I used the default vendor and product ID provided by V-USB.
• To match the circuit, "USB_CFG_IOPORTNAME" is set to D, "USB_CFG_DMINUS_BIT" is set to 4 and "USB_CFG_DPLUS_BIT" is set to 2.
• There may or may not be something I missed.

Add "usbconfig.h" to your project. Good, now V-USB is configured. Now you need to understand that a joystick and mouse are HID (Human Interface Device) devices. Your USB device will regularly send back a chunk of data to the computer called a "report", but your computer does not know how to interpret this data. To help the computer understand what your device is sending, we need to write a HID report descriptor. (This is also why we don't need to write any drivers)

I used this USB HID report descriptor tool (somewhere on that page) to help me write the descriptor. Use the tool's "save as" feature to save as a .h header file, which is how I generated the "hid_desc.h" file. Some modification afterwards was required to make it work with V-USB.

Take a look at the contents of "hid_desc.h" and add it to the project. I will talk about it as you read it from top down. Please note that even I don't understand this report descriptor stuff fully, I'm just making sense of some examples I've seen and passing what I figured out to you. I'm not even sure if what I wrote is right but it works on my computer (Windows 7 Pro 64 bit).

My report descriptor has two major halves, one for the joystick report and one for the mouse report. Take notice of "REPORT_ID", the joystick part uses 1 for its "REPORT_ID" and the mouse uses 2. This makes it so that the first byte of my report is an ID telling the computer what kind of data I'm sending. If this byte is 1, then the information that follows is to be used for the joystick, and if this byte is 2, then the information is for the mouse. This is how two devices can be implemented with one USB device.

Look at the first half, after the "REPORT_ID". I then tell the computer that I want to report the X axis and Y axis readings of the joystic, each reading should have values between -127 and 127, and each value should use 8 bits, and there are 2 such values.

Then I have three more readings that are 8 bits between -127 and 127, these are for the three accelerometer axis.

Then I tell it that I want to report the status of a range of buttons, button 1 and button 2. They should be either on or off, each using 1 bit. These are used for the two buttons on the Nunchuk controller.

But wait, that only uses 2 bits, and a byte should be 8 bits, so I then tell the computer to expect 6 more bits that are meaningless.

Now look at the 2nd half of the descriptor, the half about the mouse. After "REPORT_ID" (which I've already explained), I tell the computer to expect data represeting the status of three buttons ranging from button 1 to button 3. Each button status should be represented by a single bit, either on or off. And then like before, add 5 more useless meaningless padding bits to make 8 bits.

Then the computer should expect three values, betweem -127 and 127, each value using 8 bits, and there are three such values. These are used for the mouse movement axis and the mouse wheel movement. These values are relative to the values before (hence the "INPUT (Data,Var,Rel)" and not "INPUT (Data,Var,Abs)").

Now from this info, I can define the two data structures needed to represent the reports. These are found at the bottom of "hid_desc.h". Read the comments.

There's one last thing we need to do to get the V-USB part of the project working, there's a function called "usbFunctionSetup" that needs to be put into "main.c".

The idea is that this handles class specific request data coming from the computer to your device. We are making a joystick and mouse so this is pretty short. The computer can request the specific report, set or get the idle rate. We store the idle rate in a global char variable but ignore it.

Good, now we can figure out the next part of the puzzle, reading data from a Nintendo Nunchuk.

Before continueing, you should read up on the following resources:

• Read wii nunchuck data into arduino - by Windmeadow Labs
• Wiibrew wiki page about the Nunchuk
• My own Wii related projects

Also by now you should just load up the contents of "main.c" and read it along with this web page.

As I've already said, the Nunchuk talks with the ATmega168 using the TWI bus. The TWI code used in this project was not written by me, they are two files that are also used by the Wire library (an Arduino library). The files are "twi.c" and "twi.h". I modified both files. In twi.c, I modified the initialization function so that it did not touch the IO ports of the ATmega168 (since the pull-up resistors must be implemented externally), and in twi.h, I defined CPU_FREQ to be F_CPU (which should be 12 MHz, defined as a compiler option).

Note that all Nunchuk controllers use a TWI device address of 0x52. This is defined in my code as "NUNCHUK_ADDR".

First understand that the Nunchuk operates like a device with a set of registers. You tell it which register address to point at, and then the next set of write (or read) operations will be done to (or from) that register and the ones that follow (each operation auto-increments the pointer).

Take a look at the functions "twi_writeTo" and "twi_readFrom" in "twi.c".

The address is always 0x52, defined as "NUNCHUK_ADDR" as I said. To initialize the Nunchuk. We write 0x00 to register address 0x40.

To read the joystick, accelerometer, and button data, set the register address to 0x00 and read 6 bytes.

But the data is encrypted, we can decrypt it like so:

The above method is from Windmeadow Labs (linked above). Why is decrypting the data so easy? It's because usually the Wii tells the Nunchuk how to encrypte the data, but we never told it to, so it's using the default. (This is a really simplified way of explaining it)

Now if you keep reading "main.c", the code does some math to get the numbers in range, and load it up to the two report data structures. If mouse is disabled by the jumper on pin PC0, then the mouse data is zero-ed. The code waits until it is able to send the data via USB and then sends it.

Of course, the code does this in a gigantic main loop forever. Reading from Nunchuk -> Decrypte -> Math -> Send USB Joystick Data -> Send USB Mouse Data -> Repeat.

The file "nunchuk_config.h" is there to help store some numbers which help with the math, allowing you to calibrate the joystick and accelerometer readings.

Now you should be able to compile and build the project. Upload the generated hex file to the chip! You must use the right fuse bits though, so make sure that you set the fuses to use external crystal oscillator faster than 8 Mhz with the highest power-down and reset time, do not divide the clock by 8, and do not output the clock on PB0. The reset vector shouldn't be enabled (unless you are using a bootloader). Brown-out detection is not needed, nor is watch-dog timer. Reset pin and SPI download should be always enabled. In the end, you should have:

• Low Fuse Byte: 0xFF
• High Fuse Byte: 0xDF
• Extended Fuse Byte: 0xF9

Or refer to this page.

Electrical Waveforms

Well I talked about the code but what does this thing actually do in real life? Here's a logic analyzer waveform snapshot of the device after it's connected. You'll need Saleae Logic software 1.0.33 to view it (zoom in and analyze, etc). Below is only a preview screenshot:

Credits

• V-USB by Objective Development. Thanks for the awesome software. The mouse example project also helped a lot.
• Read wii nunchuck data into arduino - by Windmeadow Labs. Thanks for helping everybody understand how to read data from a Nintendo Nunchuk controller.
• Helm PCB - USB Joystick. Thanks for the great example, I learned a lot about HID report descriptors from it.
• PS2USB - by Primož Kranjec. Thanks for the great example, I learned how to implement "two in one" USB devices from it.
• USBasp. Thanks for the circuit diagram.