FWIINE

1 / 18 07/12/2009 - fWIIne v0.4 - Manual

Manual

Project : FWIINE SW-release : 0.4

FWIINE

2 / 18 07/12/2009 - fWIIne v0.4 - Manual

Project : FWIINE SW-release : 0.4

Release Type :

References [OS / Tools]

Development Delivery Date Comment

WinXP / Matlab 0.4 2009-09-26 New version Linux / Scilab 0.2 2008-05-10 Unchanged since fWIIne

v0.2 ________________________________________________________________ TABLE OF CONTENTS 1. INTRODUCTION 2. REFERENCE 3. SOURCE 4. FWIINE Toolbox 4.1 Main Difference between fwiine for SCILAB/Linux and fWIIne for MATLAB/WinXP 4.2. Data Acquisition 4.3. Matlab/Simulink specific function / S-function : sfwiine 5. FWIINE FOR WINDOWS XP AND MATLAB 5.1. Pre-requisite 5.2. Development Environment 5.3. Test Functions – test_fwiine_#.m 5.4. Function – fwiine_accel_fft_wiimote.m 6. FWIINE FOR LINUX AND SCILAB 6.1. Pre-requisite 6.2. Development Environment 6.3. Test Function _ test_fwiine.sce 7. TROUBLESHOOTING 8. WHAT'S NEW 9. MISCELLANEOUS REFERENCES

FWIINE

3 / 18 07/12/2009 - fWIIne v0.4 - Manual

1. INTRODUCTION The fWIIne applications are open-source libraries (third part applications) for SCILAB and MATLAB. The wiimote can be used as an acquisition tool for acceleration, IR dots position and angle velocities1. This manual is a description of the main functions and demo applications. Please refer to the Release Note and Guideline2 for more information for installing and building the application.

Nintendo Wii Remote Controller

[Tool Chain - Overview]

2. REFERENCE

Release Author 0 . 4 William A L O Z Y

wiill.iam@club-internet.fr

Type Realtime Sensor Acquisition Acquisition Type fWIIne for WinXP and Matlab

No Accelerometer (3D) Infrared (2 points) Button (A,B,1,2)

Optional : Angular rate from Wii Motion Plus

Continuous

fwiine for Linux and Scilab

No Accelerometer (3D) Infrared (2 points) Button (A,B,1,2)

Continuous

1 as usual recommendations : the application is free to download and to use. The application is provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchandability, fitness for a particular purpose and noninfrigement. In no event shall the authors be liable for any claim, damages or other liability, whether in an action of contract, arising from, out of or in connection with the software or the use or other dealings in the software. 2 fWIIne_V0.4_Release_Note(eng).pdf (see project site documentation)

FWIINE

4 / 18 07/12/2009 - fWIIne v0.4 - Manual

Type Source Files Size in KByte Comment fWIIne for WinXP and Matlab

fWIIne_v0.4_src_ winxp_matlab.zip

fWIIne.mexw32 [56KB] --

fwiine for Linux and Scilab

fwiine_v0.2_binsrc_ linux_scilab.zip

Wiiuse.so [32KB] The Linux Library has not changed since v0.2

________________________________________________________________ 3. SOURCE

http://sourceforge.net/projects/fwiine/ (web site : http://fwiineur.blogspot.com/release/ )

4. FWIINE Toolbox FWIINE is a set of functions for 2 Scientific Softwares/Operating Systems. This chapter provides a brief overview of the main common features. It assumes that you have a basic knowledge either about Matlab or Scilab tools. Please refer to the m-files (Matlab) / sce-files (Scilab) for the basic examples : - test_fwiine.m / test_fwiine.sce - test_fwiine_2.m / test_fwiine_2.sce 4.1. Main Difference between fwiine for SCILAB/Linux and fWIIne for MATLAB/WinXP Naming convention is not the same between SCILAB and MATLAB applications. The same command is called by the keywords fwiine or fWIIne. Command MAT./

WINXP SCI./ LINUX

[aX,aY,aZ]=fWIIne(3); WII -* [aX,aY,aZ]=fwiine(3); -* wii

[Naming convention – compatibility] * - The naming convention is not possible for the application 4.2. Data Acquisition Then, the Matlab naming convention will be used for a better understanding. 4.2.1. Enabling/Ending Communication To initialize the communication session between Matlab/Scilab and the wiimote :

fWIIne(1); %Start At the end of data acquisition, the communication session must be stopped by : fWIIne(0); %Stop Between both commands, Matlab/Scilab will make data acquisition through the following commands : 4.2.2. Functions for Data Acquisition

FWIINE

5 / 18 07/12/2009 - fWIIne v0.4 - Manual

For each reccurence, one of these commands shall be used for data acquisition : Command Description Result MAT./

WINXP SCI./ LINUX

fWIIne(2); WII wii

Display accelerometer and IR sensors values on Matlab prompt.

(for test purposes)

[aX,aY,aZ]=fWIIne(3); WII wii

Return values of motion sensors aX : acceleration value from X axis aY : acceleration value from Y axis aZ : acceleration value from Z axis

[aX,aY,aZ,ir1X,ir1Y,ir2X,ir2Y,ir1flag,ir2flag]=fWIIne(4); WII wii

Return accelerometer and IR sensor values

aX: acceleration value from X axis aY : acceleration value from Y axis aZ : acceleration value from Z axis ir1X : X position for 1st IR dot ir1Y : Y position for 1st IR dot ir2X : X position for 2nd IR dot ir2Y : Y position for 2nd IR dot ir1flag : IR 1 dot is present in the current acquisition ir2lag : IR 2dot is present in the current acquisition

[aX,aY,aZ,ir1X,ir1Y,ir2X,ir2Y,ir1flag,ir2flag,Button1,Button2,ButtonA,ButtonB]=fWIIne(5);

WII wii

Return accelerometer, IR, Buttons (AB12) values

[aX…ir2flag see above] Button1 : Status of Button 1 Button2: Status of Button 2 ButtonA: Status of Button A ButtonB: Status of Button B

[aX,aY,aZ,Pitch,Roll]=fWIIne(6); WII wii

Return accelerometer and orientation values (orientation values are based on wiimote’s acceleration values)

[aX..aZ see above] Pitch : Pitch angle value Roll : Roll angle value

[aX,aY,aZ,dRx,dRy,dRz]=fWIIne(8); WII -

Return accelerometer and angular rate values (angular rate values comes from Wii Motion Plus)

[aX..aZ see above] dRx,dRy,dRz :Raw values from gyroscope sensor

FWIINE

6 / 18 07/12/2009 - fWIIne v0.4 - Manual

[axis reference for fwiine and for the wiimote]

Range of recorded variables : Variables [Range] Unit Comment aX, aY, aZ Max. range

[-5 5] x9.81m/s² Minimal ensured range by Nintendo is [-3 3] x9.81m/s²

1g = 9.81 m/s² Typical range [-4.5g 4.5g] - Min./Max. saturation

ir1X, ir2X [0 1] Normalized value for a 4/3 camera : resolution = 1/1024

ir1Y, ir2Y [0 1] Normalized value for a 4/3 camera : resolution = 1/767

ir1flag, ir2flag 0 or 1 0 : Dot is not visible (ir## =0) 1 : Dot is visible

Button1, Button2, ButtonA, ButtonB

0 or 1 0 : Button is released 1 : Button is pressed

Pitch, Roll [-45 +315°] for MATLAB/WinXP[-180° +180°] for SCILAB/LIN.

Angle value in degree

dRx, dRy, dRz [0..16000] Raw value from gyroscope sensors. (beta development) For a parameter "#" : Angular rate[°/sec] = Ratio *( dR# - Offset_#) - Offset is around 8000 - Ratio +/-125 to 503 step/°.s-1

FWIINE

7 / 18 07/12/2009 - fWIIne v0.4 - Manual

Note 1 : The bluetooth communication is supposed to enable an acquisition rate of 100 data frames per second. Please be aware of Bluetooth protocol for more information about the accuracy of the recurrence. Note 2 : Oversampling are supported by fWIIne functions. Note 3 : Different functions can be called during data acquisition. Each recurrence, only one function must be called to avoid undefined states. 4.3. Matlab/Simunlink specific function / S-function sfwiine Pre-requisite : Matlab must support M-based S-function (release equal or upper than r2007a) Start MATLAB Application and select fWIIne folder. Then, run the simulink model fwiine_example.mdl Entering inside “Raw Acquisition” Block :

[S-function sfwiine - Extract from fwiine_example.mdl model for Simulink]

Note 1 : same definitions as MEX-Command Note 2 : ir#Found = ir#flag and But# = Button# definitions Note 3 : t is the delta-time between acquisition of 2 consecutives data frames (this definition is not related to the simulated time from simulink point of view)

FWIINE

8 / 18 07/12/2009 - fWIIne v0.4 - Manual

During the simulation, data can be visualized “on-the-fly” : clicking on “Scope” block

[Scope visualization - Extract from fwiine_example.mdl model for Simulink]

5. FWIINE FOR WINDOWS XP AND MATLAB 5.1. Pre-requisite Recall : MATLAB must have already been installed / Bluetooth dongle is plugged to the computer. 5.1.1. Pairing the Wiimote with Bluetooth-computer Connection

[Pairing the Wiimote - an example with WIDCOMM bluetooth driver]

Here, the procedure is not described. According to the installed bluetooth driver, the communication between the Wiimote and the computer is enabled.

Several Bluetooth drivers are existing. Just for information, 2 references : Widcomm Windows Driver: http://wiibrew.org/index.php?title=Wiimote_Tutorial Blue Soleil Windows Driver: http://www.wiili.org/index.php/How_To:_BlueSoleil 5.1.2. fWIIne vs Matlab compiler dependability The application requires Microsoft Visual C 2005 runtime libraries to be installed :

FWIINE

9 / 18 07/12/2009 - fWIIne v0.4 - Manual

In the Matlab distribution on your computer, you can run the exe [..current Matlab folder...]\bin\win32\vcredist_x86.exe If vcredist_x86.exe is not available in the folder $MATLAB\bin\win32 then you can download it on Microsoft's website : http://www.microsoft.com/downloads/details.aspx?familyid=32BC1BEE-A3F9-4C13-9C99-220B62A191EE&displaylang=en

5.2. Development Environment (validated with the referenced release for Matlab) [fWIIne_v0.4_bin_winxp_matlab.zip or fWIIne_v0.4_binsrc_winxp_matlab.zip] can be unzipped into Matlab Work folder :

Then, to check for the availability of fWIIne for data acquisition, follow these steps:

1. Initialize bluetooth connection (see section above) 2. Start Matlab and then select the folder fWIIne 3. (Test with Matlab) start test_fwiine m-files to test wiimote data acquisition 4. (Test with Simulink) Load fwiine_example.mdl model and start simulation

NB : Please refer to Release Note if you encounter some initialization issues with first command “fWIIne(1) error : …” : fWIIne_V0.4_Release_Note(eng).pdf (see chapter 3) 5.2. Test Functions – test_fwiine_#.m 5.2.1. Test_fwiine.m, test_fwiine_2.m and test_fwiine_3.m

test_fwiine.m and test_fwiine_2.m files : To test the wiimote data acquisition. fwiine_example.mdl file :

To test the wiimote data acquisition with simulink.

sfwiine.m file : s-function (m-file) for simulink models. Used by fwiine_example.mdl fWIIne.mexw32 file :

fWIIne MEX-file library . Used by test_fwiine.m, sfwiine.m

FWIINE

10 / 18 07/12/2009 - fWIIne v0.4 - Manual

About the following examples, the content and the function are the same as in the previous versions (v0.3 and v0.2) : test_fwiine.m, test_fwiine_2.m and test_fwiine_3.m 5.2.2. Test_fwiine_4.m (Wiimote and WM+) The test function requires Wiimote and Wii MotionPlus. Here, accelerations and gyro. sensor data are recorded after a manual intervention. Below, the table describes all the steps till end of acquisition : Matlab Prompt – test_fwiine_4.m Action needed >> test_fwiine_4 ... Pre-requisite / Pre-requis : Wiimote : paired / Wiimote : appairee WiiMotionPlus : unplugged ? / WiiMotionPlus : debranche ? ... Press [ENTER] if WiiMotionPlus is unplugged / Pressez [ENTREE] si WiiMotionPlus debranche Initializing/Initialisation/Inicializacion Wiimote Com... Connected to 1 wiimotes (of 1 found). ... Please plug WMP and press Button 1 to start / Branchez le WMP et pressez le Bouton 1 pour demarrer ONE pressed Activating WiiMotionPlus com. ... Starting Recording / Demarrage enregistrement - 16s. ...running... ONE pressed ONE pressed >>

For instance, result after test sequence :

FWIINE

11 / 18 07/12/2009 - fWIIne v0.4 - Manual

[test_fwiine_4.m – data recording (figure 2)]

5.2. Functions – fwiine_accel_fft_wiimote.m 5.2.1. Purpose The function records accelerometer data and provides a frequency spectrum for each axis. Estimated bandwidth [0-33Hz]. 5.2.1. fwiine_accel_fft_wiimote.m Test duration : 1mn01s 4 figures are displayed after the test sequence. Below, the table describes all the steps till end of acquisition : Matlab Prompt – fwiine_accel_fft_wiimote.m Action needed >> fwiine_accel_fft_wiimote ------------------- Recording and Analysis of an experiment with one file Recording time/Temps d enregistrement = 1mn01s ------------------- Initializing/Initialisation/Inicializacion Wiimote Com... Connected to 1 wiimotes (of 1 found). Press a key / Pressez une touche / Pulse una tecla End/Fin Shutting/Fermeture/Cerrando Wiitmote Com... ------------------- Press Key [Enter] to analyze / [1]+[Enter] to save measurement file and then to analyze

FWIINE

12 / 18 07/12/2009 - fWIIne v0.4 - Manual

Pressez [Entree] pour l analyse / [1]+[Entree] pour sauvegarder le fichier puis pour l analyse ------------------- Starting analysis/Démarrage analyse ------------------- Av. sampling time in s. : 0.0103 Selected sampling time in s. : 0.0120 >>

For instance, result after test sequence :

[fwiine_accel_fft_wiimote.m – figure 1]

The figure 1 provides an histogram of sampling times for all recordings. The figure 2 provides computed pitch and roll from accelerometer data. Note : up to 0.5Hz, accelerometer-based values are suitable for pitch and roll definition, only.

FWIINE

13 / 18 07/12/2009 - fWIIne v0.4 - Manual

[fwiine_accel_fft_wiimote.m – figure 3] The figure 3 gives an overview of the frequency spectral density and for each axis (X,Y,Z).

[fwiine_accel_fft_wiimote.m – figure 4]

The figure 4 shows the spectrograms (X,Y,Z) 6. FWIINE FOR LINUX AND SCILAB 6.1. Pre-requisite To download and unzip [fwiine_v0.2_srcbin_linux_scilab.zip] – see chapter 3. SCILAB must have already been installed / Bluetooth dongle is plugged. Please check Linux and bluetooth dependencies as written inside README file. 6.2. Development environment for fwiine3 The following tables gives an overview of the development environment. See fWIIne_V0.4_Release_Note(eng).pdf (chapter 3) for more information about build and installation.

[fwiine folder for Linux and Scilab]

3 NB : Unix name for fWIIne is : fwiine

FWIINE

14 / 18 07/12/2009 - fWIIne v0.4 - Manual

Folder description (see release note for a deeper description) : fwiine\src\ is the folder for the wiiuse library (used by fwiine.o) fwiine\include\ is the include folder for the wiiuse library (used by fwiine.o) fwiine\api\ is an example folder from Wiiuse library (just for development purpose.) - Source files from api and wiiuse library fwiine\fwiine\ Is the fwiine folder for the MEX-sourcefiles

and the root folder for “MEX-library”, .SCE files libmex.c

wiiuse.c fwiine.h fwiine.cpp Makefile Makefile.mak Makelib libmex.dia.ref builder.sce test_fwiine.sce test_fwiine_2.sce

The files generate fWIIne library file within fwiine\fwiine\ folder. The files are used by Scilab for the Wiimote data acquisition. Libmex files come from templates from the current release of Scilab.

fwiine\ Is the root folder Makefile

start_bluetooth.sh stop_bluetooth.sh README

To compile . To enable bluetooth com. To disable bluetooth com. README file for more information

6.3. Test Function – test_fwiine.sce 6.3.1. Enabling the Bluetooth Connection (open a terminal :“Ctrl+Alt+T“ Xandros shortcut) /home/use/fwiiner>sh start_bluetooth.sh 6.3.2. running SCILAB /home/user/fwiine>cd fwiine /home/user/fwiine/fwiine>scilab 6.3.3. running fwiine Within SCILAB Prompt : --> exec test_fwiine.sce Then Press Buttons 1 and 2 to initialise communication with the wiimote and follow the

instructions from the Scilab prompt.

FWIINE

15 / 18 07/12/2009 - fWIIne v0.4 - Manual

[fwiine for SCILAB – Final result for wiimote data acquisition - test_fwiine.sce]

[fwiine for SCILAB – Final result from Scilab prompt – test_fwiine.sce]

6.3.4. SCILAB Typical Controls : The controls are the same as Matlab MEX-Commands. Recall 1 : Be aware of the unix naming convention

Not OK for fwiine for Linux and for Scilab : [aX,aY,aZ]=fWIIne(3); OK for fwiine for Linux and for Scilab : [aX,aY,aZ]=fwiine(3);

Recall 2 : Pitch and Roll angle values limits are different from Matlab : [-180° +180°] Recall 3 : Scicos-related function is not available with the current release. Recall 4 : fwiine(8) is not supported by the current version.

FWIINE

16 / 18 07/12/2009 - fWIIne v0.4 - Manual

7. TROUBLESHOOTING This is release of open-source software is distributed, graciously. (No technical support but the authors and/or the contributors may answer you.) The reader will have to use forums/Newsgroup/Google/Email/IRC to help answer questions you may have related to the installation and use of fWIIne. Type Concern/Issue Solution/Work Around Type

The following failure occurred : "

??? Invalid MEX-file '...\fWIIne.mexw32': This application

has failed to start because the application configuration is incorrect.Reinstalling the application may fix

this problem. Error in ==> test_fwiine_2 at 12

fWIIne(1); "

The solution is to install the Microsoft VS runtime libraries :

In the Matlab distribution on your computer, you can run the exe

[..current Matlab folder...]\bin\win32\vcredist_x86.exe If vcredist_x86.exe is not available in the folder $MATLAB\bin\win32

then you can download it on Microsoft's website.

Software

Communication initialisation failed before prompt

“Initialization/Initialisation/Initialisacion” displayed for command fWIIne(1)

No / It is necessary to compile the project

with the current Matlab Libraries

Software

Nunchuck and 2nd Wii remote are not supported

Not supported by fWIIne v0.2 Software

No acquisition from Buttons "up", "Down", "Left", "Right"

Not supported by fWIIne v0.2 Software

Compilation is not available with RealTimeWorkShop with s-function

sfwiine

Not supported by fWIIne v0.2 Software

No realtime acquisition Pseudo real-time acquisition is available with fWIIne v0.2

Software

Simulink : a quick sampling time may slow simulation [0.01s .. 0.024s]. It is

recommended to set the sampling value to a higher value [0.024s..1s]

- Tool

fWIIne for

WinXP and

Matlab

The current Matlab release (of your computer) must support mexw32

compilation with Visual Studio

Matlab Compilation is not supported by fwiine v0.2.

Check if your Matlab release can support it.

Tool

the current bluetooth and Wiimote drivers and the communication in

“continuous” mode induce the fact that data are buffered and can introduce a lag between the data acquisition and

the visualization.

The reccurence for the call must be less than or around bluetooth

transmission (<10ms).

Drivers fwiine for

Linux and

Scilab

additionnal Wiiuse features were keeped.

(activation/deactivation of acquisition from IR sensor with Down/Up and

activation/deactivation of acquisition from motion sensor comm. with -/+)

Be aware during data acquisition : -/+ buttons disable/enable accel.

Sensor acquisition Up/Down buttons enable/disable IR

sensor acquisition.

Software

FWIINE

17 / 18 07/12/2009 - fWIIne v0.4 - Manual

After test_fwiine.sce script execution, an other execution of the script failed.

The wiimote needs to be initialized, again.

Press “Power” button (wiimote shutdowns). Then run the script and

press 1 and 2 as described within sections about fwiine for scilab

(NB : the command “sh start_bluetooth.sh” is not necessary

because the bluetooth dongle is initialised, yet)

Software

Send your feedback to wiill.iam@club-internet.fr or report a bug at http://sourceforge.net/projects/fwiine . _______________________________________________________________ 8. WHAT'S NEW

• Change – version 0.4. (see release Note)

_______________________________________________________________

FWIINE

18 / 18 07/12/2009 - fWIIne v0.4 - Manual

9. MISCELLANEOUS REFERENCES

NINTENDO http://www.nintendo.com

SCILAB http://www.scilab.org/

LINUX XANDROS http://www.xandros.com

MATLAB http://www.mathworks.com

WINDOWS XP http://www.microsoft.com/

CWIIMOTE http://thekrf.com/

WIIUSE http://www.wiiuse.net