.NET API ======== This section documents the .NET/C# interface to the BenHW SDK. The .NET API provides a modern, type-safe C# wrapper around the C API, with automatic memory management, exception handling, and simplified function signatures. The SDK supports multiple .NET versions: - .NET Framework 4.8 - .NET 8.0+ The .NET SDK is available on NuGet and can be installed using the .NET CLI: .. code-block:: bash dotnet add package BenHW Or via the Package Manager Console: .. code-block:: powershell Install-Package BenHW The ``BenHW`` NuGet 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. .. code-block:: csharp using BenHW; // Create instance with automatic DLL loading using (var hw = new BenHW.BenHW()) { try { string dllVersion = hw.Version(); string errorMsg = hw.BuildSystemModel("absolute/path/to/system.cfg"); hw.LoadSetup("absolute/path/to/system.atr"); hw.Initialise(); hw.Park(); hw.ZeroCalibration(200.0, 400.0); int settle = hw.SelectWavelength(300.0); double reading = hw.Automeasure(); Console.WriteLine(reading); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message} (Code: {ex.ErrorCode})"); } } * :ref:`BenHW.Close ` * :ref:`BenHW.Automeasure ` * :ref:`BenHW.Autorange ` * :ref:`BenHW.BuildGroup ` * :ref:`BenHW.BuildSystemModel ` * :ref:`BenHW.CloseShutter ` * :ref:`BenHW.ComponentSelectWl ` * :ref:`BenHW.CameraMeasurement ` * :ref:`BenHW.CameraGetWls ` * :ref:`BenHW.CameraZeroCalibration ` * :ref:`BenHW.CameraGetZeroCalibrationInfo ` * :ref:`BenHW.DeleteGroup ` * :ref:`BenHW.DisplaySetupWindow ` * :ref:`BenHW.DisplayAdvancedWindow ` * :ref:`BenHW.Get ` * :ref:`BenHW.GetStr ` * :ref:`BenHW.GetCGroup ` * :ref:`BenHW.GetComponentList ` * :ref:`BenHW.GetGroup ` * :ref:`BenHW.GetHardwareType ` * :ref:`BenHW.GetLog ` * :ref:`BenHW.GetLogSize ` * :ref:`BenHW.GetMonoItems ` * :ref:`BenHW.GetMinStep ` * :ref:`BenHW.GetMaxBw ` * :ref:`BenHW.GetNoOfDarkCurrents ` * :ref:`BenHW.GetNGroups ` * :ref:`BenHW.GetZeroCalibrationInfo ` * :ref:`BenHW.GroupAdd ` * :ref:`BenHW.GroupRemove ` * :ref:`BenHW.Initialise ` * :ref:`BenHW.LoadSetup ` * :ref:`BenHW.Measurement ` * :ref:`BenHW.MultiAutomeasure ` * :ref:`BenHW.MultiAutorange ` * :ref:`BenHW.MultiGetNoOfDarkCurrents ` * :ref:`BenHW.MultiGetZeroCalibrationInfo ` * :ref:`BenHW.MultiInitialise ` * :ref:`BenHW.MultiMeasurement ` * :ref:`BenHW.MultiPark ` * :ref:`BenHW.MultiSelectWavelength ` * :ref:`BenHW.MultiZeroCalibration ` * :ref:`BenHW.Park ` * :ref:`BenHW.Read ` * :ref:`BenHW.ReportError ` * :ref:`BenHW.SaveSetup ` * :ref:`BenHW.SelectWavelength ` * :ref:`BenHW.Send ` * :ref:`BenHW.Set ` * :ref:`BenHW.SetStr ` * :ref:`BenHW.StartLog ` * :ref:`BenHW.StopLog ` * :ref:`BenHW.Trace ` * :ref:`BenHW.MappedLogging ` * :ref:`BenHW.UseGroup ` * :ref:`BenHW.Version ` * :ref:`BenHW.ZeroCalibration ` * :ref:`BenHW.ScpiQuery ` * :ref:`BenHW.ScpiWrite ` ---- .. _dotnet_Close: ``BenHW.Close`` ~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Close and clean up the system model. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { hw.Close(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void 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. This method wraps the C API function :ref:`BI_close `. Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_Automeasure: ``BenHW.Automeasure`` ~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Perform an automatic measurement with autoranging. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { object reading = hw.Automeasure(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object Automeasure() 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. This method wraps the C API function :ref:`BI_automeasure `. Returns ^^^^^^^ Returns object - Measurement reading value or array Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``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. ---- .. _dotnet_Autorange: ``BenHW.Autorange`` ~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Automatically adjust the detector range. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { hw.Autorange(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void 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. This method wraps the C API function :ref:`BI_autorange `. Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_BuildGroup: ``BenHW.BuildGroup`` ~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Create a new component group. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { hw.BuildGroup(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void BuildGroup() 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. This method wraps the C API function :ref:`BI_build_group `. Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_BuildSystemModel: ``BenHW.BuildSystemModel`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Load and compile a system configuration file. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string config_file = "system.cfg"; object error = hw.BuildSystemModel(config_file); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object BuildSystemModel(string config_file) 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. This method wraps the C API function :ref:`BI_build_system_model `. Parameters ^^^^^^^^^^ * ``config_file`` (string) - Path to the system configuration file Returns ^^^^^^^ Returns object - Error message Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_CloseShutter: ``BenHW.CloseShutter`` ~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Close the monochromator shutter. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { hw.CloseShutter(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void CloseShutter() 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. This method wraps the C API function :ref:`BI_close_shutter `. Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_ComponentSelectWl: ``BenHW.ComponentSelectWl`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Set the wavelength for a specific component. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; double wl = 550.0; object settle = hw.ComponentSelectWl(id, wl); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object ComponentSelectWl(string id, double wl) 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. This method wraps the C API function :ref:`BI_component_select_wl `. Parameters ^^^^^^^^^^ * ``id`` (string) - Component identifier string * ``wl`` (double) - Wavelength value in nanometers Returns ^^^^^^^ Returns object - Settle delay time in milliseconds after wavelength change Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``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. ---- .. _dotnet_CameraMeasurement: ``BenHW.CameraMeasurement`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Take a measurement from a camera/array detector. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; int number = 100; var result = hw.CameraMeasurement(id, number); // result.Wls: Array of wavelength values in nanometers // result.Readings: Array of measurement readings } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp CamerameasurementResult CameraMeasurement(string id, int number) 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. This method wraps the C API function :ref:`BI_camera_measurement `. Parameters ^^^^^^^^^^ * ``id`` (string) - Component identifier string * ``number`` (int) - Number of data points or pixels Returns ^^^^^^^ Returns a ``CamerameasurementResult`` struct containing: * ``Wls`` (object) - Array of wavelength values in nanometers * ``Readings`` (object) - Array of measurement readings Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_CameraGetWls: ``BenHW.CameraGetWls`` ~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get wavelength calibration for camera pixels. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; object wls = hw.CameraGetWls(id); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object CameraGetWls(string id) Description ^^^^^^^^^^^ Retrieves the wavelength corresponding to each pixel of the camera or array detector. This method wraps the C API function :ref:`BI_camera_get_wls `. Parameters ^^^^^^^^^^ * ``id`` (string) - Component identifier string Returns ^^^^^^^ Returns object - Array of wavelength values in nanometers Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_CameraZeroCalibration: ``BenHW.CameraZeroCalibration`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Perform zero calibration for camera detector (obsolete). Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; double start_wl = 400.0; double stop_wl = 800.0; hw.CameraZeroCalibration(id, start_wl, stop_wl); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void CameraZeroCalibration(string 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+. This method wraps the C API function :ref:`BI_camera_zero_calibration `. Parameters ^^^^^^^^^^ * ``id`` (string) - Component identifier string * ``start_wl`` (double) - Starting wavelength for the range in nanometers * ``stop_wl`` (double) - Ending wavelength for the range in nanometers Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_CameraGetZeroCalibrationInfo: ``BenHW.CameraGetZeroCalibrationInfo`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get zero calibration data for camera (obsolete). Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; var result = hw.CameraGetZeroCalibrationInfo(id); // result.Wavelength: Wavelength value in nanometers // result.Darkcurrent: Array of dark current calibration values // result.Adcoffset: Array of ADC offset calibration values } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp CameragetzerocalibrationinfoResult CameraGetZeroCalibrationInfo(string id) Description ^^^^^^^^^^^ Legacy function for retrieving camera zero calibration data. This function is obsolete and does nothing. Kept for backwards compatibility with BenWin+. This method wraps the C API function :ref:`BI_camera_get_zero_calibration_info `. Parameters ^^^^^^^^^^ * ``id`` (string) - Component identifier string Returns ^^^^^^^ Returns a ``CameragetzerocalibrationinfoResult`` struct containing: * ``Wavelength`` (object) - Wavelength value in nanometers * ``Darkcurrent`` (object) - Array of dark current calibration values * ``Adcoffset`` (object) - Array of ADC offset calibration values Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_DeleteGroup: ``BenHW.DeleteGroup`` ~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Delete a component group. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { int n = 1; hw.DeleteGroup(n); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void DeleteGroup(int n) Description ^^^^^^^^^^^ Removes a previously created group. Returns the number of remaining groups. This method wraps the C API function :ref:`BI_delete_group `. Parameters ^^^^^^^^^^ * ``n`` (int) - Group number or count value Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_DisplaySetupWindow: ``BenHW.DisplaySetupWindow`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Show the setup window for a component. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; int hinstance = 0; hw.DisplaySetupWindow(id, hinstance); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void DisplaySetupWindow(string id, int hinstance) Description ^^^^^^^^^^^ Displays the configuration dialog for a hardware component if one is available. Requires a window handle from the calling application. This method wraps the C API function :ref:`BI_display_setup_window `. Parameters ^^^^^^^^^^ * ``id`` (string) - Component identifier string * ``hinstance`` (int) - Window handle for displaying dialog Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``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. ---- .. _dotnet_DisplayAdvancedWindow: ``BenHW.DisplayAdvancedWindow`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Show the advanced setup window for a component. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; int hinstance = 0; hw.DisplayAdvancedWindow(id, hinstance); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void DisplayAdvancedWindow(string 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. This method wraps the C API function :ref:`BI_display_advanced_window `. Parameters ^^^^^^^^^^ * ``id`` (string) - Component identifier string * ``hinstance`` (int) - Window handle for displaying dialog Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``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. ---- .. _dotnet_Get: ``BenHW.Get`` ~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get a numeric attribute value from a component. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; int token = 10; int index = 0; object value = hw.Get(id, token, index); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object Get(string id, int token, int index) 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). This method wraps the C API function :ref:`BI_get `. Parameters ^^^^^^^^^^ * ``id`` (string) - Component identifier string * ``token`` (int) - Token identifier for the attribute to access * ``index`` (int) - Index for multi-value attributes (usually 0 for single values) Returns ^^^^^^^ Returns object - Numeric value to set or retrieve Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``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. ---- .. _dotnet_GetStr: ``BenHW.GetStr`` ~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get a string attribute value from a component. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; int token = 10; int index = 0; object s = hw.GetStr(id, token, index); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object GetStr(string id, int token, int index) 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). This method wraps the C API function :ref:`BI_get_str `. Parameters ^^^^^^^^^^ * ``id`` (string) - Component identifier string * ``token`` (int) - Token identifier for the attribute to access * ``index`` (int) - Index for multi-value attributes (usually 0 for single values) Returns ^^^^^^^ Returns object - String value or buffer for text data Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``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. ---- .. _dotnet_GetCGroup: ``BenHW.GetCGroup`` ~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get the current active group number. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { object n = hw.GetCGroup(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object GetCGroup() Description ^^^^^^^^^^^ Returns the number of the currently active component group. This method wraps the C API function :ref:`BI_get_c_group `. Returns ^^^^^^^ Returns object - Group number or count value Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_GetComponentList: ``BenHW.GetComponentList`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get a comma-separated list of all components. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { object list = hw.GetComponentList(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object GetComponentList() Description ^^^^^^^^^^^ Returns a string containing the IDs of all components in the system, separated by commas. This method wraps the C API function :ref:`BI_get_component_list `. Returns ^^^^^^^ Returns object - Comma-separated list of component IDs Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_GetGroup: ``BenHW.GetGroup`` ~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get the component IDs in a specific group. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { int n = 1; object s = hw.GetGroup(n); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object GetGroup(int n) Description ^^^^^^^^^^^ Returns a comma-separated string of component IDs that belong to the specified group. This method wraps the C API function :ref:`BI_get_group `. Parameters ^^^^^^^^^^ * ``n`` (int) - Group number or count value Returns ^^^^^^^ Returns object - Comma-separated list of component IDs Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_GetHardwareType: ``BenHW.GetHardwareType`` ~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get the hardware type constant for a component. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; object hardwareType = hw.GetHardwareType(id); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object GetHardwareType(string id) 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. This method wraps the C API function :ref:`BI_get_hardware_type `. Parameters ^^^^^^^^^^ * ``id`` (string) - Component identifier string Returns ^^^^^^^ Returns object - Hardware type identifier token constant Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``InvalidComponentException`` - The function was passed a component identifier that does not exist in the system model. ---- .. _dotnet_GetLog: ``BenHW.GetLog`` ~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Retrieve accumulated log messages. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { object log = hw.GetLog(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object GetLog() Description ^^^^^^^^^^^ Gets the log messages that have been accumulated during operation. This method wraps the C API function :ref:`BI_get_log `. Returns ^^^^^^^ Returns object - Bytes containing log content. May contain \r characters. Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_GetLogSize: ``BenHW.GetLogSize`` ~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get the size of accumulated log messages. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { object size = hw.GetLogSize(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object GetLogSize() Description ^^^^^^^^^^^ Returns the number of bytes needed to store the accumulated log messages. Call this before get_log to allocate appropriate buffer size. This method wraps the C API function :ref:`BI_get_log_size `. Returns ^^^^^^^ Returns object - Number of bytes Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_GetMonoItems: ``BenHW.GetMonoItems`` ~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above List components associated with a monochromator. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string monoID = "mono1"; object ItemIDs = hw.GetMonoItems(monoID); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object GetMonoItems(string monoID) Description ^^^^^^^^^^^ Returns a comma-separated list of component IDs that are part of a monochromator (gratings, filters, etc.). Buffer must be pre-allocated. This method wraps the C API function :ref:`BI_get_mono_items `. Parameters ^^^^^^^^^^ * ``monoID`` (string) - Monochromator component identifier Returns ^^^^^^^ Returns object - Comma-separated list of item IDs Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_GetMinStep: ``BenHW.GetMinStep`` ~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get the minimum wavelength step for a wavelength range. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { int group = 1; double start_wl = 400.0; double stop_wl = 800.0; object min_step = hw.GetMinStep(group, start_wl, stop_wl); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object GetMinStep(int group, double start_wl, double stop_wl) Description ^^^^^^^^^^^ Calculates the minimum wavelength increment supported by the system for a given wavelength range. Important for scan planning. This method wraps the C API function :ref:`BI_get_min_step `. 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 Returns ^^^^^^^ Returns object - Minimum wavelength step size in nanometers Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_GetMaxBw: ``BenHW.GetMaxBw`` ~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get the maximum bandwidth for a wavelength range. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { int group = 1; double start_wl = 400.0; double stop_wl = 800.0; object bandwidth = hw.GetMaxBw(group, start_wl, stop_wl); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object GetMaxBw(int group, double start_wl, double stop_wl) Description ^^^^^^^^^^^ Calculates the maximum spectral bandwidth (slit width equivalent) available for a given wavelength range. This method wraps the C API function :ref:`BI_get_max_bw `. 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 Returns ^^^^^^^ Returns object - Spectral bandwidth value Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_GetNoOfDarkCurrents: ``BenHW.GetNoOfDarkCurrents`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get the number of dark current calibration points. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { object NoOfValues = hw.GetNoOfDarkCurrents(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object GetNoOfDarkCurrents() Description ^^^^^^^^^^^ Returns the count of wavelength points in the dark current calibration table for the current group. This method wraps the C API function :ref:`BI_get_no_of_dark_currents `. Returns ^^^^^^^ Returns object - Number of calibration values in the arrays Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_GetNGroups: ``BenHW.GetNGroups`` ~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get the total number of component groups. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { object n = hw.GetNGroups(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object GetNGroups() Description ^^^^^^^^^^^ Returns the count of all component groups that have been created. This method wraps the C API function :ref:`BI_get_n_groups `. Returns ^^^^^^^ Returns object - Group number or count value Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_GetZeroCalibrationInfo: ``BenHW.GetZeroCalibrationInfo`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get zero calibration data for current group. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { var result = hw.GetZeroCalibrationInfo(); // result.Wavelength: Wavelength value in nanometers // result.Darkcurrent: Array of dark current calibration values // result.Adcoffset: Array of ADC offset calibration values } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp GetzerocalibrationinfoResult GetZeroCalibrationInfo() 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. This method wraps the C API function :ref:`BI_get_zero_calibration_info `. Returns ^^^^^^^ Returns a ``GetzerocalibrationinfoResult`` struct containing: * ``Wavelength`` (object) - Wavelength value in nanometers * ``Darkcurrent`` (object) - Array of dark current calibration values * ``Adcoffset`` (object) - Array of ADC offset calibration values Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_GroupAdd: ``BenHW.GroupAdd`` ~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Add a component to a group. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; int n = 1; hw.GroupAdd(id, n); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void GroupAdd(string id, int n) Description ^^^^^^^^^^^ Adds a component (by ID) to an existing group. Components in a group can be controlled together. This method wraps the C API function :ref:`BI_group_add `. Parameters ^^^^^^^^^^ * ``id`` (string) - Component identifier string * ``n`` (int) - Group number or count value Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_GroupRemove: ``BenHW.GroupRemove`` ~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Remove a component from a group. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; int n = 1; hw.GroupRemove(id, n); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void GroupRemove(string id, int n) Description ^^^^^^^^^^^ Removes a component (by ID) from a group. This method wraps the C API function :ref:`BI_group_remove `. Parameters ^^^^^^^^^^ * ``id`` (string) - Component identifier string * ``n`` (int) - Group number or count value Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_Initialise: ``BenHW.Initialise`` ~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Initialize the hardware system. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { hw.Initialise(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void 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. This method wraps the C API function :ref:`BI_initialise `. Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_LoadSetup: ``BenHW.LoadSetup`` ~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Load component settings from a setup file. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string filename = "config.cfg"; hw.LoadSetup(filename); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void LoadSetup(string filename) Description ^^^^^^^^^^^ Loads previously saved component configurations from a setup file. This restores settings like wavelengths, gains, and other parameters. This method wraps the C API function :ref:`BI_load_setup `. Parameters ^^^^^^^^^^ * ``filename`` (string) - Path to the configuration or setup file Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_Measurement: ``BenHW.Measurement`` ~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Take a measurement without autoranging. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { object reading = hw.Measurement(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object Measurement() 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. This method wraps the C API function :ref:`BI_measurement `. Returns ^^^^^^^ Returns object - Measurement reading value or array Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_MultiAutomeasure: ``BenHW.MultiAutomeasure`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Take measurements from all groups with autoranging. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { object reading = hw.MultiAutomeasure(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object MultiAutomeasure() Description ^^^^^^^^^^^ Performs automeasure on all component groups simultaneously. Returns an array of readings, one per group. Array must be pre-allocated. This method wraps the C API function :ref:`BI_multi_automeasure `. Returns ^^^^^^^ Returns object - Measurement reading value or array Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_MultiAutorange: ``BenHW.MultiAutorange`` ~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Auto-range all groups simultaneously. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { hw.MultiAutorange(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void MultiAutorange() Description ^^^^^^^^^^^ Adjusts the amplifier ranges for all component groups at the same time. This method wraps the C API function :ref:`BI_multi_autorange `. Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_MultiGetNoOfDarkCurrents: ``BenHW.MultiGetNoOfDarkCurrents`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get dark current calibration point count for a specific group. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { int group = 1; object NoOfValues = hw.MultiGetNoOfDarkCurrents(group); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object MultiGetNoOfDarkCurrents(int group) Description ^^^^^^^^^^^ Returns the number of wavelength points in the dark current calibration table for the specified group. This method wraps the C API function :ref:`BI_multi_get_no_of_dark_currents `. Parameters ^^^^^^^^^^ * ``group`` (int) - Component group number Returns ^^^^^^^ Returns object - Number of calibration values in the arrays Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_MultiGetZeroCalibrationInfo: ``BenHW.MultiGetZeroCalibrationInfo`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get zero calibration data for a specific group. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { int group = 1; var result = hw.MultiGetZeroCalibrationInfo(group); // result.Wavelength: Wavelength value in nanometers // result.Darkcurrent: Array of dark current calibration values // result.Adcoffset: Array of ADC offset calibration values } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp MultigetzerocalibrationinfoResult MultiGetZeroCalibrationInfo(int group) Description ^^^^^^^^^^^ Retrieves wavelength, dark current, and ADC offset arrays for the specified group. Arrays must be pre-allocated. This method wraps the C API function :ref:`BI_multi_get_zero_calibration_info `. Parameters ^^^^^^^^^^ * ``group`` (int) - Component group number Returns ^^^^^^^ Returns a ``MultigetzerocalibrationinfoResult`` struct containing: * ``Wavelength`` (object) - Wavelength value in nanometers * ``Darkcurrent`` (object) - Array of dark current calibration values * ``Adcoffset`` (object) - Array of ADC offset calibration values Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_MultiInitialise: ``BenHW.MultiInitialise`` ~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Initialize all groups simultaneously. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { hw.MultiInitialise(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void MultiInitialise() Description ^^^^^^^^^^^ Initializes hardware for all component groups at the same time. Faster than initializing each group separately. This method wraps the C API function :ref:`BI_multi_initialise `. Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_MultiMeasurement: ``BenHW.MultiMeasurement`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Take measurements from all groups. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { object reading = hw.MultiMeasurement(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object MultiMeasurement() Description ^^^^^^^^^^^ Takes readings from all component groups simultaneously. Returns an array of readings. Array must be pre-allocated. This method wraps the C API function :ref:`BI_multi_measurement `. Returns ^^^^^^^ Returns object - Measurement reading value or array Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_MultiPark: ``BenHW.MultiPark`` ~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Park all monochromators in all groups. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { hw.MultiPark(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void MultiPark() Description ^^^^^^^^^^^ Moves all monochromators to their park positions across all groups simultaneously. This method wraps the C API function :ref:`BI_multi_park `. Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_MultiSelectWavelength: ``BenHW.MultiSelectWavelength`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Set wavelength for all groups simultaneously. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { double wavelength = 550.0; object settle_delay = hw.MultiSelectWavelength(wavelength); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object MultiSelectWavelength(double wavelength) Description ^^^^^^^^^^^ Changes the wavelength for monochromators in all groups at the same time. Returns the maximum settle delay needed. This method wraps the C API function :ref:`BI_multi_select_wavelength `. Parameters ^^^^^^^^^^ * ``wavelength`` (double) - Wavelength value in nanometers Returns ^^^^^^^ Returns object - Settle delay time in milliseconds after wavelength change Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_MultiZeroCalibration: ``BenHW.MultiZeroCalibration`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Perform zero calibration across a wavelength range for all groups. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { double start_wavelength = 400.0; double stop_wavelength = 800.0; hw.MultiZeroCalibration(start_wavelength, stop_wavelength); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void MultiZeroCalibration(double start_wavelength, double stop_wavelength) Description ^^^^^^^^^^^ Runs zero calibration (dark current and offset measurement) for all groups across the specified wavelength range. This method wraps the C API function :ref:`BI_multi_zero_calibration `. Parameters ^^^^^^^^^^ * ``start_wavelength`` (double) - Starting wavelength for the range in nanometers * ``stop_wavelength`` (double) - Ending wavelength for the range in nanometers Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_Park: ``BenHW.Park`` ~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Park the monochromator in the current group. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { hw.Park(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void Park() Description ^^^^^^^^^^^ Moves the monochromator to its park position (usually a safe wavelength or home position). This method wraps the C API function :ref:`BI_park `. Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_Read: ``BenHW.Read`` ~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Read data from an anonymous device. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { int buffer_size = 256; string id = "mono1"; var result = hw.Read(buffer_size, id); // result.Buffer: Buffer for reading or writing data // result.Chars_read: Number of characters actually read } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp ReadResult Read(int buffer_size, string 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. This method wraps the C API function :ref:`BI_read `. Parameters ^^^^^^^^^^ * ``buffer_size`` (int) - Size of the buffer in bytes * ``id`` (string) - Component identifier string Returns ^^^^^^^ Returns a ``ReadResult`` struct containing: * ``Buffer`` (object) - Buffer for reading or writing data * ``Chars_read`` (object) - Number of characters actually read Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_ReportError: ``BenHW.ReportError`` ~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get the last error code. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { object error_code = hw.ReportError(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object ReportError() 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. This method wraps the C API function :ref:`BI_report_error `. Returns ^^^^^^^ Returns object - Error code ---- .. _dotnet_SaveSetup: ``BenHW.SaveSetup`` ~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Save current component settings to a file. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string filename = "config.cfg"; hw.SaveSetup(filename); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void SaveSetup(string 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. This method wraps the C API function :ref:`BI_save_setup `. Parameters ^^^^^^^^^^ * ``filename`` (string) - Path to the configuration or setup file Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_SelectWavelength: ``BenHW.SelectWavelength`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Set the wavelength for the current group. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { double wl = 550.0; object settle_delay = hw.SelectWavelength(wl); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object SelectWavelength(double wl) 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. This method wraps the C API function :ref:`BI_select_wavelength `. Parameters ^^^^^^^^^^ * ``wl`` (double) - Wavelength value in nanometers Returns ^^^^^^^ Returns object - Settle delay time in milliseconds after wavelength change Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_Send: ``BenHW.Send`` ~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Send a command to an anonymous device. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string msg = "*IDN?"; string id = "mono1"; hw.Send(msg, id); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void Send(string msg, string id) Description ^^^^^^^^^^^ Sends a raw command string to a device like a serial instrument or controller. This method wraps the C API function :ref:`BI_send `. Parameters ^^^^^^^^^^ * ``msg`` (string) - Message string to send or query * ``id`` (string) - Component identifier string Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_Set: ``BenHW.Set`` ~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Set a numeric attribute value for a component. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; int token = 10; int index = 0; double value = 1.0; hw.Set(id, token, index, value); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void Set(string 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). This method wraps the C API function :ref:`BI_set `. Parameters ^^^^^^^^^^ * ``id`` (string) - 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 Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``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. ---- .. _dotnet_SetStr: ``BenHW.SetStr`` ~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Set a string attribute value for a component. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; int token = 10; int index = 0; string s = "mono1"; hw.SetStr(id, token, index, s); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void SetStr(string id, int token, int index, string s) Description ^^^^^^^^^^^ Sets a string attribute on a hardware component. Use tokens to specify which attribute to set. This method wraps the C API function :ref:`BI_set_str `. Parameters ^^^^^^^^^^ * ``id`` (string) - 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`` (string) - String value or buffer for text data Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``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. ---- .. _dotnet_StartLog: ``BenHW.StartLog`` ~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Start logging for specified components. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string c_list = "mono1,adc1"; hw.StartLog(c_list); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void StartLog(string c_list) Description ^^^^^^^^^^^ Begins accumulating log messages for the specified comma-separated list of component IDs. Useful for debugging and diagnostics. This method wraps the C API function :ref:`BI_start_log `. Parameters ^^^^^^^^^^ * ``c_list`` (string) - Comma-separated list of component IDs Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_StopLog: ``BenHW.StopLog`` ~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Stop logging for specified components. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string c_list = "mono1,adc1"; hw.StopLog(c_list); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void StopLog(string c_list) Description ^^^^^^^^^^^ Stops accumulating log messages for the specified components. This method wraps the C API function :ref:`BI_stop_log `. Parameters ^^^^^^^^^^ * ``c_list`` (string) - Comma-separated list of component IDs Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_Trace: ``BenHW.Trace`` ~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Enable or disable trace logging. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { int i = 1; string LoggingDir = "logs"; hw.Trace(i, LoggingDir); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void Trace(int i, string 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. This method wraps the C API function :ref:`BI_trace `. Parameters ^^^^^^^^^^ * ``i`` (int) - Integer flag or control value (0=off, 1=on) * ``LoggingDir`` (string) - Directory path for logging output Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_MappedLogging: ``BenHW.MappedLogging`` ~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Enable or disable mapped logging. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { int i = 1; hw.MappedLogging(i); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void MappedLogging(int i) Description ^^^^^^^^^^^ Controls whether motor position logging uses mapped values. Pass 1 to enable, 0 to disable. This method wraps the C API function :ref:`BI_Mapped_Logging `. Parameters ^^^^^^^^^^ * ``i`` (int) - Integer flag or control value (0=off, 1=on) ---- .. _dotnet_UseGroup: ``BenHW.UseGroup`` ~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Set the current active group. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { int n = 1; hw.UseGroup(n); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void UseGroup(int n) Description ^^^^^^^^^^^ Changes which component group is active. Subsequent operations will apply to this group. This method wraps the C API function :ref:`BI_use_group `. Parameters ^^^^^^^^^^ * ``n`` (int) - Group number or count value Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_Version: ``BenHW.Version`` ~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Get the DLL version string. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { object s = hw.Version(); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object Version() 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). This method wraps the C API function :ref:`BI_version `. Returns ^^^^^^^ Returns object - String value or buffer for text data ---- .. _dotnet_ZeroCalibration: ``BenHW.ZeroCalibration`` ~~~~~~~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Perform zero calibration across a wavelength range. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { double start_wl = 400.0; double stop_wl = 800.0; hw.ZeroCalibration(start_wl, stop_wl); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void ZeroCalibration(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. This method wraps the C API function :ref:`BI_zero_calibration `. Parameters ^^^^^^^^^^ * ``start_wl`` (double) - Starting wavelength for the range in nanometers * ``stop_wl`` (double) - Ending wavelength for the range in nanometers Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_ScpiQuery: ``BenHW.ScpiQuery`` ~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Send a SCPI query command and read response. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string id = "mono1"; string msg = "*IDN?"; int reply_size = 256; object reply = hw.ScpiQuery(id, msg, reply_size); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp object ScpiQuery(string id, string msg, 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. This method wraps the C API function :ref:`BI_SCPI_query `. Parameters ^^^^^^^^^^ * ``id`` (string) - Component identifier string * ``msg`` (string) - Message string to send or query * ``reply_size`` (int) - Maximum size of reply buffer in bytes Returns ^^^^^^^ Returns object - Buffer to receive reply data Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ---- .. _dotnet_ScpiWrite: ``BenHW.ScpiWrite`` ~~~~~~~~~~~~~~~~~~~ DLL versions ``4.4.13`` and above Send a SCPI write command. Example ^^^^^^^ .. code-block:: csharp using BenHW; using (var hw = new BenHW.BenHW()) { try { string msg = "*IDN?"; string id = "mono1"; hw.ScpiWrite(msg, id); } catch (SdkException ex) { Console.WriteLine($"Error: {ex.Message}"); } } Signature ^^^^^^^^^ .. code-block:: csharp void ScpiWrite(string msg, string id) Description ^^^^^^^^^^^ Sends a SCPI (Standard Commands for Programmable Instruments) command to a USB SCPI device without expecting a response. This method wraps the C API function :ref:`BI_SCPI_write `. Parameters ^^^^^^^^^^ * ``msg`` (string) - Message string to send or query * ``id`` (string) - Component identifier string Exceptions ^^^^^^^^^^ This method may throw the following exceptions: * ``BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code. ----