Merge pull request #28 from dmadison/documentation

Pre-Release Documentation

README.md

@@ -1,15 +1,41 @@
 # Nintendo Extension Controller Library
 
-This is an Arduino library for talking to Nintendo extension controllers over I²C.
+This is an Arduino library that makes it easy to read data from Nintendo extension controllers such as the Wii Nunchuk and Classic Controller.
+
+"Extension controller" is the name given to devices that *extend* the functionality of the [Wiimote](https://en.wikipedia.org/wiki/Wii_Remote), plugging into the expansion port at the bottom of the device. While originally designed for Wiimote accessories, the port and communication protocol is now also being used for the controllers of Nintendo's new line of "Mini" consoles.
+
+## Getting Started
+
+![ClassicController Example in IDE](/extras/NXCtrl_ClassicExample.png)
+
+### Make Your Connections
+
+Before anything else, you need to connect your controller to the Arduino. The easist way to do this is with a breakout board, which slides in to the extension controller plug and doesn't require dismantaling your controller. I recommend the [Nunchucky](https://www.adafruit.com/product/345) breakout, which is inexpensive and available at Adafruit.
+
+Controllers require 3.3V power. If you don't have 3.3V power available on your board, you will need to use an external regulator. Using 5V power can result in erratic data and risks damaging your controller. For this reason it's recommended *not* to use so-called "inline" adapters that attach to the Arduino Uno's analog pins.
+
+The "data" and "clock" lines on the breakout go to the SDA and SCL pins (respectively) on the microcontroller. For the Arduino Uno, these are pins A4 and A5. If you're not using an Uno, look [here](https://www.arduino.cc/en/reference/wire) to find the I²C pins for your Arduino board.
+
+### Run an Example
+
+After [installing the library](https://www.arduino.cc/en/guide/libraries), load an example by going to `File -> Examples -> NintendoExtensionCtrl` in the Arduino IDE and selecting an example specific to your controller. I recommend the `DebugPrint` examples to start, as they give you a nice overview of what data is available for your controller.
+
+Plug in your controller, upload the example to your board, and have fun!
 
 ## Supported Controllers
-* Wii Nunchuk
-* Wii Classic Controller
+
+### Wii
+* Nunchuk
+* Classic Controller
 * Guitar Hero Guitar
 * Guitar Hero World Tour Drums
 * DJ Hero Turntable
+
+### Mini Console
 * NES Mini Controller
 * SNES Mini Controller
 
+Currently the library supports any extension controller using unencrypted communication and data reporting mode [0x37 (6 byte request)](http://wiibrew.org/wiki/Wiimote#0x37:_Core_Buttons_and_Accelerometer_with_10_IR_bytes_and_6_Extension_Bytes). If you'd like to add support for another controller, I've written [a short guide](extras/AddingControllers.md) that should be helpful. 
+
 ## License
 This library is licensed under the terms of the [GNU Lesser General Public License (LGPL)](https://www.gnu.org/licenses/lgpl.html), either version 3 of the License, or (at your option) any later version.

examples/Any/DebugPrint/DebugPrint.ino

@@ -1,3 +1,29 @@
+/*
+*  Project     Nintendo Extension Controller Library
+*  @author     David Madison
+*  @link       github.com/dmadison/NintendoExtensionCtrl
+*  @license    LGPLv3 - Copyright (c) 2018 David Madison
+*
+*  This file is part of the Nintendo Extension Controller Library.
+*
+*  This program is free software: you can redistribute it and/or modify
+*  it under the terms of the GNU Lesser General Public License as published by
+*  the Free Software Foundation, either version 3 of the License, or
+*  (at your option) any later version.
+*
+*  This program is distributed in the hope that it will be useful,
+*  but WITHOUT ANY WARRANTY; without even the implied warranty of
+*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*  GNU Lesser General Public License for more details.
+*
+*  You should have received a copy of the GNU Lesser General Public License
+*  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*
+*  Example:      DebugPrint
+*  Description:  Connect to an extension controller and continuously print
+*                the raw control data over serial.
+*/
+
 #include <NintendoExtensionCtrl.h>
 
 ExtensionController controller;

examples/Any/IdentifyController/IdentifyController.ino

@@ -1,3 +1,29 @@
+/*
+*  Project     Nintendo Extension Controller Library
+*  @author     David Madison
+*  @link       github.com/dmadison/NintendoExtensionCtrl
+*  @license    LGPLv3 - Copyright (c) 2018 David Madison
+*
+*  This file is part of the Nintendo Extension Controller Library.
+*
+*  This program is free software: you can redistribute it and/or modify
+*  it under the terms of the GNU Lesser General Public License as published by
+*  the Free Software Foundation, either version 3 of the License, or
+*  (at your option) any later version.
+*
+*  This program is distributed in the hope that it will be useful,
+*  but WITHOUT ANY WARRANTY; without even the implied warranty of
+*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*  GNU Lesser General Public License for more details.
+*
+*  You should have received a copy of the GNU Lesser General Public License
+*  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*
+*  Example:      IdentifyController
+*  Description:  Attempt to connect to an extension controller, then print
+*                out the matching ID and ID data bytes.
+*/
+
 #include <NintendoExtensionCtrl.h>
 
 ExtensionController controller;

examples/Any/MultipleBus/MultipleBus.ino

@@ -1,6 +1,35 @@
+/*
+*  Project     Nintendo Extension Controller Library
+*  @author     David Madison
+*  @link       github.com/dmadison/NintendoExtensionCtrl
+*  @license    LGPLv3 - Copyright (c) 2018 David Madison
+*
+*  This file is part of the Nintendo Extension Controller Library.
+*
+*  This program is free software: you can redistribute it and/or modify
+*  it under the terms of the GNU Lesser General Public License as published by
+*  the Free Software Foundation, either version 3 of the License, or
+*  (at your option) any later version.
+*
+*  This program is distributed in the hope that it will be useful,
+*  but WITHOUT ANY WARRANTY; without even the implied warranty of
+*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*  GNU Lesser General Public License for more details.
+*
+*  You should have received a copy of the GNU Lesser General Public License
+*  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*
+*  Example:      MultipleBus
+*  Description:  Communicate with two extension controllers, each on their own
+*                I2C bus (e.g. Wire and Wire1). Requires a microcontroller
+*                with two I2C buses (e.g. Arduino Due or Teensy).
+*
+*                This example uses Nunchuks, but this process works the same
+*                with any controller in the library.
+*/
+
 #include <NintendoExtensionCtrl.h>
 
-// Requries a microcontroller with two I2C buses, e.g. Arduino Due or Teensy
 Nunchuk nchuk1(Wire);   // Controller on bus #1
 Nunchuk nchuk2(Wire1);  // Controller on bus #2
 

examples/Any/MultipleTypes/MultipleTypes.ino

@@ -1,3 +1,29 @@
+/*
+*  Project     Nintendo Extension Controller Library
+*  @author     David Madison
+*  @link       github.com/dmadison/NintendoExtensionCtrl
+*  @license    LGPLv3 - Copyright (c) 2018 David Madison
+*
+*  This file is part of the Nintendo Extension Controller Library.
+*
+*  This program is free software: you can redistribute it and/or modify
+*  it under the terms of the GNU Lesser General Public License as published by
+*  the Free Software Foundation, either version 3 of the License, or
+*  (at your option) any later version.
+*
+*  This program is distributed in the hope that it will be useful,
+*  but WITHOUT ANY WARRANTY; without even the implied warranty of
+*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*  GNU Lesser General Public License for more details.
+*
+*  You should have received a copy of the GNU Lesser General Public License
+*  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*
+*  Example:      MultipleTypes
+*  Description:  Connect to a controller and then switch between two controller
+*                types depending on the identity of the connected controller.
+*/
+
 #include <NintendoExtensionCtrl.h>
 
 ExtensionController controller;  // Port for communicating with extension controllers

examples/Any/SpeedTest/SpeedTest.ino

@@ -1,3 +1,29 @@
+/*
+*  Project     Nintendo Extension Controller Library
+*  @author     David Madison
+*  @link       github.com/dmadison/NintendoExtensionCtrl
+*  @license    LGPLv3 - Copyright (c) 2018 David Madison
+*
+*  This file is part of the Nintendo Extension Controller Library.
+*
+*  This program is free software: you can redistribute it and/or modify
+*  it under the terms of the GNU Lesser General Public License as published by
+*  the Free Software Foundation, either version 3 of the License, or
+*  (at your option) any later version.
+*
+*  This program is distributed in the hope that it will be useful,
+*  but WITHOUT ANY WARRANTY; without even the implied warranty of
+*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*  GNU Lesser General Public License for more details.
+*
+*  You should have received a copy of the GNU Lesser General Public License
+*  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*
+*  Example:      SpeedTest
+*  Description:  Connect to an extension controller and record the max
+*                number of updates per second.
+*/
+
 #include <NintendoExtensionCtrl.h>
 
 ExtensionController controller;  // Generic controller, 6 bytes
@@ -22,7 +48,7 @@ void loop() {
 	long millisStart = millis();
 
 	while (millis() - millisStart <= TestDuration && validData) {
-		validData = controller.update();
+		validData = controller.update();  // Update and check if sucessful
 		numUpdates++;
 	}
 

examples/Classic Controller/Classic_DebugPrint/Classic_DebugPrint.ino

@@ -1,3 +1,30 @@
+/*
+*  Project     Nintendo Extension Controller Library
+*  @author     David Madison
+*  @link       github.com/dmadison/NintendoExtensionCtrl
+*  @license    LGPLv3 - Copyright (c) 2018 David Madison
+*
+*  This file is part of the Nintendo Extension Controller Library.
+*
+*  This program is free software: you can redistribute it and/or modify
+*  it under the terms of the GNU Lesser General Public License as published by
+*  the Free Software Foundation, either version 3 of the License, or
+*  (at your option) any later version.
+*
+*  This program is distributed in the hope that it will be useful,
+*  but WITHOUT ANY WARRANTY; without even the implied warranty of
+*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*  GNU Lesser General Public License for more details.
+*
+*  You should have received a copy of the GNU Lesser General Public License
+*  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*
+*  Example:      Classic_DebugPrint
+*  Description:  Connect to a Classic Controller and continuously print
+*                its control data, nicely formatted for debugging, over
+*                the serial bus.
+*/
+
 #include <NintendoExtensionCtrl.h>
 
 ClassicController classic;

examples/Classic Controller/Classic_Demo/Classic_Demo.ino

@@ -1,3 +1,29 @@
+/*
+*  Project     Nintendo Extension Controller Library
+*  @author     David Madison
+*  @link       github.com/dmadison/NintendoExtensionCtrl
+*  @license    LGPLv3 - Copyright (c) 2018 David Madison
+*
+*  This file is part of the Nintendo Extension Controller Library.
+*
+*  This program is free software: you can redistribute it and/or modify
+*  it under the terms of the GNU Lesser General Public License as published by
+*  the Free Software Foundation, either version 3 of the License, or
+*  (at your option) any later version.
+*
+*  This program is distributed in the hope that it will be useful,
+*  but WITHOUT ANY WARRANTY; without even the implied warranty of
+*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*  GNU Lesser General Public License for more details.
+*
+*  You should have received a copy of the GNU Lesser General Public License
+*  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*
+*  Example:      Classic_Demo
+*  Description:  Connect to a Classic Controller and demonstrate all of
+*                the avaiable control data functions.
+*/
+
 #include <NintendoExtensionCtrl.h>
 
 ClassicController classic;

examples/DJ/DJ_DebugPrint/DJ_DebugPrint.ino

@@ -1,3 +1,30 @@
+/*
+*  Project     Nintendo Extension Controller Library
+*  @author     David Madison
+*  @link       github.com/dmadison/NintendoExtensionCtrl
+*  @license    LGPLv3 - Copyright (c) 2018 David Madison
+*
+*  This file is part of the Nintendo Extension Controller Library.
+*
+*  This program is free software: you can redistribute it and/or modify
+*  it under the terms of the GNU Lesser General Public License as published by
+*  the Free Software Foundation, either version 3 of the License, or
+*  (at your option) any later version.
+*
+*  This program is distributed in the hope that it will be useful,
+*  but WITHOUT ANY WARRANTY; without even the implied warranty of
+*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*  GNU Lesser General Public License for more details.
+*
+*  You should have received a copy of the GNU Lesser General Public License
+*  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*
+*  Example:      DJ_DebugPrint
+*  Description:  Connect to a DJ Hero turntable and continuously print
+*                its control data, nicely formatted for debugging, over
+*                the serial bus.
+*/
+
 #include <NintendoExtensionCtrl.h>
 
 DJTurntableController dj;

examples/DJ/DJ_Demo/DJ_Demo.ino

@@ -1,3 +1,29 @@
+/*
+*  Project     Nintendo Extension Controller Library
+*  @author     David Madison
+*  @link       github.com/dmadison/NintendoExtensionCtrl
+*  @license    LGPLv3 - Copyright (c) 2018 David Madison
+*
+*  This file is part of the Nintendo Extension Controller Library.
+*
+*  This program is free software: you can redistribute it and/or modify
+*  it under the terms of the GNU Lesser General Public License as published by
+*  the Free Software Foundation, either version 3 of the License, or
+*  (at your option) any later version.
+*
+*  This program is distributed in the hope that it will be useful,
+*  but WITHOUT ANY WARRANTY; without even the implied warranty of
+*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*  GNU Lesser General Public License for more details.
+*
+*  You should have received a copy of the GNU Lesser General Public License
+*  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*
+*  Example:      DJ_Demo
+*  Description:  Connect to a DJ Hero turntable and demonstrate all of
+*                the avaiable control data functions.
+*/
+
 #include <NintendoExtensionCtrl.h>
 
 DJTurntableController dj;

examples/DJ/DJ_EffectDial/DJ_EffectDial.ino

@@ -1,3 +1,30 @@
+/*
+*  Project     Nintendo Extension Controller Library
+*  @author     David Madison
+*  @link       github.com/dmadison/NintendoExtensionCtrl
+*  @license    LGPLv3 - Copyright (c) 2018 David Madison
+*
+*  This file is part of the Nintendo Extension Controller Library.
+*
+*  This program is free software: you can redistribute it and/or modify
+*  it under the terms of the GNU Lesser General Public License as published by
+*  the Free Software Foundation, either version 3 of the License, or
+*  (at your option) any later version.
+*
+*  This program is distributed in the hope that it will be useful,
+*  but WITHOUT ANY WARRANTY; without even the implied warranty of
+*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*  GNU Lesser General Public License for more details.
+*
+*  You should have received a copy of the GNU Lesser General Public License
+*  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*
+*  Example:      DJ_EffectDial
+*  Description:  Connect to a DJ Hero turntable and show how the
+*                EffectRollover class works to track the change in
+*                the effect dial, even between rollovers.
+*/
+
 #include <NintendoExtensionCtrl.h>
 
 DJTurntableController dj;

examples/Drums/Drums_DebugPrint/Drums_DebugPrint.ino

@@ -1,3 +1,30 @@
+/*
+*  Project     Nintendo Extension Controller Library
+*  @author     David Madison
+*  @link       github.com/dmadison/NintendoExtensionCtrl
+*  @license    LGPLv3 - Copyright (c) 2018 David Madison
+*
+*  This file is part of the Nintendo Extension Controller Library.
+*
+*  This program is free software: you can redistribute it and/or modify
+*  it under the terms of the GNU Lesser General Public License as published by
+*  the Free Software Foundation, either version 3 of the License, or
+*  (at your option) any later version.
+*
+*  This program is distributed in the hope that it will be useful,
+*  but WITHOUT ANY WARRANTY; without even the implied warranty of
+*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*  GNU Lesser General Public License for more details.
+*
+*  You should have received a copy of the GNU Lesser General Public License
+*  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*
+*  Example:      Drums_DebugPrint
+*  Description:  Connect to a Guitar Hero drum set and continuously print
+*                its control data, nicely formatted for debugging, over
+*                the serial bus.
+*/
+
 #include <NintendoExtensionCtrl.h>
 
 DrumController drums;