wiimote.h
Go to the documentation of this file.
00001 // _______________________________________________________________________________ 00002 // 00003 // - WiiYourself! - native C++ Wiimote library v1.15 00004 // (c) gl.tter 2007-10 - http://gl.tter.org 00005 // 00006 // see License.txt for conditions of use. see History.txt for change log. 00007 // _______________________________________________________________________________ 00008 // 00009 // wiimote.h (tab = 4 spaces) 00010 00011 #ifdef _MSC_VER // VC 00012 # pragma once 00013 #endif 00014 00015 #ifndef _WIIMOTE_H 00016 # define _WIIMOTE_H 00017 00018 #define WIN32_LEAN_AND_MEAN 00019 #include <windows.h> 00020 #include <tchar.h> // auto Unicode/Ansi support 00021 #include <queue> // for HID write method 00022 #include <list> // for state recording 00023 00024 #ifndef QWORD 00025 typedef unsigned __int64 QWORD; 00026 #endif 00027 00028 #ifdef _MSC_VER // VC-specific: _DEBUG build only _ASSERT() sanity checks 00029 # include <crtdbg.h> 00030 #elif defined(__MINGW32__) // define NDEBUG to disable assert 00031 # include <assert.h> 00032 # define _ASSERT assert 00033 #else 00034 # define _ASSERT(x) ((void)0) // (add your compiler's implementation if you like) 00035 #endif 00036 00037 // #ifdef SWIGWRAPPER // Python Wrapper 00038 // #include "Python/wiimote_state.i" 00039 // #else 00040 #include "wiimote_state.h" 00041 // #endif 00042 00043 // configs: 00044 //#define USE_DYNAMIC_HIDQUEUE // deprecated 00045 00046 // we request periodic status report updates to refresh the battery level 00047 // and to detect connection loss (through failed writes) 00048 #define REQUEST_STATUS_EVERY_MS 1000 00049 #define DETECT_MPLUS_EVERY_MS 1000 00050 #define DETECT_MPLUS_COUNT 1 // # of tries in quick succession 00051 00052 // all threads (read/parse, audio streaming, async rumble...) use this priority 00053 #define WORKER_THREAD_PRIORITY THREAD_PRIORITY_HIGHEST 00054 00055 // internals 00056 #define WIIYOURSELF_VERSION_MAJOR 1 00057 #define WIIYOURSELF_VERSION_MINOR1 1 00058 #define WIIYOURSELF_VERSION_MINOR2 5 00059 //#define WIIYOURSELF_VERSION_BETA // not defined for non-beta releases 00060 #define WIIYOURSELF_VERSION_STR _T("1.15") 00061 00062 // array sizes 00063 #define TOTAL_BUTTON_BITS 16 // Number of bits for (Classic)ButtonNameFromBit[] 00064 #define TOTAL_FREQUENCIES 10 // Number of frequencies (see speaker_freq[]) 00065 00066 // clarity 00067 typedef HANDLE EVENT; 00068 00069 00070 // state data changes can be signalled to the app via a callback. Set the wiimote 00071 // object's 'ChangedCallback' any time to enable them, or alternatively inherit 00072 // from the wiimote object and override the ChangedNotifier() virtual method. 00073 00074 // of flags indicating which state has changed since the last callback. 00075 typedef void (*state_changed_callback) (class wiimote &owner, 00076 state_change_flags changed, 00077 const wiimote_state &new_state); 00078 00079 // internals 00080 typedef BOOLEAN (__stdcall *hidwrite_ptr)(HANDLE HidDeviceObject, 00081 PVOID ReportBuffer, 00082 ULONG ReportBufferLength); 00083 00084 // (global due to Python wrapper) 00085 struct wiimote_state_event { 00086 DWORD time_ms; // system timestamp in milliseconds 00087 wiimote_state state; 00088 }; 00089 00090 // wiimote class - connects and manages a wiimote and its optional extensions 00091 // (Nunchuk/Classic Controller), and exposes their state 00092 class wiimote : public wiimote_state 00093 { 00094 public: 00095 wiimote (); 00096 virtual ~wiimote (); 00097 00098 public: 00099 // these can be used to identify Connect()ed wiimote objects (if both 00100 // are unconnected they will pass the compare as their handles are invalid) 00101 inline bool operator == (const wiimote& remote) 00102 { return Handle == remote.Handle; } 00103 inline bool operator != (const wiimote& remote) 00104 { return Handle != remote.Handle; } 00105 00106 // wiimote data input mode (use with SetReportType()) 00107 // (only enable what you need to save battery power) 00108 enum input_report 00109 { 00110 // combinations if buttons/acceleration/IR/Extension data 00111 IN_BUTTONS = 0x30, 00112 IN_BUTTONS_ACCEL = 0x31, 00113 IN_BUTTONS_ACCEL_IR = 0x33, // reports IR EXTENDED data (dot sizes) 00114 IN_BUTTONS_ACCEL_EXT = 0x35, 00115 IN_BUTTONS_ACCEL_IR_EXT = 0x37, // reports IR BASIC data (no dot sizes) 00116 IN_BUTTONS_BALANCE_BOARD = 0x32, // must use this for the balance board 00117 }; 00118 // string versions 00119 static const TCHAR* ReportTypeName []; 00120 00121 00122 public: // convenience accessors: 00123 inline bool IsConnected () const { return bStatusReceived; } 00124 // if IsConnected() unexpectedly returns false, connection was probably lost 00125 inline bool ConnectionLost () const { return bConnectionLost; } 00126 inline bool IsBalanceBoard () const { return (Internal.bExtension && 00127 (Internal.ExtensionType==wiimote_state::BALANCE_BOARD)); } 00128 inline bool NunchukConnected () const { return (Internal.bExtension && 00129 (Internal.ExtensionType==wiimote_state::NUNCHUK)); } 00130 inline bool ClassicConnected () const { return (Internal.bExtension && 00131 (Internal.ExtensionType==wiimote_state::CLASSIC)); } 00132 inline bool MotionPlusConnected () const { return bMotionPlusDetected; } 00133 inline bool MotionPlusEnabled () const { return bMotionPlusEnabled; } 00134 inline bool MotionPlusHasExtension() const { return bMotionPlusExtension; } 00135 inline bool IsPlayingAudio () const { return (Internal.Speaker.Freq && 00136 Internal.Speaker.Volume); } 00137 inline bool IsPlayingSample () const { return IsPlayingAudio() && 00138 (CurrentSample != NULL); } 00139 inline bool IsUsingHIDwrites () const { return bUseHIDwrite; } 00140 inline bool IsRecordingState () const { return Recording.bEnabled; } 00141 00142 static inline unsigned TotalConnected() { return _TotalConnected; } 00143 00144 00145 public: // data 00146 QWORD UniqueID; // constructed from device-specific calibration info. 00147 // Note this is not guaranteed to be truly unique 00148 // as several devices may contain the same calibration 00149 // vluaes - but unique amongst a small number of 00150 // devices. 00151 #ifdef ID2_FROM_DEVICEPATH 00152 QWORD UniqueID2; // (low-reliabilty, left for reference) 00153 // constructed from the 'device path' string (as 00154 // reported by the OS/stack). This is hopefully 00155 // unique as long as the devices remain installed 00156 // (or at least paired). 00157 #endif 00158 // optional callbacks - set these to your own fuctions (if required) 00159 state_changed_callback ChangedCallback; 00160 // you can avoid unnecessary callback overhead by specifying a mask 00161 // of which state changes should trigger them (default is any) 00162 state_change_flags CallbackTriggerFlags; 00163 // alternatively, inherit from this class and override this virtual function: 00164 virtual void ChangedNotifier (state_change_flags changed, 00165 const wiimote_state &new_state) {}; 00166 00167 // get the button name from its bit index (some bits are unused) 00168 static const TCHAR* ButtonNameFromBit [TOTAL_BUTTON_BITS]; 00169 static const TCHAR* GetButtonNameFromBit (unsigned index) 00170 { 00171 _ASSERT(index < TOTAL_BUTTON_BITS); 00172 if(index >= TOTAL_BUTTON_BITS) 00173 return _T("[invalid index]"); 00174 return ButtonNameFromBit[index]; 00175 } 00176 00177 // same for the Classic Controller 00178 static const TCHAR* ClassicButtonNameFromBit [TOTAL_BUTTON_BITS]; 00179 static const TCHAR* GetClassicButtonNameFromBit (unsigned index) 00180 { 00181 _ASSERT(index < TOTAL_BUTTON_BITS); 00182 if(index >= TOTAL_BUTTON_BITS) 00183 return _T("[invalid index]"); 00184 return ClassicButtonNameFromBit[index]; 00185 } 00186 00187 // get the frequency from speaker_freq enum 00188 static const unsigned FreqLookup [TOTAL_FREQUENCIES]; 00189 static const unsigned GetFreqLookup (unsigned index) 00190 { 00191 _ASSERT(index < TOTAL_FREQUENCIES); 00192 if(index >= TOTAL_FREQUENCIES) 00193 return 0; 00194 return FreqLookup[index]; 00195 } 00196 00197 public: // methods 00198 // call Connect() first - returns true if wiimote was found & enabled 00199 // - 'wiimote_index' specifies which *installed* (not necessarily 00200 // *connected*) wiimote should be tried (1 = first, 2 = 2nd etc). 00201 // if you just want the first *available* wiimote that isn't already 00202 // in use, pass in FIRST_AVAILABLE (default). 00203 // - 'force_hidwrites' forces HID output method (it's auto-selected 00204 // when needed and less efficient, so only force for testing). 00205 static const unsigned FIRST_AVAILABLE = 0xffffffff; 00206 bool Connect (unsigned wiimote_index = FIRST_AVAILABLE, 00207 bool force_hidwrites = false); 00208 // disconnect from the controller and stop reading data from it 00209 void Disconnect (); 00210 // set wiimote reporting mode (call after Connnect()) 00211 // continous = true forces the wiimote to send constant updates, even when 00212 // nothing has changed. 00213 // = false only sends data when something has changed (note that 00214 // acceleration data will cause frequent updates anyway as it 00215 // jitters even when the wiimote is stationary) 00216 void SetReportType (input_report type, bool continuous = false); 00217 00218 // toggle the MotionPlus extension. Call MotionPlusDetected() first to 00219 // see if it's attached. Unlike normal extensions, the MotionPlus does 00220 // not report itself as one until enabled. Once done, it then replaces 00221 // any standard extension attached to it, so be sure to disable it 00222 // if you want to read those (it's not currently known of both can 00223 // be read simultaneously). 00224 bool EnableMotionPlus (); 00225 bool DisableMotionPlus (); 00226 00227 // this is used to remove unwanted 'at rest' offsets, currently only from 00228 // the Balance Board. make sure there is no weight on the board before 00229 // calling this. it reads the current sensor values and then removes them 00230 // offsets from all subsequent KG and LB state values (the 'raw' values 00231 // are never modified). 00232 void CalibrateAtRest (); 00233 // NOTE: the library automatically calls this when the first weight values 00234 // come in after Connect()ion, but if the device wasn't at rest at 00235 // the time the app can call it again later. 00236 00237 // to read the state via polling (reading the public state data direct from 00238 // the wiimote object) you must call RefreshState() at the top of every pass. 00239 // returns a combination of flags to indicate which state (if any) has 00240 // changed since the last call. 00241 state_change_flags RefreshState (); 00242 00243 // reset the wiimote (changes report type to non-continuous buttons-only, 00244 // clears LEDs & rumble, mutes & disables speaker) 00245 void Reset (); 00246 // set/clear the wiimote LEDs 00247 void SetLEDs (BYTE led_bits); // bits 0-3 are valid 00248 // set/clear rumble 00249 void SetRumble (bool on); 00250 // alternative - rumble for a fixed amount of time (asynchronous) 00251 void RumbleForAsync (unsigned milliseconds); 00252 00253 // *experimental* speaker support: 00254 bool MuteSpeaker (bool on); 00255 bool EnableSpeaker (bool on); 00256 bool PlaySquareWave (speaker_freq freq, BYTE volume = 0x40); 00257 // note: PlaySample currently streams from the passed-in wiimote_sample - 00258 // don't delete it until playback has stopped. 00259 bool PlaySample (const wiimote_sample &sample, 00260 BYTE volume = 0x40, 00261 speaker_freq freq_override = FREQ_NONE); 00262 00263 // 16bit mono sample loading/conversion to native format: 00264 // .wav sample 00265 static bool Load16bitMonoSampleWAV (const TCHAR* filepath, 00266 wiimote_sample &out); 00267 // raw 16bit mono audio data (can be signed or unsigned) 00268 static bool Load16BitMonoSampleRAW (const TCHAR* filepath, 00269 bool _signed, 00270 speaker_freq freq, 00271 wiimote_sample &out); 00272 // converts a 16bit mono sample array to a wiimote_sample 00273 static bool Convert16bitMonoSamples (const short* samples, 00274 bool _signed, 00275 DWORD length, 00276 speaker_freq freq, 00277 wiimote_sample &out); 00278 00279 // state recording - records state snapshots to a 'state_history' supplied 00280 // by the caller. states are timestamped and only added 00281 // to the list when the specified state changes. 00282 #ifndef SWIG // !Python Wrapper 00283 typedef wiimote_state_event state_event; 00284 #endif 00285 typedef std::list<state_event> state_history; 00286 static const unsigned UNTIL_STOP = 0xffffffff; 00287 // - pass in a 'state_history' list, and don't destroy/change it until 00288 // recording is stopped. note the list will be cleared first. 00289 // - you can request a specific duration (and use IsRecordingState() to detect 00290 // the end), or UNTIL_STOP. StopRecording() can be called either way. 00291 // - you can use 'change trigger' to specify specific state changes that will 00292 // trigger an insert into the history (others are then ignored). 00293 void RecordState (state_history &events_out, 00294 unsigned max_time_ms = UNTIL_STOP, 00295 state_change_flags change_trigger = CHANGED_ALL); 00296 void StopRecording (); 00297 00298 00299 private: // methods 00300 // start reading asynchronously from the controller 00301 bool BeginAsyncRead (); 00302 // request status update (battery level, extension status etc) 00303 void RequestStatusReport (); 00304 // read address or register from Wiimote asynchronously (the result is 00305 // parsed internally whenever it arrives) 00306 bool ReadAddress (int address, short size); 00307 // write a single BYTE to a wiimote address or register 00308 inline void WriteData (int address, BYTE data) { WriteData(address, 1, &data); } 00309 // write a BYTE array to a wiimote address or register 00310 void WriteData (int address, BYTE size, const BYTE* buff); 00311 // callback when data is ready to be processed 00312 void OnReadData (DWORD bytes_read); 00313 // parse individual reports by type 00314 int ParseInput (BYTE* buff); 00315 // detects if MotionPlus is attached (it doesn't report as a normal 00316 // extesnion until it is enabled) 00317 void DetectMotionPlusExtensionAsync (); 00318 // initializes an extension when plugged in. 00319 void InitializeExtension (); 00320 // parses a status report 00321 int ParseStatus (BYTE* buff); 00322 // parses the buttons 00323 int ParseButtons (BYTE* buff); 00324 // parses accelerometer data 00325 int ParseAccel (BYTE* buff); 00326 bool EstimateOrientationFrom(wiimote_state::acceleration &accel); 00327 void ApplyJoystickDeadZones (wiimote_state::joystick &joy); 00328 // parses IR data from report 00329 int ParseIR (BYTE* buff); 00330 // parses data from an extension. 00331 int ParseExtension (BYTE* buff, unsigned offset); 00332 // parses data returned from a read report 00333 int ParseReadAddress (BYTE* buff); 00334 // reads calibration information stored on Wiimote 00335 void ReadCalibration (); 00336 float GetBalanceValue(short sensor, short min, short mid, short max); 00337 // turns on the IR sensor (the mode must match the reporting mode caps) 00338 void EnableIR (wiimote_state::ir::mode mode); 00339 // disables the IR sensor 00340 void DisableIR (); 00341 // writes a report to the Wiimote (NULL = use 'WriteBuff') 00342 bool WriteReport (BYTE* buff); 00343 bool StartSampleThread (); 00344 // returns the rumble BYTE that needs to be sent with reports. 00345 inline BYTE GetRumbleBit () const { return Internal.bRumble? 0x01 : 0x00; } 00346 00347 // static thread funcs: 00348 static unsigned __stdcall ReadParseThreadfunc (void* param); 00349 static unsigned __stdcall AsyncRumbleThreadfunc (void* param); 00350 static unsigned __stdcall SampleStreamThreadfunc(void* param); 00351 static unsigned __stdcall HIDwriteThreadfunc (void* param); 00352 00353 private: // data 00354 // wiimote output comands 00355 enum output_report 00356 { 00357 OUT_NONE = 0x00, 00358 OUT_LEDs = 0x11, 00359 OUT_TYPE = 0x12, 00360 OUT_IR = 0x13, 00361 OUT_SPEAKER_ENABLE = 0x14, 00362 OUT_STATUS = 0x15, 00363 OUT_WRITEMEMORY = 0x16, 00364 OUT_READMEMORY = 0x17, 00365 OUT_SPEAKER_DATA = 0x18, 00366 OUT_SPEAKER_MUTE = 0x19, 00367 OUT_IR2 = 0x1a, 00368 }; 00369 // input reports used only internally: 00370 static const int IN_STATUS = 0x20; 00371 static const int IN_READADDRESS = 0x21; 00372 // wiimote device IDs: 00373 static const int VID = 0x057e; // 'Nintendo' 00374 static const int PID = 0x0306; // 'Wiimote' 00375 // we could find this out the hard way using HID, but it's 22 00376 static const int REPORT_LENGTH = 22; 00377 // wiimote registers 00378 static const int REGISTER_CALIBRATION = 0x0016; 00379 static const int REGISTER_IR = 0x4b00030; 00380 static const int REGISTER_IR_SENSITIVITY_1 = 0x4b00000; 00381 static const int REGISTER_IR_SENSITIVITY_2 = 0x4b0001a; 00382 static const int REGISTER_IR_MODE = 0x4b00033; 00383 static const int REGISTER_EXTENSION_INIT1 = 0x4a400f0; 00384 static const int REGISTER_EXTENSION_INIT2 = 0x4a400fb; 00385 static const int REGISTER_EXTENSION_TYPE = 0x4a400fa; 00386 static const int REGISTER_EXTENSION_CALIBRATION = 0x4a40020; 00387 static const int REGISTER_BALANCE_CALIBRATION = 0x4a40024; 00388 static const int REGISTER_MOTIONPLUS_DETECT = 0x4a600fa; 00389 static const int REGISTER_MOTIONPLUS_INIT = 0x4a600f0; 00390 static const int REGISTER_MOTIONPLUS_ENABLE = 0x4a600fe; 00391 00392 HANDLE Handle; // read/write device handle 00393 OVERLAPPED Overlapped; // for async Read/WriteFile() IO 00394 HANDLE ReadParseThread; // waits for overlapped reads & parses result 00395 EVENT DataRead; // signals overlapped read complete 00396 bool bUseHIDwrite; // alternative write method (less efficient 00397 // but required for some BT stacks (eg. MS') 00398 // HidD_SetOutputReport is only supported from XP onwards, so detect & 00399 // load it dynamically: 00400 static HMODULE HidDLL; 00401 static hidwrite_ptr _HidD_SetOutputReport; 00402 00403 volatile bool bStatusReceived; // for output method detection 00404 volatile bool bConnectInProgress; // don't handle extensions until complete 00405 volatile bool bInitInProgress; // stop regular requests until complete 00406 volatile bool bEnablingMotionPlus; // for special init codepath 00407 volatile bool bConnectionLost; // auto-Disconnect()s if set 00408 volatile int MotionPlusDetectCount; // waiting for the result 00409 volatile bool bMotionPlusDetected; 00410 volatile bool bMotionPlusEnabled; 00411 volatile bool bMotionPlusExtension;// detected one plugged into MotionPlus 00412 volatile bool bCalibrateAtRest; // as soon as the first sensor values // come in after a Connect() call. 00413 static unsigned _TotalCreated; 00414 static unsigned _TotalConnected; 00415 input_report ReportType; // type of data the wiimote delivers 00416 // read buffer 00417 BYTE ReadBuff [REPORT_LENGTH]; 00418 // for polling: state is updated on a thread internally, and made only 00419 // made public via RefreshState() 00420 CRITICAL_SECTION StateLock; 00421 wiimote_state Internal; 00422 state_change_flags InternalChanged; // state changes since last RefreshState() 00423 // periodic status report requests (for battery level and connection loss 00424 // detection) 00425 DWORD NextStatusTime; 00426 DWORD NextMPlusDetectTime;// gap between motion plus detections 00427 DWORD MPlusDetectCount; // # of detection tries in quick succesion 00428 // async Hidd_WriteReport() thread 00429 HANDLE HIDwriteThread; 00430 #ifdef USE_DYNAMIC_HIDQUEUE 00431 std::queue<BYTE*> HIDwriteQueue; 00432 #else 00433 // fixed-size queue (to eliminate glitches caused by frequent dynamic memory 00434 // allocations) 00435 struct hid 00436 { 00437 hid () : Queue(NULL), ReadIndex(0), WriteIndex(0) {} 00438 00439 // Increase the static queue size if you get ASSERTs signalling an 00440 // overflow (too many reports queued up before being sent by the write 00441 // thread). These asserts are harmless though if caused as a result of 00442 // loosing the wiimote connection (eg. battery runs out, or wiimote is 00443 // unpaired by holding the power button). 00444 // Note: MAX_QUEUE_ENTRIES _must_ be a power-of-2, as it 00445 // uses index wraparound optimisations. 00446 static const unsigned MAX_QUEUE_ENTRIES = 1<<7; 00447 00448 inline bool IsEmpty() const { return (ReadIndex == WriteIndex); } 00449 00450 bool Allocate () { // allocate memory (only when needed) 00451 _ASSERT(!Queue); if(Queue) return true; 00452 ReadIndex = WriteIndex = 0; 00453 Queue = new queue_entry[MAX_QUEUE_ENTRIES]; 00454 _ASSERT(Queue); return (Queue != NULL); 00455 } 00456 void Deallocate () { 00457 if(!Queue) return; 00458 delete[] Queue; Queue = NULL; 00459 ReadIndex = WriteIndex = 0; 00460 } 00461 00462 struct queue_entry 00463 { 00464 queue_entry() { memset(Report, 0, sizeof(Report)); } 00465 00466 BYTE Report [REPORT_LENGTH]; 00467 } *Queue; 00468 00469 unsigned ReadIndex, WriteIndex; 00470 } HID; 00471 #endif 00472 CRITICAL_SECTION HIDwriteQueueLock; // queue must be locked before being modified 00473 00474 // async rumble 00475 HANDLE AsyncRumbleThread; // automatically disables rumble if requested 00476 volatile DWORD AsyncRumbleTimeout; 00477 // orientation estimation 00478 unsigned WiimoteNearGUpdates; 00479 unsigned NunchukNearGUpdates; 00480 // audio 00481 HANDLE SampleThread; 00482 const wiimote_sample* volatile CurrentSample; // otherwise playing square wave 00483 // state recording 00484 struct recording 00485 { 00486 volatile bool bEnabled; 00487 state_history *StateHistory; 00488 volatile DWORD StartTimeMS; 00489 volatile DWORD EndTimeMS; // can be UNTIL_STOP 00490 unsigned TriggerFlags; // wiimote changes trigger a state event 00491 unsigned ExtTriggerFlags;// extension changes " 00492 } Recording; 00493 }; 00494 00495 #endif // _WIIMOTE_H
