Spectrometer library  2.1
Simplified version of the thread-safe core
libspectr API

Functions

LIBSHARED_AND_STATIC_EXPORT int disconnectDeviceContext (uintptr_t *deviceContextPtr)
 Free a device handle. More...
 
LIBSHARED_AND_STATIC_EXPORT int connectToDeviceBySerial (const char *const serialNumber, uintptr_t *deviceContextPtr)
 Finds the requested device by the provided serial number and connects to it. This function or its analog connectToDeviceByIndex() should always precede all other library operations. More...
 
LIBSHARED_AND_STATIC_EXPORT int connectToDeviceByIndex (unsigned int index, uintptr_t *deviceContextPtr)
 Connects to the required device by index. More...
 
LIBSHARED_AND_STATIC_EXPORT int setFrameFormat (uint16_t numOfStartElement, uint16_t numOfEndElement, uint8_t reductionMode, uint16_t *numOfPixelsInFrame, uintptr_t *deviceContextPtr)
 Sets frame parameters. More...
 
LIBSHARED_AND_STATIC_EXPORT int setExposure (uint32_t timeOfExposure, uint8_t force, uintptr_t *deviceContextPtr)
 Sets exposure parameter. More...
 
LIBSHARED_AND_STATIC_EXPORT int setAcquisitionParameters (uint16_t numOfScans, uint16_t numOfBlankScans, uint8_t scanMode, uint32_t timeOfExposure, uintptr_t *deviceContextPtr)
 Sets acquisition parameters. More...
 
LIBSHARED_AND_STATIC_EXPORT int setMultipleParameters (uint16_t numOfScans, uint16_t numOfBlankScans, uint8_t scanMode, uint32_t timeOfExposure, uint8_t enableMode, uint8_t signalFrontMode, uintptr_t *deviceContextPtr)
 Sets multiple parameters - combination of setAcquisitionParameters() and setExternalTrigger() functions Clears memory and sets the required parameters (the parameters for the setAcquisitionParameters() and setExternalTrigger() functions). If enableMode = 0 or signalFrontMode = 0 (external trigger disabled) this function also triggers the acquisition. More...
 
LIBSHARED_AND_STATIC_EXPORT int setExternalTrigger (uint8_t enableMode, uint8_t signalFrontMode, uintptr_t *deviceContextPtr)
 Sets the external acquisition trigger. More...
 
LIBSHARED_AND_STATIC_EXPORT int setOpticalTrigger (uint8_t enableMode, uint16_t pixel, uint16_t threshold, uintptr_t *deviceContextPtr)
 Sets the optical atrigger. More...
 
LIBSHARED_AND_STATIC_EXPORT int triggerAcquisition (uintptr_t *deviceContextPtr)
 Start acquisition by software. More...
 
LIBSHARED_AND_STATIC_EXPORT int getStatus (uint8_t *statusFlags, uint16_t *framesInMemory, uintptr_t *deviceContextPtr)
 Gets the device status. More...
 
LIBSHARED_AND_STATIC_EXPORT int getAcquisitionParameters (uint16_t *numOfScans, uint16_t *numOfBlankScans, uint8_t *scanMode, uint32_t *timeOfExposure, uintptr_t *deviceContextPtr)
 Returns the same values as set by setAcquisitionParameters() More...
 
LIBSHARED_AND_STATIC_EXPORT int getFrameFormat (uint16_t *numOfStartElement, uint16_t *numOfEndElement, uint8_t *reductionMode, uint16_t *numOfPixelsInFrame, uintptr_t *deviceContextPtr)
 Returns the same values as set by setFrameFormat() More...
 
LIBSHARED_AND_STATIC_EXPORT int getFrame (uint16_t *framePixelsBuffer, uint16_t numOfFrame, uintptr_t *deviceContextPtr)
 Gets frame. More...
 
LIBSHARED_AND_STATIC_EXPORT int clearMemory (uintptr_t *deviceContextPtr)
 Clears memory. More...
 
LIBSHARED_AND_STATIC_EXPORT int eraseFlash (uintptr_t *deviceContextPtr)
 Erases user flash memory. More...
 
LIBSHARED_AND_STATIC_EXPORT int readFlash (uint8_t *buffer, uint32_t absoluteOffset, uint32_t bytesToRead, uintptr_t *deviceContextPtr)
 Reads from user flash memory Reads bytesToRead from user flash memory starting at offset and copies them to the buffer. More...
 
LIBSHARED_AND_STATIC_EXPORT int writeFlash (uint8_t *buffer, uint32_t absoluteOffset, uint32_t bytesToWrite, uintptr_t *deviceContextPtr)
 Writes bytesToWrite bytes from the buffer to the user flash memory starting at offset. More...
 
LIBSHARED_AND_STATIC_EXPORT int resetDevice (uintptr_t *deviceContextPtr)
 Resets all the device parameters to their default values and clears the memory. More...
 
LIBSHARED_AND_STATIC_EXPORT int detachDevice (uintptr_t *deviceContextPtr)
 Disconnects the device. More...
 

Detailed Description

Function Documentation

§ clearMemory()

LIBSHARED_AND_STATIC_EXPORT int clearMemory ( uintptr_t *  deviceContextPtr)

Clears memory.

Parameters
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ connectToDeviceByIndex()

LIBSHARED_AND_STATIC_EXPORT int connectToDeviceByIndex ( unsigned int  index,
uintptr_t *  deviceContextPtr 
)

Connects to the required device by index.

This function or connectToDeviceBySerial() should always precede all other library operations.

Parameters
[in]indexThe value of the index parameter can vary from 0 to n-1 (where n is the number of the connected devices) If only one device is connected use 0 as the index parameter.
Parameters
[out]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable. The handle inside will be initialized with device state information required for all the other functions. Set the uintptr_t variable to 0 before calling this function for the first time to start working with a device. If the requested device is already connected (dereferenced pointer value does not equal 0), disconnects the device and reinitializes the handle with a new device state.
Returns
This function returns 0 on success and error code in case of error.

§ connectToDeviceBySerial()

LIBSHARED_AND_STATIC_EXPORT int connectToDeviceBySerial ( const char *const  serialNumber,
uintptr_t *  deviceContextPtr 
)

Finds the requested device by the provided serial number and connects to it. This function or its analog connectToDeviceByIndex() should always precede all other library operations.

Parameters
[in]serialNumberIf the serialNumber pointer is NULL, the function will connect to a first found device with VID = 0xE220 and PID = 0x0100
Parameters
[out]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable. The handle inside will be initialized with device state information required for all the other functions. Set the uintptr_t variable to 0 before calling this function for the first time to start working with a device. If the requested device is already connected (dereferenced pointer value does not equal 0), disconnects the device and reinitializes the handle with a new device state.
Returns
This function returns 0 on success and error code in case of error.

§ detachDevice()

LIBSHARED_AND_STATIC_EXPORT int detachDevice ( uintptr_t *  deviceContextPtr)

Disconnects the device.

The device will be disconnected from USB, and any interaction with it will not be possible until the device is reset

Parameters
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ disconnectDeviceContext()

LIBSHARED_AND_STATIC_EXPORT int disconnectDeviceContext ( uintptr_t *  deviceContextPtr)

Free a device handle.

This function frees a device handle initialized by connectToDeviceBySerial() or connectToDeviceByIndex()

Parameters
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (containing a handle previously initialized by connectToDeviceBySerial() or connectToDeviceByIndex())
Returns
This function returns 0 on success and error code in case of error.

§ eraseFlash()

LIBSHARED_AND_STATIC_EXPORT int eraseFlash ( uintptr_t *  deviceContextPtr)

Erases user flash memory.

Note
There is no way to partially erase it.
Parameters
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ getAcquisitionParameters()

LIBSHARED_AND_STATIC_EXPORT int getAcquisitionParameters ( uint16_t *  numOfScans,
uint16_t *  numOfBlankScans,
uint8_t *  scanMode,
uint32_t *  timeOfExposure,
uintptr_t *  deviceContextPtr 
)

Returns the same values as set by setAcquisitionParameters()

Parameters
[out]numOfScans- provide an initialized pointer or NULL to skip this parameter fetch
[out]numOfBlankScans- provide an initialized pointer or NULL to skip this parameter fetch
[out]scanMode- provide an initialized pointer or NULL to skip this parameter fetch
[out]timeOfExposure- provide an initialized pointer or NULL to skip this parameter fetch
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ getFrame()

LIBSHARED_AND_STATIC_EXPORT int getFrame ( uint16_t *  framePixelsBuffer,
uint16_t  numOfFrame,
uintptr_t *  deviceContextPtr 
)

Gets frame.

Parameters
[out]framePixelsBuffer- provide an initialized pointer to the buffer of unsigned short elements.
[in]numOfFramenumOfFrame - first frame in memory is number 0, second is 1, etc numOfFrame = 0xFFFF - calculate averaged spectra (for averaging mode), for all other modes function will return last captured frame
Parameters
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ getFrameFormat()

LIBSHARED_AND_STATIC_EXPORT int getFrameFormat ( uint16_t *  numOfStartElement,
uint16_t *  numOfEndElement,
uint8_t *  reductionMode,
uint16_t *  numOfPixelsInFrame,
uintptr_t *  deviceContextPtr 
)

Returns the same values as set by setFrameFormat()

Parameters
[out]numOfStartElement
[out]numOfEndElement
[out]reductionMode
[out]numOfPixelsInFrame
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ getStatus()

LIBSHARED_AND_STATIC_EXPORT int getStatus ( uint8_t *  statusFlags,
uint16_t *  framesInMemory,
uintptr_t *  deviceContextPtr 
)

Gets the device status.

Parameters
[out]statusFlags- provide an initialized pointer or NULL to skip this parameter fetch
[out]framesInMemory- provide an initialized pointer or NULL to skip this parameter fetch
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ readFlash()

LIBSHARED_AND_STATIC_EXPORT int readFlash ( uint8_t *  buffer,
uint32_t  absoluteOffset,
uint32_t  bytesToRead,
uintptr_t *  deviceContextPtr 
)

Reads from user flash memory Reads bytesToRead from user flash memory starting at offset and copies them to the buffer.

Parameters
[out]buffer- provide an initialized pointer to the buffer of unsigned char elements.
[in]absoluteOffsetAny value from 0 to 1FFFF* you can read only 1 byte from 1FFFF, 2 bytes from 1FFFE etc.
[in]bytesToRead
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ resetDevice()

LIBSHARED_AND_STATIC_EXPORT int resetDevice ( uintptr_t *  deviceContextPtr)

Resets all the device parameters to their default values and clears the memory.

Parameters
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Note
default parameters: numOfStartElement = 0 numOfEndElement = 3647 reductionMode = 0 numOfScans = 1 numOfBlankScans = 0 scanMode = 0 exposureTime = 10
Returns
This function returns 0 on success and error code in case of error.

§ setAcquisitionParameters()

LIBSHARED_AND_STATIC_EXPORT int setAcquisitionParameters ( uint16_t  numOfScans,
uint16_t  numOfBlankScans,
uint8_t  scanMode,
uint32_t  timeOfExposure,
uintptr_t *  deviceContextPtr 
)

Sets acquisition parameters.

Note
current acquisition will be stopped by calling this function
Parameters
[in]numOfScans- up to 137 full spectra
[in]numOfBlankScans- check the description of the scanMode parameter below
[in]scanMode

0 - continuous scanMode

CCD is read continuously. On trigger numOfScans frames will be stored in memory, with numOfBlankScans blank frames between them.

1 - first frame idle scan mode

no activity on CCD before trigger. On trigger numOfScans frames with numOfBlankScans blank frames between them will be read automaticly, then CCD enters idle mode until the next trigger.

2 - every frame idle scan mode

no activity on CCD before trigger. Every frame, including blank frames will be read only on trigger.

3 - frame averaging mode. CCD is read continuously. Every numOfScans frames are averaged, result can be loaded with getFrame(0xFFFF) function. numOfBlankScans in this mode does not make sense and has to be set to 0

[in]timeOfExposuremultiple of 10 us (microseconds)
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ setExposure()

LIBSHARED_AND_STATIC_EXPORT int setExposure ( uint32_t  timeOfExposure,
uint8_t  force,
uintptr_t *  deviceContextPtr 
)

Sets exposure parameter.

Can be called in the middle of acquisition, exposure will be applied on the next frame

Parameters
[in]timeOfExposure= multiple of 10 us (microseconds)
[in]force- set force
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ setExternalTrigger()

LIBSHARED_AND_STATIC_EXPORT int setExternalTrigger ( uint8_t  enableMode,
uint8_t  signalFrontMode,
uintptr_t *  deviceContextPtr 
)

Sets the external acquisition trigger.

Parameters
[in]enableModeenableMode: 0 - trigger disabled 1 - trigger enabled 2 - one time trigger
[in]signalFrontModetriggerFront: 0 - trigger disabled 1 - front rising 2 - front falling 3 - both rising and fall
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ setFrameFormat()

LIBSHARED_AND_STATIC_EXPORT int setFrameFormat ( uint16_t  numOfStartElement,
uint16_t  numOfEndElement,
uint8_t  reductionMode,
uint16_t *  numOfPixelsInFrame,
uintptr_t *  deviceContextPtr 
)

Sets frame parameters.

Note
this function clears the memory and stops the current acquisition
Parameters
[in]numOfStartElement

Minimum value is 0 Maximum value is 3647

if numOfStartElement == numOfEndElement, a frame will contain (32 starting elements) + (1 user element) + (14 final elements).

Parameters
[in]numOfEndElement

Minimum value is 0 Maximum value is 3647

if numOfStartElement == numOfEndElement, a frame will contain (32 starting elements) + (1 user element) + (14 final elements).

Parameters
[in]reductionModereductionMode defines the mode of pixels averaging 0 - no average 1 - average of 2 2 - average of 4 3 - average of 8
Parameters
[out]numOfPixelsInFrameThe numOfPixelsInFrame parameter is used to return the frame size in pixels. Frame size in bytes = (2 * numOfPixelsInFrame) Use NULL to exclude this parameter.
Parameters
[out]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ setMultipleParameters()

LIBSHARED_AND_STATIC_EXPORT int setMultipleParameters ( uint16_t  numOfScans,
uint16_t  numOfBlankScans,
uint8_t  scanMode,
uint32_t  timeOfExposure,
uint8_t  enableMode,
uint8_t  signalFrontMode,
uintptr_t *  deviceContextPtr 
)

Sets multiple parameters - combination of setAcquisitionParameters() and setExternalTrigger() functions Clears memory and sets the required parameters (the parameters for the setAcquisitionParameters() and setExternalTrigger() functions). If enableMode = 0 or signalFrontMode = 0 (external trigger disabled) this function also triggers the acquisition.

Parameters
[in]numOfScans- up to 137 full spectra
[in]numOfBlankScans- check the description of the scanMode parameter below
[in]scanMode

0 - continuous scanMode

CCD is read continuously. On trigger numOfScans frames will be stored in memory, with numOfBlankScans blank frames between them.

1 - first frame idle scan mode

no activity on CCD before trigger. On trigger numOfScans frames with numOfBlankScans blank frames between them will be read automaticly, then CCD enters idle mode until the next trigger.

2 - every frame idle scan mode

no activity on CCD before trigger. Every frame, including blank frames will be read only on trigger.

3 - frame averaging mode. CCD is read continuously. Every numOfScans frames are averaged, result can be loaded with getFrame(0xFFFF) function. numOfBlankScans in this mode does not make sense and has to be set to 0

[in]timeOfExposuremultiple of 10 us (microseconds)
[in]enableModeenableMode: 0 - trigger disabled 1 - trigger enabled 2 - one time trigger
[in]signalFrontModetriggerFront: 0 - trigger disabled 1 - front rising 2 - front falling 3 - both rising and fall
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ setOpticalTrigger()

LIBSHARED_AND_STATIC_EXPORT int setOpticalTrigger ( uint8_t  enableMode,
uint16_t  pixel,
uint16_t  threshold,
uintptr_t *  deviceContextPtr 
)

Sets the optical atrigger.

Note
Only applicable in scanMode = 0 (check the acquisition parameters)
Parameters
[in]enableModeenableMode = 0 trigger disabled enableMode = 1 trigger for falling edge enableMode = 2 trigger on threshold enableMode = 0x81 one time trigget for rising edge enableMode = 0x82 one time trigger for falling edge
[in]pixelPixel number (for 0 to 3639 range) for with exiding level should be detected (for optical trigger only). Does not depend on frame format.
[in]threshold
[out]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ triggerAcquisition()

LIBSHARED_AND_STATIC_EXPORT int triggerAcquisition ( uintptr_t *  deviceContextPtr)

Start acquisition by software.

Parameters
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.

§ writeFlash()

LIBSHARED_AND_STATIC_EXPORT int writeFlash ( uint8_t *  buffer,
uint32_t  absoluteOffset,
uint32_t  bytesToWrite,
uintptr_t *  deviceContextPtr 
)

Writes bytesToWrite bytes from the buffer to the user flash memory starting at offset.

Parameters
[out]buffer
[in]absoluteOffset

offset can be any value from 0 to 1FFFF* you can write only 1 byte to 1FFFF, 2 bytes to 1FFFE etc.

you can write only to empty memory locations that have values = 0xff. The only way to get their state back to empty is erasing all user memory by eraseFlash(). There is no way to partially erase it. 128kb available

[in]bytesToWrite
[in]deviceContextPtrThis pointer should not be NULL - provide the address of a valid uintptr_t variable (The uintptr_t variable contains the device state information handle and should be previously initialized by either connectToDeviceBySerial() or connectToDeviceByIndex() function)
Returns
This function returns 0 on success and error code in case of error.