C API¶

This section documents C functions exported by the BenHW DLL.

The C API provides direct access to the BenHW hardware control library. The functions definitions are available in benhw.h header file which can be included in C/C++ applications.

`BI_close`¶

DLL versions 4.4.13 and above

Close and clean up the system model.

error_int BI_close();

Description¶

Frees the system model and releases all resources. Call this before exiting your application. This function instructs the DLL to destroy the system model and prepare for unloading.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_automeasure`¶

DLL versions 4.4.13 and above

Perform an automatic measurement with autoranging.

error_int BI_automeasure(
    double* reading);

Description¶

Takes a measurement with automatic gain ranging. The detector will automatically adjust its range to get the best reading. Takes the Analogue-digital Converter (ADC) offset and dark current (previously obtained by zero_calibration) into account. Negative values are clamped to zero unless AllowNegative is set.

Parameters¶

reading (double*) Measurement reading value or array

Returns¶

Error codes¶

This function can return the following error codes:

BI_ADC_Overload == 22: Analogue-digital Converter (ADC) overload detected - the input signal is too strong for the current range setting.
BI_ADC_read_error == 20: Analogue-digital Converter (ADC) is not responding or failed to complete a read operation.
BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_autorange`¶

DLL versions 4.4.13 and above

Automatically adjust the detector range.

error_int BI_autorange();

Description¶

Adjusts the amplifier gain range to optimize the signal for measurement. Should be called before taking measurements if the signal level has changed significantly. This auto-ranges the amplifier(s) in the active group.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_build_group`¶

DLL versions 4.4.13 and above

Create a new component group.

int BI_build_group();

Description¶

Creates a new, empty group for organizing components. Groups allow multiple components to be controlled together. The DLL allows up to 10 component groups. Returns the group number if successful.

Returns¶

int (group_number): The newly created group number

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_build_system_model`¶

DLL versions 4.4.13 and above

Load and compile a system configuration file.

error_int BI_build_system_model(
    char* config_file,
    char* error);

Description¶

Parses the configuration file and builds the system model representing your hardware setup. This must be called before any other operations. If an error occurs, the error message is written to the error buffer. This function must succeed before any other DLL function is called.

Parameters¶

config_file (char*) Path to the system configuration file
error (char*) Buffer to receive error message text

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_close_shutter`¶

DLL versions 4.4.13 and above

Close the monochromator shutter.

error_int BI_close_shutter();

Description¶

Closes the shutter on the current monochromator to block light. Useful for taking dark measurements. This function sends the filter wheel in the monochromator of the active group to its shutter position.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_component_select_wl`¶

DLL versions 4.4.13 and above

Set the wavelength for a specific component.

error_int BI_component_select_wl(
    char* id,
    double wl,
    int* settle);

Description¶

Sets the wavelength for a named monochromator component. Returns the settle delay time needed before taking measurements. This function sends the specified component to the specified wavelength and recommends a settle delay time before any readings are taken. It does not perform the delay itself.

Parameters¶

id (char*) Component identifier string
wl (double) Wavelength value in nanometers
settle (int*) Settle delay time in milliseconds after wavelength change

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.
BI_invalid_component == -3: The function was passed a component identifier that does not exist in the system model.

`BI_camera_measurement`¶

DLL versions 4.4.13 and above

Take a measurement from a camera/array detector.

error_int BI_camera_measurement(
    char* id,
    int number,
    double* wls,
    double* readings);

Description¶

Captures spectral data from a camera or diode array detector. Returns wavelengths and intensity readings for each pixel. This function instructs the DLL to take a camera measurement using the camera defined by the id string. The camera measurement itself is performed by the external DLL defined in the system configuration file for the relevant camera.

Parameters¶

id (char*) Component identifier string
number (int) Number of data points or pixels
wls (double*) Array of wavelength values in nanometers

This parameter is an array. Size specified by number.
readings (double*) Array of measurement readings

This parameter is an array. Size specified by number.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_camera_get_wls`¶

DLL versions 4.4.13 and above

Get wavelength calibration for camera pixels.

error_int BI_camera_get_wls(
    char* id,
    double* wls);

Description¶

Retrieves the wavelength corresponding to each pixel of the camera or array detector.

Parameters¶

id (char*) Component identifier string
wls (double*) Array of wavelength values in nanometers

This parameter is an array. Size specified by CameraDataSize.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_camera_zero_calibration`¶

DLL versions 4.4.13 and above

Perform zero calibration for camera detector (obsolete).

error_int BI_camera_zero_calibration(
    char* id,
    double start_wl,
    double stop_wl);

Description¶

Legacy function for camera zero calibration. This function is obsolete and does nothing. Kept for backwards compatibility with BenWin+.

Parameters¶

id (char*) Component identifier string
start_wl (double) Starting wavelength for the range in nanometers
stop_wl (double) Ending wavelength for the range in nanometers

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_camera_get_zero_calibration_info`¶

DLL versions 4.4.13 and above

Get zero calibration data for camera (obsolete).

error_int BI_camera_get_zero_calibration_info(
    char* id,
    double* wavelength,
    double* DarkCurrent,
    double* ADCOffset);

Description¶

Legacy function for retrieving camera zero calibration data. This function is obsolete and does nothing. Kept for backwards compatibility with BenWin+.

Parameters¶

id (char*) Component identifier string
wavelength (double*) Wavelength value in nanometers

This parameter is an array. Size specified by CameraDataSize.
DarkCurrent (double*) Array of dark current calibration values

This parameter is an array. Size specified by CameraDataSize.
ADCOffset (double*) Array of ADC offset calibration values

This parameter is an array. Size specified by CameraDataSize.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_delete_group`¶

DLL versions 4.4.13 and above

Delete a component group.

int BI_delete_group(
    int n);

Description¶

Removes a previously created group. Returns the number of remaining groups.

Parameters¶

n (int) Group number or count value

Returns¶

int (remaining_groups): The number of groups remaining after deletion

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_display_setup_window`¶

DLL versions 4.4.13 and above

Show the setup window for a component.

error_int BI_display_setup_window(
    char* id,
    int hinstance);

Description¶

Displays the configuration dialog for a hardware component if one is available. Requires a window handle from the calling application.

Parameters¶

id (char*) Component identifier string
hinstance (int) Window handle for displaying dialog

Returns¶

Error codes¶

This function can return the following error codes:

BI_invalid_component == -3: The function was passed a component identifier that does not exist in the system model.
BI_no_setup_window == -5: No setup window is available for the specified component.

`BI_display_advanced_window`¶

DLL versions 4.4.13 and above

Show the advanced setup window for a component.

error_int BI_display_advanced_window(
    char* id,
    int hinstance);

Description¶

Displays the advanced configuration dialog for a hardware component if one is available. Requires a window handle from the calling application.

Parameters¶

id (char*) Component identifier string
hinstance (int) Window handle for displaying dialog

Returns¶

Error codes¶

This function can return the following error codes:

BI_invalid_component == -3: The function was passed a component identifier that does not exist in the system model.
BI_no_setup_window == -5: No setup window is available for the specified component.

`BI_get`¶

DLL versions 4.4.13 and above

Get a numeric attribute value from a component.

error_int BI_get(
    char* id,
    int token,
    int index,
    double* value);

Description¶

Retrieves a numeric (double) attribute from a hardware component. Use tokens to specify which attribute to read. The index parameter is used for multi-value attributes (usually 0).

Parameters¶

id (char*) Component identifier string
token (int) Token identifier for the attribute to access
index (int) Index for multi-value attributes (usually 0 for single values)
value (double*) Numeric value to set or retrieve

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.
BI_invalid_attribute == -4: The function was passed an attribute token referring to an attribute that does not exist or is inaccessible for the specified component.
BI_invalid_component == -3: The function was passed a component identifier that does not exist in the system model.
BI_invalid_token == -2: The function was passed an invalid attribute token that is not recognized.

`BI_get_str`¶

DLL versions 4.4.13 and above

Get a string attribute value from a component.

error_int BI_get_str(
    char* id,
    int token,
    int index,
    char* s);

Description¶

Retrieves a string attribute from a hardware component. Use tokens to specify which attribute to read. Buffer must be pre-allocated (256 bytes recommended).

Parameters¶

id (char*) Component identifier string
token (int) Token identifier for the attribute to access
index (int) Index for multi-value attributes (usually 0 for single values)
s (char*) String value or buffer for text data

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.
BI_invalid_attribute == -4: The function was passed an attribute token referring to an attribute that does not exist or is inaccessible for the specified component.
BI_invalid_component == -3: The function was passed a component identifier that does not exist in the system model.
BI_invalid_token == -2: The function was passed an invalid attribute token that is not recognized.

`BI_get_c_group`¶

DLL versions 4.4.13 and above

Get the current active group number.

error_int BI_get_c_group(
    int* n);

Description¶

Returns the number of the currently active component group.

Parameters¶

n (int*) Group number or count value

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_get_component_list`¶

DLL versions 4.4.13 and above

Get a comma-separated list of all components.

error_int BI_get_component_list(
    char* list);

Description¶

Returns a string containing the IDs of all components in the system, separated by commas.

Parameters¶

list (char*) Buffer to receive comma-separated list of component IDs

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_get_group`¶

DLL versions 4.4.13 and above

Get the component IDs in a specific group.

error_int BI_get_group(
    int n,
    char* s);

Description¶

Returns a comma-separated string of component IDs that belong to the specified group.

Parameters¶

n (int) Group number or count value
s (char*) String value or buffer for text data

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_get_hardware_type`¶

DLL versions 4.4.13 and above

Get the hardware type constant for a component.

error_int BI_get_hardware_type(
    char* id,
    int* hardwareType);

Description¶

Returns the hardware type identifier (e.g., BenMono, BenADC) for a component. Use this to determine what kind of hardware a component represents. See Hardware Types in Tokens list.

Parameters¶

id (char*) Component identifier string
hardwareType (int*) Hardware type identifier token constant

Returns¶

Error codes¶

This function can return the following error codes:

BI_invalid_component == -3: The function was passed a component identifier that does not exist in the system model.

`BI_get_log`¶

DLL versions 4.4.13 and above

Retrieve accumulated log messages.

error_int BI_get_log(
    char* log);

Description¶

Gets the log messages that have been accumulated during operation.

Parameters¶

log (char*) Buffer to receive log message text

This parameter is an array. Size specified by size.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_get_log_size`¶

DLL versions 4.4.13 and above

Get the size of accumulated log messages.

error_int BI_get_log_size(
    int* size);

Description¶

Returns the number of bytes needed to store the accumulated log messages. Call this before get_log to allocate appropriate buffer size.

Parameters¶

size (int*) Size value in bytes

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_get_mono_items`¶

DLL versions 4.4.13 and above

List components associated with a monochromator.

error_int BI_get_mono_items(
    char* monoID,
    char* ItemIDs);

Description¶

Returns a comma-separated list of component IDs that are part of a monochromator (gratings, filters, etc.). Buffer must be pre-allocated.

Parameters¶

monoID (char*) Monochromator component identifier
ItemIDs (char*) Buffer to receive comma-separated list of item IDs

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_get_min_step`¶

DLL versions 4.4.13 and above

Get the minimum wavelength step for a wavelength range.

error_int BI_get_min_step(
    int group,
    double start_wl,
    double stop_wl,
    double* min_step);

Description¶

Calculates the minimum wavelength increment supported by the system for a given wavelength range. Important for scan planning.

Parameters¶

group (int) Component group number
start_wl (double) Starting wavelength for the range in nanometers
stop_wl (double) Ending wavelength for the range in nanometers
min_step (double*) Minimum wavelength step size in nanometers

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_get_max_bw`¶

DLL versions 4.4.13 and above

Get the maximum bandwidth for a wavelength range.

error_int BI_get_max_bw(
    int group,
    double start_wl,
    double stop_wl,
    double* bandwidth);

Description¶

Calculates the maximum spectral bandwidth (slit width equivalent) available for a given wavelength range.

Parameters¶

group (int) Component group number
start_wl (double) Starting wavelength for the range in nanometers
stop_wl (double) Ending wavelength for the range in nanometers
bandwidth (double*) Spectral bandwidth value

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_get_no_of_dark_currents`¶

DLL versions 4.4.13 and above

Get the number of dark current calibration points.

error_int BI_get_no_of_dark_currents(
    int* NoOfValues);

Description¶

Returns the count of wavelength points in the dark current calibration table for the current group.

Parameters¶

NoOfValues (int*) Number of calibration values in the arrays

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_get_n_groups`¶

DLL versions 4.4.13 and above

Get the total number of component groups.

error_int BI_get_n_groups(
    int* n);

Description¶

Returns the count of all component groups that have been created.

Parameters¶

n (int*) Group number or count value

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_get_zero_calibration_info`¶

DLL versions 4.4.13 and above

Get zero calibration data for current group.

error_int BI_get_zero_calibration_info(
    double* wavelength,
    double* DarkCurrent,
    double* ADCOffset);

Description¶

Retrieves wavelength, dark current, and Analogue-digital Converter (ADC) offset arrays from the zero calibration table. Arrays must be pre-allocated based on the count from get_no_of_dark_currents.

Parameters¶

wavelength (double*) Wavelength value in nanometers

This parameter is an array. Size specified by NoOfValues.
DarkCurrent (double*) Array of dark current calibration values

This parameter is an array. Size specified by NoOfValues.
ADCOffset (double*) Array of ADC offset calibration values

This parameter is an array. Size specified by NoOfValues.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_group_add`¶

DLL versions 4.4.13 and above

Add a component to a group.

error_int BI_group_add(
    char* id,
    int n);

Description¶

Adds a component (by ID) to an existing group. Components in a group can be controlled together.

Parameters¶

id (char*) Component identifier string
n (int) Group number or count value

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_group_remove`¶

DLL versions 4.4.13 and above

Remove a component from a group.

error_int BI_group_remove(
    char* id,
    int n);

Description¶

Removes a component (by ID) from a group.

Parameters¶

id (char*) Component identifier string
n (int) Group number or count value

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_initialise`¶

DLL versions 4.4.13 and above

Initialize the hardware system.

error_int BI_initialise();

Description¶

Initializes all hardware components for the current group. Must be called after build_system_model and before taking measurements. This homes monochromators and sets up detectors. The system must be initialized before measurements can be taken.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_load_setup`¶

DLL versions 4.4.13 and above

Load component settings from a setup file.

error_int BI_load_setup(
    char* filename);

Description¶

Loads previously saved component configurations from a setup file. This restores settings like wavelengths, gains, and other parameters.

Parameters¶

filename (char*) Path to the configuration or setup file

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_measurement`¶

DLL versions 4.4.13 and above

Take a measurement without autoranging.

error_int BI_measurement(
    double* reading);

Description¶

Takes a reading from the detector at the current settings. Unlike automeasure, this does not adjust the gain. Negative values are clamped to zero unless AllowNegative is set. This function returns the reading at the current wavelength for the active group.

Parameters¶

reading (double*) Measurement reading value or array

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_multi_automeasure`¶

DLL versions 4.4.13 and above

Take measurements from all groups with autoranging.

error_int BI_multi_automeasure(
    double* reading);

Description¶

Performs automeasure on all component groups simultaneously. Returns an array of readings, one per group. Array must be pre-allocated.

Parameters¶

reading (double*) Measurement reading value or array

This parameter is an array. Size specified by n.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_multi_autorange`¶

DLL versions 4.4.13 and above

Auto-range all groups simultaneously.

error_int BI_multi_autorange();

Description¶

Adjusts the amplifier ranges for all component groups at the same time.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_multi_get_no_of_dark_currents`¶

DLL versions 4.4.13 and above

Get dark current calibration point count for a specific group.

error_int BI_multi_get_no_of_dark_currents(
    int group,
    int* NoOfValues);

Description¶

Returns the number of wavelength points in the dark current calibration table for the specified group.

Parameters¶

group (int) Component group number
NoOfValues (int*) Number of calibration values in the arrays

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_multi_get_zero_calibration_info`¶

DLL versions 4.4.13 and above

Get zero calibration data for a specific group.

error_int BI_multi_get_zero_calibration_info(
    int group,
    double* wavelength,
    double* DarkCurrent,
    double* ADCOffset);

Description¶

Retrieves wavelength, dark current, and ADC offset arrays for the specified group. Arrays must be pre-allocated.

Parameters¶

group (int) Component group number
wavelength (double*) Wavelength value in nanometers

This parameter is an array. Size specified by NoOfValues.
DarkCurrent (double*) Array of dark current calibration values

This parameter is an array. Size specified by NoOfValues.
ADCOffset (double*) Array of ADC offset calibration values

This parameter is an array. Size specified by NoOfValues.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_multi_initialise`¶

DLL versions 4.4.13 and above

Initialize all groups simultaneously.

error_int BI_multi_initialise();

Description¶

Initializes hardware for all component groups at the same time. Faster than initializing each group separately.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_multi_measurement`¶

DLL versions 4.4.13 and above

Take measurements from all groups.

error_int BI_multi_measurement(
    double* reading);

Description¶

Takes readings from all component groups simultaneously. Returns an array of readings. Array must be pre-allocated.

Parameters¶

reading (double*) Measurement reading value or array

This parameter is an array. Size specified by n.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_multi_park`¶

DLL versions 4.4.13 and above

Park all monochromators in all groups.

error_int BI_multi_park();

Description¶

Moves all monochromators to their park positions across all groups simultaneously.

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_multi_select_wavelength`¶

DLL versions 4.4.13 and above

Set wavelength for all groups simultaneously.

error_int BI_multi_select_wavelength(
    double wavelength,
    int* settle_delay);

Description¶

Changes the wavelength for monochromators in all groups at the same time. Returns the maximum settle delay needed.

Parameters¶

wavelength (double) Wavelength value in nanometers
settle_delay (int*) Settle delay time in milliseconds after wavelength change

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_multi_zero_calibration`¶

DLL versions 4.4.13 and above

Perform zero calibration across a wavelength range for all groups.

error_int BI_multi_zero_calibration(
    double start_wavelength,
    double stop_wavelength);

Description¶

Runs zero calibration (dark current and offset measurement) for all groups across the specified wavelength range.

Parameters¶

start_wavelength (double) Starting wavelength for the range in nanometers
stop_wavelength (double) Ending wavelength for the range in nanometers

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_park`¶

DLL versions 4.4.13 and above

Park the monochromator in the current group.

error_int BI_park();

Description¶

Moves the monochromator to its park position (usually a safe wavelength or home position).

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_read`¶

DLL versions 4.4.13 and above

Read data from an anonymous device.

error_int BI_read(
    char* buffer,
    uint16_t buffer_size,
    uint16_t* chars_read,
    char* id);

Description¶

Reads raw data from a device like an ADC or serial device. Buffer and size must be specified. Returns the actual number of characters read.

Parameters¶

buffer (char*) Buffer for reading or writing data

This parameter is an array. Size specified by buffer_size.
buffer_size (uint16_t) Size of the buffer in bytes
chars_read (uint16_t*) Number of characters actually read
id (char*) Component identifier string

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_report_error`¶

DLL versions 4.4.13 and above

Get the last error code.

int BI_report_error();

Description¶

Returns the most recent error code from hardware operations. Use this to get detailed error information after a function returns an error. See error code definitions for meanings. Calling report_error clears the error code, i.e. subsequent calls will return no error (0) until another hardware error occurs.

Returns¶

`BI_save_setup`¶

DLL versions 4.4.13 and above

Save current component settings to a file.

error_int BI_save_setup(
    char* filename);

Description¶

Saves the current configuration of all components to a setup file. This includes wavelengths, gains, and other settings that can be restored with load_setup.

Parameters¶

filename (char*) Path to the configuration or setup file

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_select_wavelength`¶

DLL versions 4.4.13 and above

Set the wavelength for the current group.

error_int BI_select_wavelength(
    double wl,
    int* settle_delay);

Description¶

Changes the wavelength of monochromators in the current group. Returns the settle delay time needed before taking measurements. The DLL will coordinate the operation of gratings, filter wheels, and SAMs to achieve the target wavelength.

Parameters¶

wl (double) Wavelength value in nanometers
settle_delay (int*) Settle delay time in milliseconds after wavelength change

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_send`¶

DLL versions 4.4.13 and above

Send a command to an anonymous device.

error_int BI_send(
    char* msg,
    char* id);

Description¶

Sends a raw command string to a device like a serial instrument or controller.

Parameters¶

msg (char*) Message string to send or query
id (char*) Component identifier string

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_set`¶

DLL versions 4.4.13 and above

Set a numeric attribute value for a component.

error_int BI_set(
    char* id,
    int token,
    int index,
    double value);

Description¶

Sets a numeric (double) attribute on a hardware component. Use tokens to specify which attribute to set. The index parameter is used for multi-value attributes (usually 0).

Parameters¶

id (char*) Component identifier string
token (int) Token identifier for the attribute to access
index (int) Index for multi-value attributes (usually 0 for single values)
value (double) Numeric value to set or retrieve

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.
BI_invalid_attribute == -4: The function was passed an attribute token referring to an attribute that does not exist or is inaccessible for the specified component.
BI_invalid_component == -3: The function was passed a component identifier that does not exist in the system model.
BI_invalid_token == -2: The function was passed an invalid attribute token that is not recognized.

`BI_set_str`¶

DLL versions 4.4.13 and above

Set a string attribute value for a component.

error_int BI_set_str(
    char* id,
    int token,
    int index,
    char* s);

Description¶

Sets a string attribute on a hardware component. Use tokens to specify which attribute to set.

Parameters¶

id (char*) Component identifier string
token (int) Token identifier for the attribute to access
index (int) Index for multi-value attributes (usually 0 for single values)
s (char*) String value or buffer for text data

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.
BI_invalid_attribute == -4: The function was passed an attribute token referring to an attribute that does not exist or is inaccessible for the specified component.
BI_invalid_component == -3: The function was passed a component identifier that does not exist in the system model.
BI_invalid_token == -2: The function was passed an invalid attribute token that is not recognized.

`BI_start_log`¶

DLL versions 4.4.13 and above

Start logging for specified components.

error_int BI_start_log(
    char* c_list);

Description¶

Begins accumulating log messages for the specified comma-separated list of component IDs. Useful for debugging and diagnostics.

Parameters¶

c_list (char*) Comma-separated list of component IDs

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_stop_log`¶

DLL versions 4.4.13 and above

Stop logging for specified components.

error_int BI_stop_log(
    char* c_list);

Description¶

Stops accumulating log messages for the specified components.

Parameters¶

c_list (char*) Comma-separated list of component IDs

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_trace`¶

DLL versions 4.4.13 and above

Enable or disable trace logging.

error_int BI_trace(
    int i,
    char* LoggingDir);

Description¶

Controls detailed trace logging to file. Pass 1 to enable and provide a logging directory, or 0 to disable. Trace logs are very detailed and useful for troubleshooting hardware communication issues and debugging applications.

Parameters¶

i (int) Integer flag or control value (0=off, 1=on)
LoggingDir (char*) Directory path for logging output

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_Mapped_Logging`¶

DLL versions 4.4.13 and above

Enable or disable mapped logging.

void BI_Mapped_Logging(
    int i);

Description¶

Controls whether motor position logging uses mapped values. Pass 1 to enable, 0 to disable.

Parameters¶

i (int) Integer flag or control value (0=off, 1=on)

`BI_use_group`¶

DLL versions 4.4.13 and above

Set the current active group.

error_int BI_use_group(
    int n);

Description¶

Changes which component group is active. Subsequent operations will apply to this group.

Parameters¶

n (int) Group number or count value

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_version`¶

DLL versions 4.4.13 and above

Get the DLL version string.

void BI_version(
    char* s);

Description¶

Returns the version of the BenHW DLL as a string (e.g., ‘v4.12.0 (32 bit)’). Buffer must be pre-allocated with sufficient space (256 characters recommended).

Parameters¶

s (char*) String value or buffer for text data

`BI_zero_calibration`¶

DLL versions 4.4.13 and above

Perform zero calibration across a wavelength range.

error_int BI_zero_calibration(
    double start_wl,
    double stop_wl);

Description¶

Runs zero calibration (dark current and offset measurement) for the current group across the specified wavelength range. Essential for accurate measurements. The system should be in darkness or the shutter closed during this operation.

Parameters¶

start_wl (double) Starting wavelength for the range in nanometers
stop_wl (double) Ending wavelength for the range in nanometers

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_SCPI_query`¶

DLL versions 4.4.13 and above

Send a SCPI query command and read response.

error_int BI_SCPI_query(
    char* id,
    char* msg,
    char* reply,
    int reply_size);

Description¶

Sends a SCPI (Standard Commands for Programmable Instruments) query to a USB SCPI device and reads the response. Buffer size must be specified.

Parameters¶

id (char*) Component identifier string
msg (char*) Message string to send or query
reply (char*) Buffer to receive reply data

This parameter is an array. Size specified by reply_size.
reply_size (int) Maximum size of reply buffer in bytes

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

`BI_SCPI_write`¶

DLL versions 4.4.13 and above

Send a SCPI write command.

error_int BI_SCPI_write(
    char* msg,
    char* id);

Description¶

Sends a SCPI (Standard Commands for Programmable Instruments) command to a USB SCPI device without expecting a response.

Parameters¶

msg (char*) Message string to send or query
id (char*) Component identifier string

Returns¶

Error codes¶

This function can return the following error codes:

BI_error == -1: Function call failed. Use BI_report_error to get detailed hardware error code.

C API¶

BI_close¶

Description¶

Returns¶

Error codes¶

BI_automeasure¶

Description¶

Parameters¶

Returns¶

Error codes¶

BI_autorange¶

Description¶

Returns¶

Error codes¶

BI_build_group¶

Description¶

Returns¶

Error codes¶

BI_build_system_model¶

Description¶

Parameters¶

Returns¶

Error codes¶

BI_close_shutter¶

Description¶

Returns¶

Error codes¶

BI_component_select_wl¶

Description¶

Parameters¶

Returns¶

Error codes¶

BI_camera_measurement¶

Description¶

Parameters¶

Returns¶

Error codes¶

BI_camera_get_wls¶

Description¶

Parameters¶

Returns¶

Error codes¶

BI_camera_zero_calibration¶

Description¶

Parameters¶

Returns¶

Error codes¶

BI_camera_get_zero_calibration_info¶

Description¶

Parameters¶

Returns¶

Error codes¶

BI_delete_group¶

Description¶

Parameters¶

Returns¶

Error codes¶

BI_display_setup_window¶

Description¶

Parameters¶

Returns¶

Error codes¶

BI_display_advanced_window¶

Description¶

Parameters¶

Returns¶

Error codes¶

BI_get¶

Description¶

Parameters¶

Returns¶

Error codes¶

BI_get_str¶

Description¶

Parameters¶

Returns¶

Error codes¶

BI_get_c_group¶

Description¶

Parameters¶

`BI_close`¶

`BI_automeasure`¶

`BI_autorange`¶

`BI_build_group`¶

`BI_build_system_model`¶

`BI_close_shutter`¶

`BI_component_select_wl`¶

`BI_camera_measurement`¶

`BI_camera_get_wls`¶

`BI_camera_zero_calibration`¶

`BI_camera_get_zero_calibration_info`¶

`BI_delete_group`¶

`BI_display_setup_window`¶

`BI_display_advanced_window`¶

`BI_get`¶

`BI_get_str`¶

`BI_get_c_group`¶

`BI_get_component_list`¶

`BI_get_group`¶

`BI_get_hardware_type`¶

`BI_get_log`¶

`BI_get_log_size`¶

`BI_get_mono_items`¶

`BI_get_min_step`¶

`BI_get_max_bw`¶

`BI_get_no_of_dark_currents`¶

`BI_get_n_groups`¶

`BI_get_zero_calibration_info`¶

`BI_group_add`¶

`BI_group_remove`¶

`BI_initialise`¶