Ocean Optics OmniDriver User Manual

OmniDriver Installation

We here at Ocean Optics want you to know that we appreciate your business. To speak to a Technical Support
representative or an Ocean Optics Applications Scientist, please call [phone]. Our office hours are
8 a.m.– 8 p.m. (Mon-Thu), 8 a.m.– 6 p.m . (F ri ) ES T.

Overview

OmniDriver can be downloaded from the Ocean Opt i cs website, or retrieved from the CD that you received with
your purchase of the software. In either case, you will need the password to complete the installation process. If you
have a CD with the OmniDriver software, the password is located on the back of the CD jacket.

Once you have installed the software, you’ll want to verify your installation, look at the javadocs provided to get an
idea of how the objects and methods for OmniDriver are organized, and then run a sample program.

When the installation process is finished, the following subdirectories will be created beneath the OmniDriver home
directory:

Subdirectory Contents

docs Main documentation area

docs\OmniDriver Javadocs for OmniDriver library functions

docs\SPAM Javadocs for SPAM library functions

include Header files for use with C/C++ application development

LabVIEW *.llb libraries and *.vi files to make the OmniDriver functions available to LabVIEW

applications

OOI_HOME The DLL, LIB, and JAR files which make up the OmniDriver and SPAM libraries

This directory also contains the Linux *.so files and the MacOSX *.dylib files.

redistribution Windows USB driver and device information files. Linux “rules” file.

samples All working sample applications which demonstrate how to use OmniDriver. The

samples are grouped by language. Refer to the “Sample Programs” chapter for a
list of all available samples.

VisualBasic6_Declarations

OmniDriver.bas file for inclusion in VB6 applications that need to use the “C”

interface to the functions in the OmniDriver DLL.

Once you have installed the software, you’ll want to verify your installation, look at the javadocs provided to get an
idea of how the objects and methods for OmniDriver are organized, and then run a sample program.

Downloading from the Ocean Optics Website

Installing on a Windows XP Platform XP

There are no issues unique to XP. The installer, named “OmniDrive rSPAM_yyyy.mm.dd_Win32.exe” should run
successfully on this platform. Simple download this file and double-click on it in Windows Explorer to begin the
installation procedure. The installer will guide you through the install process.

► Procedure

1. Start Internet Explorer.

000-20000-400-01-0109 1

OmniDriver Installation Instructions

2. Browse to http://www.oceanoptics.com/technical/softwaredownloads.asp.

3. Select the OmniDriver software appropriate for your operating system.

4. Double-click on OmniDriverSPAM_yyyy.mm.dd_Win32.exe installer and enter the password you
received when you purchased the software. The installer wizard guides you through the installation process.

5. After you have finished installing OmniDriver, you must also install Java on your PC. See
for details on how to install the required version of Java.

6. After OmniDriver and Java have been installed, you should run the OmniDoctor application to verify that
everything has been installed successfully. If OmniDriver has not been installed correctly, your
OmniDriver applications will not run properly and it may be difficult to diagnose the cause of the failure.
See

Running the OmniDoctor Verification Utility.

Installing Java

Installing on a Windows Vista Platform

You can use the install wizard “OmniDriverSPAM_yyyy.mm.dd_Win32.exe” to install OmniDriver under Windows
Vista (32-bit edition only). However, you must run it in Windows XP Compatibility mode and it must be run in
Console mode; you must be logged into an account that has Administrative privileges.

Caution

If you attempt to run the installer “normally” (i.e., without foll ow ing the steps given below),
you will encounter one or both of the following error conditions:

▪ A popup window will appear telling you the installer is unable to run in

graphical mode, or

▪ The installer will report that the total number of bytes to be installed is 0 KB.

► Procedure

To set the compatibility mode for the installer, follow these steps:

1. Ensure that you are logged on with administrative privileges. You do not need to log on to the
Administrator account, but whatever account you do log in with, it must have administrative privileges.

2. Locate the installer EXE file using Windows Explorer.

3. Right-click on the installer EXE file and choose Properties.

4. Click on the Compatibility tab.

5. Check the box labeled run this program in compatibility mode.

6. Choose Windows XP from the drop-down list box.

7. Click OK.

8. After you have finished installing OmniDriver, you must also install Java on your PC. See
for details on how to install the required version of Java.

9. After OmniDriver and Java have been installed, you can run the OmniDoctor application to verify that
everything has been installed successfully. If OmniDriver has not been installed correctly, your
OmniDriver applications will not run properly and it may be difficult to diagnose the cause of the failure.
See

Running the OmniDoctor Verification Utility.

Installing Java

Installing on a Windows 2000 Platform

The OmniDriver installer does not work under Windows 2000. Follow the steps below to manually install
OmniDriver on your PC.

2 000-20000-400-01-0109

OmniDriver Installation Instructions

Caution

Be very careful to follow these steps precisely. Improper or incomplete installation of
OmniDriver can result in obscure failures in your OmniDriver-based application.

► Procedure

Download OmniDriverSPAM_yyyy.mm.dd_LegacyWin32.zip and follow these steps.

1. Unzip OmniDriverSPAM_yyyy.mm.dd_LegacyWin32.zip to a new location on your C: drive. This will
create a directory named OmniDriverSPAM.yyyy.mm.dd and sev eral subdirectories (docs, include,
OOI_HOME, redistribution, samples, etc.).

2. Update your OOI_HOME environment variable to point to the newly cr eated OOI_HOME directory. For
example, if you unzipped the files to
C:\OmniDriverSPAM.yyyy.mm.dd, you should set the OOI_HOME environment variable to
“C:\OmniDriverSPAM.yyyy.mm.dd\OOI_HOME”.
To set the environment variable:

a. Go to the Control Panel and click on the System icon.
b. Click on the Advanced tab.
c. Click on the Environment Variables button.
d. In the System Variables list, find (or create) the OOI_HOME variable and set its value appropriately.

3. Make sure the new OOI_HOME directory is in the system PATH. To do this in Windows:
a. Go to the Control Panel and click on the System icon.
b. Click on the Advanced tab.
c. Click on the Environment Variables button
d. In the "System Variables" list, find the PATH variable and prepend %OOI_HOME%; to its current

value.

4. Register the new DLLs:
a. Open a Command Prompt window.
b. Cd into the new OOI_HOME directory.
c. Type the command: regsvr32 OmniDriver32.dll.
d. Type the command: regsvr3 2 SPAM 32 .dll.
If the registration processes are successful, a small popup window will appear after 10-15 seconds

indicating that the DLL was registered.

5. Install the USB driver and device information files:
a. Copy *.sys from the Redistribution directory to c:\windows\system32\drivers.

b. Copy *.inf from the Redistribution directory to c:\Windows\inf.

After you have finished installing OmniDriver, you must also install Java on your PC. See

for details on how to install the required version of Java.

Installing Java

6. After OmniDriver and Java have been installed, you should run the OmniDoctor application to verify that
everything has been installed successfully. If OmniDriver has not been installed correctly, your
OmniDriver applications will not run properly and it may be difficult to diagnose the cause of the failure.
Thus, it is especially important to run OmniDoctor after manually installing OmniDriver on Windows

2000. See Running the OmniDoctor Verification Utility.

Installing on a Mac Platform

OmniDriver for Mac OSX is distributed as a disk image file.

000-20000-400-01-0109 3

OmniDriver Installation Instructions

► Procedure

The basic procedure for installing OmniDriver on the Mac is as follows:

1. Download the OmniDriverSPAM.yyyy.mm.dd_Mac.dmg file.

2. Double-click on this file to open it. It will prompt you for the standard OmniDriver installation password.

4. Read the instructions given in the text file in the root folder of the DMG.

5. Copy the contents of the DMG to the location where you wish to install OmniDriver. By default this is
/developer/OmniDriver.

6. Define the OOI_HOME environment variable to be the full pathname of the OOI_HOME directory.

7. Add the path of the OOI_HOME directory to the system PATH.

8. Run the shell script (located in the Utilities directory) named MacDiagnostic.sh to verify that OmniDriver
was successfully installed.

There is no need to install Java on the Mac because the required version of Java is already installed as an integral
part of MacOSX 10.4 (Tiger) and 10.5 (Leopard). If you are running an earlier version of MacOSX, you will need
to upgrade your Java installation to at least Java 1.6.

Installing on a Linux Platform

We provide a convenient installer for OmniDriver on the Linux family of operating systems. For Linux systems,
download the OmniDriverSPAM.yyyy.mm.dd_Linux.bin file. You may need to chmod the file to make it
executable. Then run it and follow the prompts.

If you are unable to use the Linux installer, we also provide a password-protected tarball named
OmniDriver_yyyy.mm.dd_Legacy_Linux.tar.gpg containing all of the OmniDriver files. To expand this file, use the
following commands:

• gpg --output <output_file.tar> –decrypt <input_file.gpg>

• tar -xvf output_file.tar

You will also need to manually ensure that the OOI_HOME environment variable is set to the full pathname of the
OOI_HOME folder, and that the OOI_HOME folder is in the system PATH.

► Procedure

After the installer has finished, perform the following steps to verify that the installation was successful:

1. Plug in an Ocean Optics USB spectrometer into the USB port of your Linux-based computer.

2. Open a terminal window.

3. Run the dmesg command. A message appears near the bottom of the output that shows your spectrometer
was deleted.

If the computer did not detect your spectrometer, you must perform the following additional steps. These steps will
install a rules file to tell Linux which driver to use to communicate with Ocean Optics spectrometers.

► Procedure

To install a rules file:

1. Open a terminal window.

2. Copy the file 10-oceanoptics.rules from the Redistribution directory of the OmniDriver installation area to
/etc/rules.d.

3. Restart udev.
On Fedora and similar Linux distros, you can restart udev with the following sequence of commands:

a. udevcontrol reload_rules
b. udevstart

4 000-20000-400-01-0109

OmniDriver Installation Instructions

4. If the previous command does not successfully restart udev, you will need to reboot your system.

5. After you have finished installing OmniDriver, you must also install Java on your computer. See Installing
Java for details on how to install the required version of Java.

6. After completing all of the above steps, run the shell script LinuxDiagnostic.sh provided with OmniDriver
to verify that OmniDriver was successfully installed on your Linux system. This script is located in the
Utilities subdirectory of the OmniDriver installation. Note that the OmniDoctor utility is not available for
the Linux platform.

Retrieving from a CD

Your OmniDriver software is shipped to you from Ocean Optics on a CD. The software is located either on the main

Software and Technical Resources CD, or on a separate CD labeled OmniDriver Spectroscopy Development
Platform. You will need the password located on the jacket of the CD containing your OmniDriver software to

complete the installation.

► Procedure

1. Insert the CD that you received containing your OmniDriver software into your computer.

2. Select the OmniDriver software for your computer’s operating platform. Then follow the prompts in the
installation wizard.

Or,
Browse to the appropriate OmniDriver set-up file for your computer and double-click it to start the

software installation. Set-up files are as follows:

• Windows: OmniDriverSPAM_yyyy.mm.dd_Win32.exe

• Mac: OmniDriverSPAM_yyyy.mm.dd_Mac.dmg

• Linux: OmniDriverSPAM_yyyy.mm.dd_Linux.bin

Where: yyyy.mm.dd = year.month.day (example 2008.08.05)

3. Refer to the appropriate installation section, depending on your operating platform to complete the
installation. See

on a Windows 2000 Platform, Installing on a Mac Platform, or Installing on a Linux Platform and follow

the steps listed in that section.

Installing on a Windows XP Platform, Installing on a Windows Vista Platform, Installing

Installing Java

All operating platforms other than Mac OSX require you to manually install Java. If you are developing on Mac
OSX, you do not need to install or upgrade Java. Mac OSX comes with Java 1.5 preinstalled, which is adequate for
OmniDriver development on the Mac platform. For all other platforms, you must install Java version 1.6 or later
after you have installed OmniDriver. If you are developing in C or C++, you must install the full “JDK” (Java
Developer’s Kit) flavor of Java. For development with any of the other languages, you may install the smaller “JRE”
(Java Runtime Edition) flavor of Java. If you have already installed the required flavor of Java JDK 1.6 on your
system, you do not need to do anything further.

Note

If you are installing OmniDriver on an end-user’s PC for someone who is not developing new
OmniDriver applications, but merely using your application, you only need to install the smaller
JRE flavor of Java 1.6. If the user already has the JDK version of Java 1.6 installed, this will work
just fine. You can obtain the JDK flavor of Java fr om
JRE flavor of java by going to
There is no charge for any version or flavor of Java.

000-20000-400-01-0109 5

www.java.com and clicking on the Free Java Download button.

www.javasoft.com. Or you can install the

OmniDriver Installation Instructions

If you have an earlier version of Java already installed on your PC, you do not need to uninstall that version,
although it might keep things simpler if you do. However, you must install the 1.6 version in order to develop
OmniDriver applications. Earlier versions of java will not work with OmniDriver.

After installing Java, you must add the Java bin directory to the system PATH.

► Procedure

To add the Java bin directory to the system PATH:

1. Start the Control Panel.

2. Click on the System icon.

3. Click on the Advanced tab.

4. Click on the Environment Variables button.

5. In the System Variables list, find the PATH variable and prepend the pathname of the new Java bin
directory (for example, C:\Program Files\Java\jdk1.6.0_10\bin).

6. To verify that the system is using the new version of java, open a new Command Prompt window and type
java –version. It should indicate you are running java 1.6 or later.

Running the OmniDoctor Verification Utility

OmniDoctor is a small command-line utility that verifies OmniDriver has been properly installed. If you have
recently installed or upgraded OmniDriver and you are experiencing unexplained difficulties with your application
(or the OmniDriver samples do not run), it is highly recommended that you run this utility. OmniDoctor is available
for Windows only, not for Linux or MacOSX

OmniDoctor performs the following checks:

• Verifies that the OOI_HOME environment variable has been defined and that it points to a valid directory.

• Verifies that the OOI_HOME directory is in the system PATH.

• Confirms that certain critical files are present in the OOI_HOME directory.

• Verifies that the required version of Java has been installed on the user’s PC.

The OmniDoctor utility is located in OmniDriver\utilities\win32. You can run OmniDoctor from the command line,
or by double-clicking it from within Windows File Explorer. OmniDoctor will display several simple pass/fail
messages indicating the status of your OmniDriver installation. OmniDoctor also creates a log file, named
ooi_home_file.txt, in the current directory. The log file contains greater detail about the current installation of
OmniDriver. In some cases you may be asked to e-mail this log file back to Ocean Optics Tech Support for
diagnosis.

For More Information

You can access complete documentation for Ocean Optics products on the Software and Technical Resources CD or
by visiting our website at
appropriate document from the drop-down lists or use the Search by Model Number field.

http://www.oceanoptics.com. Select Technical | Operating Instructions. Choose the

6 000-20000-400-01-0109