|
SeaBreeze
|
SeaBreeze is a minimalistic, multi-platform (Windows, Linux, MacOS) device driver for Ocean Optics spectrometers, designed specifically for embedded applications needing to run in resource-constrained hardware environments. SeaBreeze provides a fully working and tested REFERENCE IMPLEMENTATION of the Ocean Optics USB interface, demonstrating how Ocean Optics spectrometers can be commanded and controlled from C/C++. It is provided with full C/C++ source code so that customers can customize and extend it to support exactly those features and functions they require.
Unlike the larger OmniDriver/SPAM driver library, SeaBreeze itself does not contain advanced spectroscopic processing and manipulation, but full sample code is included showing how these functions can be implemented in client applications using C++, C#, and a variety of other languages.
SeaBreeze is licensed under the MIT License. Additional information may be found in the "LICENSE" file which should accompany this source distribution.
(Also available at http://opensource.org/licenses/MIT)
SeaBreeze provides two distinct interfaces to control spectrometers. You are free to use and extend either interface, but note that most new development and support from Ocean Optics will focus on the newer SeaBreezeAPI interface, in preference to the older legacy SeaBreezeWrapper interface.
Note that detailed documentation for the C++ methods can be found in the corresponding C functions.
Regrettably, at writing the SeaBreezeAPI (2.0) can only be used from a full SeaBreeze source distribution. Its headers are not designed in such a way that SeaBreezeAPI can be called without access to the full SeaBreeze include tree, which currently is not provided through the binary installers.
SeaBreeze/ The driver and key components
doc/ Documentation relating to SeaBreeze and its API
include/ headers for building SeaBreeze
api/ exportable headers for client applications
os-support/ helpers for specific operating systems
linux/ provides udev rules allowing non-root users to claim devices
windows/ provides working Visual Studio 2005, 2010 and 2012 solutions
src/ core SeaBreeze source for all operating systems
test/ command-line tests, including seabreeze-util cmd-line utility
sample-code/ "recipes" demonstrating how to call SeaBreeze for common tasks
daemons/ server daemons layered atop SeaBreeze for remote / concurrent access
util/ miscellaneous programs related to spectroscopy which may or may not
require SeaBreeze
SeaBreeze documentation is now maintained in Doxygen format, and can be rendered as HTML, RTF (MS Word), Unix 'man' pages, or other styles. For convenience, pre-rendered documentation is generated for each customer release (RTF, converted to Microsoft .docx) which may be found in the ./doc directory.
Assuming you have the "doxygen" command installed (available free at http://doxygen.org – optionally with GraphViz for UML), you can generate documentation automatically in HTML, RTF, and 'man' formats by typing:
$ make doc
Open doc/html/index.html in a browser (or rtf/refman.rtf in Word) to navigate the results. Note that RTF fields won't self-populate until you "Select All" then "Update Fields" (F9).
If you did not receive the SeaBreeze source code, or already have a pre-compiled SetUp.msi installer, you may skip this section.
SeaBreeze is normally built under Windows using Visual Studio 2010, although we've provided working solution and project directories for 2005, 2010, 2012, and 2013 in the os-support/windows directory.
Dependencies
The following should work on most Cygwin environments, assuming Visual Studio is installed:
$ cd seabreeze
$ export VISUALSTUDIO_PROJ=VisualStudio2010 (or 2005 or 2012)
$ make
Note that this is simply using the Cygwin bash shell and GNU toolchain (make) for automation; the actual compiler invoked is Visual Studio. At this time, we have not found a way to support native Cygwin GCC or MinGW (submissions/solutions welcome!)
Error: NativeUSBWinUSB.c(26): fatal error C1083: Cannot open include file: 'Winusb.h'
Fix: add os-support\windows\WinDDK_Includes to your configuration's include path
(SeaBreeze->References->Configuration Properties->VC++ Directories->Include)
Error: fatal error LNK1104: cannot open file 'winusb.lib'
Fix: Add C:\WinDDK\nnn\lib\$(OS)\$(ARCH) to your configuration's "Library Directories"
(same process as above).
Error: fatal error C1083: Cannot open include file: 'api/SeaBreezeWrapper.h' (etc)
Fix: add seabreeze\include to your configuration's include path with
(Solution 'SeaBreeze' -> Project 'SeaBreeze' -> Properties -> Configuration
Properties -> C/C++ -> General -> "Additional Include Directories")
Error: Cannot open .sln file
Fix: Our sources are normally built and tested using Microsoft Visual Studio
2010. If you require support for other compilers, please let us know and we
will endeavor to provide appropriate configuration files.
Error: LINK : fatal error LNK1123: failure during conversion to COFF: file invalid or corrupt
Fix: Uninstall .NET 4.5.1 and re-install .NET 4.0
(cf http://stackoverflow.com/questions/10888391, 6626397, etc)
Error: Runtime: An unhandled exception of type 'System.BadImageFormatException' occured in CSharpDemo.exe
Fix: This nearly always means that SeaBreeze.dll was compiled in 32-bit mode and linked to
a 64-bit CSharpDemo.exe, or vice-versa. Please ensure that both the library and client
application are compiled to the same target and try again.
Dependencies
To compile SeaBreeze, simply run 'make' on the command line of a POSIX system. SeaBreeze is a C++ driver libary with a simplified C interface. This will build with a combination of g++ and gcc. At the moment, only Linux is fully supported, and requires at least a 2.4.20 kernel for USB support.
Building SeaBreeze requires that libusb-0.1 is installed (with its shared libraries in /usr/lib and its header files in /usr/include (e.g. usb.h)). It is also recommended that the target system have the Ocean Optics rules file for udev (10-oceanoptics.rules) so that ordinary users can access the devices. This is likely the problem if root can connect to devices but nobody else can.
It is necessary to put libseabreeze.so into your library path to run any programs against this driver. It should suffice to do this within the SeaBreeze root directory (where this README.txt is) for testing:
$ export LD_LIBRARY_PATH="$PWD/lib"
Alternately, libseabreeze.so could be installed into a system library directory like /usr/local/lib that ld.so knows about.
Test programs in the 'test' directory should be built alongside SeaBreeze and can be used as starting points for new development. As long as the LD_LIBRARY_PATH above is properly defined, these should work. If they do not, then they may need to be updated to reflect the current state of the driver API.
Dependencies
Basically, you should be able to follow the Linux instructions (i.e. make).
The following was tested with an msys environment using 64bit (mingw-w64) gcc (4.8.2).
Dependencies
With respect to the msys tree:
To use Ocean spectrometers via libusb on Windows, you can create libusb0-based drivers using Zadig (http://zadig.akeo.ie/).
Simply double-click SeaBreeze-vX.Y-Setup32.msi (or *64.msi), which should install:
SeaBreeze.dll -> C:\Windows\System32
*.INF -> C:\Program Files\Ocean Optics\SeaBreeze\Drivers
*.h -> C:\Program Files\Ocean Optics\SeaBreeze\API
*.lib -> C:\Program Files\Ocean Optics\SeaBreeze\Library
Note that the driver installation process won't be complete until you physically insert an Ocean Optics spectrometer into your computer's USB port. At that time, the New Hardware Wizard should pop-up and ask how you would like to locate an appropriate device driver. The recommended process is:
If the New Hardware Wizard doesn't come up on its own, you can use the following procedure instead:
You will know that the drivers have been installed correctly if the Device Manager adds the string "(WinUSB)" at the end of the spectrometer name.
Finally, you can "pre-load" the drivers using Microsoft's dpinst.exe utility (included), where $ARCH is i386 or amd64 as appropriate (see 'dpinst /?' for other options):
C:> cd /Program Files/Ocean Optics/SeaBreeze/Drivers C:> $ARCH/dpinst.exe /q /lm /c
For Linux computers to recognize Ocean Optics spectrometers and allow non-root users to claim and control the devices, you'll need to install the provided "10-oceanoptics.rules" file, found under os-support/linux, copying it to (usually) /etc/udev/rules.d. Note that older versions of udev use the "SYSFS" rule nomenclature; the provided file uses the newer "ATTR" standard.
A number of test programs and sample-code demonstrations are provided with SeaBreeze. Note that many of them (the VisualCppConsoleDemo for instance) are intended for use with a locally-built copy of SeaBreeze, meaning that you're expected to compile SeaBreeze first. Other programs (the CSharpDemo) should work with a "runtime / redistributable" copy of SeaBreeze installed through .msi installers. However, the expectation remains that users would normally compile SeaBreeze locally.
To ensure that the device driver has been installed correctly:
To test SeaBreeze from a command-line environment, try building and running the provided tests and sample_code files:
$ cd test $ make $ ./seabreeze-util --help
To test SeaBreeze from a Windows GUI, build and run the "CSharpDemo" provided in sample-code.
To debug SeaBreeze.dll from the "CSharpDemo", edit "SeaBreezeWrapper.cs" to load your debug build of SeaBreeze.dll, then change the following line in "SeaBreezeWrapper.cs":
const string DLL = @"SeaBreeze.dll";
To the path of your debug SeaBreeze.dll, i.e.:
const string DLL = @"C:\Code\seabreeze-code\trunk\SeaBreeze\os-support\windows\VisualStudio2013\x64\Debug\SeaBreeze.dll";
$ make new
$ export LD_LIBRARY_PATH="$PWD/lib"
$ ./test/seabreeze_test_posix
$ make new
$ export DYLD_FALLBACK_FRAMEWORK_PATH="$PWD/lib"
$ export DYLD_LIBRARY_PATH="$PWD/lib"
$ test/seabreeze_test_posix
For examples of how to call the newer SeaBreezeAPI.h API from C, please see test/api_test.c.
For examples of how to call the older SeaBreezeWrapper.h API from C, please see:
When developing a Visual C# program that uses SeaBreeze, in the application Project, use "Add Existing" to add API\SeaBreezeWrapper.cs to the project.
See sample-code/CSharpDemo for a working example.
Note the command-line tests are normally built from Cygwin (Windows), Ubuntu or CentOS (Linux), and MacOS 10.6+. Future releases may change from Cygwin to MinGW for better 64-bit support.
When developing a Visual C++ program that uses SeaBreeze, in the application Project, use "Add Existing" to add Library\SeaBreeze.lib to the Project Source, as well as API\SeaBreezeWrapper.h.
An application built with SeaBreeze can access the shared DLL in the Windows/System32 folder. The DLL can alternatively be co-located in your application directory.
SeaBreeze has been successfully tested under a variety of 32-bit and 64-bit environments, yet it is not guaranteed that any one particular release of SeaBreeze will definitely build out-of-the-box on a specific platform, without some tweaking of configuration settings.
While we are working to make the installation and linking process as automatic and trouble-free on a wide variety of platforms, we don't yet have an automated regression testing framework in place to rigorously check every release against every compiler in every context.
If you have trouble building, linking, or running from a particular environment, please let us know and we will endeavor to include your use-case in our test procedures.
SeaBreeze is believed to be mostly thread-safe at the level of SeaBreezeWrapper (the public API). While SeaBreeze does not currently create or utilize any threads internally, you should be able to safely make SeaBreeze calls from different threads. Fully tested support for simultaneous access of multiple spectrometers is forthcoming.
If you wish to place a "timeout" on a call to SeaBreeze, such as seabreeze_get_formatted_spectrum(), you can do so using the multi- threaded timeout support provided by your host language. For example, a simple C program using POSIX threads to enforce a timeout on SeaBreeze calls can be found in sample_code/c/demo-timeout.c
A multi-threaded C# demo is also available in sample_code/CSharpDemo.
For support with SeaBreeze issues, please contact oem@oceanoptics.com.
Under Ubuntu 10.04 LTS and other Linux versions, you may have trouble claiming certain spectrometers, including the USB4000, due to a conflict with the vstmod kernel module. Try running "sudo rmmod vstmod", then re-running your SeaBreeze application.
A similar problem was found between HR4000, Debian 6, and the "vstusb" module. Again, adding "blacklist vstusb" to /etc/modprobe.d/blacklist.conf and rebooting resolved the issue.
Some versions of libusb, including that used by some Linux distributions and the latest release of MacOS (El Capitan 10.11.3) lead to very slow enumeration of Toshiba-based spectrometers (the USB4000 and Flame-T). This is being investigated.
This was a significant release of SeaBreeze in that it merged the Ocean Optics "core" version of the SeaBreeze driver (used for internal projects) with the "OEM" version (sometimes called SeaBreezeOEM), which was used for external customer projects.
By merging the two forks back into a unified whole, this ensured that:
Both consequences are anticipated to benefit OEM customers over time, by improving both timeliness and robustness of future releases.
Key changes in SeaBreeze 2.0 for existing internal (non-OEM users) include:
Key changes in SeaBreeze 2.0 for existing OEM users include:
Additional changes will be new for all users:
Ocean Optics supports two different USB drivers on 32-bit Windows: WinUSB (used by Ocean Optics SeaBreeze), and Cypress's ezUSB (used by Ocean Optics OmniDriver, SpectraSuite, OceanView and USB Programmer).
It has been found that the two drivers can coexist on the same system, although the user or a script is required to switch between one and another. This can be done manually:
Computer -> Manage -> Device Manager -> Update Driver ->
No Not This Time -> Install From a List -> Don't Search I Will Choose ->
"USB2000+" (ezUSB) or "USB2000+ (WinUSB)" (SeaBreeze)
Alternately, this can be scripted using the "devcon.exe" executable which comes with the WinDDK (C:/WinDDK/7600.16385.1/tools/devcon/i386). The following Cygwin transcript shows drivers for a pair of connected USB2000+ being flipped between ezUSB (OmniDriver) and WinUSB (SeaBreeze) and back again:
$ devcon update C:\\WINDOWS\\inf\\oem13.inf 'USB\Vid_2457&Pid_101e'
Updating drivers for USB\Vid_2457&Pid_101e from C:\WINDOWS\inf\oem13.inf.
Drivers installed successfully.
$ devcon update C:\\WINDOWS\\inf\\ooi_usb.inf 'USB\Vid_2457&Pid_101e'
Updating drivers for USB\Vid_2457&Pid_101e from C:\WINDOWS\inf\ooi_usb.inf.
Drivers installed successfully.
Note that the correct "oemXX.inf" driver name will be specific to your system, and can be established through something like this:
$ devcon driverfiles '=OceanOpticsUSBDevice'
USB\VID_2457&PID_101E\6&22194588&0&1
Name: Ocean Optics USB2000+ (WinUSB)
Driver installed from c:\windows\inf\oem13.inf [OOIUSB_Install]. 2 file(s) used by driver:
C:\WINDOWS\system32\WinUSBCoInstaller.dll
C:\WINDOWS\system32\WdfCoInstaller01007.dll
1 matching device(s) found.
$ devcon driverfiles '=OceanOpticsUSBDevice' | grep inf | awk '{print $4}'
c:\windows\inf\oem13.inf
...or...
$ grep -l "Ocean Optics USB Devices" /cygdrive/c/windows/inf/*.inf | xargs cygpath -d
C:\windows\inf\oem13.inf
Likewise, the "hardware id" which devcon expects to refer to a spectrometer model will need to be ascertained for your units. This can typically be found in the Device Manager (Properties -> Details -> Hardware IDs), or by running:
$ devcon hwids '*Vid_2457*'
USB\VID_2457&PID_101E\6&22194588&0&1
Name: Ocean Optics USB2000+
Hardware IDs:
USB\Vid_2457&Pid_101e&Rev_0002
USB\Vid_2457&Pid_101e
Compatible IDs:
USB\Class_ff&SubClass_00&Prot_00
USB\Class_ff&SubClass_00
USB\Class_ff
USB\VID_2457&PID_101E\6&22194588&0&2
Name: Ocean Optics USB2000+
Hardware IDs:
USB\Vid_2457&Pid_101e&Rev_0002
USB\Vid_2457&Pid_101e
Compatible IDs:
USB\Class_ff&SubClass_00&Prot_00
USB\Class_ff&SubClass_00
USB\Class_ff
2 matching device(s) found.
$Header: http://gforge.oceanoptics.com/svn/seabreeze/releases/Release_2014_10_01-1730-3.0/README.txt 1221 2014-10-01 21:35:43Z mzieg $
1.8.13