#include "api/DllDecl.h"

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:

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.

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.
slot_number	(Input) The number of the slot to read out. Possible values are 0 through 16*.
buffer	(Output) A buffer (with memory already allocated) to hold the value read out of the EEPROM slot
buffer_length	(Input) The length of the allocated output buffer (typically 16)

Returns: int: The number of bytes read from the EEPROM slot into the buffer

(*) Actual maximum slot count varies by spectrometer model. For the number of supported slots on your spectrometer, see EEPROMSlotFeature instantiation in appropriate device file under src/vendors/OceanOptics/devices.

◆ seabreeze_write_eeprom_slot()

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.

Parameters

index	(Input) The index of a device previously opened with open_spectrometer().
error_code	(Output) A pointer to an integer for storing error codes.
slot_number	(Input) The number of the slot being written (e.g. 0-16*).
buffer	(Input) A buffer containing the text to write to the slot.
buffer_length	(Input) The length of the text to write (typically 15)

Returns: number of bytes written

Warning: CARELESS USE OF THIS FUNCTION CAN RENDER YOUR SPECTROMETER INOPERABLE, POSSIBLY REQUIRING R.M.A. OR REFLASHING TO RESTORE FUNCTIONALITY. PLEASE READ YOUR SPECTROMETER'S DATA SHEET CAREFULLY BEFORE USE.

(*) See note in seabreeze_read_eeprom_slot() regarding per-device slot limits.

◆ seabreeze_read_irrad_calibration()

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.

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.
buffer	(Output) array of floating point values into which calibration values are stored
buffer_length	(Input) maximum number of values to copy from the device into buffer

Returns: int: the number of floats read from the device into the buffer

◆ seabreeze_write_irrad_calibration()

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.

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.
buffer	(Output) array of floating point values to store into the device
buffer_length	(Input) number of calibration factors to write

Returns: int: the number of floats written from the buffer to the device

◆ seabreeze_has_irrad_collection_area()

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.

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: 0 if no collection area available, 1 if available.

◆ seabreeze_read_irrad_collection_area()

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.

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: float: collection area (typically in units of cm^2) read from device

◆ seabreeze_write_irrad_collection_area()

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.

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.
area	(Input) collection area to save to the EEPROM (presumably cm^2)

◆ seabreeze_read_tec_temperature()

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.

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: The TEC temperature in degrees Celsius.

◆ seabreeze_set_tec_temperature()

DLL_DECL void seabreeze_set_tec_temperature	(	int	index,
		int *	error_code,
		double	temperature_degrees_celsius
	)

This function sets the TEC temperature.

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.
temperature_degrees_celsius	(Input) The desired temperature, in degrees Celsius.

◆ seabreeze_set_tec_enable()

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.

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.
tec_enable	(Input) A logical boolean that denotes the desired TEC enable state. If the value of tec_enable is zero, the TEC should be disabled. If the value of tec_enable is non-zero, the TEC should be enabled.

◆ seabreeze_set_tec_fan_enable()

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.

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.
tec_fan_enable	(Input) A logical boolean that denotes the desired TEC fan enable state. If the value of tec_fan_enable is zero, the TEC fan should be disabled. If the value of tec_fan_enable is non-zero, the TEC fan should be enabled.

◆ seabreeze_get_unformatted_spectrum()

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.

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.
buffer	(Output) A buffer (with memory already allocated) to hold the spectral data
buffer_length	(Input) The length of the buffer in bytes (not pixels)

Returns: int: The number of bytes read into the buffer

See also: sample-code/c/demo-unformatted-spectrum.c

An unformatted spectrum is the raw sequence of bytes returned by the spectrometer to the PC over USB. The bytes have not been broken down into pixels, they're in the original endianness, absolutely nothing has been done to them. The caller is expected to know how many bytes are returned by each spectrometer model, which bytes indicate synchronization points or whatever, etc.

◆ seabreeze_get_formatted_spectrum()

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.

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.
buffer	(Output) A buffer (with memory already allocated) to hold the spectral data
buffer_length	(Input) The length of the buffer in floats (not bytes)

Returns: int: The number of floats read into the buffer

A formatted spectrum returns exactly one double-precision floating-point IEEE value per pixel, as opposed to a raw byte stream. It has also had autonulling (gain control) applied, meaning it has been scaled up to the spectrometer's full dynamic range using the gain setting recorded in that spectrometer’s EEPROM.

◆ seabreeze_get_unformatted_spectrum_length()

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(...)).

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: An integer denoting the length of an unformatted spectrum in bytes

The caller is expected to know the number of bytes per pixel and the endian ordering, but it will normally be 2 bytes per pixel, LSB-MSB order.

◆ seabreeze_get_formatted_spectrum_length()

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(...)).

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: An integer denoting the length of a formatted spectrum (in pixels)

◆ seabreeze_get_wavelengths()

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.

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.
wavelengths	(Output) A pre-allocated array of doubles into which the wavelengths will be copied
length	(Input) The number of values to copy into the wavelength array (this should be no larger than the number of doubles allocated in the wavelengths array)

Returns: int: An integer denoting the number of wavelengths written to the buffer

◆ seabreeze_get_serial_number()

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.

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.
buffer	(Output) A pre-allocated array of characters into which the serial number will be copied
buffer_length	(Input) The number of values to copy into the buffer (this should be no larger than the number of chars allocated in the buffer) (typically 16)

Returns: int: An integer denoting the number of bytes written into the buffer

Note that "serial numbers" may include both digits and letters

◆ seabreeze_get_electric_dark_pixel_indices()

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).

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.
indices	(Output) A pre-allocated array of ints into which the pixel indices will be copied
length	(Input) The number of values to copy into the indices array (this should be no larger than the number of ints allocated in the indices array)

Returns: int: An integer denoting the number of indices written into the indices buffer

Note that not all detectors have optically masked pixels; in that case, this function will return zero.

◆ seabreeze_shutdown()

DLL_DECL void seabreeze_shutdown ( )

Shutdown SeaBreeze completely, releasing all resources and destroying any cached device handles.

This function is not normally needed (Singletons are destroyed automatically at process end), but calling this explicitly can resolve some spurious warnings in highly paranoid memory leak profilers.

◆ seabreeze_write_usb()

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.

Parameters

index	(Input) index of an opened spectrometer
errorCode	(Output) pointer to an allocated integer field for receiving error codes
endpoint	(Input) USB endpoint for write operation (see src/vendors/OceanOptics/features/raw_bus_access/RawUSBBusAccessFeature.cpp)
buffer	(Input) array of bytes to send to USB spectrometer
length	(Input) number of bytes to write from buffer to spectrometer

Returns: number of bytes written

Write the bytes in the buffer according to the two command bytes at the start of the buffer.

Endpoints

You may wonder why the caller needs to specify an explicit endpoint for raw read and write operations; does not SeaBreeze already know the appro- priate endpoints for any open spectrometer, for example. Yes it does, but currently there is no easy way to extract endpoints from a generic spectrometer, due to the fact that OOIUSBCypressEndpointMap and OOIUSBSTSEndpointMap do not share a common base class (see OOIUSBEndpointMaps.h).

We could attempt to extract them from the TransferHelpers held by OOIUSBInterface, but without a Hint to use as a key, we would likely obtain unmatched or inappropriate versions for control exchanges. As ControlHint and OBPControlHint share no common ancestor or type data to associate them while distinguishing from other hint types, we cannot automatically infer appropriate control endpoints.

And finally, we have no way of knowing that the user really wants to use control endpoints anyway: they may actually desire high-speed spectral retrieval. So really, this needs to remain a manual external operation until such time as we provide a much richer, generic query interface over our internal endpoint lookup tables.

Example

For instance, for most USB spectrometers, the hex values 05 00 in the buffer means 'read EEPROM slot 0'. Writing this command, and following it with the seabreeze_read_usb command and the same hex 05 00 in the buffer, will result in the spectrometer's serial number, in ASCII characters, being delivered to the subsequent bytes in the buffer array. This would appear in the output buffer as:

05 00 55 53 42 32 2B 48 30 31 34 31 36 00 00 00 00 (hex)

(USB2+H01416 ASCII, skipping the two command bytes)

A C or C++ program could use the data as-is, but a C# program could append to a string, each byte, cast as char, stopping on the first null character:

string serial = "";
for (int i = 0; i < length && buffer[i] != '\0'; i++)
  serial += (char)buffer[i];

This is equivalent to:

string serial = System.Text.ASCIIEncoding.ASCII.GetString(buffer).Trim('\0');

For C# and VB.NET, the trailing zero-fill must be removed. Those null characters would not print or display on a screen but would make a file name invalid.

◆ seabreeze_read_usb()

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.

Parameters

index	(Input) index of a previously opened spectrometer
errorCode	(Output) pointer to an allocated integer field for receiving error codes
endpoint	(Input) USB endpoint for read operation (see src/vendors/OceanOptics/features/raw_bus_access/RawUSBBusAccessFeature.cpp)
buffer	(Input) array of allocated bytes at which to recieve USB data
length	(Input) maximum number of bytes to read from spectrometer

Returns: number of received bytes written to buffer

Read bytes from the spectrometer into the buffer. The buffer starts with two bytes of command information that will be followed by the transferred bytes. The read and write USB functions allow low-level control of the spectrometer via USB commands. The higher-level SeaBreeze functions issue USB commands internally.

Reading USB data takes two steps. First a seabreeze_write_usb call requests the transfer, then a seabreeze_read_usb call delivers the data. Writing a buffer to USB takes one step. The operating system handle for the spectrometer is managed by SeaBreeze. USB has a concept of "end points". These are implicitly addressed by the seabreeze_read_usb and seabreeze_write_usb functions.

◆ seabreeze_get_api_version_string()

DLL_DECL int seabreeze_get_api_version_string	(	char *	buffer,
		int	len
	)

Get the SeaBreeze library's internal version identifier.

Parameters

buffer	(Output) pointer to an allocated character array to hold the returned version string
len	(Input) size of the allocated buffer

Returns: number of bytes written to buffer

◆ seabreeze_get_usb_descriptor_string()

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.

Parameters

index	(Input) Which spectrometer to set
errorCode	(Output) pointer to allocated integer to receive error code
id	(Input) numeric ID of the desired USB descriptor string
buffer	(Output) pointer to an allocated character array to hold the returned descriptor string
len	(Input) size of the allocated buffer

Returns: number of bytes written to buffer

◆ seabreeze_set_continuous_strobe_period_microsec()

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.

Parameters

index	(Input) Which spectrometer to set
errorCode	(Output) pointer to allocated integer to receive error code
strobe_id	(Input) index of the strobe generator (currently always zero)
period_usec	(Input) total period of the strobe, in microseconds

Returns: zero (on success or failure; check errorCode)

The resolution is 0.1 milliseconds (100 microseconds).

◆ seabreeze_clear_buffer()

DLL_DECL void seabreeze_clear_buffer	(	int	index,
		int *	error_code
	)

Clear the spectrum buffer (if equipped)

Parameters

index	(Input) Which spectrometer should have its buffer cleared
error_code	(Output) Pointer to allocated integer to receive error code

◆ seabreeze_get_buffer_element_count()

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)

Parameters

index	(Input) Which spectrometer should have its buffer queried
error_code	(Output) Pointer to allocated integer to receive error code

Returns: Number of spectra in the buffer

◆ seabreeze_get_buffer_capacity()

DLL_DECL unsigned long seabreeze_get_buffer_capacity	(	int	index,
		int *	error_code
	)

Get the currently configured size of the data buffer (if equipped)

Parameters

index	(Input) Which spectrometer should have its buffer queried
error_code	(Output) Pointer to allocated integer to receive error code

Returns: The present limit on the number of spectra that will be retained.

◆ seabreeze_get_buffer_capacity_maximum()

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)

Parameters

index	(Input) Which spectrometer should have its buffer queried
error_code	(Output) Pointer to allocated integer to receive error code

Returns: Maximum allowed value for the buffer size

◆ seabreeze_get_buffer_capacity_minimum()

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)

Parameters

index	(Input) Which spectrometer should have its buffer queried
error_code	(Output) Pointer to allocated integer to receive error code

Returns: Minimum allowed value for the buffer size

◆ seabreeze_set_buffer_capacity()

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.

Parameters

index	(Input) Which spectrometer should have its buffer modified
error_code	(Output) Pointer to allocated integer to receive error code
capacity	(Input) Limit on number of spectra to store. Note that this must be within the range defined by the capacity minimum and maximum values.

◆ seabreeze_set_verbose()

DLL_DECL void seabreeze_set_verbose ( int flag )

Programmatically enable debug outputs to stderr.

Parameters

flag	(Input) zero to disable (default), non-zero to enable

◆ seabreeze_set_logfile()

DLL_DECL void seabreeze_set_logfile	(	char *	pathname,
		int	len
	)

redirect verbose logging to named file

Parameters

flag	(Input) NULL for default behavior (stderr), non-null for valid OS path

Data Structures

Namespaces

Macros

Functions

Detailed Description

Function Documentation

◆ seabreeze_open_spectrometer()

◆ seabreeze_close_spectrometer()

◆ seabreeze_get_error_string()

◆ seabreeze_get_model()

◆ seabreeze_set_trigger_mode()

◆ seabreeze_set_integration_time_microsec()

◆ seabreeze_get_min_integration_time_microsec()

◆ seabreeze_set_shutter_open()

◆ seabreeze_set_strobe_enable()

◆ seabreeze_get_light_source_count()

◆ seabreeze_set_light_source_enable()

◆ seabreeze_set_light_source_intensity()

◆ seabreeze_read_eeprom_slot()

◆ seabreeze_write_eeprom_slot()

◆ seabreeze_read_irrad_calibration()

◆ seabreeze_write_irrad_calibration()

◆ seabreeze_has_irrad_collection_area()

◆ seabreeze_read_irrad_collection_area()

◆ seabreeze_write_irrad_collection_area()

◆ seabreeze_read_tec_temperature()

◆ seabreeze_set_tec_temperature()

◆ seabreeze_set_tec_enable()

◆ seabreeze_set_tec_fan_enable()

◆ seabreeze_get_unformatted_spectrum()

◆ seabreeze_get_formatted_spectrum()

◆ seabreeze_get_unformatted_spectrum_length()

◆ seabreeze_get_formatted_spectrum_length()

◆ seabreeze_get_wavelengths()

◆ seabreeze_get_serial_number()

◆ seabreeze_get_electric_dark_pixel_indices()

◆ seabreeze_shutdown()

◆ seabreeze_write_usb()

Endpoints

Example

◆ seabreeze_read_usb()

◆ seabreeze_get_api_version_string()

◆ seabreeze_get_usb_descriptor_string()

◆ seabreeze_set_continuous_strobe_period_microsec()

◆ seabreeze_clear_buffer()

◆ seabreeze_get_buffer_element_count()

◆ seabreeze_get_buffer_capacity()

◆ seabreeze_get_buffer_capacity_maximum()

◆ seabreeze_get_buffer_capacity_minimum()

◆ seabreeze_set_buffer_capacity()

◆ seabreeze_set_verbose()

◆ seabreeze_set_logfile()