Anhang 3: Dataexchange Specification for the ComClient with EIB Interface and a Networkdevice

1. Introduction

The ComClient with EIB - Interface is based on the "universal network protocol translation device" of F. Schlaps & Partner GmbH (Germany) called the ComClient. For dataexchange to other networkdevices it uses the well known TCP/IP protocol. Most popular operating systems support this type of network protocol.

1.1 TCP/IP

Every device in a TCP/IP network is identified by an unique IP-address. If this device is connected to the world-wide Internet, this IP-address must be unique world-wide. These IP-addresses are assigned by your local provider. If you are not connected to the world-wide Internet you can free select an IP-address. If you are unsure what the right IP-address might be, ask your network administrator for a valid IP-address.

1.1.1 Addressing

A valid IP-address has the format aaa.bbb.ccc.ddd. Every field from aaa to ddd can contain a numeric value from 0 to 255. For example a valid IP-address is 193.2.1.1.

The first number (aaa) has a special meaning:
1..127 Class A network
128..191 Class B network
192..254 Class C network

Any other values have special meanings not mentioned here.

Any IP-address consists of two parts. The first part is the networkaddress and the second part is the hostaddress within this network..

In a Class A network the IP-address 117.1.2.3 maps to the networkaddress 117 and the hostaddress 1.2.3. In a Class A network can be 127 subnetworks installed with each (2^24)-2 hosts connected. This configuration is typically used by network organizations.

In a Class B network the IP-address 130.67.62.1 maps to the networkaddress 130.67 and the hostaddress 62.1. In a Class B network can be 2^14 subnetworks installed with each (2^16)-2 hosts connected. This configration is typically used by big companies. In a Class C network the IP-address 193.2.1.1 maps to the networkaddress 193.2.1 and the hostaddress 1.

In a Class C network can be 2^22 subnetworks installed with each (2^8)-2 hosts connected. This configration is typically used by small companies.

For special conditions on using a netmask ask your network administrator. Devices that wish to comunicate together, need to have either the same networkaddress or need to know the address of a routerdevice (sometimes called default gateway). You can use the PING utility for checking the connection between to hosts.

Syntax: PING address, e. g.: PING 193.2.1.1

1.1.2 Ports

In a standard environment may concurrently run more than one networkapplication. To determine which application gets wich data from the incomming stream, every application allocates a unique port. This port is used by the lowlevel network interface to supply incomming data to the application which allocated the port. Most standard applications use "well known" ports such as FTP or WWW Browser. The ports from 1024 to 2048 are general purpose ports and may be used freely.

The ComClient listens on port 1111. The answer of a request will be sent to the port suppied by the remote peer (most the same as the ComClient).

2. Description of the Datapackages

2.1 General

The Transmission Control Protocol (TCP)

TCP is stream orientated. That means that a connection must be established before any conversation can be started. As the connection is established data can be sent or received via this connection. At the end of the conversation the connection must be closed. Both partners of the conversation must be available and accessable for this mechanism to work. If one side of both connection endpoints does not meet this conditions a blocking timeout will occure. On the other side TCP handles all handshaking and the correct data delivery. All datas are sent in an endless stream, usefull for "terminal like" applications e. g. Browsers or Telnet.

TCP guarantees the data delivery and the order of the bytes in the stream. But you can not assume that if you send 10 strings of 10 chars each and the receiver will get 10 strings of 10 chars each. The receiver might get first 75 bytes and later 25 bytes. So the reassembling of data must be done by the application if needed.

The User Datagram Protocol (UDP)

UDP is packet orientated. No connection need to be established. The data will be sent, not checking if the receiver is online or ready. There is no mechnism to detect this failure. So any delivery checks need to be done by the sending application. This type of protocol seems to be bad but there are a lot of reasons to use it anywhere:

* If it is not important to receive the data due to it is sent periodically (e: g. the current date and time)

* Every package sent by a host needs to be acknowledged by the other peer. The sender might check a maximum time to acknowledge before signaling a timeout condition.

* Since all data is sent in distinct packages the receiver is not subject to reassemble the original framing from a stream, which is often impossible.

* If high speed operation is needed (because of less overhead).

* If the other host is often not accessable (no blocking timeouts).

The disadvantage of TCP not having handy packages of data does not exist in UDP. If one peer sends first 100 bytes and later 240 bytes, the other peer will get a package of 100 bytes and a package of 240 bytes.

The ComClient uses UDP for communication with other hosts.

Attention:

If not explicitly stated otherwise all integer values are assumed in "INTEL Byte Order".

WORD (16 Bit)

DWORD (32 Bit)

As stated before all data to and from the ComClient is transferred using UDP. All packages received by the ComClient are acknowledged using an Acknowledge packet with or without data appended. Every package has a sequence number which is left unchanged by the ComClient in any case.

Every package that is sent to the ComClient or the acknowledge packet consists of two parts:

* Fixed Header contains all controlling informations

* Raw data data for a command or answerdata to a request.

2.2 Fixed Header

The fixed header has the folowing fields:

DWORD m_packettype 32 Bit integer value using Intel Byte Order
COMMAND 0x00000002
ACK_REPLY 0x00000003
NAK_REPLY 0x00000004
COMMAND_REPLY 0x00000005
The sending peer initializes this field always to COMMAND. The ComClient will answer to COMMAND with ACK_REPLY,NAK_REPLY or COMMAND_REPLY.

DWORD m_handle 32 Bit integer value using Intel Byte Order
a value returned by the EibOpenCom command. This field is to be initialzed in all commands but EibOpenCom

DWORD m_error 32 Bit integer value using Intel Byte Order errorcodes of the request
CCE_NOERR ( 0) no error
CCE_BAD_PWD (-1) bad or invalid login
CCE_TOO_MANY (-2) too many connections
CCE_UNKWN_HST (-3) invalid IP-address
CCE_BAD_CMD (-4) invalid command
CCE_SB_FULL (-5) sendbuffer full
CCE_BAD_COM (-6) bad COM port address
CCE_COM_LOCKED (-7) COM port already in use
CCE_PROTOCOL_NOT_LOADED (-8) protocoldriver not loaded
CCE_COM_NOT_OPEN (-9) COM port not open
CCE_BAD_ARGS (-10) bad or invalid raw data
CCE_BAD_FILE (-11) bad file
CCE_VALUE_NOT_READY (-12) value not available
CCE_COM_BUSY (-13) COM port temporary not

accessable
CCE_COM_INSUFF_MEMORY (-14) insufficient memory

DWORD m_tnum 32 Bit integer value using Intel Byte Order
Sequencenumber of this package. This number needs to be incremented on each request.

DWORD m_protocol 32 Bit integer value using Intel Byte Order
Protocol ID always 00000205 hex

DWORD m_command 32 Bit integer value using Intel Byte Order
1 EibOpenComm Opens a connection to a ComClient
2 EibCloseCom Closes an open connection to a ComClient
3 EibWriteGroup Writes a value to a specific group address
4 EibReadHist Reads the current historybuffer
5 EibPeekHist Checks the historybuffer for new entries
6 EibFlushHist Resets the historybuffer
7 EibReqGroup Requests the value of a specific group

address

2.1 Description of the raw data by command

2.3.1 EibOpenCom

Purpose: Opens a connection to a ComClient

Raw Datas:

DWORD m_login 32 Bit integer value using Intel Byte Order
alway: 61649120 hex

Reply: On reply the field m_handle will have the handle to that connection if no error occured. To check for errors see m_error description in the fixed header above.

2.3.2 EibCloseCom

Purpose: Closes a connection to a ComClient

Raw Datas:

none

Reply: On successful reply the field m_handle will be released and invalid. To check for errors see m_error description in the fixed header above.

2.3.3 EibWriteGroup

Purpose: Writes a single value to a group address

Raw Datas:

WORD m_ga 16 Bit integer value using Intel Byte Order
value of the groupaddress

WORD m_len 16 Bit integer value using Intel Byte Order
value length 0 = 1 .. 6 Bit, 1 = 1 Byte, 2 = 2 Byte....

BYTE[14] m_value array of 14 bytes to hold the value

Reply: To check for errors see m_error description in the fixed header above.

2.3.4 EibReadHist

Purpose: Reads the historylist and flushes all entries from the buffer

Raw Datas:

WORD m_len 16 Bit integer value using Intel Byte Order
size of the buffer that will receive the historylist The size must not excceed 512 bytes.

Reply: To check for errors see m_error description in the fixed header above.

and so on

WORD m_count 16 Bit integer value using Intel Byte Order number of values returned

WORD m_allt 16 Bit integer value using Intel Byte Order
0 if values reside in buffer, not 0 if all values returned.

WORD m_ga[x] 16 Bit integer value using Intel Byte Order value of the groupaddress in entry x

BYTE[14] m_value[x] array of 14 bytes to hold the value in entry x

DWORD m_timestamp[x] 32 Bit integer value using Intel Byte Order timestamp of this value (higher means newer) in entry x

2.3.5 EibPeekHist

Purpose: Reads the historylist and leave entries in the buffer

Raw Datas:

WORD m_len 16 Bit integer value using Intel Byte Order
size of the buffer that will receive the historylist The size must not excceed 512 bytes.

Reply: To check for errors see m_error description in the fixed header above.

and so on

WORD m_count 16 Bit integer value using Intel Byte Order number of values returned

WORD m_allt 16 Bit integer value using Intel Byte Order
0 if values reside in buffer, not 0 if all values returned.

WORD m_ga[x] 16 Bit integer value using Intel Byte Order value of the groupaddress in entry x

BYTE[14] m_value[x] array of 14 bytes to hold the value in entry x

DWORD m_timestamp[x] 32 Bit integer value using Intel Byte Order timestamp of this value (higher means newer) in entry x

2.3.6 EibFlushHist

Purpose: Clear the complete historylist

Raw Datas:

none

Reply: On successful reply the field m_handle will be released and invalid. To check for errors see m_error description in the fixed header above.

2.3.7 EibReqGroup

Purpose: Request to read a groupadress value from the instabus

Raw Datas:

WORD m_ga 16 Bit integer value using Intel Byte Order
value of the groupaddress

Reply: On reply the field m_handle will have the handle to that connection if no error occured. To check for errors see m_error description in the fixed header above.

3. Flow of data

The application creates a UDP socket on port 1111.

Use the socketfunction send_to() to send a packet to a ComClient.

Use the socketfunction receive_from() to receive any incomming packet for port 1111.

For details refer to the TCP/IP documentation.

Sample:

4. Common Datatypes and Macros

Types used by the samplecode

typedef void VOID ,*PVOID ,FAR* LPVOID ,FAR* const LPCVOID;

typedef char CHAR ,*PSTR ,FAR* LPSTR ,FAR* const LPCSTR;

typedef unsigned char BYTE ,*PBYTE ,FAR* LPBYTE ,FAR* const LPCBYTE;

typedef short int SINT ,*PSINT ,FAR* LPSINT ,FAR* const LPCSINT;

typedef unsigned short int WORD ,*PWORD ,FAR* LPWORD ,FAR* const LPCWORD;

typedef int INT ,*PINT ,FAR* LPINT ,FAR* const LPCINT;

typedef unsigned int UINT ,*PUINT ,FAR* LPUINT ,FAR* const LPCUINT;

typedef long LONG ,*PLONG ,FAR* LPLONG ,FAR* const LPCLONG;

typedef unsigned long DWORD,*PDWORD,FAR* LPDWORD,FAR* const LPCDWORD;

Macros used by the samplecode

LOBYTE

BYTE LOBYTE(value)

Extracts the LSByte (lowest significant byte) from a value

Parameter value
sourcevalue

Return LSByte from the sourcevalue

HIBYTE

BYTE HIBYTE(value)

Extracts the MSByte (most significant byte) from a value

Parameter value
sourcevalue

Return MSByte from the sourcevalue

LOWORD

WORD LOWORD(value)

Extracts the LSWord(lowest significant word) from a value

Parameter value
sourcevalue

Return LSWord from the sourcevalue

HIWORD

WORD HIWORD(value)

Extracts the MSWord(lowest significant word) from a value

Parameter value
sourcevalue

Return MSWord from the sourcevalue

ML

LONG ML(low,high)

WORD low;

WORD high;

Creates a signed 32 Bit value from low and high.

Parameter low LSWord
high MSWord

Return the resulting signed 32 Bit value

MDW

DWORD MDW(low,high)

WORD low;

WORD high;

Creates an unsigned 32 Bit value from low and high.

Parameter low LSWord
high MSWord

Return the resulting unsigned 32 Bit value

5. Sequences

OpenSequence

Host send to ComClient

Reply from ComClient

CloseSequence

Host send to ComClient

Reply from ComClient

Write Value

Host send to ComClient

Reply from ComClient

Request Value Read

Host send to ComClient

Reply from ComClient

Flush History

Host send to ComClient

Reply from ComClient

Read/Peek History Buffer

Host send to ComClient

Reply from ComClient