C++ Instrument Catalog
C++ Instrument Catalog Documentation
Remarks
Document no 21448

This package offers various ways to communicate with Metrolab Technology's magnetometers.

License

For a detailed explanation of the terms in which this package is distributed, please see the "C++ Instrument Catalog License Terms" document located in the root folder.

Preamble

Metrolab offers several solutions allowing a software engineer to start a new project in which one of our magnetometers must be integrated. This document will specifically focus on the “Instrument Catalog Interface”, describing the underlying concept and how to use it to rapidly gather measurement in your own code. All new generation instruments, i.e. MFC2046, PT2026, FDI2056, THM1176, despites offering different communication channels – USB, Ethernet - are sharing the same set of commands that follows the IEEE-488.2 standard. Notice however that some commands are specific to the instrument – i.e. the configuration of a Hall meter differs from the configuration of a flux meter -. To leverage the burden of interfacing all SCPI commands and translate all parameters from high level type abstraction to plain ASCII character sequence, Metrolab decided to provide a full C++ API offering easy access to the instrument SCPI command set and a new approach that we called “the catalog”.

The Catalog Concept

To write a software interface for an instrument using a list of methods is quite often a tedious task, one has to understand the imbrication and the consequences of calling one method before another. To simplify the developer's life Metrolab decided to propose a simple and unified way to control instrument using a data-oriented protocol, occulting most of the instrument's internals specificities. Using the catalog simplifies the software engineer workload by offering a way to access instruments through a set of pre-defined variables that may have composite data type. Variables having “Controls” capabilities are provided allowing the modification of the instrument state and configuration and variables having “Observers” capabilities enable subscribing to “Controls” changes. “Observers” and “Controls” are pointing to the same protected data. “Controls” have read and write access to the data whereas “Observers” only have read access upon it. A modification of a data will automatically trigger an event to an “Observer”. The layered structure of the concept is shown on the following figure.

To address all the basic operations needed to interact with our magnetometers, our data-oriented interface propose the following variables:

  • a list of all instruments, including the make, serial number and communication interface (USB, Ethernet, etc.),
  • a link to the instrument,
  • all instrument parameters,
  • a list of all available measuring channels, when applicable,
  • a channel selection, when applicable,
  • a control over the measurement operations,
  • the measurements themselves with new measurements subscription,

and, most notably, a value change notification system allowing easy subscriptions and callbacks.

Notification

Upon value change, assuming subscription, a notification is emitted. Notification behavior is made variable dependent, as it might be important to keep track of all values taken by a variable or one just its latests - ie the freshest one.

Notification Type

Context

Description

Synchronous

Notification:
Variable handler

Processing:
Variable handler

 

The notification will result in a call of a callback function in charge of the data processing.

 

Asynchronous

Notification:
Variable handler

Processing:
Subscriber recipient

The notification will be sent to a synchronization mechanism (i.e. a protected FIFO). When the data handler is ready to process the notified request, it may use the associated observer providing access to the current value of the variable. The value that will be read during this access is the most recent one.

Asynchronous with copy

Notification:
Variable handler

Processing:
Subscriber recipient

The handling of the notification follows the asynchronous one but the data value that will be read using the observer is the one that resulted in the notification. This gives the warranty that no value is never lost. This also means that if the notification is ignored for a certain amount of time, the value that is read is probably obsolete.

 

Each variable registered in the instrument's catalog can be considered as a two-sided message passing interface in which a thread post data and another one, upon notification, reads the data.

MFC Catalog

The catalog offered for the MFC2046 and MFC3045 is located in the file InstrumentCatalog.h. This file defines the two sides of the catalog, one is the side used by our code named MTL::CInstrManCatalogInterface, which makes use of the PT2026 and MFC3045 APIs. The second, named MTL::CGUICatalogInterface is the one you should use to interact with your piece of software.

Here is the complete list of structured variables you have access to:

  • Connection
  • Instrument / Probe-Array information
    • CObserver<CInstrumentCatalog::sInstrumentInformation> oInstrumentInformation;
    • CObserver<CInstrumentCatalog::sInstrumentConfiguration> oInstrumentConfiguration;
    • CObserver<CInstrumentCatalog::sProbeArrayInformation> oProbeArrayInformation;
    • CObserver<CInstrumentCatalog::sProbeArrayAngle> oProbeArrayAngle;
  • Instrument / Probe-Array control and status
  • Results
    • CObserver<CInstrumentCatalog::sSearchResult> oSearchResult;
    • CObserver<CInstrumentCatalog::sMeasurementResults> oMeasurementResults;
  • Others
    • CControl<CInstrumentCatalog::sNormalization> cNormalizationRequest;
    • CObserver<CInstrumentCatalog::sNormalization> oNormalizationReturned;
    • CObserver<CInstrumentCatalog::sError> oError;
    • CObserver<CInstrumentCatalog::sLogMessage> oLogMessage;

Launching any operation goes through the instrument state MTL::CGUICatalogInterface::cInstrumentState. Setting its OperatingMode field to either value of eOperatingMode, ie kIdle, kSearch or kMeasure will induce this instrument behavior. Nothing more is needed, the MFC Manager will handle all the internal configuration and send as much as needed SCPI commands to the instrument to enter in the specified mode.

Example

This example MFCCatalogExample.cpp shows how to connect to an instrument, set the search range and launch the search operation and, finally, collect the search result which, for a camera, is a measurement by itself.

PT2026 C++ API

Introduction

The PT2026 C++ API controls a PT2026 via an IVI-Foundation compatible VISA library. It provides access to the entire functionality of the PT2026 SCPI command set, as documented in chapter 6, "Host Interfaces," of the "NMR Precision Teslameter PT2026 User's Manual".

The figure that follows depict the dependencies between the various packages constituting the API.

Getters, setters

All instrument and measurement parameters can be modified and read back using classic GET/SET accessors. All parameters have a default value. This default value may come from either the probe or the instrument itself. Upon instrument reception or after factory reset you may count on all parameters being automatically initialized in a way that should insure an NMR measurement to be performed in good conditions. Before being able to operate, the instrument need to be stated which probe it must use. Even if only one probe is connected to the instrument it is mandatory to proceed to the probe selection operation. Changing a parameter should be performed with its mode set to “manual”. Failing to set the mode to manual will result in your parameters being stored in the instrument but unchanged. Its only after being set to "manual" that the stored value will be taken into account.

Triggering a measurement

The PT2026, when locked, measure continuously. As such, the trigger doesn't actually request a measurement to start. It merely ask the acquisition subsystem to memorize the measurement that follows the trigger. One has to be aware that the input trigger and the output trigger connector on the back panel of the instrument is mutually exclusive, only one BNC plug is present. That doesn’t mean that the trigger system can't work together, it just means that one cannot use the Input External Trigger (provided through the BNC connector) in conjunction with the features offered by the Output Trigger, meant to inform the output world of internal events using electrical signals.

Using the API

  1. Create and initialize a CVISAResourceManager object.
  2. Call CVISAResourceManager::FindResources with the filter "USB[0-9]*::0x1BFA::0x07EA::[0-9]+::INSTR".
  3. Create a CPT2026Instrument object, with the resource manager and desired resource as arguments.
  4. Call CPT2026Instrument::Connect.
  5. Call whatever other methods you want to control the PT2026.
  6. Call CPT2026Instrument::Disconnect.
  7. Destroy the PT2026 instrument and resource manager objects.

Example

The folder "example" contains a full-featured example. It can be used to start your own "hello world"-like project. This example has been compiled and tested using Microsoft Visual Studio Community 2017.

MFC3045 C++ API

Note

The MFC instrument catalog we provide is intended to handle both MFC2046 and MFC3045 systems. For this reason, we developed the MFC3045 C++ API. As a customer, please do not interact with the MFC3045 C++ API itself, but base your developement on the instrument catalog interface.