GI.bench API Quick Start Guide

All core processes of GI.bench, as well as the Q.station controller, are running XML-RPC servers and provide multiple APIs.

Q.station controller APIs:

• DataAPI
• DataLoggerAPI
• DiagnosticAPI
• FileTransferAPI
• …
• → via routes:
  • /GI.com - DeviceConfigAPI
  • /GI.config - ConfigAPI
• or routes to PluginAPIs

• ConfigAPI
• → most important: routes to subprocesses and their APIs:
  • /GI.com - DeviceConfigAPI
  • /GI.config - ConfigAPI

The APIs are used for communication between the processes, but also to facilitate easy access for other (third-party) XML-RPC clients without requiring special adaptation (device and OS agnostic). There is no difference if both communicating processes are on the same physical device or if they are connected via Ethernet or any other transport protocol.

Please also read: GI.bench Introduction

To use/implement the APIs for the configuration of Q.series devices (GI.config, GI.com), you need to have GI.bench running on your PC or you need to have a running Q.station controller in your network.

If you have no hardware available, you can also use the GI.bench UI to load a demo project (provided with the setup) or create your own offline project. GI.bench UI is the user interface for the GI.bench APIs. This can be replaced by any other third-party UI. If you run GI.bench for the first time, you can also find a Quick Start Guide in the download section of our website.

Use this tool during your development to test and inspect the APIs manually. GI.monitor is installed with the GI.bench setup and can be launched via the GI.bench tray icon or from the GI.bench installation directory.

For more info see: GI.monitor

GInsXmlRpcStdAPI

All  XML-RPC APIs are based on the GInsXmlRpcStdAPI. This API provides commonly used types by all APIs. See the article XML-RPC API for detailed information about the GInsXmlRpcStdAPI.

The GI.bench installation provides all source files and examples you require to implement an XML-RPC client in either C++ or C#. The default installation path of these files is:

 C:\Users\Public\Documents\Gantner Instruments\GI.bench\api 

Hello World

This section shows a minimal, step-by-step, example/procedure on how to do a configuration setting (change the name of a variable) with the GI.config API using GI.monitor and GI.bench UI. To try this example it is not necessary to have real hardware connected.

Step 1

1. Launch GI.bench (with an empty project) -> an empty project will also automatically be created in GI.config
2. Launch GI.monitor from the system tray
3. Connect to GI.service ( server address: localhost or 127.0.0.1 / port: 8090)
   
4. By selecting a method in the list, GI.monitor calls the GetParams method (see XML-RPC API) in the background and will automatically load the available parameters.

The screenshot below shows GI.bench with an empty project including a project object as a top object [1] and feature objects as child (owned) objects [2]. All these objects get unique IDs (UUID) generated by GI.config.

You can see the same information now in GI.monitor using the APIs. For example, click on the method GetConfigs of the GI.config API. Then on the right side, the parameters of the method will appear. The list of IDs will be filled by GI.monitor with all available objects. In the screenshot you can see 3 objects in the list:

• TyFeat (UUID)
• TyFeat (UUID)
• TyPrj: unnamed (UUID)

Step 2

Load a demo project in GI.bench, which includes some devices (controller and modules) and some variables.

1. In GI.bench UI click on the Load button
2. Select the Demo.gibpj and click OK
3. The project will be loaded in GI.bench (and GI.config). In this screenshot you can see the column Config ID, which represents again the unique IDs for all objects:
   
   
   
   
4. Use again GI.monitor, reselect the method GetConfigs in GI.config/ConfigAPI (as described in Step 1, GetParams is called in the background). You will also see all available objects that exist in GI.config.
    
   
   You can see again in the list all available objects with different types like for example TyAda for Adapter, TyCtr for Controller, TyIntMod for Internal Module, and so on… You can find a list of possible object types here: GI.config.

Step 3

Select a desired variable object in GI.monitor (marked as TyVar) with the corresponding Variable Name and UUID.

Step 4

In GI.monitor select the PropertyName you would like to set. With the logic of GI.monitor, it provides all possible properties of a selected object type in a drop-down menu. As you will see, a Variable object has a lot of different properties. For this example, we want to change the variable description (name). Therefore select General/Description and click on the Send button.

In the method response, you will see the desired information (as well as some return states or lists of affected changes).

Step 5

To change the value of the property (in this case General/Description), you need to execute the method SetConfigs in GI.config/ConfigAPI. 

1. Set a new value for the selected property (variable name), for example, “New Name 1234” and click on the Send button
2. Since GI.monitor remembers the selection for Object ID and PropertyName from GetConfigs, you don't need to change them.
3. For the parameter ReturnConfigChangesReasonBitset type “0”. Leave DisableDRC on “false” (default). More information about DRC can be found in the article about GI.config.

1. Click on the Send button to execute the method. The method results will give you any indication of errors or changes (depending on ReturnConfigChangesReasonsBitset).

Step 6

If SetConfigs was executed successfully, you can now verify if changes are set correctly using GI.bench UI:

1. Select the affected variable in GI.bench UI (or any overlaying object like Module, Adapter, Controller, or Project)
2. Press the key combination Ctrl + r to refresh the selected objects in the UI. You will now see the new variable name in GI.bench UI:
   
   
   
   Or you can again use GI.monitor and the method GetConfigs to check the modification:
   
   

Common procedures

In the “How To...” section you can find some common procedures for using the GI.bench APIs, especially for device configuration (read/write project, scan devices, get object IDs, configure objects…). More procedures will be added from time to time or by request.