Calling the NIR SDK from Python on Windows: Guide and Example

Overview

This article describes how to read wavelength and intensity data from a NIR spectrometer or module using Python via the SDK dynamic library on 64-bit Windows. The SDK is a C-language wrapper, and Python can call it directly through the standard ctypes library with no third-party packages required. This solution targets DLP-type NIR spectroscopy modules (900-1700nm) and provides full-band data for 228 pixels.

1. Basic Function Introduction

The SDK exposes six essential functions, which are sufficient for the vast majority of application scenarios.

1.1 Open Device via USB

int dlpOpenByUsb(int index);
  • Parameter index: device index of the connected spectrometer, starting from 0. If only one device is connected, set it to 0.
  • Return: 0 on success, <0 on failure.

1.2 Close USB Interface

void dlpClose();
  • Closes the device connection; takes no parameters and returns no value.

1.3 Read Wavelengths

int dlpGetWavelengths(double *wls, int length);
  • Parameter wls: wavelength pointer, a double array with a length not exceeding 228.
  • Parameter length: data length; 228 (full-band data points) is recommended.
  • Return: 0 on success, <0 on failure.

1.4 Read Intensity Values

int dlpGetIntensities(int activeIndex, int *intensities, int length);
  • Parameter activeIndex: active configuration index; for new devices the default column configuration (index 0) is recommended.
  • Parameter intensities: intensity pointer, an int array of length 228.
  • Parameter length: data length; 228 is recommended.
  • Return: 0 on success, <0 on failure.

1.5 Control the Lamp

int dlpSetLampOn(int status);
  • Parameter status: 1 turns the lamp on (reflection type only), 0 turns it off.
  • Return: 0 on success, <0 on failure.

1.6 Set the PGA Gain

int dlpSetPgaGain(int pga);
  • Parameter pga: gain multiplier; only 1, 2, 4, 8, 16, 32 and 64 are supported. When the signal is not saturated, 64 is recommended; reduce it as needed when saturated.
  • Note: The default value is 64. Setting other values may cause compatibility issues; keeping 64 is recommended.

2. Complete Example Code

The following code shows the full workflow from connecting to the device through reading and printing wavelength and intensity data:

import ctypes

# ==================== Basic functions ====================

# Load the shared library
libwrapper = ctypes.CDLL("lib/libwrapper.dll")

# Define function prototypes
libwrapper.dlpOpenByUsb.argtypes = [ctypes.c_int]
libwrapper.dlpOpenByUsb.restype = ctypes.c_int

libwrapper.dlpGetWavelengths.argtypes = [ctypes.POINTER(ctypes.c_double), ctypes.c_int]
libwrapper.dlpGetWavelengths.restype = ctypes.c_int

libwrapper.dlpGetIntensities.argtypes = [ctypes.c_int, ctypes.POINTER(ctypes.c_int),
                                         ctypes.c_int]
libwrapper.dlpGetIntensities.restype = ctypes.c_int

libwrapper.dlpSetLampOn.argtypes = [ctypes.c_int]
libwrapper.dlpSetLampOn.restype = ctypes.c_int

libwrapper.dlpSetPgaGain.argtypes = [ctypes.c_int]
libwrapper.dlpSetPgaGain.restype = ctypes.c_int

# Wrap as Python functions
def dlpOpenByUsb(index):
    return libwrapper.dlpOpenByUsb(index)

def dlpClose():
    return libwrapper.dlpClose()

def dlpGetWavelengths(wls, wlsNum):
    return libwrapper.dlpGetWavelengths(wls, wlsNum)

def dlpGetIntensities(activeIndex, intensities, wlsNum):
    return libwrapper.dlpGetIntensities(activeIndex, intensities, wlsNum)

def dlpSetLampOn(index):
    return libwrapper.dlpSetLampOn(index)

def dlpSetPgaGain(index):
    return libwrapper.dlpSetPgaGain(index)

# ==================== Usage example ====================

PIXEL_NUM = 228  # The 900-1700nm module has 228 data points

# Open the device
index = 0
result = dlpOpenByUsb(index)
if result >= 0:
    print("HID USB opened successfully!
")
else:
    print("HID USB open failed!
")

# Turn on the lamp
dlpSetLampOn(1)

# Set the PGA gain
dlpSetPgaGain(64)

# Read wavelengths
wls_buf = (ctypes.c_double * PIXEL_NUM)()
print("Print the first 5 wavelengths:
")
result = dlpGetWavelengths(wls_buf, PIXEL_NUM)
if result >= 0:
    for i in range(5):
        print(f"{wls_buf[i]:.2f}")

# Read intensity values
intensities_buf = (ctypes.c_int * PIXEL_NUM)()
activeIndex = 0
print("
Print the first 5 wavelengths and their intensities:
")
result = dlpGetIntensities(activeIndex, intensities_buf, PIXEL_NUM)
if result >= 0:
    for i in range(5):
        print(f"{wls_buf[i]:.2f}: {intensities_buf[i]}")

# Turn off the lamp
dlpSetLampOn(0)

Code Walkthrough

  1. Load the dynamic library: load libwrapper.dll with ctypes.CDLL().
  2. Define function prototypes: explicitly declare parameter and return types with argtypes and restype.
  3. Create C-type buffers: (ctypes.c_double * PIXEL_NUM)() allocates memory compatible with a C array.
  4. Call SDK functions: run in order open device → control lamp → set gain → read wavelengths → read intensities.

3. FAQ

3.1 dlpSetPgaGain has no effect when set to a value other than 64

Initial testing found that when the gain is set to a value other than 64, the actual gain does not change. Keeping the default value of 64 is recommended; if the signal is saturated, adjust it by reducing the integration time or by blocking/attenuating the light path.

3.2 Device connection failure

  • Check whether the USB cable is intact.
  • Confirm the device is powered on and ready.
  • Open Device Manager to see whether the HID device is recognized.

This article was compiled by Pynect.