Troubleshooting

This section describes common problems that you may encounter when using the BenHW SDK and how to solve them.

Windows Errors

These are error messages that Windows may report when it encounters a problem running an application using the BenHW DLL. They appear in dialogue boxes that lock the system until dismissed.

File Error: Unable to find <name>.DLL

Ensure that <name>.dll is correctly installed in the appropriate directory or in a location accessible via your system PATH.

Runtime Error 202

This is a stack overflow error. The DLL uses the client application’s stack for function calls and local variables. If this error occurs, increase the stack size allocated to your application. In normal use, a client stack size of 8KB has been found sufficient (depending on how much the client application uses).

Runtime Error 006

This error can occur when an application using the DLL has crashed and is re-executed. When an application crashes, Windows does not unload the DLL, and it is left in memory in an undefined state. Trying to access the DLL again will almost always fail, producing this error.

Solution: If your application crashes, the safest course of action is to restart your development environment or Windows. This is the only reliable way to remove the DLL from memory and reset its state.

Hardware Control Problems

All DLL functions return an error and the hardware will not respond

  • Ensure that you have called build_system_model and that it has succeeded (returned success/OK).

  • Check that the system configuration file is correct and matches your hardware setup.

  • Verify that the hardware is powered on and properly connected to the PC.

initialise keeps failing

  • Ensure that you have called build_system_model and that it has succeeded.

  • For IEEE TM300/DTM300 systems, ensure that all cable connections are secure and that the hardware is switched on.

  • Check that the correct communication interface (USB, IEEE, RS232) is specified in the system configuration file.

  • Verify that the communication port (COM port, USB IDs) specified in the configuration file is correct.

  • For USB systems, ensure that the USB device is recognized by the operating system and that no other application is using it.

The monochromator does not go to the correct wavelength

For TM300/DTM300 systems, check:

  • You have called initialise and it has succeeded

  • You have called park and it has succeeded

  • The SDK has the correct z-ord (zero order) and alpha values for your monochromator

  • The grating line density (d) is correctly configured

For non-parking M300/DM150 systems, check:

  • The SDK has the correct dial reading set via MonochromatorCurrentDialReading

  • Valid values are 0 to 999.99

For self-parking M300/DM150 systems, check:

  • You have called park and it has succeeded

  • The park position is correctly configured

The filter wheel does not go to the correct position

For TM300/DTM300 systems, check:

  • You have called initialise and it has succeeded

  • You have called park and it has succeeded

For non-parking M300/DM150 systems, check:

  • The SDK has the correct filter position set via FWheelCurrentPosition

For self-parking M300/DM150 systems, check:

  • You have called park and it has succeeded

For all systems, check:

  • The SDK has the correct filter value for each position (any empty positions should be set to a filter value of 0)

  • Filter values are assigned correctly to match the physical filters installed in the wheel

  • The last position is reserved as the shutter position

autorange keeps failing

The autorange function will fail if there is a problem reading the ADC. This is often caused by:

  • Communications error: An intermittent communications error can be caused by a bad connection on the IEEE bus or USB cable. Check all cable connections.

  • Sudden input change: The ADC can experience a sudden change in input when the amplifier(s) change range or the filter wheel changes position. Ensure that all settle delays are long enough and are actually being used in your code.

  • ADC overload: The input signal may be too strong for the current range setting. Try starting with a lower sensitivity range.

zero_calibration keeps failing

The zero_calibration function will fail for the same reasons as autorange. Additionally, check:

  • The shutter is properly closed or the system is in darkness during zero calibration

  • The wavelength range specified for calibration is valid for your system

  • Sufficient time is allowed for the system to settle at each wavelength

  • The integration time settings are appropriate for the light levels

measurement keeps failing

The measurement function will fail for the same reasons as autorange. Additionally, check:

  • You have performed zero calibration before taking measurements

  • The current wavelength is within the valid range for your system configuration

  • The amplifier is not overloaded (check with the AmpOverload token)

  • Settle delays are sufficient after wavelength changes

Communication Issues

Timeout errors (PMC, MSD, MSC, MAC)

These errors indicate that a motor controller or stepper motor drive is not responding to commands:

  • Check that the device is powered on

  • Verify all cable connections

  • Ensure the correct address is specified in the system configuration file

  • For IEEE devices, verify the IEEE interface card is functioning

  • For RS232 devices, verify the correct COM port is specified and that no other application is using it

  • For USB devices, check that the device is recognized by the operating system

Electronics not responding (225, 265, 267, 277, 262 dead errors)

These errors indicate that an amplifier or relay unit is not responding:

  • Check that the device is powered on

  • Verify all cable connections, especially the IEEE or I2C bus connections

  • Ensure the correct address is specified in the system configuration file

  • Check that the address doesn’t conflict with another device

  • For USB_COMMS systems, verify the USB connection and that the electronics bin is powered

ADC read errors

  • Verify the ADC is powered and connected correctly

  • Check the address in the system configuration file

  • Ensure the input signal is within the valid range

  • For adaptive integration, verify the integration time settings are appropriate

Configuration File Issues

System model fails to build

  • Check the syntax of your system configuration file

  • Ensure each line follows the format: ComponentType identifier parameters

  • Verify that identifiers are unique and don’t use reserved keywords

  • Check that components are declared in the correct order (interfaces first, then electronics, then mechanical components, finally monochromators)

  • Ensure the use parameter references correctly identify previously declared components

  • Look for typos in component type names (they are case-sensitive)

Component not found errors

  • Verify the component identifier in your code matches exactly (case-sensitive) with the identifier in the system configuration file

  • Ensure the component was successfully added to a group if you’re using component groups

  • Check that the component type supports the attribute or operation you’re trying to use

Group Configuration Issues

Operations affect the wrong components

  • Verify you have called use_group to select the correct active group

  • Check that components are added to the correct groups

  • Remember that operations like select_wavelength and measurement operate on the active group

  • Ensure zero calibration is performed for each group that will take measurements

Zero calibration values not applied

  • Verify the monochromator is included in the group used for measurements

  • Ensure zero_calibration is called for the active group before taking measurements

  • Check that the wavelength range specified for calibration covers the wavelengths you’re measuring

Performance Issues

Measurements are very slow

  • Check the ADC integration time (ADCSamplesPerReading and ADCSamplePeriod)

  • Reduce the number of samples per reading if appropriate for your signal levels

  • Verify adaptive integration settings are optimized

  • Ensure settle delays are not excessively long

  • For AC systems, check the time constant settings

Wavelength changes take too long

  • Verify the settle delay (biSettleDelay) is not set unnecessarily high

  • Check that the scan direction (MonochromatorScanDirection) matches your scanning direction to avoid unnecessary backlash compensation

  • Ensure the motor speeds are correctly configured for your hardware

Measurement Quality Issues

Noisy or unstable readings

  • Increase the ADC integration time by increasing samples per reading

  • Enable adaptive integration to use longer integration times for weak signals

  • Check for loose cables or intermittent connections

  • Verify the system is allowed to settle properly after wavelength changes

  • For AC systems, check the time constant and phase settings

  • Ensure electrical noise sources are minimized near sensitive electronics

Readings are always negative or zero

  • Perform zero calibration with the shutter closed or in complete darkness

  • Check the amplifier range settings (AmpMinRange, AmpMaxRange)

  • Verify the signal polarity is correct for your detector

  • Check that the ADC offset and dark current calibration was successful

Readings vary significantly between runs

  • Perform zero calibration before each scan

  • Allow sufficient warm-up time for the light source and electronics

  • Check for thermal drift in the system

  • Verify that all hardware settings remain consistent between runs

  • Ensure environmental conditions (temperature, vibration) are stable

Advanced Troubleshooting

Enabling trace logging

For detailed troubleshooting, you can enable trace logging to capture all DLL operations:

# Enable trace logging to a directory
trace(1, "c:\\logs")

# Your measurement code here

# Disable trace logging
trace(0, "")

Trace logs are very detailed and useful for troubleshooting hardware communication issues and debugging applications. They record all commands sent to hardware and responses received.

Using component logging

You can enable logging for specific components to diagnose issues:

# Start logging for specific components
start_log("mono1,adc1")

# Your code that interacts with these components

# Stop logging
stop_log("mono1,adc1")

Checking error codes

Always check the return values from SDK functions and use report_error to get detailed hardware error codes:

result = select_wavelength(500.0)
if result != 0:  # BI_OK
    error_code = report_error()
    print(f"Error code: {error_code}")

Error codes provide specific information about what went wrong and are documented in the errors section of this documentation.

Getting Further Help

If you continue to experience problems after trying these troubleshooting steps:

  1. Check that you’re using the latest version of the BenHW DLL

  2. Review the example code provided with the SDK for proper usage patterns

  3. Enable trace logging to capture detailed diagnostic information

  4. Contact Bentham Instruments support with:

    • Your system configuration file

    • A description of the problem and when it occurs

    • Any error messages or error codes

    • Trace logs if available

    • Hardware model numbers and firmware versions

Contact information:

Bentham Instruments Ltd
2 Boulton Road, Reading, Berkshire, RG2 0NH, UK
Tel: +44 (0)118 975 1355
Email: sales@bentham.co.uk
Web: www.bentham.co.uk