# 7/28/2005
# Instructions for Setting up MATLAB & TinyOS interoperability for windows

Background
**********
These instructions were created using Matlab 6.5 and the version of
matlab tinyos tools in the CVS tree as of 7/28/2005, though it may
very well work for other setups.

The matlab interfacing code for TinyOS is in tinyos-1.x/tools/matlab.
Unfortunately, some of the files are out of date or not fully working.
I've emailed Kamin to update some of them, but he hasn't done anything
yet (and I don't have enough access to modify that portion of the CVS
tree).

Notably, I've found that I need to explicitly modify:
	 tinyos-1.x/tools/matlab/{defineTOSEnvironment.m,startup.m}
because the 'ncc -print-tosdir' does not work, and some directories
like tinyos-1.x/tools/matlab/{lib,tools} do not exist.

I've also found
tinyos-1.x/tools/matlab/comm/{receive.m,stopReceiving.m}
to have some typos for special cases (forgetting to transpose matrices
and create empty cell arrays).  The differences are in the file
matlab_receive_stopReceiving_diff.txt .  They have not been committed
back to the CVS tree.


Modifications
*************
WINDOWS, local installation of Matlab R13.
1) Replace the line
     [flag, value] = system('ncc -print-tosdir');
   in tinyos-1.x/tools/matlab/startup.m with the hardcoded path of
   where your $TOSDIR resides, such as
     flag = 0;
     value = 'c:/cygwin/opt/tinyos-1.x/tos/';

2) Replace the line
     [flag, TOSDIR] = system('ncc -print-tosdir');
   in tinyos-1.x/tools/matlab/defineTOSEnvironment.m with the
   hardcoded path of where your $TOSDIR resides, such as
     flag = 0;
     TOSDIR = 'c:/cygwin/opt/tinyos-1.x/tos/';

3) Comment out the lines
     addpath([TOSDIR '/../tools/matlab/lib']);
     addpath([TOSDIR '/../tools/matlab/tools']);
   in defineTOSEnvironment.m

4) If you are using tinyos-1.x/contrib/ucbRobo, follow the
   instructions in the README.matlab file under that tree for
   additional modifications to startup.m

5) Edit tinyos-1.x/tools/matlab/comm/{receive.m,stopReceiving.m}
   to match the diff in matlab_receive_stopReceiving_diff.txt

6) Startup Matlab and go to the menu "File->Set Path..."
   Click on the "Add Folder" button.  Browse to your
   tinyos-1.x/tools/matlab directory and add that folder.  (or
   alternatively, modify the default startup.m file used by matlab).

7) Follow Kamin's Instructions at
	   tinyos-1.x/tools/matlab/doc/faq.html#setup
   on compiling your matlab java tools and editing your matlab
   installation's default classpath.txt file to load the proper jar
   files.  The default location of the classpath.txt file might be
   something like: 
	   C:\ProgramFiles\MATLAB6p5\toolbox\local

8) Restart Matlab.  You should see a bunch of variables loaded onto
   your workspace such as COMM DEBUG TOSDIR and flag.


You can follow the rest of Kamin's matlab tutorial from here, but
there are some typos for commands.  Just look in the
tinyos-1.x/tools/matlab directory and it should be easy to find the
appropriate command.


Sample Files
************
windows_startup.m		# a startup.m file
windows_defineTOSEnvironment.m	# a defineTOSEnvironment.m file
windows_matlab_classpath.txt	# a classpath.txt file

Troubleshooting
***************
1) If you do not start up serialforwarder before calling
   "connect(sf@localhost:9001)" from matlab, your matlab environment
   will hang.  In such a situation, start up a serialforwarder from
   your cygwin prompt connected to port 9001, and you should get your
   matlab prompt back (with a bunch of error messages).