March 20, 2012


This software contains no kernel mode routines and runs entirely
in user mode.  It was tested on an Intel based MAC running OSX 10.5.8
(also known as Leopard).  The Xcode compiler on this system (3.1.2)
generates 32 bit code by default and can generate 64 bit code when
requested.

The BioSemi Mac software is distributed here in both prebuilt binary
form - for Intel MAC OSX 10.5 - and with a Makefile so that it can be
rebuild to run with updated components.

To access the computer's USB this software uses an open source package,
"libusb1.0" (see http://libusb.wiki.sourceforge.net/Libusb1.0).
The "libusb1.0" package has the "GNU Lesser General Public License"
(or "LGPL") which means it must be distributed in source form.

Prebuild binary files are located in the "OSX-10.5-32/bin" and
"OSX-10.5-64/bin" subdirectories.  The first set of instructions below give
the steps required to use these pre-built binary files.

These binary files can be re-created using the files in the "OSX-10.5-32/src"
and "OSX-10.5-64/src" subdirectories.  To do this, Apple's program development
package "Xcode Tools" must be installed.  This package is on the MAC OSX 10.5
distribution disk or it can be downloaded through the internet.  The steps
for rebuilding the binary files from the source files are also given farther
below. 

MAC Installation Procedure
==========================

1. Download and unpack the BioSemi support software.

2. Move to the appropriate subdirectory,
   for 32 bit software:  cd OSX-10.5-32/bin
   for 64 bit software:  cd OSX-10.5-64/bin

   The bin directories contains these files:

Labview_DLL_SyncTest
   This is a test program that acquires data from the BioSemi receiver and
   checks the data format.

liblabview_dll.0.0.1.dylib
   This is the BioSemi shared library that controls the ring buffer.

libusb-1.0.0.dylib
   This is the shared library that controls the computer's usb interface and
   that the BioSemi shared library uses to fill the  ring buffer.

BioSemi-Labview_DLL.framework 
   This is a Mac OSX data structure that contains everything needed by National
   Instruments LabView to enable it acquire data from the BioSemi receiver.  It
   contains copies of the two shared libraries mentioned above.

labview_dll.ini
   This is a sample parameter file used by liblabview_dll.  The parameters are
   explained in the file TUNING.  Here they are commented out.


   Try out the software by running the Labview_DLL_SyncTest program as
   described in the next step.
    
3. Plug the Biosemi Receiver's USB cable into the computer and type
   "./Labview_DLL_SyncTest 0" to start the test program.  Use CTRL-C to
   stop the test.  See the "Labview_DLL_SyncTest Usage" section below for
   more about this program.

   If you get this message:
dyld: Library not loaded: liblabview_dll.0.0.1.dylib
  Referenced from: /Users/ ... /Labview_DLL_SyncTest
  Reason: image not found

   this usually means that the DYLD_LIBRARY_PATH is not set correctly.  Use
   this command and then try again:

export DYLD_LIBRARY_PATH=`pwd`:$DYLD_LIBRARY_PATH

4. At present 64 bit software cannot be used with the BioSemi ActiView LabVIEW
   application because it is a 32 bit application.  For this application use
   the OSX-10.5-32 directory tree.


Rebuilding the binary files
---------------------------

Perform the following steps to build first the libusb-1.0  package
and then the BioSemi Labview_DLL package. In these instructions the bash
shell is assumed.

1. The downloaded and unpacked BioSemi support software includes
   the current (March 2012) "libusb-1.0.8" source distribution as
   a convenience for installation.  The libsub software is
   identical to that available on the sourceforge web site.

2. Move to the appropriate subdirectory,
   for 32 bit software: cd OSX-10.5-32/src
   for 64 bit software: cd OSX-10.5-64/src

3. Define a destination directory for the libusb build.
   For instance:

export LIBUSB_PREFIX=`pwd`

   "cd libusb-1.0.8" into the libusb subdirectory and read the file
   "INSTALL".  You probably only need to do these 3 commands,

for 32 bits:
./configure  --prefix=$LIBUSB_PREFIX --target=i386 CFLAGS=-m32 LDFLAGS=-m32
for 64 bits:
./configure  --prefix=$LIBUSB_PREFIX --target=x86_64 CFLAGS=-m64 LDFLAGS=-m64

Then for 32 and 64 bits:
make
make install

   You can ignore the warning messages:
   "declaration of ‘index’ shadows a global declaration"
   or use this command:
export CFLAGS=-Wno-shadow
   before the "./configure" above to suppress shadow warning messages..

4. "cd .." back to the BioSemi software directory.

5. Add the location of "libusb"'s lib subdirectory to the
   environment variable DYLD_LIBRARY_PATH, i.e.

export DYLD_LIBRARY_PATH=$LIBUSB_PREFIX/lib:$DYLD_LIBRARY_PATH

6. Type,

for 32 bits:  make ARCH='-m32'
for 64 bits:  make ARCH='-m64'

   This should build the Biosemi shared library -
   labview_dll - and a test program - Labview_DLL_SyncTest - that uses
   the library for acquisition.  Use this command to check that the
   program just built is for the correct architecture:

lipo  -info  Labview_DLL_SyncTest

   Note: The shared library is referred to as "labview_dll" for compatibility
         with BioSemi's version of this software that runs on Windows.
         To follow Mac naming conventions the file produced is
         actually called "liblabview_dll.0.0.1.dylib", and a "linker name"
         "liblabview.dylib" is setup to point to this file.

7. To run the test program, the location of the "liblabview_dll" shared
   library must be added to the environment variable DYLD_LIBRARY_PATH.
   If it is the current directory, this is the command:

export DYLD_LIBRARY_PATH=`pwd`:$DYLD_LIBRARY_PATH

   As well, the location of the "libusb" shared library must be
   declared - as in step 5 above.  If you just performed this step then
   this has been taken care of. Otherwise, use

export DYLD_LIBRARY_PATH=`pwd`/lib:$DYLD_LIBRARY_PATH

   Plug the Biosemi Receiver's USB cable into the computer and type
   "./Labview_DLL_SyncTest 0" to start the test program.  Use CTRL-C to
   stop the test.  See the "Labview_DLL_SyncTest Usage" section below for
   more about this program.

   If you get this message:
dyld: Library not loaded: liblabview_dll.0.0.1.dylib
  Referenced from: /Users/ ... /Labview_DLL_SyncTest
  Reason: image not found

   this usually means that the DYLD_LIBRARY_PATH is not set correctly.

8. A more permanent arrangement for the liblabview_dll and libusb
   shared libraries and associated link pointers is to put them
   in /usr/local/lib.

    This removes the need to have to setup the DYLD_LIBRARY_PATH environment
    variable to be able to find these shared libraries.


Labview_DLL_SyncTest Usage
==========================

This program checks that the 0xffffff00 sync words appear in all the
right places in the input stream.  It stops with a message if they don't.

There can be 2 command line parameters for this program:
- ring buffer size, in 512 byte units,
- time to run.
They can be in any order or left out completely.

Ring buffer size must start with a 'b' or 'B' and is given in units
of 512 bytes.  The default if not given is b65536 for 32 Mbytes.

The time to run is in seconds.  The default if not given is 600 seconds
(10 minutes).  If given as 0 there will be no time limit.

Hitting CTRL-C when the program is running will stop the run.


liblabview_dll.so Usage Notes
=============================

1. The ring buffer can be any size as long as it is a multiple of 512
bytes.  Note: on Vista and XP the size need only be a multiple of 4 bytes.

2. Some performance improvement may be gained by using the library
parameters explained in the file "TUNING".


ReCreate the Framework for use with LabVIEW and other programs
==============================================================

LabVIEW for Mac requires user Call Libraries be in a framework.  Instructions
for creating such a framework are given at
http://digital.ni.com/public.nsf/allkb/A6A6371FE0EA333B86257015005E3400
and are reproduced here:

------
1. Open Xcode.
2. Select File»New Project.
3. Select Framework»Carbon Framework as the project type.
4. Name the framework when prompted. Click Finish.
5. The Xcode browser will now appear. Click on main.c to open the file. This is where you will create your functions. For an example open the file main.c in the Call Library Function Node on Mac with Xcode zip file.
6. After adding your functions, compile the framework. The compiler settings should all be left at default.
7. Access your functions via a Call Library Function Node in LabVIEW.
------

For our purpose, use this variation to these instructions:

Perform steps 1-4.  In step 4 name the project "BioSemi-Labview_DLL32" or
"BioSemi-Labview_DLL64" as appropriate.

When the Xcode window appears, from the tool bar select "Project" ->
"Edit Project Settings".

If building for 64 bits and "Valid Architectures" doen't include "x86_64", add it to
the Arctitectures line, under "Other".

Check "Build Active Architecture Only" box.

Close the Project Settings window.

In place of step 5 above, add these files to "Source" (i.e. right click
"Source", choose "Add" -> "Existing Files"):
bsif.h
bsif_libusb.o
poll_keys.o
labview_dll.cpp
labview_dll.h
libusb-1.0.0.dylib

Right click on "External Frameworks and Libraries", choose "Add" ->
"Existing Frameworks" and choose "IOKit.framework".

Choose "Active SDK" (10.5), "Active Configuration" (Release) and
"Active Architecture" (i386 or x86_64).

Build -> Clean All Targets

Build

To check that the framework just built is for the correct architecture,
use this command on the file in the framework's "Versions/Current" subdirectory:

lipo  -info  BioSemi-Labview_DLL



To make the framework portable so it can be used on other similar computers,
after it is created, do this:

1. Copy the libusb library "libusb-1.0.0.dylib" to the new framework's subdirectory "Versions/Current/Resourses".

2. cd to the "Versions/Current" subdirectory.

3. View the framework's absolute location dependancy for libusb using this command: 
otool -L BioSemi-Labview_DLL

4. Make this a relative location dependancy by using the following command,
replacing the "XXX" with the specific directory being used: 
install_name_tool -change /Users/XXX/lib/libusb-1.0.0.dylib @loader_path/Resources/libusb-1.0.0.dylib BioSemi-Labview_DLL

5. Check this dependancy change by repeating the command:
otool -L BioSemi-Labview_DLL
