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 velocities
1
. This manual is a
description of the main functions and demo applications. Please refer to the
Release Note and Guideline
2
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 1
st
IR dot
ir1Y : Y position for 1
st
IR dot
ir2X : X position for 2
nd
IR dot
ir2Y : Y position for 2
nd
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,Bu
ttonA,ButtonB]=fWIIne(5);

WII wii
Return accelerometer, IR, Buttons
(AB12) values
[aXir2flag 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
wiimotes 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/Dmarrage 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 fwiine
3


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 2
nd
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