C++ API
=======

This section documents the C++ object-oriented interface to the BenHW SDK: ``benhw.hpp``.

``benhw.hpp`` is a thin object-oriented wrapper around the flat :doc:`C API <c_api>` declared in
``benhw.h``: each ``benhw::BenHW`` method calls the corresponding ``BI_xxx()`` function, converts
between the C API's raw types (``char*``, ``double*``, ``int*``, ``uint16_t*``) and convenient C++
types (``std::string``, ``std::vector<double>``), and throws an exception instead of returning an
error code - mirroring the design of the Python and .NET SDKs. Both headers are included in the
same Conan package: C users can include just ``benhw.h``, while C++ users can additionally include
``benhw.hpp`` for the object-oriented interface.

The SDK is distributed as a Conan2 package on Cloudsmith. After installing Conan, add the
Cloudsmith remote:

.. code-block:: bash

   conan remote add bentham-ec1i-public https://conan.cloudsmith.io/bentham-ec1i/public/

Then add the package to your ``conanfile.txt``:

.. code-block:: ini

   [requires]
   benhw/0.6.0

   [generators]
   CMakeDeps
   CMakeToolchain

The package is header-only (no import library): the runtime DLLs are bundled alongside the headers
and are dynamically loaded, so no separate DLL installation is required.

The main interface to the BenHW SDK is through the ``benhw::BenHW`` class, which provides methods
corresponding to each C API function.

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw; // automatically locates and loads the bundled BenHW DLL

   try {
       std::string dll_version = 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);
       double reading = hw.automeasure();
       std::cout << reading << "\n";
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }
   // The DLL is automatically unloaded when hw goes out of scope

If your own code has already loaded the BenHW DLL - e.g. via ``LoadLibrary(_T("benhw32.dll"))`` -
construct ``benhw::BenHW`` from that ``HMODULE`` instead, to attach to it directly rather than
loading the DLL a second time:

.. code-block:: cpp

   HMODULE module = LoadLibrary(_T("benhw32.dll")); // your own code's existing load
   benhw::BenHW hw(module);
   // ... use hw as normal ...
   // hw's destructor will NOT call FreeLibrary on `module` - you retain ownership
   // and are responsible for freeing it yourself, if appropriate.


* :ref:`BenHW.close <cpp_close>`
* :ref:`BenHW.automeasure <cpp_automeasure>`
* :ref:`BenHW.autorange <cpp_autorange>`
* :ref:`BenHW.build_group <cpp_build_group>`
* :ref:`BenHW.build_system_model <cpp_build_system_model>`
* :ref:`BenHW.close_shutter <cpp_close_shutter>`
* :ref:`BenHW.component_select_wl <cpp_component_select_wl>`
* :ref:`BenHW.camera_measurement <cpp_camera_measurement>`
* :ref:`BenHW.camera_get_wls <cpp_camera_get_wls>`
* :ref:`BenHW.camera_zero_calibration <cpp_camera_zero_calibration>`
* :ref:`BenHW.camera_get_zero_calibration_info <cpp_camera_get_zero_calibration_info>`
* :ref:`BenHW.delete_group <cpp_delete_group>`
* :ref:`BenHW.display_setup_window <cpp_display_setup_window>`
* :ref:`BenHW.display_advanced_window <cpp_display_advanced_window>`
* :ref:`BenHW.get <cpp_get>`
* :ref:`BenHW.get_str <cpp_get_str>`
* :ref:`BenHW.get_c_group <cpp_get_c_group>`
* :ref:`BenHW.get_component_list <cpp_get_component_list>`
* :ref:`BenHW.get_group <cpp_get_group>`
* :ref:`BenHW.get_hardware_type <cpp_get_hardware_type>`
* :ref:`BenHW.get_log <cpp_get_log>`
* :ref:`BenHW.get_log_size <cpp_get_log_size>`
* :ref:`BenHW.get_mono_items <cpp_get_mono_items>`
* :ref:`BenHW.get_min_step <cpp_get_min_step>`
* :ref:`BenHW.get_max_bw <cpp_get_max_bw>`
* :ref:`BenHW.get_no_of_dark_currents <cpp_get_no_of_dark_currents>`
* :ref:`BenHW.get_n_groups <cpp_get_n_groups>`
* :ref:`BenHW.get_zero_calibration_info <cpp_get_zero_calibration_info>`
* :ref:`BenHW.group_add <cpp_group_add>`
* :ref:`BenHW.group_remove <cpp_group_remove>`
* :ref:`BenHW.initialise <cpp_initialise>`
* :ref:`BenHW.load_setup <cpp_load_setup>`
* :ref:`BenHW.measurement <cpp_measurement>`
* :ref:`BenHW.multi_automeasure <cpp_multi_automeasure>`
* :ref:`BenHW.multi_autorange <cpp_multi_autorange>`
* :ref:`BenHW.multi_get_no_of_dark_currents <cpp_multi_get_no_of_dark_currents>`
* :ref:`BenHW.multi_get_zero_calibration_info <cpp_multi_get_zero_calibration_info>`
* :ref:`BenHW.multi_initialise <cpp_multi_initialise>`
* :ref:`BenHW.multi_measurement <cpp_multi_measurement>`
* :ref:`BenHW.multi_park <cpp_multi_park>`
* :ref:`BenHW.multi_select_wavelength <cpp_multi_select_wavelength>`
* :ref:`BenHW.multi_zero_calibration <cpp_multi_zero_calibration>`
* :ref:`BenHW.park <cpp_park>`
* :ref:`BenHW.read <cpp_read>`
* :ref:`BenHW.report_error <cpp_report_error>`
* :ref:`BenHW.save_setup <cpp_save_setup>`
* :ref:`BenHW.select_wavelength <cpp_select_wavelength>`
* :ref:`BenHW.send <cpp_send>`
* :ref:`BenHW.set <cpp_set>`
* :ref:`BenHW.set_str <cpp_set_str>`
* :ref:`BenHW.start_log <cpp_start_log>`
* :ref:`BenHW.stop_log <cpp_stop_log>`
* :ref:`BenHW.trace <cpp_trace>`
* :ref:`BenHW.Mapped_Logging <cpp_Mapped_Logging>`
* :ref:`BenHW.use_group <cpp_use_group>`
* :ref:`BenHW.version <cpp_version>`
* :ref:`BenHW.zero_calibration <cpp_zero_calibration>`
* :ref:`BenHW.SCPI_query <cpp_SCPI_query>`
* :ref:`BenHW.SCPI_write <cpp_SCPI_write>`
----


.. _cpp_close:

``BenHW.close``
~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Close and clean up the system model.

Signature
^^^^^^^^^

.. code-block:: cpp

   void close()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       hw.close();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_close>`.



Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_automeasure:

``BenHW.automeasure``
~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Perform an automatic measurement with autoranging.

Signature
^^^^^^^^^

.. code-block:: cpp

   double automeasure()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       double reading = hw.automeasure();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_automeasure>`.


Returns
^^^^^^^

Returns ``double`` - Measurement reading value or array

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::AdcOverloadException`` - Analogue-digital Converter (ADC) overload detected - the input signal is too strong for the current range setting.
* ``benhw::AdcReadErrorException`` - Analogue-digital Converter (ADC) is not responding or failed to complete a read operation.
* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_autorange:

``BenHW.autorange``
~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Automatically adjust the detector range.

Signature
^^^^^^^^^

.. code-block:: cpp

   void autorange()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       hw.autorange();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_autorange>`.



Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_build_group:

``BenHW.build_group``
~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Create a new component group.

Signature
^^^^^^^^^

.. code-block:: cpp

   int build_group()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       hw.build_group();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_build_group>`.



Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_build_system_model:

``BenHW.build_system_model``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Load and compile a system configuration file.

Signature
^^^^^^^^^

.. code-block:: cpp

   std::string build_system_model(const std::string& config_file)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string config_file = "system.cfg";

       std::string error = hw.build_system_model(config_file);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_build_system_model>`.

Parameters
^^^^^^^^^^

* ``config_file`` (``const std::string&``) - Path to the system configuration file

Returns
^^^^^^^

Returns ``std::string`` - Error message

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_close_shutter:

``BenHW.close_shutter``
~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Close the monochromator shutter.

Signature
^^^^^^^^^

.. code-block:: cpp

   void close_shutter()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       hw.close_shutter();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_close_shutter>`.



Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_component_select_wl:

``BenHW.component_select_wl``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Set the wavelength for a specific component.

Signature
^^^^^^^^^

.. code-block:: cpp

   int component_select_wl(const std::string& id, double wl)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";
       double wl = 550.0;

       int settle = hw.component_select_wl(id, wl);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_component_select_wl>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::string&``) - Component identifier string
* ``wl`` (``double``) - Wavelength value in nanometers

Returns
^^^^^^^

Returns ``int`` - Settle delay time in milliseconds after wavelength change

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.
* ``benhw::InvalidComponentException`` - The function was passed a component identifier that does not exist in the system model.

----


.. _cpp_camera_measurement:

``BenHW.camera_measurement``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Take a measurement from a camera/array detector.

Signature
^^^^^^^^^

.. code-block:: cpp

   camera_measurement_result camera_measurement(const std::string& id, int number)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";
       int number = 100;

       auto result = hw.camera_measurement(id, number);
       // result.wls: Array of wavelength values in nanometers
       // result.readings: Array of measurement readings

   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_camera_measurement>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::string&``) - Component identifier string
* ``number`` (``int``) - Number of data points or pixels

Returns
^^^^^^^

Returns a ``camera_measurement_result`` struct containing:

* ``wls`` (``std::vector<double>``) - Array of wavelength values in nanometers
* ``readings`` (``std::vector<double>``) - Array of measurement readings

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_camera_get_wls:

``BenHW.camera_get_wls``
~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get wavelength calibration for camera pixels.

Signature
^^^^^^^^^

.. code-block:: cpp

   std::vector<double> camera_get_wls(const std::string& id)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";

       std::vector<double> wls = hw.camera_get_wls(id);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_camera_get_wls>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::string&``) - Component identifier string

Returns
^^^^^^^

Returns ``std::vector<double>`` - Array of wavelength values in nanometers

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_camera_zero_calibration:

``BenHW.camera_zero_calibration``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Perform zero calibration for camera detector (obsolete).

Signature
^^^^^^^^^

.. code-block:: cpp

   void camera_zero_calibration(const std::string& id, double start_wl, double stop_wl)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";
       double start_wl = 400.0;
       double stop_wl = 800.0;

       hw.camera_zero_calibration(id, start_wl, stop_wl);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_camera_zero_calibration>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::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 (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_camera_get_zero_calibration_info:

``BenHW.camera_get_zero_calibration_info``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get zero calibration data for camera (obsolete).

Signature
^^^^^^^^^

.. code-block:: cpp

   camera_get_zero_calibration_info_result camera_get_zero_calibration_info(const std::string& id)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";

       auto result = hw.camera_get_zero_calibration_info(id);
       // result.wavelength: Wavelength value in nanometers
       // result.DarkCurrent: Array of dark current calibration values
       // result.ADCOffset: Array of ADC offset calibration values

   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_camera_get_zero_calibration_info>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::string&``) - Component identifier string

Returns
^^^^^^^

Returns a ``camera_get_zero_calibration_info_result`` struct containing:

* ``wavelength`` (``std::vector<double>``) - Wavelength value in nanometers
* ``DarkCurrent`` (``std::vector<double>``) - Array of dark current calibration values
* ``ADCOffset`` (``std::vector<double>``) - Array of ADC offset calibration values

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_delete_group:

``BenHW.delete_group``
~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Delete a component group.

Signature
^^^^^^^^^

.. code-block:: cpp

   int delete_group(int n)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int n = 1;

       hw.delete_group(n);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

Description
^^^^^^^^^^^

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

This method wraps the C API function :ref:`BI_delete_group <c_BI_delete_group>`.

Parameters
^^^^^^^^^^

* ``n`` (``int``) - Group number or count value


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_display_setup_window:

``BenHW.display_setup_window``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Show the setup window for a component.

Signature
^^^^^^^^^

.. code-block:: cpp

   void display_setup_window(const std::string& id, int hinstance)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";
       int hinstance = 0;

       hw.display_setup_window(id, hinstance);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_display_setup_window>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::string&``) - Component identifier string
* ``hinstance`` (``int``) - Window handle for displaying dialog


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::InvalidComponentException`` - The function was passed a component identifier that does not exist in the system model.
* ``benhw::NoSetupWindowException`` - No setup window is available for the specified component.

----


.. _cpp_display_advanced_window:

``BenHW.display_advanced_window``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Show the advanced setup window for a component.

Signature
^^^^^^^^^

.. code-block:: cpp

   void display_advanced_window(const std::string& id, int hinstance)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";
       int hinstance = 0;

       hw.display_advanced_window(id, hinstance);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_display_advanced_window>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::string&``) - Component identifier string
* ``hinstance`` (``int``) - Window handle for displaying dialog


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::InvalidComponentException`` - The function was passed a component identifier that does not exist in the system model.
* ``benhw::NoSetupWindowException`` - No setup window is available for the specified component.

----


.. _cpp_get:

``BenHW.get``
~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get a numeric attribute value from a component.

Signature
^^^^^^^^^

.. code-block:: cpp

   double get(const std::string& id, int token, int index)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";
       int token = 10;
       int index = 0;

       double value = hw.get(id, token, index);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_get>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::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 ``double`` - Numeric value to set or retrieve

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.
* ``benhw::InvalidAttributeException`` - The function was passed an attribute token referring to an attribute that does not exist or is inaccessible for the specified component.
* ``benhw::InvalidComponentException`` - The function was passed a component identifier that does not exist in the system model.
* ``benhw::InvalidTokenException`` - The function was passed an invalid attribute token that is not recognized.

----


.. _cpp_get_str:

``BenHW.get_str``
~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get a string attribute value from a component.

Signature
^^^^^^^^^

.. code-block:: cpp

   std::string get_str(const std::string& id, int token, int index)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";
       int token = 10;
       int index = 0;

       std::string s = hw.get_str(id, token, index);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_get_str>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::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 ``std::string`` - String value or buffer for text data

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.
* ``benhw::InvalidAttributeException`` - The function was passed an attribute token referring to an attribute that does not exist or is inaccessible for the specified component.
* ``benhw::InvalidComponentException`` - The function was passed a component identifier that does not exist in the system model.
* ``benhw::InvalidTokenException`` - The function was passed an invalid attribute token that is not recognized.

----


.. _cpp_get_c_group:

``BenHW.get_c_group``
~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get the current active group number.

Signature
^^^^^^^^^

.. code-block:: cpp

   int get_c_group()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int n = hw.get_c_group();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

Description
^^^^^^^^^^^

Returns the number of the currently active component group.

This method wraps the C API function :ref:`BI_get_c_group <c_BI_get_c_group>`.


Returns
^^^^^^^

Returns ``int`` - Group number or count value

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_get_component_list:

``BenHW.get_component_list``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get a comma-separated list of all components.

Signature
^^^^^^^^^

.. code-block:: cpp

   std::string get_component_list()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string list = hw.get_component_list();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_get_component_list>`.


Returns
^^^^^^^

Returns ``std::string`` - Comma-separated list of component IDs

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_get_group:

``BenHW.get_group``
~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get the component IDs in a specific group.

Signature
^^^^^^^^^

.. code-block:: cpp

   std::string get_group(int n)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int n = 1;

       std::string s = hw.get_group(n);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\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 <c_BI_get_group>`.

Parameters
^^^^^^^^^^

* ``n`` (``int``) - Group number or count value

Returns
^^^^^^^

Returns ``std::string`` - Comma-separated list of component IDs

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_get_hardware_type:

``BenHW.get_hardware_type``
~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get the hardware type constant for a component.

Signature
^^^^^^^^^

.. code-block:: cpp

   int get_hardware_type(const std::string& id)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";

       int hardwareType = hw.get_hardware_type(id);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_get_hardware_type>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::string&``) - Component identifier string

Returns
^^^^^^^

Returns ``int`` - Hardware type identifier token constant

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::InvalidComponentException`` - The function was passed a component identifier that does not exist in the system model.

----


.. _cpp_get_log:

``BenHW.get_log``
~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Retrieve accumulated log messages.

Signature
^^^^^^^^^

.. code-block:: cpp

   std::vector<unsigned char> get_log()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::vector<unsigned char> log = hw.get_log();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

Description
^^^^^^^^^^^

Gets the log messages that have been accumulated during operation.

This method wraps the C API function :ref:`BI_get_log <c_BI_get_log>`.


Returns
^^^^^^^

Returns ``std::vector<unsigned char>`` - Bytes containing log content. May contain \r characters.

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_get_log_size:

``BenHW.get_log_size``
~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get the size of accumulated log messages.

Signature
^^^^^^^^^

.. code-block:: cpp

   int get_log_size()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int size = hw.get_log_size();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_get_log_size>`.


Returns
^^^^^^^

Returns ``int`` - Number of bytes

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_get_mono_items:

``BenHW.get_mono_items``
~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

List components associated with a monochromator.

Signature
^^^^^^^^^

.. code-block:: cpp

   std::string get_mono_items(const std::string& monoID)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string monoID = "mono1";

       std::string ItemIDs = hw.get_mono_items(monoID);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_get_mono_items>`.

Parameters
^^^^^^^^^^

* ``monoID`` (``const std::string&``) - Monochromator component identifier

Returns
^^^^^^^

Returns ``std::string`` - Comma-separated list of item IDs

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_get_min_step:

``BenHW.get_min_step``
~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get the minimum wavelength step for a wavelength range.

Signature
^^^^^^^^^

.. code-block:: cpp

   double get_min_step(int group, double start_wl, double stop_wl)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int group = 1;
       double start_wl = 400.0;
       double stop_wl = 800.0;

       double min_step = hw.get_min_step(group, start_wl, stop_wl);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_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 ``double`` - Minimum wavelength step size in nanometers

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_get_max_bw:

``BenHW.get_max_bw``
~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get the maximum bandwidth for a wavelength range.

Signature
^^^^^^^^^

.. code-block:: cpp

   double get_max_bw(int group, double start_wl, double stop_wl)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int group = 1;
       double start_wl = 400.0;
       double stop_wl = 800.0;

       double bandwidth = hw.get_max_bw(group, start_wl, stop_wl);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_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 ``double`` - Spectral bandwidth value

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_get_no_of_dark_currents:

``BenHW.get_no_of_dark_currents``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get the number of dark current calibration points.

Signature
^^^^^^^^^

.. code-block:: cpp

   int get_no_of_dark_currents()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int NoOfValues = hw.get_no_of_dark_currents();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_get_no_of_dark_currents>`.


Returns
^^^^^^^

Returns ``int`` - Number of calibration values in the arrays

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_get_n_groups:

``BenHW.get_n_groups``
~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get the total number of component groups.

Signature
^^^^^^^^^

.. code-block:: cpp

   int get_n_groups()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int n = hw.get_n_groups();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

Description
^^^^^^^^^^^

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

This method wraps the C API function :ref:`BI_get_n_groups <c_BI_get_n_groups>`.


Returns
^^^^^^^

Returns ``int`` - Group number or count value

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_get_zero_calibration_info:

``BenHW.get_zero_calibration_info``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get zero calibration data for current group.

Signature
^^^^^^^^^

.. code-block:: cpp

   get_zero_calibration_info_result get_zero_calibration_info()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       auto result = hw.get_zero_calibration_info();
       // result.wavelength: Wavelength value in nanometers
       // result.DarkCurrent: Array of dark current calibration values
       // result.ADCOffset: Array of ADC offset calibration values

   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_get_zero_calibration_info>`.


Returns
^^^^^^^

Returns a ``get_zero_calibration_info_result`` struct containing:

* ``wavelength`` (``std::vector<double>``) - Wavelength value in nanometers
* ``DarkCurrent`` (``std::vector<double>``) - Array of dark current calibration values
* ``ADCOffset`` (``std::vector<double>``) - Array of ADC offset calibration values

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_group_add:

``BenHW.group_add``
~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Add a component to a group.

Signature
^^^^^^^^^

.. code-block:: cpp

   void group_add(const std::string& id, int n)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";
       int n = 1;

       hw.group_add(id, n);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\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 <c_BI_group_add>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::string&``) - Component identifier string
* ``n`` (``int``) - Group number or count value


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_group_remove:

``BenHW.group_remove``
~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Remove a component from a group.

Signature
^^^^^^^^^

.. code-block:: cpp

   void group_remove(const std::string& id, int n)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";
       int n = 1;

       hw.group_remove(id, n);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

Description
^^^^^^^^^^^

Removes a component (by ID) from a group.

This method wraps the C API function :ref:`BI_group_remove <c_BI_group_remove>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::string&``) - Component identifier string
* ``n`` (``int``) - Group number or count value


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_initialise:

``BenHW.initialise``
~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Initialize the hardware system.

Signature
^^^^^^^^^

.. code-block:: cpp

   void initialise()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       hw.initialise();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_initialise>`.



Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_load_setup:

``BenHW.load_setup``
~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Load component settings from a setup file.

Signature
^^^^^^^^^

.. code-block:: cpp

   void load_setup(const std::string& filename)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string filename = "config.cfg";

       hw.load_setup(filename);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_load_setup>`.

Parameters
^^^^^^^^^^

* ``filename`` (``const std::string&``) - Path to the configuration or setup file


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_measurement:

``BenHW.measurement``
~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Take a measurement without autoranging.

Signature
^^^^^^^^^

.. code-block:: cpp

   double measurement()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       double reading = hw.measurement();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_measurement>`.


Returns
^^^^^^^

Returns ``double`` - Measurement reading value or array

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_multi_automeasure:

``BenHW.multi_automeasure``
~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Take measurements from all groups with autoranging.

Signature
^^^^^^^^^

.. code-block:: cpp

   std::vector<double> multi_automeasure()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::vector<double> reading = hw.multi_automeasure();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_multi_automeasure>`.


Returns
^^^^^^^

Returns ``std::vector<double>`` - Measurement reading value or array

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_multi_autorange:

``BenHW.multi_autorange``
~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Auto-range all groups simultaneously.

Signature
^^^^^^^^^

.. code-block:: cpp

   void multi_autorange()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       hw.multi_autorange();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

Description
^^^^^^^^^^^

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

This method wraps the C API function :ref:`BI_multi_autorange <c_BI_multi_autorange>`.



Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_multi_get_no_of_dark_currents:

``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
^^^^^^^^^

.. code-block:: cpp

   int multi_get_no_of_dark_currents(int group)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int group = 1;

       int NoOfValues = hw.multi_get_no_of_dark_currents(group);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_multi_get_no_of_dark_currents>`.

Parameters
^^^^^^^^^^

* ``group`` (``int``) - Component group number

Returns
^^^^^^^

Returns ``int`` - Number of calibration values in the arrays

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_multi_get_zero_calibration_info:

``BenHW.multi_get_zero_calibration_info``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get zero calibration data for a specific group.

Signature
^^^^^^^^^

.. code-block:: cpp

   multi_get_zero_calibration_info_result multi_get_zero_calibration_info(int group)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int group = 1;

       auto result = hw.multi_get_zero_calibration_info(group);
       // result.wavelength: Wavelength value in nanometers
       // result.DarkCurrent: Array of dark current calibration values
       // result.ADCOffset: Array of ADC offset calibration values

   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_multi_get_zero_calibration_info>`.

Parameters
^^^^^^^^^^

* ``group`` (``int``) - Component group number

Returns
^^^^^^^

Returns a ``multi_get_zero_calibration_info_result`` struct containing:

* ``wavelength`` (``std::vector<double>``) - Wavelength value in nanometers
* ``DarkCurrent`` (``std::vector<double>``) - Array of dark current calibration values
* ``ADCOffset`` (``std::vector<double>``) - Array of ADC offset calibration values

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_multi_initialise:

``BenHW.multi_initialise``
~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Initialize all groups simultaneously.

Signature
^^^^^^^^^

.. code-block:: cpp

   void multi_initialise()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       hw.multi_initialise();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_multi_initialise>`.



Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_multi_measurement:

``BenHW.multi_measurement``
~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Take measurements from all groups.

Signature
^^^^^^^^^

.. code-block:: cpp

   std::vector<double> multi_measurement()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::vector<double> reading = hw.multi_measurement();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_multi_measurement>`.


Returns
^^^^^^^

Returns ``std::vector<double>`` - Measurement reading value or array

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_multi_park:

``BenHW.multi_park``
~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Park all monochromators in all groups.

Signature
^^^^^^^^^

.. code-block:: cpp

   void multi_park()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       hw.multi_park();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

Description
^^^^^^^^^^^

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

This method wraps the C API function :ref:`BI_multi_park <c_BI_multi_park>`.



Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_multi_select_wavelength:

``BenHW.multi_select_wavelength``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Set wavelength for all groups simultaneously.

Signature
^^^^^^^^^

.. code-block:: cpp

   int multi_select_wavelength(double wavelength)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       double wavelength = 550.0;

       int settle_delay = hw.multi_select_wavelength(wavelength);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_multi_select_wavelength>`.

Parameters
^^^^^^^^^^

* ``wavelength`` (``double``) - Wavelength value in nanometers

Returns
^^^^^^^

Returns ``int`` - Settle delay time in milliseconds after wavelength change

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_multi_zero_calibration:

``BenHW.multi_zero_calibration``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Perform zero calibration across a wavelength range for all groups.

Signature
^^^^^^^^^

.. code-block:: cpp

   void multi_zero_calibration(double start_wavelength, double stop_wavelength)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       double start_wavelength = 400.0;
       double stop_wavelength = 800.0;

       hw.multi_zero_calibration(start_wavelength, stop_wavelength);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_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 (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_park:

``BenHW.park``
~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Park the monochromator in the current group.

Signature
^^^^^^^^^

.. code-block:: cpp

   void park()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       hw.park();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_park>`.



Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_read:

``BenHW.read``
~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Read data from an anonymous device.

Signature
^^^^^^^^^

.. code-block:: cpp

   read_result read(uint16_t buffer_size, const std::string& id)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int buffer_size = 256;
       std::string id = "mono1";

       auto result = hw.read(buffer_size, id);
       // result.buffer: Buffer for reading or writing data
       // result.chars_read: Number of characters actually read

   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_read>`.

Parameters
^^^^^^^^^^

* ``buffer_size`` (``uint16_t``) - Size of the buffer in bytes
* ``id`` (``const std::string&``) - Component identifier string

Returns
^^^^^^^

Returns a ``read_result`` struct containing:

* ``buffer`` (``std::vector<unsigned char>``) - Buffer for reading or writing data
* ``chars_read`` (``int``) - Number of characters actually read

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_report_error:

``BenHW.report_error``
~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get the last error code.

Signature
^^^^^^^^^

.. code-block:: cpp

   int report_error()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int error_code = hw.report_error();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_report_error>`.


Returns
^^^^^^^

Returns ``int`` - Error code


----


.. _cpp_save_setup:

``BenHW.save_setup``
~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Save current component settings to a file.

Signature
^^^^^^^^^

.. code-block:: cpp

   void save_setup(const std::string& filename)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string filename = "config.cfg";

       hw.save_setup(filename);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_save_setup>`.

Parameters
^^^^^^^^^^

* ``filename`` (``const std::string&``) - Path to the configuration or setup file


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_select_wavelength:

``BenHW.select_wavelength``
~~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Set the wavelength for the current group.

Signature
^^^^^^^^^

.. code-block:: cpp

   int select_wavelength(double wl)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       double wl = 550.0;

       int settle_delay = hw.select_wavelength(wl);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_select_wavelength>`.

Parameters
^^^^^^^^^^

* ``wl`` (``double``) - Wavelength value in nanometers

Returns
^^^^^^^

Returns ``int`` - Settle delay time in milliseconds after wavelength change

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_send:

``BenHW.send``
~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Send a command to an anonymous device.

Signature
^^^^^^^^^

.. code-block:: cpp

   void send(const std::string& msg, const std::string& id)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string msg = "*IDN?";
       std::string id = "mono1";

       hw.send(msg, id);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_send>`.

Parameters
^^^^^^^^^^

* ``msg`` (``const std::string&``) - Message string to send or query
* ``id`` (``const std::string&``) - Component identifier string


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_set:

``BenHW.set``
~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Set a numeric attribute value for a component.

Signature
^^^^^^^^^

.. code-block:: cpp

   void set(const std::string& id, int token, int index, double value)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";
       int token = 10;
       int index = 0;
       double value = 1.0;

       hw.set(id, token, index, value);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_set>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::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 (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.
* ``benhw::InvalidAttributeException`` - The function was passed an attribute token referring to an attribute that does not exist or is inaccessible for the specified component.
* ``benhw::InvalidComponentException`` - The function was passed a component identifier that does not exist in the system model.
* ``benhw::InvalidTokenException`` - The function was passed an invalid attribute token that is not recognized.

----


.. _cpp_set_str:

``BenHW.set_str``
~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Set a string attribute value for a component.

Signature
^^^^^^^^^

.. code-block:: cpp

   void set_str(const std::string& id, int token, int index, const std::string& s)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";
       int token = 10;
       int index = 0;
       std::string s = "mono1";

       hw.set_str(id, token, index, s);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_set_str>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::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`` (``const std::string&``) - String value or buffer for text data


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.
* ``benhw::InvalidAttributeException`` - The function was passed an attribute token referring to an attribute that does not exist or is inaccessible for the specified component.
* ``benhw::InvalidComponentException`` - The function was passed a component identifier that does not exist in the system model.
* ``benhw::InvalidTokenException`` - The function was passed an invalid attribute token that is not recognized.

----


.. _cpp_start_log:

``BenHW.start_log``
~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Start logging for specified components.

Signature
^^^^^^^^^

.. code-block:: cpp

   void start_log(const std::string& c_list)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string c_list = "mono1,adc1";

       hw.start_log(c_list);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_start_log>`.

Parameters
^^^^^^^^^^

* ``c_list`` (``const std::string&``) - Comma-separated list of component IDs


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_stop_log:

``BenHW.stop_log``
~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Stop logging for specified components.

Signature
^^^^^^^^^

.. code-block:: cpp

   void stop_log(const std::string& c_list)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string c_list = "mono1,adc1";

       hw.stop_log(c_list);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

Description
^^^^^^^^^^^

Stops accumulating log messages for the specified components.

This method wraps the C API function :ref:`BI_stop_log <c_BI_stop_log>`.

Parameters
^^^^^^^^^^

* ``c_list`` (``const std::string&``) - Comma-separated list of component IDs


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_trace:

``BenHW.trace``
~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Enable or disable trace logging.

Signature
^^^^^^^^^

.. code-block:: cpp

   void trace(int i, const std::string& LoggingDir)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int i = 1;
       std::string LoggingDir = "logs";

       hw.trace(i, LoggingDir);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_trace>`.

Parameters
^^^^^^^^^^

* ``i`` (``int``) - Integer flag or control value (0=off, 1=on)
* ``LoggingDir`` (``const std::string&``) - Directory path for logging output


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_Mapped_Logging:

``BenHW.Mapped_Logging``
~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Enable or disable mapped logging.

Signature
^^^^^^^^^

.. code-block:: cpp

   void Mapped_Logging(int i)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int i = 1;

       hw.Mapped_Logging(i);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_Mapped_Logging>`.

Parameters
^^^^^^^^^^

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



----


.. _cpp_use_group:

``BenHW.use_group``
~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Set the current active group.

Signature
^^^^^^^^^

.. code-block:: cpp

   void use_group(int n)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       int n = 1;

       hw.use_group(n);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\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 <c_BI_use_group>`.

Parameters
^^^^^^^^^^

* ``n`` (``int``) - Group number or count value


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_version:

``BenHW.version``
~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Get the DLL version string.

Signature
^^^^^^^^^

.. code-block:: cpp

   std::string version()

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string s = hw.version();
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_version>`.


Returns
^^^^^^^

Returns ``std::string`` - String value or buffer for text data


----


.. _cpp_zero_calibration:

``BenHW.zero_calibration``
~~~~~~~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Perform zero calibration across a wavelength range.

Signature
^^^^^^^^^

.. code-block:: cpp

   void zero_calibration(double start_wl, double stop_wl)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       double start_wl = 400.0;
       double stop_wl = 800.0;

       hw.zero_calibration(start_wl, stop_wl);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_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 (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_SCPI_query:

``BenHW.SCPI_query``
~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Send a SCPI query command and read response.

Signature
^^^^^^^^^

.. code-block:: cpp

   std::vector<unsigned char> SCPI_query(const std::string& id, const std::string& msg, int reply_size)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string id = "mono1";
       std::string msg = "*IDN?";
       int reply_size = 256;

       std::vector<unsigned char> reply = hw.SCPI_query(id, msg, reply_size);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_SCPI_query>`.

Parameters
^^^^^^^^^^

* ``id`` (``const std::string&``) - Component identifier string
* ``msg`` (``const std::string&``) - Message string to send or query
* ``reply_size`` (``int``) - Maximum size of reply buffer in bytes

Returns
^^^^^^^

Returns ``std::vector<unsigned char>`` - Buffer to receive reply data

Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----


.. _cpp_SCPI_write:

``BenHW.SCPI_write``
~~~~~~~~~~~~~~~~~~~~


DLL versions ``4.4.13`` and above

Send a SCPI write command.

Signature
^^^^^^^^^

.. code-block:: cpp

   void SCPI_write(const std::string& msg, const std::string& id)

Example
^^^^^^^

.. code-block:: cpp

   #include "benhw.hpp"

   benhw::BenHW hw;

   try {
       std::string msg = "*IDN?";
       std::string id = "mono1";

       hw.SCPI_write(msg, id);
   } catch (const benhw::SdkException& e) {
       std::cerr << "Error: " << e.what() << "\n";
   }

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 <c_BI_SCPI_write>`.

Parameters
^^^^^^^^^^

* ``msg`` (``const std::string&``) - Message string to send or query
* ``id`` (``const std::string&``) - Component identifier string


Exceptions
^^^^^^^^^^

This method may throw the following exceptions (all derived from ``benhw::SdkException``):

* ``benhw::BenHWException`` - Function call failed. Use BI_report_error to get detailed hardware error code.

----