eGateHighSpeedPort API

• 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)

Strings:

Integers:

Device Info ID

Strings:

Integers:

Slave module info ID

Strings:

Integers:

Storage info ID

Buffer ID

Data direction IDs

Connection types

Statistic info types

Diagnostic types

Data storage types

Directory types

File locations

Data types

Callback types

Variable types

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).

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

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).

Read the sample rate as configured at Init or SetSampleRate.

Read the current time of the device.

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

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.

GetReceiveTimeout

Reads the timeout configured with SetReceiveTimeout.

Closes an opened connection and terminates its worker threads.

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

Create a new post-process buffer/system stream.

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

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.

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.

GetDeviceInfo

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

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.

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.

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

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

ReadOnline_Frame

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

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!

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,…).

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.

WriteOnline_ReleaseOutputData

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

This function writes multiple sequential output channels simultaneously.

SetClientState

TBD

TBD

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

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

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).

SeekTimeStamp

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.

GetBufferFrames_All

TBD

LoadBufferData

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

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.

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.

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.

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.

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

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.

GetDebugMessage

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

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.

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.

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).

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.

GetFileInfo

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

CopyFile

Used to copy a file from sourceFileName to savePath.

DeleteFile

TBD

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

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.

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