APIs
      Back to home
      1. GI.knowledgebase
      2. Connectivity & Integration
      3. APIs

      Read/Write Project

      This procedures show how to work with GI.bench (GI.com, GI.config, GI.data) using the function calls of the XML-RPC interfaces. This section is preliminary information which might still change!!

      Existing projects (including controller, modules, loggers, data streams, …) can be

      • Offline Projects - saved to a local directory which can be loaded via project-file from harddisk.
      • Online Projects - hardware setup is available and complete setup can be “read” into GI.config

      It also depends on, if GI.config is running directly on Q.station, or if it is running on a PC.

       

      Read Project

      From Controller

      On Controller

      This process is to upload a controller configuration (controller + modules) into GI.config on Q.station directly.

      → see Create Objects

      old

      Info:

      • connected modules with different/new configurations will be updated in the controller!
      Step Parameters/Results Action
      Connect to GI.com → DeviceConfigAPI    
      Execute method “Connect” Parameters: when working with GI.config/GI.com directly on Q.station, no ID is necessary as parameter
      Results: Connection Token-String      		 Q.station changes state to “Configuration Mode”
      Execute method “GetConfigState” Parameters: Token-String from “Connect”
      Results:
      * ConfigState: struct
      * ConfigModeActive: → during configuration mode: true
      * Devices: array with information of connected modules (Address, ConfigState, ID, Name)
      * MeasModeActive: → during configuration mode: false
      * Stable: true/false
      * Events
      * ReturnState      		 During this process, connected modules on the UARTs are scanned and checked if they are available and valid.
      - Execute until “Stable” == true
      - check “ConfigState” of the modules → if “ConfigDifferent” == true, configuration will be uploaded
      Execute method “HandleConfig” Parameters:
      * Token: string from “Connect”
      * Action: Read all - update (TyRdAllUpd)      		 Initializes the “read project” (update) process → modules on the UART are synchronized with the controller.
      Execute method “GetConfigState” Parameters: Token-String from “Connect” Execute until “Stable” == true.
      Read “Events” to follow the actual process.
      Execute method “Disconnect” Parameters: Token-String from “Connect” Measurement Mode will be activated again.
       

      On Host

      Result of this procedure is:

      • Configuration files of a Q.station (*.gcf) uploaded to a temp directory on the PC.
      • “Project” object generated in GI.config.
      • “Controller” object generated out of *.gcf files and attached to “Project” object.
      Step Parameters/Results Action
      Connect to GI.service (localhost:8090) → ConfigAPI    
      Execute method “HandleProject” Parameters:
      * Action: Clear project, clear autostart (ClPrjClAs)
      * ProjectName/ProjectPath: empty      		 Removes all existing objects in an actual project.
      Route GI.service → GI.config → ConfigAPI    
      Execute method “CreateObject” Paramerers:
      * BehaviourOnOwnerIndexExisting: Generate Error (TyErr)
      * DisableDRC: false
      * FileName:
      * OwnerID: *
      * OwnerIndex: -1
      * ReturnConfigChangesReasonBitset: 0
      * Type: Project (TyPrj)
      Results:
      * ID: Project object ID (needed later)
      * ReturnLists/ReturnState      		 This step creates an object of type “Project” in GI.config, which is at highest level in hierarchy (see GI.config - Basics). Using “GetConfigs” and “SetConfigs” parameters of the object uploaded/changed.
      Route GI.service → GI.com → DeviceConfigAPI    
      Execute method “Connect” Parameters:
      * ID: controller ID
      * all other empty
      Results:
      * ProjectPath: Temp path of configuration files (→ needed later)
      * Token: connection token
      * ReturnState: general returnstates      		 Use controller “ID” from Networkscan results (see: Scan Devices). With this step, Q.station changes state to “Configuration Mode”!!
      Alternatively use IPAddress directly if ID is not known yet.
      Execute method “HandleConfig” Parameters:
      * Read all - update (TyRdAllUpd)
      * Token: connection token (from “Connect”)      		 Configuration files are uploaded to Temp ProjectPath
      Execute method “Disonnect” Parameters:
      * Token: connection token      		 Disconnect from device. Q.station changes state back to “Measurement Mode”.
      Route GI.service → GI.config → ConfigAPI    
      Execute method “CreateObject” Parameters:
      * BehaviourOnOwnerIndexExisting: Generate Error (TyErr)
      * DisableDRC: false
      * FileName: → Temp ProjectPath of configuration files (see step: “Connect”)
      * OwnerID: Project object ID (from “CreateObject” of the project)
      * OwnerIndex: -1
      * ReturnConfigChangesReasonBitset: 0
      * Type: Controller (TyCtr)      		 This step creates an object of type “Controller” in GI.config + all connected objects (modules, variables…). Its owner is the “Project” object → ID is from “CreateObject” when project was generated. You can also get the Project IDs using method “GetIDsFromObjectType”.
       
       

      From File

      GI-bench project can be saved to a file archive on your host PC. A project is managed by GI.service, so it is only possible to read/write a project to a file on a host-PC.

      To have it available again in GI.config, the project needs to be loaded back into GI.bench with the following steps:

      Step Parameters/Results Action
      Connect to GI.service (localhost:8090) → ConfigAPI    
      Execute method “HandleProject” Parameters:
      * Action: Clear project, clear autostart (ClPrjClAs)
      * ProjectName/ProjectPath: empty      		 Removes all existing objects in an actual project.
      Execute method “HandleProject” Parameters:
      * Action: Load project (LdPrj)
      * ProjectName: Project name (.gibpj file)
      * ProjectPath: Project path (path of .gibpj file)      		 GI.bench project will be loaded into GI.config!
      Instead of “ProjectName” and “ProjectPath” it is also possible to only use “ProjectPath” (full path + .gibpj-file, for example “c:\project\test\test.gibpj”) and leave “ProjectName” empty.

      It can happen, that the ReturnState of this method will deliver “< Device not found in network. >”. In this case, the controller in the project does not yet have a valid UUID (for example when an old test.commander project was converted to a Gibench project). To download a project in this case to a controller a network scan needs to be done to get the IP-address directly (→ not possible with GI-bench UI!).
       
       

      Write Project

       

      To Controller

       

      On Controller

      When all settings are done via GI.config (directly on the controller), the project files need to be downloaded/activated on the controller + modules. Be sure, that all changes in GI.config are saved (GI.config → SaveObject + Controller-ID).

      Info:

      • only modules with different configurations are updated!
      Step Parameters/Results Action
      Save Configuration:
      Connect to GI.config → ConfigAPI      		    
      Execute method “SaveObject” Parameters:
      * BehaviourOnExisting: TyErr
      * DirectoryName:
      * HostingDirectoryName:
      * ID: Controller-ID
      * IgnoreErrors: false      		  
      Connect to GI.com → DeviceConfigAPI    
      Execute method “Connect” Parameters: when working with GI.config/GI.com directly on Q.station, no ID is necessary as parameter
      Results: Connection Token-String      		 Q.station changes state to “Configuration Mode”
      Execute method “GetConfigState” Parameters: Token-String from “Connect”
      Results:
      * ConfigState: struct
      * ConfigModeActive: → during configuration mode: true
      * Devices: array with information of connected modules (Address, ConfigState, ID, Name)
      * MeasModeActive: → during configuration mode: false
      * Stable: true/false
      * Events
      * ReturnState      		 During this process, connected modules on the UARTs are scanned and checked if they are available and valid.
      Execute until “Stable” == true and check “ConfigState” of the modules.
      Execute method “HandleConfig” Parameters:
      * Token: from “Connect”
      * Action: Write all - update (TyWrAllUpd)      		 Initializes the “write project” (update) process → modules are synchronized with new configuration.
      Execute method “GetConfigState” Parameters: Token-String from “Connect” Execute until “Stable” == true.
      Read “Events” to follow the actual process.
      Execute method “Disconnect” Parameters: Token-String from “Connect” Measurement Mode will be activated again.
       
       

      On Host

      When all settings are done via GI.config (on host), the project files can be downloaded to the controller + modules.

      Info:

      • same procedure as “Write Project” using GI.bench-UI.
      Step Parameters/Results Action
      Connect to GI.service → GI.com → DeviceConfigAPI    
      Execute method “Connect” Parameters:
      * ID: controller ID
      * all other empty
      Results:
      * ProjectPath: Temp path of configuration files (→ needed later)
      * Token: connection token
      * ReturnState: general returnstates      		 Q.station changes state to “Configuration Mode”. The “Connect” gives you a temporary path for the project files, generated by GI.config with “SaveObject”.

      If “ID” is not known yet, it is also possible to use “IPAddress” instead.
      Route GI.service → GI.config → ConfigAPI    
      Execute method “SaveObject” Parameters:
      * BehaviourOnExisting: “Generate error (TyErr)”
      * DirectoryName: Temp path from “Connect”
      * HostingDirectoryName: empty
      * ID: Controller-ID      		 Configuration files are generated in GI.config and saved into the temp path.

      If Controller-ID is not yet known, use method “GetIDsFromObjectType” from GI.config → ConfigAPI
      Route GI.service → GI.com → DeviceConfigAPI    
      Execute method “HandleConfig” Parameters:
      * Action: Write all - update (TyWrAllUpd)
      * Token: from “Connect”      		 Initializes the „write project“ (update) process → modules are synchronized with new configuration.
      Execute method “GetConfigState” Parameters:
      * ClearEvents:
      * Token: from “Connect”
      Results:
      * ConfigState: check if “Stable” is “true”      		 Execute this function until ConfigState → Stable is true! When finished, check ConfigState → Controllers → Controllers[x] → ConfigState if there is an error.
      Read „Events“ to follow the actual process.
      Execute method “Disconnect” Parameters:
      * Token: from “Connect”      		 Measurement Mode will be activated again.
      Execute method “GetConfigState” Parameters:
      * ClearEvents
      * Token: empty
      Results:
      * ConfigState: check if “MeasModeActive” is “true”