Implementation of the flattened C API exported by WasatchVCPP.dll. More...

#include "pch.h"
#include "WasatchVCPP.h"
#include <algorithm>
#include <vector>
#include <string>
#include <map>
#include <math.h>
#include <string.h>
#include "Util.h"
#include "Logger.h"
#include "Driver.h"
#include "Spectrometer.h"

Functions
int	exportString (string s, char *buf, int len)
	copy a std::string to a C string More...

int	wp_open_all_spectrometers ()
	Connects to and initializes all enumerated USB spectrometers. More...

int	wp_close_spectrometer (int specIndex)
	Closes the specified spectrometer. More...

int	wp_close_all_spectrometers ()
	Closes all connected spectrometers. More...

void	wp_destroy_driver ()
	Permanently releases all objects from memory. More...

int	wp_get_library_version (char *value, int len)
	Obtains the version number of the WasatchVCPP library itself. More...

int	wp_get_number_of_spectrometers ()
	Returns number of spectrometers previously opened. More...

int	wp_get_pixels (int specIndex)
	Returns the number of pixels in the selected spectrometer.o. More...

int	wp_get_model (int specIndex, char *value, int len)
	Get the selected spectrometer's model. More...

int	wp_get_serial_number (int specIndex, char *value, int len)
	Get the selected spectrometer's serial number. More...

int	wp_get_wavelengths (int specIndex, double *wavelengths, int len)
	Get the selected spectrometer's calibrated wavelength x-axis in nanometers. More...

int	wp_get_wavelengths_float (int specIndex, float *wavelengths, int len)
	Get the selected spectrometer's calibrated wavelength x-axis in nanometers as float. More...

int	wp_get_wavenumbers (int specIndex, double *wavenumbers, int len)
	Get the selected spectrometer's calibrated x-axis in wavenumbers (1/cm) More...

int	wp_get_wavenumbers_float (int specIndex, float *wavenumbers, int len)
	Get the selected spectrometer's calibrated x-axis in wavenumbers (1/cm) as float. More...

int	wp_get_spectrum (int specIndex, double *spectrum, int len)
	Read one spectrum from the selected spectrometer. More...

int	wp_get_spectrum_float (int specIndex, float *spectrum, int len)
	Read one spectrum from the selected spectrometer as float. More...

int	wp_get_eeprom_field_count (int specIndex)
	This is provided so the caller can correctly size the 'names' and 'values' arrays for a call to wp_get_eeprom(). More...

int	wp_get_eeprom_field_name (int specIndex, int index, char *value, int len)
	Obtain the nth ordered EEPROM field name. More...

int	wp_get_eeprom (int specIndex, const char names, const char values, int len)
	Read a table of all EEPROM fields, as strings. More...

int	wp_get_eeprom_field (int specIndex, const char name, char valueOut, int len)
	Read one stringified EEPROM field by name. More...

int	wp_get_eeprom_page (int specIndex, int page, uint8_t *buf, int len)

int	wp_set_logfile_path (const char *pathname, int len)
	Sets a pathname for WasatchVCPP to write a debug logfile. More...

int	wp_set_log_level (int level)
	Sets driver log level. More...

int	wp_log_debug (const char *msg, int len)
	Allows calling code (and wrappers) to inject lines into the library's log. More...

int	wp_set_integration_time_ms (int specIndex, unsigned long ms)
	Set the spectrometer's integration time in milliseconds. More...

int	wp_set_laser_enable (int specIndex, int value)
	Turns the laser on or off. More...

int	wp_set_laser_power_perc (int specIndex, float percent)
	Sets laser power as a percentage of max power. More...

int	wp_set_laser_power_mW (int specIndex, float percent)
	Sets laser power as a mW value. More...

int	wp_set_detector_gain (int specIndex, float value)
	Set detector gain. More...

int	wp_set_detector_gain_odd (int specIndex, float value)
	On InGaAs spectrometers, configures the gain for odd-numbered pixels. More...

int	wp_set_detector_offset (int specIndex, int value)
	Set detector offset. More...

int	wp_set_detector_offset_odd (int specIndex, int value)
	On InGaAs spectrometers, configures the offset for odd-numbered pixels. More...

int	wp_set_detector_tec_enable (int specIndex, int value)
	Turn the detector TEC on or off. More...

int	wp_set_detector_tec_setpoint_deg_c (int specIndex, int value)
	Set the detector TEC setpoint. More...

int	wp_set_high_gain_mode_enable (int specIndex, int value)
	Enable or disable "high gain" mode on InGaAs detectors. More...

int	wp_get_firmware_version (int specIndex, char *value, int len)
	Get the firmware version of the microcontroller (FX2 or ARM). More...

int	wp_get_fpga_version (int specIndex, char *value, int len)
	Get the version of the FPGA. More...

float	wp_get_detector_temperature_deg_c (int specIndex)
	Get the detector temperature. More...

long	wp_get_integration_time_ms (int specIndex)
	Get the curent integration time. More...

int	wp_get_laser_enable (int specIndex)
	Reports whether laser is currently enabled (firing, or configured to do so). More...

float	wp_get_detector_gain (int specIndex)
	Get the current detector gain (on InGaAs, even pixels only). More...

float	wp_get_detector_gain_odd (int specIndex)
	Get the current detector gain for odd InGaAs pixels. More...

int	wp_get_detector_offset (int specIndex)
	Get the current detector offset (on InGaAs, even pixels only). More...

int	wp_get_detector_offset_odd (int specIndex)
	Get the current detector offset for odd InGaAs pixels. More...

int	wp_get_detector_tec_enable (int specIndex)
	Reports whether the detector TEC is enabled. More...

int	wp_get_detector_tec_setpoint_deg_c (int specIndex)
	Get the current detector TEC setpoint in degrees Celsius. More...

int	wp_get_high_gain_mode_enable (int specIndex)
	Reports whether "high-gain mode" is currently enabled on InGaAs detectors. More...

int	wp_cancel_operation (int specIndex, int blocking)
	If an acquisition is currently in progress, cancel it. More...

int	wp_set_max_timeout_ms (int specIndex, int maxTimeoutMS)
	Configure the maximum internal timeout when waiting on blocking USB operations. More...

int	wp_get_max_timeout_ms (int specIndex)
	Get the maximum internal timeout when waiting on blocking USB operations. More...

int	wp_write_eeprom_page (int specIndex, int pageIndex, unsigned char *data, int dataLen)

int	wp_send_control_msg (int specIndex, unsigned char bRequest, unsigned int wValue, unsigned int wIndex, unsigned char *data, int len)
	Provide direct access to writing spectrometer opcodes via USB setup packets (endpoint 0 control. More...

int	wp_read_control_msg (int specIndex, unsigned char bRequest, unsigned int wIndex, unsigned char *data, int len)
	Provide direct access to reading spectrometer opcodes via USB setup packets (endpoint 0 control. More...

int	wp_get_vignetted_spectrum_length (int specIndex)

int	wp_get_raman_intensity_factors (int specIndex, double *factors, int factorsLen)

int	wp_apply_raman_intensity_factors (int specIndex, double spectrum, int spectrum_len, double factors, int factors_len, int start_pixel, int end_pixel)

int	wp_has_srm_calibration (int specIndex)

Variables
Driver *	driver = Driver::getInstance()

Detailed Description

Implementation of the flattened C API exported by WasatchVCPP.dll.

Author: Mark Zieg mzieg.nosp@m.@was.nosp@m.atchp.nosp@m.hoto.nosp@m.nics..nosp@m.com

Note: customers normally wouldn't access this file; use WasatchVCPP.h instead

This file implements the "C" interface to the WasatchVCPP library and DLL which is defined in WasatchCPP.h.

This file is the one and only place where the WasatchVCPP::Driver Singleton is actually instantiated (meaning it probably doesn't actually have to be a Singleton...)

Todo:: rename to WasatchVCPP.cpp, as the impl to WasatchVCPP.h?

Function Documentation

◆ exportString()

int exportString	(	string	s,
		char *	buf,
		int	len
	)

copy a std::string to a C string

Parameters

s	(Input) a populated std::string
buf	(Output) the destination where the string is to be copied
len	(Input) allocated size of 'buf'

Returns: WP_SUCCESS or WP_ERROR_INSUFFICIENT_STORAGE

◆ wp_cancel_operation()

int wp_cancel_operation	(	int	specIndex,
		int	blocking
	)

If an acquisition is currently in progress, cancel it.

Note that while this function will return instantly, the current operation is guaranteed to complete within the currently configured "maximum timeout" as set through wp_set_max_timeout_ms.

Warning: new firmware is required to support this at the hardware level

See also: should block at most the value configured in wp_set_max_timeout_ms

Parameters

specIndex	(Input) which spectrometer
block	(Input) whether the function should block until the current operation completes (0 for non-blocking, non-zero for blocking)

Returns: WP_SUCCESS or non-zero on error

◆ wp_close_all_spectrometers()

int wp_close_all_spectrometers ( )

Closes all connected spectrometers.

Returns: WP_SUCCESS or non-zero on error

◆ wp_close_spectrometer()

int wp_close_spectrometer ( int specIndex )

Closes the specified spectrometer.

Parameters

specIndex (Input) which spectrometer

Returns: WP_SUCCESS or non-zero on error

◆ wp_destroy_driver()

void wp_destroy_driver ( )

Permanently releases all objects from memory.

It is recommended to close and restart the application be after calling this function, before wp_open_all_spectrometers can be called again.

◆ wp_get_detector_gain()

float wp_get_detector_gain ( int specIndex )

Get the current detector gain (on InGaAs, even pixels only).

Parameters

specIndex (Input) which spectrometer

Returns: configured gain or WP_ERROR_INVALID_GAIN on error

◆ wp_get_detector_gain_odd()

float wp_get_detector_gain_odd ( int specIndex )

Get the current detector gain for odd InGaAs pixels.

Parameters

specIndex (Input) which spectrometer

Returns: configured gain or WP_ERROR_INVALID_GAIN on error

◆ wp_get_detector_offset()

int wp_get_detector_offset ( int specIndex )

Get the current detector offset (on InGaAs, even pixels only).

Parameters

specIndex (Input) which spectrometer

Returns: configured gain or WP_ERROR_INVALID_OFFSET on error

◆ wp_get_detector_offset_odd()

int wp_get_detector_offset_odd ( int specIndex )

Get the current detector offset for odd InGaAs pixels.

Parameters

specIndex (Input) which spectrometer

Returns: configured gain or WP_ERROR_INVALID_OFFSET on error

◆ wp_get_detector_tec_enable()

int wp_get_detector_tec_enable ( int specIndex )

Reports whether the detector TEC is enabled.

Parameters

specIndex (Input) which spectrometer

Returns: 1 if enabled, 0 if disabled, negative on error

◆ wp_get_detector_tec_setpoint_deg_c()

int wp_get_detector_tec_setpoint_deg_c ( int specIndex )

Get the current detector TEC setpoint in degrees Celsius.

Parameters

specIndex (Input) which spectrometer

Returns: cached value most recently set

◆ wp_get_detector_temperature_deg_c()

float wp_get_detector_temperature_deg_c ( int specIndex )

Get the detector temperature.

Parameters

specIndex (Input) which spectrometer

Returns: WP_ERROR_INVALID_TEMPERATURE on error, else detector temperature in degrees Celsius

◆ wp_get_eeprom()

int wp_get_eeprom	(	int	specIndex,
		const char **	names,
		const char **	values,
		int	len
	)

Read a table of all EEPROM fields, as strings.

This is provided as a fast-and-simple way to expose the entire EEPROM to the caller in one function call. It would be nice if we could return the actual EEPROM object with all the fields parsed into native types, but you can't send objects across the ABI. It would be nice if we could send a std::map of name-value pairs, but you can't send templates across the ABI. So we get...this.

Note this doesn't actually copy any data...all it does is copy the current pointer location of each EEPROM field name and stringified value from the EEPROM::stringified map. Currently, there is no use-case where those strings are changed after the spectrometer is instantiated, partly because we're not yet supporting "EEPROM write".

Therefore these character pointers SHOULD be valid until the spectrometers are closed and their EEPROM objects destroyed. However, it would probably be a good idea for calling code to make copies of these values if it wants to persist them. (This is what WasatchVCPP::Proxy does, instantiating each field into a new map<string, string> immediately after calling this function.)

A "full" API implementation could probably include native-type accessors (and settors!) for every field in the EEPROM; I've already added such "convenience accessors" for pixels, model and serialNumber due to their relative importance when testing spectroscopy applications. However, that's a lot of typing and testing, and this will do for now.

Parameters

specIndex	(Input) which spectrometer
names	(Output) a pre-allocated array of character pointers to hold field names
values	(Output) a pre-allocated array of character pointers to hold field values
len	(Input) number of elements in names and values arrays

Returns: WP_SUCCESS or non-zero on error

◆ wp_get_eeprom_field()

int wp_get_eeprom_field	(	int	specIndex,
		const char *	name,
		char *	value,
		int	len
	)

Read one stringified EEPROM field by name.

If you don't want to call wp_get_eeprom and only want one or two fields and you already know their names, this can be easier than reading the whole table.

Parameters

specIndex	(Input) which spectrometer
name	(Input) case-insensitive name of the desired EEPROM field
value	(Output) a pre-allocated character array to hold the value
len	(Input) length of pre-allocated array

Returns: WP_SUCCESS or non-zero on error

◆ wp_get_eeprom_field_count()

int wp_get_eeprom_field_count ( int specIndex )

This is provided so the caller can correctly size the 'names' and 'values' arrays for a call to wp_get_eeprom().

Parameters

specIndex (Input) which spectrometer

Returns: how many EEPROM fields are available (negative on error)

◆ wp_get_eeprom_field_name()

int wp_get_eeprom_field_name	(	int	specIndex,
		int	index,
		char *	value,
		int	len
	)

Obtain the nth ordered EEPROM field name.

Parameters

specIndex	(Input) which spectrometer
index	(Input) which field (1...wp_get_eeprom_field_count)
value	(Output) allocated character buffer of 'len' bytes
len	(Input) size of allocated value buffer

Returns: WP_SUCCESS, WP_INSUFFICIENT_STORAGE or WP_ERROR if index > field count)

◆ wp_get_firmware_version()

int wp_get_firmware_version	(	int	specIndex,
		char *	value,
		int	len
	)

Get the firmware version of the microcontroller (FX2 or ARM).

Parameters

specIndex	(Input) which spectrometer
value	(Output) pre-allocated character array
len	(Input) allocated size (should be 16+)

Returns: WP_SUCCESS or non-zero on error

◆ wp_get_fpga_version()

int wp_get_fpga_version	(	int	specIndex,
		char *	value,
		int	len
	)

Get the version of the FPGA.

Parameters

specIndex	(Input) which spectrometer
value	(Output) pre-allocated character array
len	(Input) allocated size (should be 16+)

Returns: WP_SUCCESS or non-zero on error

◆ wp_get_high_gain_mode_enable()

int wp_get_high_gain_mode_enable ( int specIndex )

Reports whether "high-gain mode" is currently enabled on InGaAs detectors.

Parameters

specIndex (Input) which spectrometer

Returns: 1 if enabled, 0 if disabled, negative on error

◆ wp_get_integration_time_ms()

long wp_get_integration_time_ms ( int specIndex )

Get the curent integration time.

Parameters

specIndex (Input) which spectrometer

Returns: current integration time in ms (negative for error)

◆ wp_get_laser_enable()

int wp_get_laser_enable ( int specIndex )

Reports whether laser is currently enabled (firing, or configured to do so).

Parameters

specIndex (Input) which spectrometer

Returns: 1 if enabled, 0 if disabled, negative on error

◆ wp_get_library_version()

int wp_get_library_version	(	char *	value,
		int	len
	)

Obtains the version number of the WasatchVCPP library itself.

Parameters

value	(Output) pre-allocated string to receive the value
len	(Input) length of allocated buffer (16 recommended)

Returns: WP_SUCCESS or non-zero on error

◆ wp_get_max_timeout_ms()

int wp_get_max_timeout_ms ( int specIndex )

Get the maximum internal timeout when waiting on blocking USB operations.

See also: wp_set_max_timeout_ms

Parameters

specIndex (Input) which spectrometer

Returns: configured maximum timeout (ms)

◆ wp_get_model()

int wp_get_model	(	int	specIndex,
		char *	value,
		int	len
	)

Get the selected spectrometer's model.

Note: convenience function around eepromFields["model"]

Parameters

specIndex	(Input) which spectrometer
value	(Output) pre-allocated buffer of 'len' bytes (33 recommended)
len	(Input) allocated length of 'value'

Returns: WP_SUCCESS or non-zero on error

◆ wp_get_number_of_spectrometers()

int wp_get_number_of_spectrometers ( )

Returns number of spectrometers previously opened.

Assumes that wp_open_all_spectrometers has already been called. Does not open or re-open anything; no state is changed. (convenience function)

Returns: number of spectrometers

◆ wp_get_pixels()

int wp_get_pixels ( int specIndex )

Returns the number of pixels in the selected spectrometer.o.

This is critical for correctly sizing arrays sent to other functions like get_spectrum or get_wavelengths.

Note: convenience function around eepromFields["activePixelsHoriz"]

Parameters

specIndex (Input) which spectrometer

Returns: the number of pixels (negative on error)

◆ wp_get_serial_number()

int wp_get_serial_number	(	int	specIndex,
		char *	value,
		int	len
	)

Get the selected spectrometer's serial number.

Note: convenience function around eepromFields["serialNumber"]

Parameters

value	(Output) pre-allocated buffer of 'len' bytes (33 recommended)
len	(Input) allocated length of 'value'

Returns: WP_SUCCESS or non-zero on error

◆ wp_get_spectrum()

int wp_get_spectrum	(	int	specIndex,
		double *	spectrum,
		int	len
	)

Read one spectrum from the selected spectrometer.

This sends an "ACQUIRE" command, waits for "integration time" to pass, then performs a blocking read from the bulk endpoint.

Parameters

specIndex	(Input) which spectrometer
spectrum	(Output) pre-allocated buffer of 'len' doubles
len	(Input) allocated length of 'xAxis' (should match 'pixels')

Returns: WP_SUCCESS or non-zero on error

◆ wp_get_spectrum_float()

int wp_get_spectrum_float	(	int	specIndex,
		float *	spectrum,
		int	len
	)

Read one spectrum from the selected spectrometer as float.

This sends an "ACQUIRE" command, waits for "integration time" to pass, then performs a blocking read from the bulk endpoint.

Parameters

specIndex	(Input) which spectrometer
spectrum	(Output) pre-allocated buffer of 'len' floats
len	(Input) allocated length of 'xAxis' (should match 'pixels')

Returns: WP_SUCCESS or non-zero on error

◆ wp_get_wavelengths()

int wp_get_wavelengths	(	int	specIndex,
		double *	wavelengths,
		int	len
	)

Get the selected spectrometer's calibrated wavelength x-axis in nanometers.

Parameters

specIndex	(Input) which spectrometer
wavelengths	(Output) pre-allocated buffer of 'len' doubles
len	(Input) allocated length of 'wavelengths' (should match 'pixels')

Returns: WP_SUCCESS or non-zero on error

◆ wp_get_wavelengths_float()

int wp_get_wavelengths_float	(	int	specIndex,
		float *	wavelengths,
		int	len
	)

Get the selected spectrometer's calibrated wavelength x-axis in nanometers as float.

Parameters

specIndex	(Input) which spectrometer
wavelengths	(Output) pre-allocated buffer of 'len' floats
len	(Input) allocated length of 'wavelengths' (should match 'pixels')

Returns: WP_SUCCESS or non-zero on error

◆ wp_get_wavenumbers()

int wp_get_wavenumbers	(	int	specIndex,
		double *	wavenumbers,
		int	len
	)

Get the selected spectrometer's calibrated x-axis in wavenumbers (1/cm)

Parameters

specIndex	(Input) which spectrometer
wavenumbers	(Output) pre-allocated buffer of 'len' doubles
len	(Input) allocated length of 'wavenumbers' (should match 'pixels')

Returns: WP_SUCCESS or non-zero on error (e.g., no configured excitation)

◆ wp_get_wavenumbers_float()

int wp_get_wavenumbers_float	(	int	specIndex,
		float *	wavenumbers,
		int	len
	)

Get the selected spectrometer's calibrated x-axis in wavenumbers (1/cm) as float.

Parameters

specIndex	(Input) which spectrometer
wavenumbers	(Output) pre-allocated buffer of 'len' floats
len	(Input) allocated length of 'wavenumbers' (should match 'pixels')

Returns: WP_SUCCESS or non-zero on error (e.g., no configured excitation)

◆ wp_log_debug()

int wp_log_debug	(	const char *	msg,
		int	len
	)

Allows calling code (and wrappers) to inject lines into the library's log.

Parameters

msg	(Input) null-terminated C string
len	(Input) length of string

Returns: WP_SUCCESS or non-zero on error

◆ wp_open_all_spectrometers()

int wp_open_all_spectrometers ( )

Connects to and initializes all enumerated USB spectrometers.

This is normally the first function called against the library. It is normally called only once per application session.

It does quite a lot of work:

iterates over all connected USB busses
iterates over every USB device connected to those busses
finds any "valid Wasatch spectrometers" (supported VID and PID)
opens each spectrometer
"sets the configuration" and "claims the interface"
instantiates an internal WasatchVCPP::Spectrometer object
reads and parses the EEPROM
applies any post-load configuration

After calling this function, the driver is fully configured and ready to control all connected spectrometers.

Returns: The number of spectrometers found. Most other functions in this namespace take an integral "spectrometer index" parameter. That "specIndex" relates directly to this "spectrometer count", as each spectrometer is tracked in a zero-indexed vector. To be clear, if you call wp_open_all_spectrometers() and receive a value of 3, it means you can then call the other library functions with specIndex values from 0-2.

◆ wp_read_control_msg()

int wp_read_control_msg	(	int	specIndex,
		unsigned char	bRequest,
		unsigned int	wIndex,
		unsigned char *	data,
		int	len
	)

Provide direct access to reading spectrometer opcodes via USB setup packets (endpoint 0 control.

If a particular spectrometer feature documented in ENG-0001 is not yet suppoted by the library, or if you need to test an experimental / un- released feature against beta firmware, you can do so with this function.

Warning: It is possible to "brick" your spectrometer through careless use of this feature, potentially requiring RMA factory repair.
Consequences can include damaging components by exceeding temperature or power tolerances, and/or risk of human injury by misconfiguring the laser. Use of this function voids all factory warranties unless pre-approved through your sales representative.

Parameters

specIndex	(Input) which spectrometer
bRequest	(Input) control packet request (uint8_t)
wIndex	(Input) control packet wIndex (uint16_t)
data	(Output) pre-allocated buffer to hold response (uint8_t[])
len	(Input) number of bytes to read (data should be sized accordingly)

Returns: number of bytes read, negative on error

See also: https://www.beyondlogic.org/usbnutshell/usb6.shtml; https://www.wasatchphotonics.com/eng-0001/

◆ wp_send_control_msg()

int wp_send_control_msg	(	int	specIndex,
		unsigned char	bRequest,
		unsigned int	wValue,
		unsigned int	wIndex,
		unsigned char *	data,
		int	len
	)

Provide direct access to writing spectrometer opcodes via USB setup packets (endpoint 0 control.

If a particular spectrometer feature documented in ENG-0001 is not yet suppoted by the library, or if you need to test an experimental / un- released feature against beta firmware, you can do so with this function.

Warning: It is possible to "brick" your spectrometer through careless use of this feature, potentially requiring RMA factory repair.
Consequences can include damaging components by exceeding temperature or power tolerances, and/or risk of human injury by misconfiguring the laser. Use of this function voids all factory warranties unless pre-approved through your sales representative.

Parameters

specIndex	(Input) which spectrometer
bRequest	(Input) control packet request (uint8_t)
wValue	(Input) control packet wValue (uint16_t)
wIndex	(Input) control packet wIndex (uint16_t)
data	(Input) control packet payload (uint8_t[])
len	(Input) length of control packet payload

Returns: number of bytes written, negative on error

See also: https://www.beyondlogic.org/usbnutshell/usb6.shtml; https://www.wasatchphotonics.com/eng-0001/

◆ wp_set_detector_gain()

int wp_set_detector_gain	(	int	specIndex,
		float	value
	)

Set detector gain.

This should not be done casually by the user; detector gain is normally optimized for a given detector series, and rarely varies significantly from component to component. In the event that detector gain calibration is required, it is done at the factory, and the calibrated value is stored in the EEPROM ("detectorGain").

There is a lot which can be said about this attribute, which may be fleshed-out here at a later date. The internal data format is somewhat odd, essentially a signed bfloat16 (see WasatchNET documentation on FunkyFloat). For historical reasons, many spectrometers are tuned to a default gain of 1.9 (0x01e6). It is a valid question why the calibrated gain is stored on the spectrometer (in the EEPROM) yet needs to be applied from software over USB.

Warning: don't call this function unless you really know what you're doing; experimentation is unlikely to improve measurement quality

Parameters

specIndex	(Input) which spectrometer
value	(Input) desired gain (e.g. 1.9)

Returns: WP_SUCCESS or non-zero on error

◆ wp_set_detector_gain_odd()

int wp_set_detector_gain_odd	(	int	specIndex,
		float	value
	)

On InGaAs spectrometers, configures the gain for odd-numbered pixels.

Even vs Odd Pixels

Hamamatsu InGaAs detectors use two interleaved arrays of photodiodes, where one array controls even-numbered pixels and the other array controls the odd-numbered. This means that with regard to gain and noise characteristics, all even pixels are electrically related, and all odd pixels are electrically related, but the two sets may behave differently from one another. Therefore, NIR spectrometers support independent gain and offset calibration for the two pixels sets.

See also: wp_set_detector_gain for information about detector gain itself

Parameters

specIndex	(Input) which spectrometer
value	(Input) desired gain (positive or negative)

Returns: WP_SUCCESS or non-zero on error (such as use with silicon detectors)

◆ wp_set_detector_offset()

int wp_set_detector_offset	(	int	specIndex,
		int	value
	)

Set detector offset.

See also: set_detector_offset for discussion on detector offset; set_detector_gain_odd for discussion on even-vs-odd pixels

Parameters

specIndex	(Input) which spectrometer
value	(Input) desired offset (positive or negative)

Returns: WP_SUCCESS or non-zero on error (e.g. silicon detector)

◆ wp_set_detector_offset_odd()

int wp_set_detector_offset_odd	(	int	specIndex,
		int	value
	)

On InGaAs spectrometers, configures the offset for odd-numbered pixels.

See also: set_detector_offset for discussion on detector offset; set_detector_gain_odd for discussion on even-vs-odd pixels

Parameters

specIndex	(Input) which spectrometer
value	(Input) desired offset (positive or negative)

Returns: WP_SUCCESS or non-zero on error (e.g. silicon detector)

◆ wp_set_detector_tec_enable()

int wp_set_detector_tec_enable	(	int	specIndex,
		int	value
	)

Turn the detector TEC on or off.

Note: if TEC setpoint has not yet been set, will automatically set to EEPROM configured minimum

Parameters

specIndex	(Input) which spectrometer
value	(Input) zero for off, non-zero for on

Returns: WP_SUCCESS or non-zero on error (e.g. uncooled spectrometer)

◆ wp_set_detector_tec_setpoint_deg_c()

int wp_set_detector_tec_setpoint_deg_c	(	int	specIndex,
		int	value
	)

Set the detector TEC setpoint.

Parameters

specIndex	(Input) which spectrometer
value	(Input) desired temperature in degrees Celsius

Returns: WP_SUCCESS or non-zero on error (e.g. uncooled spectrometer)

◆ wp_set_high_gain_mode_enable()

int wp_set_high_gain_mode_enable	(	int	specIndex,
		int	value
	)

Enable or disable "high gain" mode on InGaAs detectors.

Note: this is enabled by default on suitable detectors

Parameters

specIndex	(Input) which spectrometer
value	(Input) zero to disable, non-zero to enable

Returns: WP_SUCCESS or non-zero on error (e.g. silicon detector)

◆ wp_set_integration_time_ms()

int wp_set_integration_time_ms	(	int	specIndex,
		unsigned long	ms
	)

Set the spectrometer's integration time in milliseconds.

Parameters

specIndex (Input) which spectrometer

Returns: WP_SUCCESS or non-zero on error

◆ wp_set_laser_enable()

int wp_set_laser_enable	(	int	specIndex,
		int	value
	)

Turns the laser on or off.

Parameters

specIndex	(Input) which spectrometer
value	(Input) whether laser should be off (zero) or on (non-zero)

Returns: WP_SUCCESS or non-zero on error

◆ wp_set_laser_power_mW()

int wp_set_laser_power_mW	(	int	specIndex,
		float	power
	)

Sets laser power as a mW value.

Parameters

power (Input) mW power to set laser

Returns: WP_SUCCESS or non-zero on error

◆ wp_set_laser_power_perc()

int wp_set_laser_power_perc	(	int	specIndex,
		float	percent
	)

Sets laser power as a percentage of max power.

Parameters

percent (Input) percent of max power

Returns: WP_SUCCESS or non-zero on error

◆ wp_set_log_level()

int wp_set_log_level ( int level )

Sets driver log level.

Parameters

level (Input) one of the WP_LOG_LEVEL macros

Returns: WP_SUCCESS or non-zero on error

◆ wp_set_logfile_path()

int wp_set_logfile_path	(	const char *	pathname,
		int	len
	)

Sets a pathname for WasatchVCPP to write a debug logfile.

Parameters

pathname	(Input) a valid pathname (need not exist, will be overwritten if found)
len	(Input) length of pathname

Returns: WP_SUCCESS or non-zero on error

◆ wp_set_max_timeout_ms()

int wp_set_max_timeout_ms	(	int	specIndex,
		int	maxTimeoutMS
	)

Configure the maximum internal timeout when waiting on blocking USB operations.

Note this value can be less than integration time. If a configured integration time is longer than the maximum timeout, then the "wait" on the requested spectrum will be performed through a series of individual reads, each no longer than the configured maximum timeout.

That is, if maxTimeoutMS is 1000, and a 5sec integration is requested, The library will loop through five 1sec blocking reads before the spectrum is expected to return. (The library will internally wait even longer than that, to account for USB latency and other timing delays, but no individual blocking read will wait longer than the configured maximum.)

This value also represents the longest that wp_cancel_operation(true) should block.

This function essentially configures the maximum window before a call to wp_cancel_operation will be expected to take effect.

See also: wp_cancel_operation

Parameters

specIndex	(Input) which spectrometer
maxTimeoutMS	(Input) maximum timeout in milliseconds (default 1000; probably should not be < 200)

Returns: WP_SUCCESS or non-zero on error

Functions

Variables

Detailed Description

Function Documentation

◆ exportString()

◆ wp_cancel_operation()

◆ wp_close_all_spectrometers()

◆ wp_close_spectrometer()

◆ wp_destroy_driver()

◆ wp_get_detector_gain()

◆ wp_get_detector_gain_odd()

◆ wp_get_detector_offset()

◆ wp_get_detector_offset_odd()

◆ wp_get_detector_tec_enable()

◆ wp_get_detector_tec_setpoint_deg_c()

◆ wp_get_detector_temperature_deg_c()

◆ wp_get_eeprom()

◆ wp_get_eeprom_field()

◆ wp_get_eeprom_field_count()

◆ wp_get_eeprom_field_name()

◆ wp_get_firmware_version()

◆ wp_get_fpga_version()

◆ wp_get_high_gain_mode_enable()

◆ wp_get_integration_time_ms()

◆ wp_get_laser_enable()

◆ wp_get_library_version()

◆ wp_get_max_timeout_ms()

◆ wp_get_model()

◆ wp_get_number_of_spectrometers()

◆ wp_get_pixels()

◆ wp_get_serial_number()

◆ wp_get_spectrum()

◆ wp_get_spectrum_float()

◆ wp_get_wavelengths()

◆ wp_get_wavelengths_float()

◆ wp_get_wavenumbers()

◆ wp_get_wavenumbers_float()

◆ wp_log_debug()

◆ wp_open_all_spectrometers()

◆ wp_read_control_msg()

◆ wp_send_control_msg()

◆ wp_set_detector_gain()

◆ wp_set_detector_gain_odd()

◆ wp_set_detector_offset()

◆ wp_set_detector_offset_odd()

◆ wp_set_detector_tec_enable()

◆ wp_set_detector_tec_setpoint_deg_c()

◆ wp_set_high_gain_mode_enable()

◆ wp_set_integration_time_ms()

◆ wp_set_laser_enable()

◆ wp_set_laser_power_mW()

◆ wp_set_laser_power_perc()

◆ wp_set_log_level()

◆ wp_set_logfile_path()

◆ wp_set_max_timeout_ms()