Python API¶
This section documents the Python interface to the BenHW SDK.
The Python API provides a Pythonic wrapper around the C API, with automatic memory management, exception handling, and simplified function signatures.
The Python SDK is available on PyPI and can be installed using pip:
pip install benhw
The benhw PyPI package comes bundled with the BenHW DLL, so no separate DLL installation is required.
The package automatically manages the DLL loading and initialization.
The main interface to the BenHW SDK is through the BenHW class, which provides methods
corresponding to each C API function.
from benhw import BenHW, tokens, SdkException
hw = BenHW() # automatically picks up bundled BenHW dll
try:
dll_version:str = hw.version()
hw.build_system_model("absolute/path/to/system.cfg")
hw.load_setup("absolute/path/to/system.atr")
hw.initialise()
hw.park()
hw.zero_calibration(200.0,400.0)
hw.select_wavelength(300.0)
reading:float = hw.automeasure()
print(reading)
except SdkException as e:
print(e)
BenHW.close¶
DLL versions 4.4.13 and above
Close and clean up the system model.
Signature¶
def close(self) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
hw.close()
print("Success")
except SdkException as e:
print(f"Error: {e}")
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.
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.automeasure¶
DLL versions 4.4.13 and above
Perform an automatic measurement with autoranging.
Signature¶
def automeasure(self) -> float:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
reading = hw.automeasure()
print(f"reading: {reading}")
except SdkException as e:
print(f"Error: {e}")
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.
Returns¶
reading (float): Measurement reading value or array
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
AdcOverloadException: Analogue-digital Converter (ADC) overload detected - the input signal is too strong for the current range setting.AdcReadErrorException: Analogue-digital Converter (ADC) is not responding or failed to complete a read operation.BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.autorange¶
DLL versions 4.4.13 and above
Automatically adjust the detector range.
Signature¶
def autorange(self) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
hw.autorange()
print("Success")
except SdkException as e:
print(f"Error: {e}")
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.
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.build_group¶
DLL versions 4.4.13 and above
Create a new component group.
Signature¶
def build_group(self) -> int:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
group_number = hw.build_group()
print(f"group_number: {group_number}")
except SdkException as e:
print(f"Error: {e}")
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.
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.build_system_model¶
DLL versions 4.4.13 and above
Load and compile a system configuration file.
Signature¶
def build_system_model(self, config_file: str) -> str:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
config_file = "system.cfg"
error = hw.build_system_model(config_file)
print(f"error: {error}")
except SdkException as e:
print(f"Error: {e}")
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(str) - Path to the system configuration file
Returns¶
error (str): Error message
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.close_shutter¶
DLL versions 4.4.13 and above
Close the monochromator shutter.
Signature¶
def close_shutter(self) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
hw.close_shutter()
print("Success")
except SdkException as e:
print(f"Error: {e}")
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.
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.component_select_wl¶
DLL versions 4.4.13 and above
Set the wavelength for a specific component.
Signature¶
def component_select_wl(self, id: str, wl: float) -> int:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
wl = 550.0
settle = hw.component_select_wl(id, wl)
print(f"settle: {settle}")
except SdkException as e:
print(f"Error: {e}")
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(str) - Component identifier stringwl(float) - Wavelength value in nanometers
Returns¶
settle (int): Settle delay time in milliseconds after wavelength change
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.InvalidComponentException: The function was passed a component identifier that does not exist in the system model.
BenHW.camera_measurement¶
DLL versions 4.4.13 and above
Take a measurement from a camera/array detector.
Signature¶
def camera_measurement(self, id: str, number: int) -> BI_camera_measurement_result:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
number = 100
result = hw.camera_measurement(id, number)
print(f"wls: {result.wls}")
print(f"readings: {result.readings}")
except SdkException as e:
print(f"Error: {e}")
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(str) - Component identifier stringnumber(int) - Number of data points or pixels
Returns¶
A BI_camera_measurement_result object containing:
wls(list[float]): Array of wavelength values in nanometersreadings(list[float]): Array of measurement readings
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.camera_get_wls¶
DLL versions 4.4.13 and above
Get wavelength calibration for camera pixels.
Signature¶
def camera_get_wls(self, id: str) -> list[float]:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
wls = hw.camera_get_wls(id)
print(f"wls: {wls}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Retrieves the wavelength corresponding to each pixel of the camera or array detector.
Parameters¶
id(str) - Component identifier string
Returns¶
wls (list[float]): Array of wavelength values in nanometers
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.camera_zero_calibration¶
DLL versions 4.4.13 and above
Perform zero calibration for camera detector (obsolete).
Signature¶
def camera_zero_calibration(self, id: str, start_wl: float, stop_wl: float) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
start_wl = 400.0
stop_wl = 800.0
hw.camera_zero_calibration(id, start_wl, stop_wl)
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Legacy function for camera zero calibration. This function is obsolete and does nothing. Kept for backwards compatibility with BenWin+.
Parameters¶
id(str) - Component identifier stringstart_wl(float) - Starting wavelength for the range in nanometersstop_wl(float) - Ending wavelength for the range in nanometers
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.camera_get_zero_calibration_info¶
DLL versions 4.4.13 and above
Get zero calibration data for camera (obsolete).
Signature¶
def camera_get_zero_calibration_info(self, id: str) -> BI_camera_get_zero_calibration_info_result:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
result = hw.camera_get_zero_calibration_info(id)
print(f"wavelength: {result.wavelength}")
print(f"DarkCurrent: {result.DarkCurrent}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Legacy function for retrieving camera zero calibration data. This function is obsolete and does nothing. Kept for backwards compatibility with BenWin+.
Parameters¶
id(str) - Component identifier string
Returns¶
A BI_camera_get_zero_calibration_info_result object containing:
wavelength(list[float]): Wavelength value in nanometersDarkCurrent(list[float]): Array of dark current calibration valuesADCOffset(list[float]): Array of ADC offset calibration values
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.delete_group¶
DLL versions 4.4.13 and above
Delete a component group.
Signature¶
def delete_group(self, n: int) -> int:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
n = 1
remaining_groups = hw.delete_group(n)
print(f"remaining_groups: {remaining_groups}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Removes a previously created group. Returns the number of remaining groups.
Parameters¶
n(int) - Group number or count value
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.display_setup_window¶
DLL versions 4.4.13 and above
Show the setup window for a component.
Signature¶
def display_setup_window(self, id: str, hinstance: int) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
hinstance = 0
hw.display_setup_window(id, hinstance)
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Displays the configuration dialog for a hardware component if one is available. Requires a window handle from the calling application.
Parameters¶
id(str) - Component identifier stringhinstance(int) - Window handle for displaying dialog
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
InvalidComponentException: The function was passed a component identifier that does not exist in the system model.NoSetupWindowException: No setup window is available for the specified component.
BenHW.display_advanced_window¶
DLL versions 4.4.13 and above
Show the advanced setup window for a component.
Signature¶
def display_advanced_window(self, id: str, hinstance: int) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
hinstance = 0
hw.display_advanced_window(id, hinstance)
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Displays the advanced configuration dialog for a hardware component if one is available. Requires a window handle from the calling application.
Parameters¶
id(str) - Component identifier stringhinstance(int) - Window handle for displaying dialog
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
InvalidComponentException: The function was passed a component identifier that does not exist in the system model.NoSetupWindowException: No setup window is available for the specified component.
BenHW.get¶
DLL versions 4.4.13 and above
Get a numeric attribute value from a component.
Signature¶
def get(self, id: str, token: int, index: int) -> float:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
token = 10
index = 0
value = hw.get(id, token, index)
print(f"value: {value}")
except SdkException as e:
print(f"Error: {e}")
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(str) - Component identifier stringtoken(int) - Token identifier for the attribute to accessindex(int) - Index for multi-value attributes (usually 0 for single values)
Returns¶
value (float): Numeric value to set or retrieve
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.InvalidAttributeException: The function was passed an attribute token referring to an attribute that does not exist or is inaccessible for the specified component.InvalidComponentException: The function was passed a component identifier that does not exist in the system model.InvalidTokenException: The function was passed an invalid attribute token that is not recognized.
BenHW.get_str¶
DLL versions 4.4.13 and above
Get a string attribute value from a component.
Signature¶
def get_str(self, id: str, token: int, index: int) -> str:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
token = 10
index = 0
s = hw.get_str(id, token, index)
print(f"s: {s}")
except SdkException as e:
print(f"Error: {e}")
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(str) - Component identifier stringtoken(int) - Token identifier for the attribute to accessindex(int) - Index for multi-value attributes (usually 0 for single values)
Returns¶
s (str): String value or buffer for text data
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.InvalidAttributeException: The function was passed an attribute token referring to an attribute that does not exist or is inaccessible for the specified component.InvalidComponentException: The function was passed a component identifier that does not exist in the system model.InvalidTokenException: The function was passed an invalid attribute token that is not recognized.
BenHW.get_c_group¶
DLL versions 4.4.13 and above
Get the current active group number.
Signature¶
def get_c_group(self) -> int:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
n = hw.get_c_group()
print(f"n: {n}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Returns the number of the currently active component group.
Returns¶
n (int): Group number or count value
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.get_component_list¶
DLL versions 4.4.13 and above
Get a comma-separated list of all components.
Signature¶
def get_component_list(self) -> str:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
list = hw.get_component_list()
print(f"list: {list}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Returns a string containing the IDs of all components in the system, separated by commas.
Returns¶
list (str): Comma-separated list of component IDs
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.get_group¶
DLL versions 4.4.13 and above
Get the component IDs in a specific group.
Signature¶
def get_group(self, n: int) -> str:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
n = 1
s = hw.get_group(n)
print(f"s: {s}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Returns a comma-separated string of component IDs that belong to the specified group.
Parameters¶
n(int) - Group number or count value
Returns¶
s (str): Comma-separated list of component IDs
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.get_hardware_type¶
DLL versions 4.4.13 and above
Get the hardware type constant for a component.
Signature¶
def get_hardware_type(self, id: str) -> int:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
hardwareType = hw.get_hardware_type(id)
print(f"hardwareType: {hardwareType}")
except SdkException as e:
print(f"Error: {e}")
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(str) - Component identifier string
Returns¶
hardwareType (int): Hardware type identifier token constant
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
InvalidComponentException: The function was passed a component identifier that does not exist in the system model.
BenHW.get_log¶
DLL versions 4.4.13 and above
Retrieve accumulated log messages.
Signature¶
def get_log(self) -> bytes:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
log = hw.get_log()
print(f"log: {log}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Gets the log messages that have been accumulated during operation.
Returns¶
log (bytes): Bytes containing log content. May contain r characters.
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.get_log_size¶
DLL versions 4.4.13 and above
Get the size of accumulated log messages.
Signature¶
def get_log_size(self) -> int:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
size = hw.get_log_size()
print(f"size: {size}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Returns the number of bytes needed to store the accumulated log messages. Call this before get_log to allocate appropriate buffer size.
Returns¶
size (int): Number of bytes
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.get_mono_items¶
DLL versions 4.4.13 and above
List components associated with a monochromator.
Signature¶
def get_mono_items(self, monoID: str) -> str:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
monoID = "mono1"
ItemIDs = hw.get_mono_items(monoID)
print(f"ItemIDs: {ItemIDs}")
except SdkException as e:
print(f"Error: {e}")
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(str) - Monochromator component identifier
Returns¶
ItemIDs (str): Comma-separated list of item IDs
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.get_min_step¶
DLL versions 4.4.13 and above
Get the minimum wavelength step for a wavelength range.
Signature¶
def get_min_step(self, group: int, start_wl: float, stop_wl: float) -> float:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
group = 1
start_wl = 400.0
stop_wl = 800.0
min_step = hw.get_min_step(group, start_wl, stop_wl)
print(f"min_step: {min_step}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Calculates the minimum wavelength increment supported by the system for a given wavelength range. Important for scan planning.
Parameters¶
group(int) - Component group numberstart_wl(float) - Starting wavelength for the range in nanometersstop_wl(float) - Ending wavelength for the range in nanometers
Returns¶
min_step (float): Minimum wavelength step size in nanometers
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.get_max_bw¶
DLL versions 4.4.13 and above
Get the maximum bandwidth for a wavelength range.
Signature¶
def get_max_bw(self, group: int, start_wl: float, stop_wl: float) -> float:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
group = 1
start_wl = 400.0
stop_wl = 800.0
bandwidth = hw.get_max_bw(group, start_wl, stop_wl)
print(f"bandwidth: {bandwidth}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Calculates the maximum spectral bandwidth (slit width equivalent) available for a given wavelength range.
Parameters¶
group(int) - Component group numberstart_wl(float) - Starting wavelength for the range in nanometersstop_wl(float) - Ending wavelength for the range in nanometers
Returns¶
bandwidth (float): Spectral bandwidth value
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.get_no_of_dark_currents¶
DLL versions 4.4.13 and above
Get the number of dark current calibration points.
Signature¶
def get_no_of_dark_currents(self) -> int:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
NoOfValues = hw.get_no_of_dark_currents()
print(f"NoOfValues: {NoOfValues}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Returns the count of wavelength points in the dark current calibration table for the current group.
Returns¶
NoOfValues (int): Number of calibration values in the arrays
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.get_n_groups¶
DLL versions 4.4.13 and above
Get the total number of component groups.
Signature¶
def get_n_groups(self) -> int:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
n = hw.get_n_groups()
print(f"n: {n}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Returns the count of all component groups that have been created.
Returns¶
n (int): Group number or count value
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.get_zero_calibration_info¶
DLL versions 4.4.13 and above
Get zero calibration data for current group.
Signature¶
def get_zero_calibration_info(self) -> BI_get_zero_calibration_info_result:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
result = hw.get_zero_calibration_info()
print(f"wavelength: {result.wavelength}")
print(f"DarkCurrent: {result.DarkCurrent}")
except SdkException as e:
print(f"Error: {e}")
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.
Returns¶
A BI_get_zero_calibration_info_result object containing:
wavelength(list[float]): Wavelength value in nanometersDarkCurrent(list[float]): Array of dark current calibration valuesADCOffset(list[float]): Array of ADC offset calibration values
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.group_add¶
DLL versions 4.4.13 and above
Add a component to a group.
Signature¶
def group_add(self, id: str, n: int) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
n = 1
hw.group_add(id, n)
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Adds a component (by ID) to an existing group. Components in a group can be controlled together.
Parameters¶
id(str) - Component identifier stringn(int) - Group number or count value
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.group_remove¶
DLL versions 4.4.13 and above
Remove a component from a group.
Signature¶
def group_remove(self, id: str, n: int) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
n = 1
hw.group_remove(id, n)
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Removes a component (by ID) from a group.
Parameters¶
id(str) - Component identifier stringn(int) - Group number or count value
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.initialise¶
DLL versions 4.4.13 and above
Initialize the hardware system.
Signature¶
def initialise(self) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
hw.initialise()
print("Success")
except SdkException as e:
print(f"Error: {e}")
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.
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.load_setup¶
DLL versions 4.4.13 and above
Load component settings from a setup file.
Signature¶
def load_setup(self, filename: str) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
filename = "config.cfg"
hw.load_setup(filename)
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Loads previously saved component configurations from a setup file. This restores settings like wavelengths, gains, and other parameters.
Parameters¶
filename(str) - Path to the configuration or setup file
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.measurement¶
DLL versions 4.4.13 and above
Take a measurement without autoranging.
Signature¶
def measurement(self) -> float:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
reading = hw.measurement()
print(f"reading: {reading}")
except SdkException as e:
print(f"Error: {e}")
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.
Returns¶
reading (float): Measurement reading value or array
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.multi_automeasure¶
DLL versions 4.4.13 and above
Take measurements from all groups with autoranging.
Signature¶
def multi_automeasure(self) -> list[float]:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
reading = hw.multi_automeasure()
print(f"reading: {reading}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Performs automeasure on all component groups simultaneously. Returns an array of readings, one per group. Array must be pre-allocated.
Returns¶
reading (list[float]): Measurement reading value or array
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.multi_autorange¶
DLL versions 4.4.13 and above
Auto-range all groups simultaneously.
Signature¶
def multi_autorange(self) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
hw.multi_autorange()
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Adjusts the amplifier ranges for all component groups at the same time.
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.multi_get_no_of_dark_currents¶
DLL versions 4.4.13 and above
Get dark current calibration point count for a specific group.
Signature¶
def multi_get_no_of_dark_currents(self, group: int) -> int:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
group = 1
NoOfValues = hw.multi_get_no_of_dark_currents(group)
print(f"NoOfValues: {NoOfValues}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Returns the number of wavelength points in the dark current calibration table for the specified group.
Parameters¶
group(int) - Component group number
Returns¶
NoOfValues (int): Number of calibration values in the arrays
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.multi_get_zero_calibration_info¶
DLL versions 4.4.13 and above
Get zero calibration data for a specific group.
Signature¶
def multi_get_zero_calibration_info(self, group: int) -> BI_multi_get_zero_calibration_info_result:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
group = 1
result = hw.multi_get_zero_calibration_info(group)
print(f"wavelength: {result.wavelength}")
print(f"DarkCurrent: {result.DarkCurrent}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Retrieves wavelength, dark current, and ADC offset arrays for the specified group. Arrays must be pre-allocated.
Parameters¶
group(int) - Component group number
Returns¶
A BI_multi_get_zero_calibration_info_result object containing:
wavelength(list[float]): Wavelength value in nanometersDarkCurrent(list[float]): Array of dark current calibration valuesADCOffset(list[float]): Array of ADC offset calibration values
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.multi_initialise¶
DLL versions 4.4.13 and above
Initialize all groups simultaneously.
Signature¶
def multi_initialise(self) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
hw.multi_initialise()
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Initializes hardware for all component groups at the same time. Faster than initializing each group separately.
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.multi_measurement¶
DLL versions 4.4.13 and above
Take measurements from all groups.
Signature¶
def multi_measurement(self) -> list[float]:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
reading = hw.multi_measurement()
print(f"reading: {reading}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Takes readings from all component groups simultaneously. Returns an array of readings. Array must be pre-allocated.
Returns¶
reading (list[float]): Measurement reading value or array
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.multi_park¶
DLL versions 4.4.13 and above
Park all monochromators in all groups.
Signature¶
def multi_park(self) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
hw.multi_park()
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Moves all monochromators to their park positions across all groups simultaneously.
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.multi_select_wavelength¶
DLL versions 4.4.13 and above
Set wavelength for all groups simultaneously.
Signature¶
def multi_select_wavelength(self, wavelength: float) -> int:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
wavelength = 550.0
settle_delay = hw.multi_select_wavelength(wavelength)
print(f"settle_delay: {settle_delay}")
except SdkException as e:
print(f"Error: {e}")
Description¶
Changes the wavelength for monochromators in all groups at the same time. Returns the maximum settle delay needed.
Parameters¶
wavelength(float) - Wavelength value in nanometers
Returns¶
settle_delay (int): Settle delay time in milliseconds after wavelength change
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.multi_zero_calibration¶
DLL versions 4.4.13 and above
Perform zero calibration across a wavelength range for all groups.
Signature¶
def multi_zero_calibration(self, start_wavelength: float, stop_wavelength: float) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
start_wavelength = 400.0
stop_wavelength = 800.0
hw.multi_zero_calibration(start_wavelength, stop_wavelength)
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Runs zero calibration (dark current and offset measurement) for all groups across the specified wavelength range.
Parameters¶
start_wavelength(float) - Starting wavelength for the range in nanometersstop_wavelength(float) - Ending wavelength for the range in nanometers
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.park¶
DLL versions 4.4.13 and above
Park the monochromator in the current group.
Signature¶
def park(self) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
hw.park()
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Moves the monochromator to its park position (usually a safe wavelength or home position).
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.read¶
DLL versions 4.4.13 and above
Read data from an anonymous device.
Signature¶
def read(self, buffer_size: int, id: str) -> BI_read_result:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
buffer_size = 256
id = "mono1"
result = hw.read(buffer_size, id)
print(f"buffer: {result.buffer}")
print(f"chars_read: {result.chars_read}")
except SdkException as e:
print(f"Error: {e}")
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_size(int) - Size of the buffer in bytesid(str) - Component identifier string
Returns¶
A BI_read_result object containing:
buffer(bytes): Buffer for reading or writing datachars_read(int): Number of characters actually read
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.report_error¶
DLL versions 4.4.13 and above
Get the last error code.
Signature¶
def report_error(self) -> int:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
error_code = hw.report_error()
print(f"error_code: {error_code}")
except SdkException as e:
print(f"Error: {e}")
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¶
error_code (int): Error code
Exceptions¶
Raises SdkException on failure.
BenHW.save_setup¶
DLL versions 4.4.13 and above
Save current component settings to a file.
Signature¶
def save_setup(self, filename: str) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
filename = "config.cfg"
hw.save_setup(filename)
print("Success")
except SdkException as e:
print(f"Error: {e}")
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(str) - Path to the configuration or setup file
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.select_wavelength¶
DLL versions 4.4.13 and above
Set the wavelength for the current group.
Signature¶
def select_wavelength(self, wl: float) -> int:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
wl = 550.0
settle_delay = hw.select_wavelength(wl)
print(f"settle_delay: {settle_delay}")
except SdkException as e:
print(f"Error: {e}")
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(float) - Wavelength value in nanometers
Returns¶
settle_delay (int): Settle delay time in milliseconds after wavelength change
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.send¶
DLL versions 4.4.13 and above
Send a command to an anonymous device.
Signature¶
def send(self, msg: str, id: str) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
msg = "*IDN?"
id = "mono1"
hw.send(msg, id)
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Sends a raw command string to a device like a serial instrument or controller.
Parameters¶
msg(str) - Message string to send or queryid(str) - Component identifier string
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.set¶
DLL versions 4.4.13 and above
Set a numeric attribute value for a component.
Signature¶
def set(self, id: str, token: int, index: int, value: float) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
token = 10
index = 0
value = 1.0
hw.set(id, token, index, value)
print("Success")
except SdkException as e:
print(f"Error: {e}")
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(str) - Component identifier stringtoken(int) - Token identifier for the attribute to accessindex(int) - Index for multi-value attributes (usually 0 for single values)value(float) - Numeric value to set or retrieve
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.InvalidAttributeException: The function was passed an attribute token referring to an attribute that does not exist or is inaccessible for the specified component.InvalidComponentException: The function was passed a component identifier that does not exist in the system model.InvalidTokenException: The function was passed an invalid attribute token that is not recognized.
BenHW.set_str¶
DLL versions 4.4.13 and above
Set a string attribute value for a component.
Signature¶
def set_str(self, id: str, token: int, index: int, s: str) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
token = 10
index = 0
s = "mono1"
hw.set_str(id, token, index, s)
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Sets a string attribute on a hardware component. Use tokens to specify which attribute to set.
Parameters¶
id(str) - Component identifier stringtoken(int) - Token identifier for the attribute to accessindex(int) - Index for multi-value attributes (usually 0 for single values)s(str) - String value or buffer for text data
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.InvalidAttributeException: The function was passed an attribute token referring to an attribute that does not exist or is inaccessible for the specified component.InvalidComponentException: The function was passed a component identifier that does not exist in the system model.InvalidTokenException: The function was passed an invalid attribute token that is not recognized.
BenHW.start_log¶
DLL versions 4.4.13 and above
Start logging for specified components.
Signature¶
def start_log(self, c_list: str) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
c_list = "mono1,adc1"
hw.start_log(c_list)
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Begins accumulating log messages for the specified comma-separated list of component IDs. Useful for debugging and diagnostics.
Parameters¶
c_list(str) - Comma-separated list of component IDs
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.stop_log¶
DLL versions 4.4.13 and above
Stop logging for specified components.
Signature¶
def stop_log(self, c_list: str) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
c_list = "mono1,adc1"
hw.stop_log(c_list)
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Stops accumulating log messages for the specified components.
Parameters¶
c_list(str) - Comma-separated list of component IDs
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.trace¶
DLL versions 4.4.13 and above
Enable or disable trace logging.
Signature¶
def trace(self, i: int, LoggingDir: str) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
i = 1
LoggingDir = "logs"
hw.trace(i, LoggingDir)
print("Success")
except SdkException as e:
print(f"Error: {e}")
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(str) - Directory path for logging output
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.Mapped_Logging¶
DLL versions 4.4.13 and above
Enable or disable mapped logging.
Signature¶
def Mapped_Logging(self, i: int) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
i = 1
hw.Mapped_Logging(i)
print("Success")
except SdkException as e:
print(f"Error: {e}")
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)
Exceptions¶
Raises SdkException on failure.
BenHW.use_group¶
DLL versions 4.4.13 and above
Set the current active group.
Signature¶
def use_group(self, n: int) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
n = 1
hw.use_group(n)
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Changes which component group is active. Subsequent operations will apply to this group.
Parameters¶
n(int) - Group number or count value
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.version¶
DLL versions 4.4.13 and above
Get the DLL version string.
Signature¶
def version(self) -> str:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
s = hw.version()
print(f"s: {s}")
except SdkException as e:
print(f"Error: {e}")
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).
Returns¶
s (str): String value or buffer for text data
Exceptions¶
Raises SdkException on failure.
BenHW.zero_calibration¶
DLL versions 4.4.13 and above
Perform zero calibration across a wavelength range.
Signature¶
def zero_calibration(self, start_wl: float, stop_wl: float) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
start_wl = 400.0
stop_wl = 800.0
hw.zero_calibration(start_wl, stop_wl)
print("Success")
except SdkException as e:
print(f"Error: {e}")
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(float) - Starting wavelength for the range in nanometersstop_wl(float) - Ending wavelength for the range in nanometers
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.SCPI_query¶
DLL versions 4.4.13 and above
Send a SCPI query command and read response.
Signature¶
def SCPI_query(self, id: str, msg: str, reply_size: int) -> bytes:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
id = "mono1"
msg = "*IDN?"
reply_size = 256
reply = hw.SCPI_query(id, msg, reply_size)
print(f"reply: {reply}")
except SdkException as e:
print(f"Error: {e}")
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(str) - Component identifier stringmsg(str) - Message string to send or queryreply_size(int) - Maximum size of reply buffer in bytes
Returns¶
reply (bytes): Buffer to receive reply data
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.
BenHW.SCPI_write¶
DLL versions 4.4.13 and above
Send a SCPI write command.
Signature¶
def SCPI_write(self, msg: str, id: str) -> None:
Example¶
from benhw import BenHW, tokens, SdkException
hw = BenHW()
try:
msg = "*IDN?"
id = "mono1"
hw.SCPI_write(msg, id)
print("Success")
except SdkException as e:
print(f"Error: {e}")
Description¶
Sends a SCPI (Standard Commands for Programmable Instruments) command to a USB SCPI device without expecting a response.
Parameters¶
msg(str) - Message string to send or queryid(str) - Component identifier string
Exceptions¶
Raises SdkException on failure. The following derivative exceptions may be raised due to failure originating in BenHW dll:
BenHWException: Function call failed. Use BI_report_error to get detailed hardware error code.