eGateHighSpeedPort API

The eGateHighSpeedPort API can be used as a data interface to common programming languages and software tools, like Matlab, LabVIEW, and Python

The eGateHighSpeedPort API, part of the GInsData library, is a C-style API using primitive types only. It provides a list of functions based on the HighSpeedPort protocol for:

  • Buffered data transfer (reading data streams from the controller's circular buffer via TCP/IP)
  • Online data transfer (reading/writing of actual values from a controller via TCP/IP)
  • File decoding (access and decode Gantner *.dat files from a local path).
  • Diagnostic data (retrieve diagnostic information about I/O modules via TCP/IP)
👉 A simple code example can be found at the bottom of this article.

As of version 3.0.1.0, the DLL is available in both 32-bit and 64-bit versions.

The new DLL is not fully compatible with the old eGateHighSpeedPort.dll. You can use the new version by simply renaming and replacing it with the old one.

 

👉 Expert users only, otherwise or contact Gantner product support

If you are using a Q.station with firmware version 1.11/2.11B03 (or higher) and an old version of the DLL (<V3.0.0.0), then two settings in the qstation01.ini file have to be changed (FTP connection 0/0):

Note: If you change the qstation01.ini file, the connection with GI.bench will not work anymore. The other option is that you use the giutility.dll (taken from GI.bench x86 version), replace it with the old eGateHighSpeedPort.dll, and rename it to eGateHighSpeedPort.dll.

 

As of controller firmware version 2.12B11 and GI.bench version 1.4.3 (or higher), the UDBF structure compatibility can be set through the GI.bench user interface.

Version history

Version Comment
V2.0.2.1

Bugs eliminated:

  • the connection wasn't cleaned up correctly when the TCP/IP connection was already closed by the device
  • Removed bugs with PImage > 1024 bytes
  • Added cleanup for remaining buffer data when the connection is closed
V2.0.2.2

Bugs eliminated:

  • TotalFrameLength wasn't correctly decoded from #summary.sta file
  • Increased number of max connections from 10 to 20
  • Fixed bug that Channel - Unit sometimes had invalid/old value
V3.0.0.1
  • Complete new implementation based on GInsData interface.
  • Added platform support: windows amd64, Linux x86, Linux amd64, ARM, Android
  • Fixed bug with wrong error counter order if internal variables were used.
  • Replaces unused diagnostic value states with cycleCount because Q.station can sample devices with different cycle rates.
  • Added functions:
    • eGateHighSpeedPort_ReadBuffer_Single_RawType
    • eGateHighSpeedPort_ReadOnline_Frame
    • eGateHighSpeedPort_ReadOnline_FrameToDoubleArray
  • Added device info types: MID, BufferCount, LoggerCount, Timestamp Type
V3.0.2.0
  • Added PostProcessBuffer features to access buffers on GI.bench
  • Fixed problem if the sample rate of certain sources is <0>
V3.0.3.0
  • Fixed the problem that the data rate could not be read correctly
  • Added possibility to read timestamp variable also from the device interface
  • Fixed bug when reading out the variable list from HeaderInterface
  • Changed library interface for Linux so that internal functions are not exposed anymore (caused incompatibility on platforms with different libstdc++)
V3.0.4.0
  • Removed deprecated data storage functions

Header file #defines

General return codes

Name Value Comment
HSP_OK 0  
HSP_ERROR 1  

Channel info ID

Strings:

Name Value Comment
CHINFO_NAME 0 Channel Name
CHINFO_UNIT 1 Unit
CHINFO_DADI 2 Data direction (Input, Output, Empty,..)
CHINFO_FORM 3 e.g.: %8.3
CHINFO_TYPE 4 FLOAT, DOUBLE, …
CHINFO_VART 33 Variable type (AIN, AOU, ...)


Integers:

Name Value Comment
CHINFO_INDI 5 Input access index
CHINFO_INDO 6 Output access index
CHINFO_INDX 7 Total access index
CHINFO_PREC 8 Precision
CHINFO_FLEN 9 Field length
CHINFO_RMIN 30 Range min
CHINFO_RMAX 31 Range max
CHINFO_MIND 32 Module index
CHINFO_DTYI 34 Data type index

Device Info ID

Strings:

Name Value Comment
DEVICE_LOCATION 10  
DEVICE_ADDRESS 11  
DEVICE_TYPE 12  
DEVICE_TYPENAME DEVICE_TYPE  
DEVICE_VERSION 13  
DEVICE_TYPECODE 14  
DEVICE_SERIALNR 15  


Integers:

Name Value Comment
DEVICE_SAMPLERATE 16  
DEVICE_MODULECOUNT 17  
DEVICE_CHANNELCOUNT 18  

Slave module info ID

Strings:

Name Value Comment
MODULE_TYPE 19  
MODULE_TYPECODE 20  
MODULE_Location 21  


Integers:

Name Value Comment
MODULE_UARTINDEX 22  
MODULE_ADDRESS 23  
MODULE_VARCOUNT 24  

Storage info ID

Name Value Comment
STORE_FILECOUNT 25  
STORE_SECONDS 26  

Buffer ID

Name Value Comment
BUFFER_MAXFRAMES 27  

Data direction IDs

Name Value Comment
DADI_INPUT 0 Input
DADI_OUTPT 1 Output
DADI_INOUT 2 Input/output
DADI_EMPTY 3 Empty
DADI_STATS 4 Statistic Channels

Connection types

Name Value Comment
HSP_ONLINE 1  
HSP_BUFFER 2  
HSP_ECONLOGGER 3  
HSP_ARCHIVES 4  
HSP_FILES 5  
HSP_DIAG 7  
DSP_UDP 8  
DLL_CONTROL 9  
HSP_DIRECT 7  
HSP_BUFFER0 100  
HSP_BUFFER1 101  

Statistic info types

Name Value Comment
STAT_CONNECTED 0  
STAT_STACKSIZE 1  
STAT_DECODETIME 2  

Diagnostic types

Name Value Comment
DIAG_CONTROLLER 0  
DIAG_INTERFACE 1  
DIAG_TRANSPORT 2  
DIAG_VARIABLE 3  
DIAG_ITEMCOUNT 4  

Data storage types

Name Value Comment
STOR_MDF 0  
STOR_CSV 1  

Directory types

Name Value Comment
DIR_ALL 0  
FLASHAPPLICATION 1  
FLASHDATA 2  
USBDATA 3  
VIRTUALSTATE 4  
VIRTUALONLINEBUFFER 5  
VIRTUALCIRCLEBUFFER 6  
VIRTUALARCHIVE 7  
VIRTUALLOGGER 8  

File locations

Name Value Comment
LOC_LOCALE 0  
LOC_CONTROLLER 1  

Data types

Name Value Comment
DATY_NO 0  
DATY_BOOL 1  
DATY_SINT8 2  
DATY_USINT8 3  
DATY_SINT16 4  
DAYT_USINT16 5  
DATY_SINT32 6  
DATY_USINT32 7  
DATY_FLOAT 8  
DATY_SET8 9  
DATY_SET16 10  
DATY_SET32 11  
DATY_DOUBLE 12  
DATY_SINT64 13  
DATY_USINT64 14  
DATY_SET64 15  

Callback types

Name Value Comment
CALL_CONTROL 0  
CALL_ERROR 1  
CALL_DIAG 2  
CALL_DSPDATA 3  
CALL_FREADY 4  
CALL_DEBUG 5  

Variable types

Name Value Comment
VarKind_Empty 0  
VarKind_AnalogOutput 1  
VarKind_AnalogInput 2  
VarKind_DigitalOutput 3  
VarKind_DigitalInput 4  
VarKind_Arithmetic 5  
VarKind_Setpoint 6  
VarKind_Alarm 7  
VarKind_PIDController 8  
VarKind_SignalConditioning 9  
VarKind_Remote 10  
VarKind_Reference 11  
VarKind_Unknown 12  
VarKind_NotDefined 13  

Remote control types

Name Value Comment
REMOTE_START 0  
REMOTE_STOP 1  
REMOTE_END 2  

System limits

Name Value Comment
MAXCONNECTIONS 100 Max connections for this DLL
MAXADDRESSLENGTH 100  
MAXDEBUGMESSAGELEN 1024  

Methods general info

All method names listed below have as prefix: eGateHighSpeedPort_

For example: eGateHighSpeedPort_Init.

All methods are of type INT and throw back a GENERAL RETURNCODE.

Methods: General Control

The following functions provide options for general setup:

Init

Every Ethernet HighSpeedPort connection to a controller has to be created with Init first. To load data files, use DecodeFile_Select instead of Init.

The Connection Instance and Client Instance have to be stored globally for each connection to be able to select the correct connection again. Both variables should be initialized with -1 at the very beginning of the program.

  • Connection Instance: If the same IP address or communication type was not already initialized before, the connection instance will return a new value to be able to use exactly this connection later. If the connection and communication type are already initialized, Init will return a new client instance. In this case, be sure that all clients are used (otherwise close!).
  • Client Instance: Within one process, several clients can be registered by calling Init with the same IP address and connection type. This can be used to access data synchronously from different threads or functions within the process the DLL was called (e.g. a new data frame from a buffered connection is only available when registered clients in this process have read it).
Parameters
Name Type Comment
HostName char* The IP address of the controller
timeOut integer The connection timeout of the DLL in seconds
mode integer The communication mode (see Connection Types)
  • If HSP_ONLINE: This function initializes the complete communication
  • If HSP_BUFFER or HSP_LOGGER: function InitBuffer is needed to select the buffer index before data transfer
  • Other communication types will only open the port but not initialize anything.
sampleRate integer The sample rate for reading single or buffered data from the controller.
  • HSP_ONLINE: up to 1000 Hz (check system health!), recommended 50-100 Hz
  • HSP_BUFFER: 2 Hz default (otherwise check system health!)
since DLL v3.0.0.0 → not used

Results
Name Type Comment
clientInstance int* If several tasks of the application use the same connection, some DLL functions need the client instance for synchronization.
connectionInstance int* This DLL supports up to 20 connections, which work in different threads. To identify the connection, the Instance has to be stored.

SetAutoSyncMode

Buffered connections support the automatic synchronization of data streams. If different connections have hardware-synchronized controllers, data streaming will start only with similar timestamps.

  • 1 = enable
  • 0 = disable
Parameters
Name Type Comment
connectionInstance int  
enable int  

This function is not supported anymore since DLL v3.

SetSampleRate

Modifies the sample rate at runtime. This sample rate only defines the interval for reading data from the controller to the PC. Due to Ethernet not being deterministic, this will not be an exact timing. It only helps to manipulate the rate of how fast data is copied between the controller and the PC. The exact measurement rate of the controller has to be configured with GI.bench (or test.commander).

Parameters
Name Type Comment
connectionInstance int to select the correct connection
sampleRateHz long sample rate in Hz
  

This function is not supported anymore since DLL v3.

GetSampleRate

Read the sample rate as configured at Init or SetSampleRate.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
sampleRateHz long* sample rate in Hz
 

This function is not supported anymore since DLL v3.

GetRTC

Read the current time of the device.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
year uint16*  
month uint8*  
day uint8*  
hour uint8*  
minute uint8*  
second uint8*  
millisecond uint16*  

SetRTC

Set the time on the device with a specified time, for example, actual PC time.

Ensure that no other time synchronization is configured on the controller.


Parameters
Name Type Comment
connectionInstance int to select the correct connection
year uint16  
month uint8  
day uint8  
hour uint8  
minute uint8  
second uint8  
millisecond uint16  

SetReceiveTimeout

At eGateHighSpeedPort_init(..) connection and receive timeout is similar. This function configures the timeout for receiving data. The winsock.h function select() is used to generate the timeout → no blocking while timeout.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
timeOut long receive timeout in seconds
 

This function is not supported anymore since DLL v3,

GetReceiveTimeout

Reads the timeout configured with SetReceiveTimeout.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
timeOut long* receive timeout in seconds
 

This function is not supported anymore since DLL v3.

Close

Closes an opened connection and terminates its worker threads.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
clientInstance int to select the correct client

Methods: PostProcess Buffer Server

The following functions allow the creation of post-process buffers/system streams. Depending on environment settings, different data backends are supported.

Create

Create a new post-process buffer/system stream.

Parameters
Name Type Comment
sourceID const char* source UUID (SID) of this buffer
sourceName const char* the name of this buffer
sampleRateHz double the desired sample rate for this measurement
bufferSizeByte uint64_t the maximum size of this buffer in bytes
segmentSizeByte uint64_t the size of a buffer segment (if supported)
retentionTimeSec double the data retention time of this buffer (if supported)
dataTypeIdent const char* the only possible option currently is raw
bufferHandle int32_t* the result handle
errorMsg char* buffer for error message text if not successful
errorMsgLen uint32_t length of the error message buffer

AddVariableDefinition

Add a variable definition to the post-process buffer/system stream.

Parameters
Name Type Comment
bufferHandle int32_t  
variableID const char*  
variableName const char*  
Unit const char*  
DataTypeCode int32_t see data_types
VariableKindCode int32_t see variable_types
Precision uint16_t  
FieldLength uint16_t  
RangeMin double  
RangeMax double  
errorMsg char* buffer for error message text if not successful
errorMsgLen uint32_t length of the error message buffer

Initialize

Initialize a post-process buffer. This function finalizes the configuration and really creates the buffer. If successful, data can be appended to the buffer. There is also the possibility to allocate an internal frame buffer, which geometry automatically fits the actual buffer configuration.

Parameters
Name Type Comment
bufferHandle int32_t handle the requested buffer
tempBufferLength uint32_t number of temporary buffer frames to be allocated 
errorMsg char* buffer for error message text if not successful
errorMsgLen uint32_t length of the error message buffer

WriteDoubleToFrameBuffer

TBD

WriteTimestampToFrameBuffer

TBD

AppendFrameBuffer

TBD

AppendDataBuffer

TBD

Close

TBD

Methods: Config Data

The following functions provide config information from a specific connection. The connection has to be initialized first.

GetNumberOfChannels

Reads the number of channels of a specific connection and a specific data direction.

Buffered connections will not show any output channels, although they are configured on the controller


Parameters
Name Type Comment
connectionInstance int to select the correct connection
directionID int to select the channel direction:
  • DADI_INPUT → Input channels
  • DADI_OUTPUT → Output channels
  • DADI_INOUT → Input or output channels

Results
Name Type Comment
ChannelCount int* Number of channels

GetDeviceInfo

Can be used to get different system info from an initialized connection.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
typeID int to select the requested type:
  • DEVICE_LOCATION → reads the device location to 'channelInfo[]'
  • DEVICE_ADDRESS → reads the IP Address to 'channelInfo[]'
  • DEVICE_TYPE → reads the module type to 'channelInfo[]'
  • DEVICE_VERSION → reads the firmware version to 'channelInfo[]'
  • DEVICE_TYPECODE → reads the MK-Code to 'channelInfo[]'
  • DEVICE_SERIALNR → reads the serial number to 'channelInfo[]'
  • DEVICE_SAMPLERATE → reads the sample rate to info
  • DEVICE_MODULECOUNT → reads the number of slave modules to 'info'
  • DEVICE_CHANNELCOUNT → reads the number of channels to info
Index int  

Results
Name Type Comment
info double* desired Information (see Parameters)
channelInfo char[] see parameters

GetChannelInfo_String

Reads channel-specific text-based info by type ID, channel index, and direction. Use GetNumberOfChannels first to get the number of channels for the desired data direction. Then read any necessary info to the channels by indexing within a loop. The channel order must strictly conform to the system configuration. The same directionID as for GetNumberOfChannels must be used.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
typeID int to select the requested type:
  • CHINFO_NAME → Channel name
  • CHINFO_UNIT → Unit (°C, m, kg, …)
  • CHINFO_DADI → Data direction (Input, Output, Empty,…)
  • CHINFO_FORM → Data type
  • CHINFO_TYPE → Channel type (analog, digital, …)
directionID int same as with GetNumberOfChannels
channelIndex int to access the correct channel from the list
 
Results
Name Type Comment
channelInfo char[] channel info as a string

GetChannelInfo_Int

Reads channel-specific int-based info by type ID, the channel index, and direction. Use GetNumberOfChannels first to get the number of channels of the desired data direction. Then read any necessary info to the channels by indexing within a loop. The channel order must strictly conform to the system configuration. The same directionID as for GetNumberOfChannels must be used.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
typeID int to select the requested type:
  • CHINFO_INDI → Input Access Index
  • CHINFO_INDO → Output Access Index
  • CHINFO_INDX → Total access index
  • CHINFO_PREC → precision
  • CHINFO_FLEN → field length
directionID int same as with GetNumberOfChannels
channelIndex int to access the correct channel from the list
 
Results
Name Type Comment
channelInfo int* channel info as an integer

Methods: Online Communication

The following functions provide communication possibilities for online data. The connection has to be initialized first (see General Control) and config data functions can be used to read some channel information first.

The cyclic data transmission between the controller and PC is done by the DLL. The DLL only provides buffers containing double values, which are already decoded. The following functions provide read/write access to the DLL buffers.

Regarding performance, the cycle time for updating online values is defined by the sample rate at initialization. The timing is not very exact and the cycle time can be about 100 Hz max. It is recommended to use online data transfer functions for:

  • check values (e.g. to trigger buffer communications)
  • slow controlling applications
  • monitor static, or non-high dynamic values
  • write output channels
  • For high dynamic values use buffer functions instead.
  • For applications requiring fast control DistributorPort functions instead.

ReadOnline_Single

Read a single double value from a specific channel on the connection, selected with connectionIndex. All channels (analog, digital/floating point, integer, boolean,…).

Parameters
Name Type Comment
connectionInstance int to select the correct connection
channelIndex int to access the correct channel from the list → here always the total index is necessary. Use GetChannelInfo_Int to convert any IN, OUT, or INOUT index to the correct total index.

Results
Name Type Comment
value double* the actual value of the channel converted to double

ReadOnline_Frame

Reads a complete online frame to be stored internally and accessed with ReadOnline_Single. All channels (analog, digital/floating point, integer, boolean,…).

Parameters
Name Type Comment
connectionInstance int to select the correct connection

ReadOnline_FrameToDoubleArray

Reads a complete or part of an online frame to a double array. No worker threads are needed, every call initiates TCP/IP communication. eGateHighSpeedPort_Init has to be used first!

Parameters
Name Type Comment
connectionInstance int to select the correct connection
arrayLength int The number of elements in valueArray. If valueArray is smaller than arrayLength then this will cause a segfault.
startIndex int Index of the first variable to be read. This will be the first value in the valueArray.
channelCount int Number of Channels to be read starting from startIndex.
  • If channelCount is larger than arrayLength, only arrayLengh channels will be read.
  • If channelCount is -1 or larger than the real number of channels, all channels will be read.

Results
Name Type Comment
valueArray double* Pointer to a double array with at least arrayLength elements. Contains double converted values.

ReadOnline_Window

TBD

WriteOnline_Single

Write a single double value to a specific channel on the connection, selected with connectionIndex. All channels (analog, digital, floating-point, integer, boolean,…).

All channels can be written one by one. They will be stored in the DLL output buffer until WriteOnline_ReleaseOutputData is called for this connection. Channels, which are not filled in the output buffer, will remain 0 but they will be written when WriteOnline_ReleaseOutputData is executed. Alternatively,


Parameters
Name Type Comment
connectionInstance int to select the correct connection
channelIndex int to access the correct channel from the list → here always the total index is necessary! Use GetChannelInfo_Int to convert any IN, OUT, or INOUT index to the correct total index.
value double the new value for this channel is presented as double (will be converted to the correct data type on the controller)

WriteOnline_Single_Immediate

Write a single double value to a specific channel on the connection, selected with connectionIndex immediately. All channels (analog, digital, floating-point, integer, boolean, …). A different connection initialization is necessary → HSP_DIRECT. The function WriteOnline_ReleaseOutputData is not needed.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
channelIndex int to access the correct channel from the list → here always the total index is necessary! Use GetChannelInfo_Int to convert any IN, OUT, or INOUT index to the correct total index.
value double the new value for this channel presented as double (will be converted to the correct data type on the device)

WriteOnline_ReleaseOutputData

Use WriteOnline_Window to write multiple output channels simultaneously. Releases all buffered output values. This ensures, that all channels are written simultaneously.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
 

This function is not supported anymore since DLL v3

WriteOnline_Window

This function writes multiple sequential output channels simultaneously.

 Parameters
Name Type Comment
connectionInstance int to select the correct connection
startIndex int index of the first output variable to write
(use Output-Var Index)
size int size of values-array → number of sequent output variables to write, beginning from startIndex
valuesArray int pointer to an array of double values

SetClientState

TBD

GetClientState

TBD

Methods: Buffered Communication

The following functions provide communication possibilities for buffered data. Connection and buffer have to be initialized first and config data functions can be used to read some channel information first. For initialization, communication type HSP_BUFFER or HSP_ECONLOGGER must be used:

  • HSP_BUFFER: read data from the internal circle buffer
  • HSP_ECONLOGGER: read data from a test.con logger
The cyclic data transmission between the controller and PC is done by the DLL. The DLL only provides buffers containing double values, which are already decoded. The following functions provide read access to the DLL buffers:

InitBuffer

Initializes a buffered connection with a specified circular buffer or test.con data logger.

Initialize the Highseedport communication first with Init and type HSP_BUFFER or HSP_LOGGER.


Parameters
Name Type Comment
connectionInstance int to select the correct connection
bufferIndex int the index of a circular buffer or test.con data logger (index starts with 0 for the first buffer). Check configuration if the correct buffer type is supported and configured correctly!
autoRun int  

GetPostProcessBufferCount

TBD

Init_PostProcessBuffer

TBD

GetPostProcessBufferInfo

TBD

GetTimeRange

TBD

SetBackTime

Is used to set a BackTime manually for one Ethernet request. The BackTime defines how many seconds of a circular buffer should be read with one request (check the controller configuration for the size of the circular buffer).

Parameters
Name Type Comment
connectionInstance int to select the correct connection
BackTime double > 0 → complete buffer will be read
<= 0 → the next request will contain at least BackTime seconds or the complete buffer if less than BackTime seconds are stored

SeekTimeStamp

TBD

Seek

TBD

Rewind

TBD

ReadBuffer_Clear

Clear buffer frames - same as SetBackTime.

GetBufferFrames

Returns the number of available data frames to read and decode (all loaded data frames / internal actual frame index). The internal actual frame index will be increased by 1 using ReadBuffer_NextFrame. The DLL contains a FIFO with a fixed length → data has to be read out continuously with all clients otherwise the data transfer will be paused and the circular buffer may be overrun.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
clientInstance int to select the correct client

GetBufferFrames_All

TBD

LoadBufferData

Loads all available data frames (including back time) and sets the internal actual frame index back to 0.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
clientInstance int to select the correct client

Results
Name Type Comment
frames int number of available data frames

ReadBuffer_NextFrame

Used to step to the next frame (internal frame index increased by 1). LoadBufferData needs to be called first. If the return code of the function != HSP_OK (0), then no more frames are available, and LoadBufferData needs to be called again. As long as this function is not called for all clients, the functions ReadBuffer_Single and ReadBuffer_Single_RawType will not point to the next frame.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
clientInstance int to select the correct client

ReadBuffer_Single

Used to read the value of a specified channel from the actual frame. Use in combination with ReadBuffer_NextFrame to load the next frame.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
clientInstance int to select the correct client
ChannelIndex int to select the channel index (total index!). Use GetChannelInfo_Int to convert the channel index if necessary.

Results
Name Type Comment
value double* the value of the channel converted to double

ReadBuffer_Single_RawType

Used to read the value of a specified channel from the actual frame to the buffer. Use in combination with ReadBuffer_NextFrame to load the next frame.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
clientInstance int to select the correct client
ChannelIndex int to select the channel index (total index!). Use GetChannelInfo_Int to convert the channel index if necessary.

Results
Name Type Comment
value char* raw value
valueSize size_t size

ReadBufferToDoubleArray

Reads buffered data to a double array. No worker threads are needed, every call initiates TCP/IP communication and data decoding. Init and InitBuffer have to be used first.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
arrayLength int The number of elements in valueArray. If valueArray is smaller than arrayLength this will cause a segfault.
fillArray int With fillArray set to 1 this call will block until arrayLength / channelCount frames are received. With 0, the function will fill the valueArray with all available buffer data (not waiting until valueArray is full). If the controller buffer is read completely, output complete will return 1.
 
Results
Name Type Comment
valueArray double* Pointer to a double array with at least ArrayLength elements. Contains double converted values. The timestamp is automatically converted to TimeOLE2.
receiveFrames int* Number of frames in valueArray after processing (frame = 1 sample over all channels).
channelCount int* The number of channels in one frame (can also be read with getNumberOfChannels).
complete int* Indicates if one TCP/IP request was completely decoded.

ReadBufferToDoubleArray_StraightTimestamp

Same as ReadBufferToDoubleArray, but the timestamp will not be converted automatically to TimeOLE2.

LogToUDBF_File

Not implemented yet.

Methods: DLL Diagnostic

The following functions provide diagnostic actions and information.

IdentDLL

Results
Name Type Comment
dllVersion char[] Version number of the DLL
dllDate char[] Release date of the DLL

ToggleDebugMode

In debug mode, the DLL will generate a log file.

ExplainError

Is used to get error information in plain text if any error return code is thrown.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
 
Results
Name Type Comment
errorMessage char[] Plain text error message

GetDebugMessage

Is used to get error information in plain text if any error return code is thrown.

Parameters
Name Type Comment
connectionInstance int to select the correct connection

Results
Name Type Comment
errorMessage char[] Plain text error message

WriteDebugMessage

TBD

Connected

If a connection is broken (e.g. Ethernet disconnected or the module restarted) the DLL will try to establish the connection again as long as the connection is not terminated. This function can be used to indicate the actual connection state.

Parameters
Name Type Comment
connectionInstance int to select the correct connection

Results
1 connection open
0 connection closed

Diagnostic

Provides system diagnostic information. Diagnostic info is only up to date when diagLevel==DIAG_CONTROLLER was used before. If errorCount != 0 then other diagLevels can be checked for errors.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
diagLevel int to request the desired info (see Diagnostic types)
index int request the info from a specified index

Results
Name Type Comment
state int* not used
errorCount int*
  • diagLevel == DIAG_CONTROLLER: the number of errors over the whole system. Use this diagLevel to refresh diagnostic data.
  • diagLevel == DIAG_INTERFACE: the number of errors on a specific interface (ISys, IVir, ExtUART0, ExtUART1, …)
  • diagLevel == DIAG_TRANSPORT: the number of errors on a specific transport (system variables, virtual variables, Slave1, Slave2, …)
  • diagLevel == DIAG_VARIABLE: not used
  • diagLevel == DIAG_ITEMCOUNT: the number of items for the defined level

Methods: File transfer

The following functions provide file transfer - and decode functions. Files can only be read or deleted completely, but not written or modified. Configuration handling has to be done with eGateUtility.dll (FTP). Files can either be copied to a drive or decoded online without saving them to a file. After decoding data from local files or a file stream from the controller, the values are accessible in the same way as reading buffer values (ReadBuffer_NextFrame, ReadBuffer_Single).

GetFileCount

Used to read the number of files on the controller. A fileTypeID is also necessary to control the desired file type. This function will also store file-specific info, which can be read with GetFileInfo.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
fileTypeID int to define the file type

Results
Name Type Comment
fileCount int* number of files regarding file type

GetFileInfo

Used to read the name, size, and time of a specified file.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
fileIndex int index to select a certain file

Results
Name Type Comment
fileName char[] filename on device
size int* size of file
OLETime double* days since 01.01.1900 (use OLETime2TimeStruct to convert)
ATTENTION: this time is not absolutely synchronous to the data timestamp.

CopyFile

Used to copy a file from sourceFileName to savePath.

Parameters
Name Type Comment
connectionInstance int to select the correct connection
fileIndex int not used
sourceFileName char[] name of the file on the device
savePath char[] existing path + file name

DeleteFile

TBD

DecodeFile_Select

This function initializes any UDBF file as if it was a connection. Common buffer functions can be used to access the data.

Parameters
Name Type Comment
clientInstance int* if several tasks of the application use the same connection, some DLL functions need the client instance for synchronization.
connectionInstance int* handle that identifies/selects a connection.
fileName char[] source file name

C Programming Examples

This section contains some C code examples for common use cases. These samples should not be seen as complete projects, but they should cover everything needed for a minimal setup. Similar example projects are available as Visual Studio (Windows) and Eclipse (Linux) Projects.

Example: read buffered data

This example shows all functions needed to read a continuous data stream (up to 100 kHz) from a controller. It connects to a controller, reads some general information, and then starts to read measurement values in an endless loop.

#include "eGateHighSpeedPort.h"

int32_t HCONNECTION=-1;
int32_t HCLIENT=-1;
const char* controllerIP = "192.168.5.27";
double* values = NULL;
double channelData = 0;
uint32_t NumberOfChannels = 0;
uint32_t NumberOfFrames = 5000, //needed to dynamically allocate the value-array (-> adjust depending on samplerate);
uint32_t ReceivedFrames = 0,
uint32_t Complete = 0,

bufferIndex=0;

ret = _CD_eGateHighSpeedPort_Init(controllerIP, 5, HSP_BUFFER, 100, &HCLIENT, &HCONNECTION); //Init connection to a Gantner Instruments device
ret = _CD_eGateHighSpeedPort_InitBuffer(HCONNECTION, bufferindex, 0); //init buffer (this is mainly to select a certain buffer by index)
ret = _CD_eGateHighSpeedPort_SetBackTime(HCONNECTION, 0); //empty the device circulat buffer to get only actual data

/******************* Read some device and variable information as needed ********************************************/

ret = _CD_eGateHighSpeedPort_GetDeviceInfo(HCONNECTION, DEVICE_LOCATION, 0, NULL, tempString); //Location means the name of the device
printf("Controller Location: %s\n", tempString);

ret = _CD_eGateHighSpeedPort_GetDeviceInfo(HCONNECTION, DEVICE_CHANNELCOUNT, 0, &info, NULL); //Number of channels in this data stream
printf("Controller Channel Count: %lf\n", info);
ChannelCount = (int)info;

for (uint32_t i = 0; i < ChannelCount; i++)
{
ret = _CD_eGateHighSpeedPort_GetDeviceInfo(HCONNECTION, CHINFO_NAME, i, NULL, tempString); //The name of a channel
printf("Channel %d - %s\n", i, tempString);
}

/******************* Read Data in a loop*****************************************************************************/

values = new double[NumberOfChannels * NumberOfFrames]; //allocate an array with space for a defined number of frames
while (ret == HSP_OK)
{
ret = _CD_eGateHighSpeedPort_ReadBufferToDoubleArray(HCONNECTION, //Read and automatically decode data to the double array
values,
NumberOfChannels * NumberOfFrames,
0,
&ReceivedFrames,
&ChannelCount,
&Complete);
int varNumber = 0;
if(ret == HSP_OK)
{
for (uint32_t i = 0; i < ReceivedFrames;i++) //iterate through the frames in buffer
{
channelData = values[i * NumberOfChannels + varNumber]; //select the double value containing the timestamp (first channel/index = 0)
//all other variables can also be accessed by index

printf("Timestamp: %8.8lf \n", channelData); //print the value
}
}
}
printf("Communication stopped!!");

delete[](values); //don't forget to delete
_CD_eGateHighSpeedPort_Close(HCONNECTION, HCLIENT); //close connection - if not done, the connection will be deleted at dll unload