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

#include <vector>
#include <string>
#include <map>

Classes
class	WasatchVCPP::Proxy::Spectrometer
	A proxy customer-facing class providing an object-oriented / STL-based interface to command and control an individual Spectrometer. More...

class	WasatchVCPP::Proxy::Driver
	A proxy customer-facing class providing an object-oriented / STL-based interface to command and control the WasatchVCPP library. More...

Namespaces
namespace	WasatchVCPP
	Namespace encapsulating the internal implementation of WasatchVCPP; customers would not normally access these classes or objects directly.

namespace	WasatchVCPP::Proxy
	provides object-oriented Driver and Spectrometer C++ classes on the client (caller) side

Macros
#define	DLL_API

#define	WP_SUCCESS 0
	the function completed successfully

#define	WP_ERROR -1
	other unspecified error

#define	WP_ERROR_INVALID_SPECTROMETER -2
	specIndex referenced an invalid / unopen spectrometer

#define	WP_ERROR_INSUFFICIENT_STORAGE -3
	insufficient storage was allocated to receive the full value

#define	WP_ERROR_NO_LASER -4
	command is only valid on models with a laser and/or defined excitation wavelength

#define	WP_ERROR_NOT_INGAAS -5
	command is only valid on models with an InGaAs detector

#define	WP_ERROR_INVALID_GAIN -256
	detector gain could not be determined (impossible value)

#define	WP_ERROR_INVALID_TEMPERATURE -999
	temperature could not be measured (impossible value)

#define	WP_ERROR_INVALID_OFFSET -32768
	offset could not be determined (unreasonable value)

#define	WP_LOG_LEVEL_DEBUG 0

#define	WP_LOG_LEVEL_INFO 1

#define	WP_LOG_LEVEL_ERROR 2

#define	WP_LOG_LEVEL_NEVER 3

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

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

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

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

DLL_API int	wp_get_vignetted_spectrum_length (int specIndex)

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

DLL_API int	wp_has_srm_calibration (int specIndex)

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

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

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

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

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

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

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

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

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

DLL_API int	wp_get_eeprom_page (int specIndex, int page, unsigned char *buf, int len)
	Read one page of the EEPROM in raw binary form. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Detailed Description

Declaration 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: Users can copy and import this file into their own Visual C++ solutions (optionally with WasatchVCPPProxy.h/cpp as well)

It uses legacy C native types (no STL templates or C++ language features) to avoid ABI problems when calling the DLL from code which was compiled in a different compiler (even a different version of Visual Studio).

Calling code can use these functions directly, or they can use the higher-level WasatchVCPP::Proxy classes defined in WasatchVCPPProxy.h/cpp.

Although the majority of WasatchVCPP is written in C++ and uses a variety of internal classes, those classes and objects cannot be accessed through the DLL ABI barrier. This file is the only part of the DLL that customers can actually "see" and "talk to."

This file is still under development; many spectrometer functions have not yet been added.

See also: README_BACKLOG.md for implementation status.

Function Documentation

◆ wp_cancel_operation()

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

DLL_API int wp_close_all_spectrometers ( )

Closes all connected spectrometers.

Returns: WP_SUCCESS or non-zero on error

◆ wp_close_spectrometer()

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

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

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

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

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

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

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

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

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

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

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

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

DLL_API 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_eeprom_page()

DLL_API int wp_get_eeprom_page	(	int	specIndex,
		int	page,
		unsigned char *	buf,
		int	len
	)

Read one page of the EEPROM in raw binary form.

Parameters

specIndex	(Input) which spectrometer
page	(Input) which page (0-7)
buf	(Output) pre-allocated array of bytes to hold the page
len	(Input) size of allocated buffer (should be 64)

Returns: WP_SUCCESS or non-zero on error

See also: ENG-0034

◆ wp_get_firmware_version()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DLL_API 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

Classes

Namespaces

Macros

Functions

Detailed Description

Function Documentation

◆ 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_eeprom_page()

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