SeaBreeze
Data Structures | Namespaces | Macros | Functions
SeaBreezeWrapper.h File Reference
#include "api/DllDecl.h"

Go to the source code of this file.

Data Structures

class  SeaBreezeWrapper
 

Namespaces

 seabreeze
 Encapsulates all SeaBreeze classes.
 

Macros

#define SEABREEZE_API_VERSION   "3.0.11"
 current version of the SeaBreezeWrapper API
 
#define SEABREEZE_MAX_DEVICES   32
 how many different spectrometer types we support
 

Functions

DLL_DECL int seabreeze_open_spectrometer (int index, int *error_code)
 This function opens a device attached to the system. More...
 
DLL_DECL int seabreeze_close_spectrometer (int index, int *error_code)
 This function closes the spectrometer attached to the system. More...
 
DLL_DECL int seabreeze_get_error_string (int error_code, char *buffer, int buffer_length)
 This function returns a description of the error denoted by error_code. More...
 
DLL_DECL int seabreeze_get_model (int index, int *error_code, char *buffer, int buffer_length)
 This function returns a string denoting the type of the device. More...
 
DLL_DECL void seabreeze_set_trigger_mode (int index, int *error_code, int mode)
 This function sets the trigger mode for the specified device. More...
 
DLL_DECL void seabreeze_set_integration_time_microsec (int index, int *error_code, unsigned long integration_time_micros)
 This function sets the integration time for the specified device. More...
 
DLL_DECL long seabreeze_get_min_integration_time_microsec (int index, int *error_code)
 This function returns the smallest integration time setting, in microseconds, that is valid for the spectrometer. More...
 
DLL_DECL void seabreeze_set_shutter_open (int index, int *error_code, unsigned char opened)
 This function sets the shutter state on the spectrometer. More...
 
DLL_DECL void seabreeze_set_strobe_enable (int index, int *error_code, unsigned char strobe_enable)
 This function sets the strobe enable on the spectrometer. Note that this refers to a particular set of one or more digital pins on the device: lamp enable, single strobe, and continuous strobe may all be affected by this setting, and these generally control lamps that are external to the device. Note that this is related to, but different from, the light source interface which allows the intensity and/or enable status of individual light sources (e.g. lamp bulbs, LEDs, or lasers) in attached modules to be controlled. Refer to the seabreeze_xxx_light_source_ functions for finer control of certain light source modules that are more closely integrated with the spectrometer. More...
 
DLL_DECL int seabreeze_get_light_source_count (int index, int *error_code)
 This function gets the number of attached light sources that can be programmatically controlled. More...
 
DLL_DECL void seabreeze_set_light_source_enable (int index, int *error_code, int light_index, unsigned char enable)
 This function sets the enable status on a connected light source. More...
 
DLL_DECL void seabreeze_set_light_source_intensity (int index, int *error_code, int light_index, double intensity)
 This function sets the intensity of a connected light source. More...
 
DLL_DECL int seabreeze_read_eeprom_slot (int index, int *error_code, int slot_number, unsigned char *buffer, int buffer_length)
 This function reads a string out of the spectrometer's EEPROM slot and returns the result. More...
 
DLL_DECL int seabreeze_write_eeprom_slot (int index, int *error_code, int slot_number, unsigned char *buffer, int buffer_length)
 This function writes a string to a spectrometer's EEPROM slot. More...
 
DLL_DECL int seabreeze_read_irrad_calibration (int index, int *error_code, float *buffer, int buffer_length)
 This function reads out an irradiance calibration from the spectrometer's internal memory if that feature is supported. More...
 
DLL_DECL int seabreeze_write_irrad_calibration (int index, int *error_code, float *buffer, int buffer_length)
 This function writes an irradiance calibration to the spectrometer's internal memory if that feature is supported. More...
 
DLL_DECL int seabreeze_has_irrad_collection_area (int index, int *error_code)
 This function checks for an irradiance collection area in the spectrometer's internal memory if that feature is supported. More...
 
DLL_DECL float seabreeze_read_irrad_collection_area (int index, int *error_code)
 This function reads an irradiance collection area from the spectrometer's internal memory if that feature is supported. More...
 
DLL_DECL void seabreeze_write_irrad_collection_area (int index, int *error_code, float area)
 This function writes an irradiance collection area to the spectrometer's internal memory if that feature is supported. More...
 
DLL_DECL double seabreeze_read_tec_temperature (int index, int *error_code)
 This function reads the value of the TEC and returns the value in degrees celsius. More...
 
DLL_DECL void seabreeze_set_tec_temperature (int index, int *error_code, double temperature_degrees_celsius)
 This function sets the TEC temperature. More...
 
DLL_DECL void seabreeze_set_tec_enable (int index, int *error_code, unsigned char tec_enable)
 This function enables the TEC feature on the spectrometer. More...
 
DLL_DECL void seabreeze_set_tec_fan_enable (int index, int *error_code, unsigned char tec_fan_enable)
 This function enables the TEC Fan on the spectrometer. More...
 
DLL_DECL int seabreeze_get_unformatted_spectrum (int index, int *error_code, unsigned char *buffer, int buffer_length)
 This acquires a spectrum and returns the answer in raw, unformatted bytes. More...
 
DLL_DECL int seabreeze_get_formatted_spectrum (int index, int *error_code, double *buffer, int buffer_length)
 This acquires a spectrum and returns the answer in formatted floats. In this mode, auto-nulling should be automatically performed for devices that support it. More...
 
DLL_DECL int seabreeze_get_unformatted_spectrum_length (int index, int *error_code)
 This returns an integer denoting the length of a raw spectrum (as returned by get_unformatted_spectrum(...)). More...
 
DLL_DECL int seabreeze_get_formatted_spectrum_length (int index, int *error_code)
 This returns an integer denoting the number of pixels in a formatted spectrum (as returned by get_formatted_spectrum(...)). More...
 
DLL_DECL int seabreeze_get_wavelengths (int index, int *error_code, double *wavelengths, int length)
 This computes the wavelengths for the spectrometer and fills in the provided array (up to the given length) with those values. More...
 
DLL_DECL int seabreeze_get_serial_number (int index, int *error_code, char *buffer, int buffer_length)
 This reads the device's serial number and fills the provided array (up to the given length) with it. More...
 
DLL_DECL int seabreeze_get_electric_dark_pixel_indices (int index, int *error_code, int *indices, int length)
 This fills in the provided array (up to the given length) with the indices of the pixels that are electrically active but optically masked (a.k.a. electric dark pixels). More...
 
DLL_DECL void seabreeze_shutdown ()
 Shutdown SeaBreeze completely, releasing all resources and destroying any cached device handles. More...
 
DLL_DECL int seabreeze_write_usb (int index, int *errorCode, unsigned char endpoint, unsigned char *buffer, unsigned int length)
 Write a raw array of bytes to a USB spectrometer. More...
 
DLL_DECL int seabreeze_read_usb (int index, int *errorCode, unsigned char endpoint, unsigned char *buffer, unsigned int length)
 Read a raw array of bytes from a USB spectrometer. More...
 
DLL_DECL int seabreeze_get_api_version_string (char *buffer, int len)
 Get the SeaBreeze library's internal version identifier. More...
 
DLL_DECL int seabreeze_get_usb_descriptor_string (int index, int *errorCode, int id, unsigned char *buffer, int len)
 Get a USB descriptor string by number. More...
 
DLL_DECL void seabreeze_set_continuous_strobe_period_microsec (int index, int *errorCode, unsigned short strobe_id, unsigned long period_usec)
 Set the continuous strobe period in microseconds. More...
 
DLL_DECL void seabreeze_set_acquisition_delay_microsec (int index, int *errorCode, unsigned long delay_usec)
 Set the acquisition delay (trigger delay) in microseconds. This controls the amount of time between a particular event (usually a request for spectrum or an external trigger pulse) and the start of acquisition.
 
DLL_DECL void seabreeze_clear_buffer (int index, int *error_code)
 Clear the spectrum buffer (if equipped) More...
 
DLL_DECL unsigned long seabreeze_get_buffer_element_count (int index, int *error_code)
 Get the number of spectra presently in the buffer (if equipped) More...
 
DLL_DECL unsigned long seabreeze_get_buffer_capacity (int index, int *error_code)
 Get the currently configured size of the data buffer (if equipped) More...
 
DLL_DECL unsigned long seabreeze_get_buffer_capacity_maximum (int index, int *error_code)
 Get the maximum possible configurable size for the data buffer (if equipped) More...
 
DLL_DECL unsigned long seabreeze_get_buffer_capacity_minimum (int index, int *error_code)
 Get the minimum possible configurable size for the data buffer (if equipped) More...
 
DLL_DECL void seabreeze_set_buffer_capacity (int index, int *error_code, unsigned long capacity)
 Set the number of spectra that the buffer should keep. More...
 
DLL_DECL void seabreeze_set_verbose (int flag)
 Programmatically enable debug outputs to stderr. More...
 
DLL_DECL void seabreeze_set_logfile (char *pathname, int len)
 redirect verbose logging to named file More...
 

Detailed Description

Date
July 2009
Author
Ocean Optics, Inc.

This is a trivial interface to SeaBreeze that allows the user to connect to devices over USB. This is intended as a usable and extensible API.

This provides a C interface to help with linkage.

LICENSE:

SeaBreeze Copyright (C) 2014, Ocean Optics Inc

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Function Documentation

◆ seabreeze_open_spectrometer()

DLL_DECL int seabreeze_open_spectrometer ( int  index,
int *  error_code 
)

This function opens a device attached to the system.

Parameters
index(Input) The index of a USB device to try to open. Valid values will range from 0 to N-1 for N connected devices.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
int: The function will return an integer of 0 if it opened a device successfully, or 1 if no device was opened (in which case the error_code variable will be set).

This can be called repeatedly with incrementing index values (until it returns 1) to open all connected devices.

Note that the index used to open a device with this function should also be used to communicate with that same device in the other functions provided here.

◆ seabreeze_close_spectrometer()

DLL_DECL int seabreeze_close_spectrometer ( int  index,
int *  error_code 
)

This function closes the spectrometer attached to the system.

Parameters
index(Input) The index of a device previously opened with open_spectrometer().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
int: This function will return 1 no matter what! (MZ)

◆ seabreeze_get_error_string()

DLL_DECL int seabreeze_get_error_string ( int  error_code,
char *  buffer,
int  buffer_length 
)

This function returns a description of the error denoted by error_code.

Parameters
error_code(Input) The integer error code to look up. Error codes not be zero, but can be any non-zero integer (positive or negative).
buffer(Output) A character buffer allocated to contain at least 'buffer_length' bytes, which will be populated with the string description of the given error code.
buffer_length(Input) allocated size of the output buffer
Returns
int: Number of bytes written to buffer.

◆ seabreeze_get_model()

DLL_DECL int seabreeze_get_model ( int  index,
int *  error_code,
char *  buffer,
int  buffer_length 
)

This function returns a string denoting the type of the device.

Parameters
index(Input) The index of a device previously opened with open_spectrometer().
error_code(Output) A pointer to an integer that can be used for storing error codes. This may be NULL.
buffer(Output) A character buffer allocated to contain at least 'buffer_length' bytes, which will be populated with the spectrometer type.
buffer_length(Input) allocated size of the buffer
Returns
int: Number of bytes written to the buffer.

The populated buffer will hold one of the following strings:

*      NONE:        Used if no spectrometer is found (error_code will also be set)
*      HR2000:      Represents an HR2000 Spectrometer
*      HR2000PLUS:  Represents an HR2000+ Spectrometer
*      HR4000:      Represents an HR4000 Spectrometer
*      JAZ:         Represents a Jaz Spectrometer
*      MAYA2000:    Represents a Maya2000 Spectrometer
*      MAYALSL:     Represents a Maya-LSL Spectrometer
*      MAYA2000PRO: Represents a Maya2000 Pro Spectrometer
*      NIRQUEST256: Represents an NIRQuest256 Spectrometer
*      NIRQUEST512: Represents an NIRQuest512 Spectrometer
*      QE65000:     Represents a QE65000 Spectrometer
*      QE-PRO:      Represents a QE-Pro Spectrometer
*      STS:         Represents an STS Spectrometer
*      TORUS:       Represents a Torus Spectrometer
*      USB2000:     Represents a USB2000 Spectrometer
*      USB2000PLUS: Represents a USB2000+ Spectrometer
*      USB4000:     Represents a USB4000 Spectrometer
* 

◆ seabreeze_set_trigger_mode()

DLL_DECL void seabreeze_set_trigger_mode ( int  index,
int *  error_code,
int  mode 
)

This function sets the trigger mode for the specified device.

Parameters
index(Input) The index of a device previously opened with open_spectrometer().
error_code(Output) A pointer to an integer that can be used for storing error codes.
mode(Input) a trigger mode (0 = normal, 1 = software, 2 = synchronization, 3 = external hardware, etc.)

Note that requesting an unsupported mode will result in an error.

◆ seabreeze_set_integration_time_microsec()

DLL_DECL void seabreeze_set_integration_time_microsec ( int  index,
int *  error_code,
unsigned long  integration_time_micros 
)

This function sets the integration time for the specified device.

Parameters
index(Input) The index of a device previously opened with open_spectrometer().
error_code(Output) A pointer to an integer that can be used for storing error codes.
integration_time_micros(Input) The new integration time in units of microseconds

This function does not automatically perform a stability scan. If your application requires a stability scan following a change in integration time, you need to command that yourself.

◆ seabreeze_get_min_integration_time_microsec()

DLL_DECL long seabreeze_get_min_integration_time_microsec ( int  index,
int *  error_code 
)

This function returns the smallest integration time setting, in microseconds, that is valid for the spectrometer.

Parameters
index(Input) The index of a device previously opened with open_spectrometer().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
Returns minimum legal integration time in microseconds if > 0. On error, returns -1 and error_code will be set accordingly.

◆ seabreeze_set_shutter_open()

DLL_DECL void seabreeze_set_shutter_open ( int  index,
int *  error_code,
unsigned char  opened 
)

This function sets the shutter state on the spectrometer.

Parameters
index(Input) The index of a device previously opened with open_spectrometer().
error_code(Output) A pointer to an integer that can be used for storing error codes.
opened(Input) A logical boolean used for denoting the desired state (opened/closed) of the shutter. If the value of opened is non-zero, then the shutter will open. If the value of opened is zero, then the shutter will close.

◆ seabreeze_set_strobe_enable()

DLL_DECL void seabreeze_set_strobe_enable ( int  index,
int *  error_code,
unsigned char  strobe_enable 
)

This function sets the strobe enable on the spectrometer. Note that this refers to a particular set of one or more digital pins on the device: lamp enable, single strobe, and continuous strobe may all be affected by this setting, and these generally control lamps that are external to the device. Note that this is related to, but different from, the light source interface which allows the intensity and/or enable status of individual light sources (e.g. lamp bulbs, LEDs, or lasers) in attached modules to be controlled. Refer to the seabreeze_xxx_light_source_ functions for finer control of certain light source modules that are more closely integrated with the spectrometer.

Parameters
index(Input) The index of a device previously opened with open_spectrometer().
error_code(Output) A pointer to an integer that can be used for storing error codes.
strobe_enable(Input) A logical boolean used for denoting the desired value (high/low) of the strobe-enable pin. If the value of strobe_enable is zero, then the pin should be set low. If the value of strobe_enable is non-zero, then the pin should be set high.

◆ seabreeze_get_light_source_count()

DLL_DECL int seabreeze_get_light_source_count ( int  index,
int *  error_code 
)

This function gets the number of attached light sources that can be programmatically controlled.

Parameters
index(Input) The index of a device previously opened with open_spectrometer().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
The number of light sources that can be controlled

◆ seabreeze_set_light_source_enable()

DLL_DECL void seabreeze_set_light_source_enable ( int  index,
int *  error_code,
int  light_index,
unsigned char  enable 
)

This function sets the enable status on a connected light source.

Parameters
index(Input) The index of a device previously opened with open_spectrometer().
error_code(Output) A pointer to an integer that can be used for storing error codes.
light_index(Input) The index of the light source. This will usually be zero, but if the light module contains multiple LEDs, bulbs, lasers, etc. then this may be higher. Use seabreeze_get_light_source_count() to bound the maximum value .
enable(Input) A logical boolean used for denoting whether to enable the indicated light source. If the value of enable is zero, then the light source should be disabled. If the value of enable is non-zero, then the light source should be enabled.

◆ seabreeze_set_light_source_intensity()

DLL_DECL void seabreeze_set_light_source_intensity ( int  index,
int *  error_code,
int  light_index,
double  intensity 
)

This function sets the intensity of a connected light source.

Parameters
index(Input) The index of a device previously opened with open_spectrometer().
error_code(Output) A pointer to an integer that can be used for storing error codes.
light_index(Input) The index of the light source. This will usually be zero, but if the light module contains multiple LEDs, bulbs, lasers, etc. then this may be higher. Use seabreeze_get_light_source_count() to bound the maximum value.
intensity(Input) The desired intensity of the light source. The range of intensities is normalized over [0, 1], where 0 is the minimum controllable intensity of the light source, and 1 is the maximum.
Warning
SETTING THE INTENSITY TO ZERO MAY NOT CAUSE THE LIGHT SOURCE TO TURN OFF COMPLETELY. The light source will go to the dimmest level it can reach without changing its enable status. To switch the light source off, try using the seabreeze_set_light_source_enable() function or provide the operator with another way to disable or block the light source.

◆ seabreeze_read_eeprom_slot()

DLL_DECL int seabreeze_read_eeprom_slot ( int  index,
int *  error_code,
int  slot_number,
unsigned char *  buffer,
int  buffer_length 
)

This function reads a string out of the spectrometer's EEPROM slot and returns the result. </