00001 // USBJoystick.h 00002 // 00003 // USB Interface to USB joystick/game pad, such as Logitech 'Dual Action' game pad 00004 /// 00005 /// \mainpage Arduino USB Interface to USB joystick/game pad 00006 /// 00007 /// This is the USBJoystick 1.1 library. 00008 /// It provides an Arduino library and class for reading input from a 00009 /// USB joystick/game pad, such as Logitech 'Dual Action' game pad. 00010 /// It can be subclassed to get control when new input values are read, or when they actually change. 00011 /// Alternatively, you can set up callback functions to be called 00012 /// when new input values are read, or when they actually change. 00013 /// 00014 /// The version of the package that this documentation refers to can be downloaded 00015 /// from http://www.open.com.au/mikem/arduino/USBJoystick/USBJoystick-1.1.zip 00016 /// You can find the latest version at http://www.open.com.au/mikem/arduino/USBJoystick 00017 /// 00018 /// \par Prerequisites 00019 /// 00020 /// Requires: 00021 /// - SparkFun USB Host Shield 00022 /// - USB_Host_Shield library. Install this in your libraries folder with a command like: 00023 /// \code 00024 /// git clone git://github.com/felis/USB_Host_Shield.git 00025 /// \endcode 00026 /// 00027 /// This library does not steal any timers or add any interrupt handlers. 00028 /// 00029 /// \par Example programs 00030 /// 00031 /// Example Arduino programs are included to show the main modes of use. 00032 /// 00033 /// The following example programs are provided: 00034 /// - usbjoystick_test: Simple demonstration that prints to Serial when input changes 00035 /// 00036 /// \par Installation 00037 /// 00038 /// Install in the usual way: unzip the distribution zip file to the libraries 00039 /// sub-folder of your sketchbook. 00040 /// 00041 /// If you are using the older Sparkfun DEV-09628 USB Host Shield, you will need to alter the 00042 /// pin definitions in Max3421e_constants.h in the USB_Host_Shield library as discussed in 00043 /// http://www.sparkfun.com/products/9628 00044 /// 00045 /// If you require the USB Host Shield to be installed with WiShield, expect pin conflicts. These can be resolved by 00046 /// Bending the USB Host Shield pins D8, D9 and D10 out of the way and then jumpering Host Shield D10 to D6, 00047 /// Host Shield D9 to D3, Host Shield D8 to D5, then changing the settings in Max3421e_constants.h like this 00048 /// (for the older Sparkfun DEV-09628 USB Host Shield). See <a href="IMG_8837.JPG">this photo</a> showing Duemilanove, 00049 /// WiShield and USB Host Shield stack. 00050 /// \code 00051 /// // For USB Host Shield DEV-09628 interop with WiShield 00052 /// #define MAX_SS 6 00053 /// #define MAX_INT 3 00054 /// #define MAX_GPX 7 00055 /// #define MAX_RESET 5 00056 /// \endcode 00057 /// 00058 /// This library has been tested with Duemilanove and SparkFun USB Host Shield DEV-09628, with the 00059 /// Logitech 'Dual Action' USB Game Pad P/N 863247-0010 compiled with arduino-0021 00060 /// on OpenSuSE 11.1 and avr-libc-1.6.1-1.15, 00061 /// cross-avr-binutils-2.19-9.1, cross-avr-gcc-4.1.3_20080612-26.5. 00062 /// 00063 /// \author Mike McCauley (mikem@open.com.au) 00064 /// 00065 /// This software is Copyright (C) 2011 Mike McCauley. Use is subject to license 00066 /// conditions. The main licensing options available are GPL V2 or Commercial: 00067 /// 00068 /// \par Open Source Licensing GPL V2 00069 /// This is the appropriate option if you want to share the source code of your 00070 /// application with everyone you distribute it to, and you also want to give them 00071 /// the right to share who uses it. If you wish to use this software under Open 00072 /// Source Licensing, you must contribute all your source code to the open source 00073 /// community in accordance with the GPL Version 2 when your application is 00074 /// distributed. See http://www.gnu.org/copyleft/gpl.html 00075 /// 00076 /// \par Commercial Licensing 00077 /// This is the appropriate option if you are creating proprietary applications 00078 /// and you are not prepared to distribute and share the source code of your 00079 /// application. Contact info@open.com.au for details. 00080 /// 00081 /// \par Revision History 00082 /// 00083 /// - Version 1.0: Initial release 00084 /// - Version 1.1: Compiles under Arduino 1.0 PROVIDED: you modify (or update) 00085 /// the USB_Host_Shield library so it builds under 1.0 too. At the time of writing there 00086 /// was no update to USB_Host_Shield available for 1.0. 00087 00088 // Copyright (C) 2010 Mike McCauley 00089 // $Id: USBJoystick.h,v 1.1 2011/03/14 06:05:34 mikem Exp mikem $ 00090 00091 #ifndef USBJoystick_h 00092 #define USBJoystick_h 00093 00094 #include <Usb.h> 00095 #include <inttypes.h> 00096 #include "Max3421e_constants.h" 00097 00098 ///////////////////////////////////////////////////////////////////// 00099 /// \class USBJoystick USBJoystick.h <USBJoystick.h> 00100 /// \brief USB Interface to USB joystick/game pad, such as Logitech 'Dual Action' game pad 00101 /// 00102 /// \par Overview 00103 /// 00104 /// A class that interfaces with a USB Joystick or game pad. 00105 /// It can be subclassed to get control when new input values are read, or when they actually change. 00106 /// Alternatively, you can set up callback functions to be called 00107 /// when new input values are read, or when they actually change. 00108 /// 00109 /// Input data such as stick positions, button presses and hat-switch directions are read from the device 00110 /// and delivered to the calling 00111 /// application. 00112 /// 00113 /// USBJoystick uses the USB_Host_Shield library to initialise and interrogate a USB joystick or game pad. 00114 /// When the task() function is called, an attempt to read new values from the joystick is made every 00115 /// USBJOYSTICK_POLL_INTERVAL milliseconds. 00116 /// If successful the NewValue 00117 /// virtual functions are called. These in turn call the ValueDidChange virtual functions if the value 00118 /// changed since last poll. After the poll the new values can also be read with the data accessor functions. 00119 /// 00120 /// The virtual functions will call their respective callbacks if callback functions have been set up. 00121 /// 00122 /// Therefore developers have several choices for getting input data from a device: 00123 /// - subclass USBJoystick and override the *NewValue() and/or *ValueDidChange() functions. 00124 /// - set callback functions with set*NewValueCallback() and set*ValueDidChangeCallback() functions 00125 /// - Asynchronously read current values with the *Value() functions. 00126 /// 00127 /// \par Input indexes 00128 /// 00129 /// The joystick/game pad is considered to have a number of joysticks, buttons and hat switches. In order 00130 /// to identifiy which joysticks, buttons or hat switch is being referred to in callbacks etc, an index number is used. 00131 /// Macros can be used to refer to specific items by name, see the USBJOYSTICK_STICK_*, USBJOYSTICK_BUTTON_* and 00132 /// USBJOYSTICK_HAT_* macros. The Logitech Dula Action game pad has 4 sticks 00133 /// (really 2 physical sticks with vertical and horizontal movement), 13 buttons and 1 hat switch. 00134 /// 00135 /// \par Input Device Values 00136 /// 00137 /// Stick positions are represented as 8 bit unsigned integers: 00138 /// - 0 is fully left or up 00139 /// - 255 is fully right or down 00140 /// 00141 /// Button positions are represented by booleans: 00142 /// - true - button is pressed (in the case of MODE button, mode is enabled and the red light is on) 00143 /// - false - otherwise 00144 /// 00145 /// Hat switch positions are represented as 8 bit unsigned integers. 00146 /// The current hat position is one of USBJOYSTICK_HAT_POS_*. 00147 class USBJoystick 00148 { 00149 00150 #define USBJOYSTICK_NUM_STICKS 4 00151 #define USBJOYSTICK_NUM_BUTTONS 13 00152 #define USBJOYSTICK_NUM_HATS 1 00153 00154 /// These are valid values for the stick index in callbacks etc 00155 #define USBJOYSTICK_STICK_LEFT_HORIZ 0 00156 #define USBJOYSTICK_STICK_LEFT_VERT 1 00157 #define USBJOYSTICK_STICK_RIGHT_HORIZ 2 00158 #define USBJOYSTICK_STICK_RIGHT_VERT 3 00159 00160 /// These are valid values for the button index in callbacks etc 00161 #define USBJOYSTICK_BUTTON_MODE 0 00162 #define USBJOYSTICK_BUTTON_1 1 00163 #define USBJOYSTICK_BUTTON_2 2 00164 #define USBJOYSTICK_BUTTON_3 3 00165 #define USBJOYSTICK_BUTTON_4 4 00166 #define USBJOYSTICK_BUTTON_5 5 00167 #define USBJOYSTICK_BUTTON_6 6 00168 #define USBJOYSTICK_BUTTON_7 7 00169 #define USBJOYSTICK_BUTTON_8 8 00170 #define USBJOYSTICK_BUTTON_9 9 00171 #define USBJOYSTICK_BUTTON_10 10 00172 #define USBJOYSTICK_BUTTON_LEFT_STICK 11 00173 #define USBJOYSTICK_BUTTON_RIGHT_STICK 12 00174 00175 // These are valid values for the hat index in callbacks etc 00176 #define USBJOYSTICK_HAT_1 0 00177 00178 // These are valid values for the hat value in callbacks etc 00179 #define USBJOYSTICK_HAT_POS_N 0 00180 #define USBJOYSTICK_HAT_POS_NE 1 00181 #define USBJOYSTICK_HAT_POS_E 2 00182 #define USBJOYSTICK_HAT_POS_SE 3 00183 #define USBJOYSTICK_HAT_POS_S 4 00184 #define USBJOYSTICK_HAT_POS_SW 5 00185 #define USBJOYSTICK_HAT_POS_W 6 00186 #define USBJOYSTICK_HAT_POS_NW 7 00187 #define USBJOYSTICK_HAT_POS_IDLE 8 00188 00189 // Milliseconds 00190 #define USBJOYSTICK_POLL_INTERVAL 50 00191 00192 public: 00193 /// Constructor. 00194 /// Stick positions are initialised to 0x80, buttons to false and hat switches to idle 00195 USBJoystick(); 00196 00197 /// Library initialisation. 00198 /// Must be called once during setup() 00199 /// Enables the USB hardware and delays 200msec 00200 void init(); 00201 00202 /// USB Device regular poll function. 00203 /// Attempts to read current data from the USB device. 00204 /// If successful, calls the *NewValue() and/or *ValueDidChange() functions, and any calbacks if so configured. 00205 /// This must be called as often as possible in your main loop(). 00206 /// Calls the intenal poll() functi0on every USBJOYSTICK_POLL_INTERVAL milliseconds 00207 void run(); 00208 00209 /// Read the current value of a joystick 00210 /// \param[in] stick The stick index. One of USBJOYSTICK_STICK_* 00211 /// \return the most recently read stick position value 00212 uint8_t stickValue(uint8_t stick); 00213 00214 /// Read the current value of a button 00215 /// param[in] button The button index. One of USBJOYSTICK_BUTTON_* 00216 /// \return the most recently read button position value 00217 boolean buttonValue(uint8_t button); 00218 00219 /// Read the current value of a joystick 00220 /// \param[in] hat The stick index. One of USBJOYSTICK_HAT_* 00221 /// \return the most recently read hat position value, one of USBJOYSTICK_HAT_POS_* 00222 uint8_t hatValue(uint8_t hat); 00223 00224 /// Set a callback to be called when a stick value is read from 00225 /// the usb device. Overrides any previously set callback. May be called at any time 00226 /// to set or change the callback. 00227 /// \param[in] cb The new callback function pointer 00228 void setStickNewValueCallback(void (*cb)(uint8_t stick, uint8_t value)); 00229 00230 /// Set a callback to be called when a button value is read from 00231 /// the usb device. Overrides any previously set callback. May be called at any time 00232 /// to set or change the callback. 00233 /// \param[in] cb The new callback function pointer 00234 void setButtonNewValueCallback(void (*cb)(uint8_t button, uint8_t value)); 00235 00236 /// Set a callback to be called when a hat value is read from 00237 /// the usb device. Overrides any previously set callback. May be called at any time 00238 /// to set or change the callback. 00239 /// \param[in] cb The new callback function pointer 00240 void setHatNewValueCallback(void (*cb)(uint8_t hat, uint8_t value)); 00241 00242 /// Set a callback to be called when a stick value is read from 00243 /// the usb device and the value has changed since the last poll. 00244 /// Overrides any previously set callback. May be called at any time 00245 /// to set or change the callback. 00246 /// \param[in] cb The new callback function pointer 00247 void setStickValueDidChangeCallback(void (*cb)(uint8_t stick, uint8_t value)); 00248 00249 /// Set a callback to be called when a button value is read from 00250 /// the usb device and the value has changed since the last poll. 00251 /// Overrides any previously set callback. May be called at any time 00252 /// to set or change the callback. 00253 /// \param[in] cb The new callback function pointer 00254 void setButtonValueDidChangeCallback(void (*cb)(uint8_t button, uint8_t value)); 00255 00256 /// Set a callback to be called when a hat value is read from 00257 /// the usb device and the value has changed since the last poll. 00258 /// Overrides any previously set callback. May be called at any time 00259 /// to set or change the callback. 00260 /// \param[in] cb The new callback function pointer 00261 void setHatValueDidChangeCallback(void (*cb)(uint8_t hat, uint8_t value)); 00262 00263 protected: 00264 00265 /// Initialises the USB hardware. 00266 /// Internal use: should not be called directly. 00267 /// \return true if initialisation was successful 00268 boolean device_init(); 00269 00270 /// Polls the USB device for a new reading. 00271 /// Internal use: should not be called directly. 00272 void poll(); 00273 00274 /// This virtual function is called when a new stick value is read from the USB device 00275 /// Default implementation calls the apropriate callback (if set) then calls 00276 /// stickValueDidChange() if the value changed since the last poll. 00277 /// Subclasses may override this to change get control for each value read and change 00278 /// the default behaviour 00279 /// \param[in] stick The stick index, one of USBJOYSTICK_STICK_* 00280 /// \param[in] value The new stick value 00281 virtual void stickNewValue(uint8_t stick, uint8_t value); 00282 00283 /// This virtual function is called when a new button value is read from the USB device 00284 /// Default implementation calls the apropriate callback (if set) then calls 00285 /// buttonValueDidChange() if the value changed since the last poll. 00286 /// Subclasses may override this to change get control for each value read and change 00287 /// the default behaviour 00288 /// \param[in] button The button index, one of USBJOYSTICK_BUTTON_* 00289 /// \param[in] value The new button value 00290 virtual void buttonNewValue(uint8_t button, boolean value); 00291 00292 /// This virtual function is called when a new hat switch value is read from the USB device 00293 /// Default implementation calls the apropriate callback (if set) then calls 00294 /// hatValueDidChange() if the value changed since the last poll. 00295 /// Subclasses may override this to change get control for each value read and change 00296 /// the default behaviour 00297 /// \param[in] hat The hat switch index, one of USBJOYSTICK_HAT_* 00298 /// \param[in] value The new hat position value 00299 virtual void hatNewValue(uint8_t hat, uint8_t value); 00300 00301 /// This virtual function is called when a stick value changes 00302 /// Default implementation calls the apropriate callback (if set) 00303 /// \param[in] stick The stick index, one of USBJOYSTICK_STICK_* 00304 /// \param[in] value The new stick value 00305 virtual void stickValueDidChange(uint8_t stick, uint8_t value); 00306 00307 /// This virtual function is called when a button value changes 00308 /// Default implementation calls the apropriate callback (if set) 00309 /// \param[in] button The button index, one of USBJOYSTICK_BUTTON_* 00310 /// \param[in] value The new button value 00311 virtual void buttonValueDidChange(uint8_t button, boolean value); 00312 00313 /// This virtual function is called when a hat switch value changes 00314 /// Default implementation calls the apropriate callback (if set) 00315 /// \param[in] hat The hat index, one of USBJOYSTICK_HAT_* 00316 /// \param[in] value The new hat switch value 00317 virtual void hatValueDidChange(uint8_t hat, uint8_t value); 00318 00319 private: 00320 // Stores current (last read) value for each stick and button 00321 uint8_t _stick_value[USBJOYSTICK_NUM_STICKS]; 00322 boolean _button_value[USBJOYSTICK_NUM_BUTTONS]; 00323 uint8_t _hat_value[USBJOYSTICK_NUM_HATS]; 00324 00325 // Callback pointers 00326 void (*_stick_new_value_cb)(uint8_t stick, uint8_t value); 00327 void (*_button_new_value_cb)(uint8_t button, boolean value); 00328 void (*_hat_new_value_cb)(uint8_t hat, uint8_t value); 00329 void (*_stick_value_did_change_cb)(uint8_t stick, uint8_t value); 00330 void (*_button_value_did_change_cb)(uint8_t button, boolean value); 00331 void (*_hat_value_did_change_cb)(uint8_t hat, uint8_t value); 00332 00333 // USB interface data 00334 EP_RECORD ep_record[2]; 00335 uint8_t buf[8]; 00336 }; 00337 00338 #endif