The TCPORT protocol

Field descriptions

Commands:

Connection Open
Connection Close
Connection Time
List Create
List Reply
List Destroy
List CreateBinary
List ReplyBinary
List CreateWErrs
Do Set, SetBinary
Do Control

Field Descriptions

A message is an ASCII case-insensitive string. It is made of fields separated by the delimiter ',' and terminated by semicolon and NULL ';\00'. There are no optional fields within a message. All messages are made of a fixed header followed by request-specific data or reply status. All numerical data fields are in decimal unless prefixed with an '0x'. All ACNET error status fields are in 4-character hex.

The header fields are:

size	4-characters; total byte size of message including termination characters
object	'cnctn' ,'list','do'
command	depends on the object; see below
id	integer specified by the client; unique for each list or command;echoed in TCPORT server replies

Most replies will have right after the header fields a reply status:

status

a hexadecimal number. If status code indicates a fatal error than there will be no remainder of the reply.

The remainder of the message is the data field which is individually defined for each command.

Connection Open

Opens the connection to the VAX CFSS.fnal.gov or another test VAX as specified. The header and data fields of the request are:

Header
Entry	Value
size	4 char decimal
object	'cnctn'
cmd	'open'
id	msg id decimal
Data
name	node/proj string


Example:
0024,cnctn,open,1,demo;\00

The reply of the VAX TCPORT server on request for opening connection:

Header
Entry	Value
size	4 char decimal
object	'cnctn'
cmd	'open'
id	msg id decimal
Data
status	Acnet status in hex


Example:
0026,cnctn,open,1,0x0000;\00

Connection Close

Request to close the connection:

Header
Entry	Value
size	4 char decimal
object	'cnctn'
cmd	'close'
id	msg id decimal


Example:
0020,cnctn,close,1;\00

Reply of the VAX TCPORT server on request for closing the connection:

Header
Entry	Value
size	4 char decimal
object	'cnctn'
cmd	'close'
id	msg id decimal
Data
status	Acnet status in hex


Example:
0027,cnctn,close,1,0x0000;\00

Connection Time

Ask the TCPORT Server for the current time in order to synchronize the client:

Header
Entry	Value
size	4 char decimal
object	'cnctn'
cmd	'time'
id	msg id decimal

No Data field.


Example:
0019,cnctn,time,1;\00

Reply of the VAX TCPORT server on request for current time:

Header
Entry	Value
size	4 char decimal
object	'cnctn'
cmd	'time'
id	msg id decimal
Data
status	Acnet status in hex
time_s	ctime string
time_d	clink decimal


Example:
0061,cnctn,time,1,0x0000,Fri Jul 21 14:27:22 2000,964189642;\00

List Create

Header
Entry	Value
size	4 char decimal
object	'list'
cmd	'create'
id	msg id decimal
Data
ftd	update rate in hex
entries	num of devices

Create a list with devices to read at periodic intervals:
Repeated for each device:

Device
Entry	Value
name	8 char device name
property	'prread/prset/prbsts'
index	decimal
#elem	decimal


Example:
0067,list,create,1,0x0000,2,
t:ibeam,prread,0,1,t:tbeam,
prread,0,1;\00

Ftd is the frequency time descriptor, see ACnet console manual from AD/Controls. Both events and time-intervals descriptors are allowed. Index*element_size (DABBEL entry) is the byte offset and #elem*element_size is the number of bytes to read. The retrieved bytes are scaled (DABBEL entry) and the results are replied as strings separated by comma's, see List Reply.

The reply to the create list reflects if any of the devices were unknown or the Server was not able in any other way the handle the request:

Header
Entry	Value
size	4 char decimal
object	'list'
cmd	'create'
id	msg id decimal
Data
status	Acnet status in hex


Example:
0027,list,create,1,0x0000;\00

See List CreateWErrs if you want error messages about each device in your list.

List Reply

Reply with readings of the devices in a list:

Header
Entry	Value
size	4 char decimal
object	'list'
cmd	'reply'
id	msg id decimal
Data
status	Acnet status in hex
time	clink time decimal

Repeated for each device:

Device
Entry	Value
status	Acnet status in hex
values	decimals/strings

The values can be the numerical value, e.g. 1.34555, or one of: on, off, reset, pos, neg.


Example:
0069,list,reply,1,0x0000,964190799,0x0000,0.123125,0x0000,30.719063;\00

List Destroy

The request to delete the list does not have a data field and is as follows:

Header
Entry	Value
size	4 char decimal
object	'list'
cmd	'destroy'
id	msg id decimal


Example:
0021,list,destroy,5;\00

The reply coming back from the server has as data field the status of the request, if zero then the list is destroyed otherwise an error occured, e.g. list doesn't exist. Note that you don't have to destroy a one-shot list (FTD=0x0000) and you will get an error if you try to.

Header
Entry	Value
size	4 char decimal
object	'list'
cmd	'destroy'
id	msg id decimal
Data
status	Acnet status in hex


Example:
0028,list,destroy,5,0x0000;\00

List CreateBinary

Create a list with devices to read at periodic intervals with binary replies. Note that the data type and order fields, although required and checked for an allowable value, are ignored. Nothing is done with these values.

Header
Entry	Value
size	4 char decimal
object	'list'
cmd	'createbin'
id	msg id decimal
Data
ftd	update rate in hex
entries	num of devices

Create a list with devices to read at periodic intervals:
Repeated for each device:

Device
Entry	Value
name	8 char device name
property	'prread/prset/prbsts'
type	'default/U8/I8/U16/I16/U32/I32/SGL'
order	'big/little/default'
index	decimal
#elem	decimal


Example:
0098,list,createbin,7,0x0000,2,
t:ibeam,prread,default,big,0,1,i:ibeamm,prread,default,little,0,1;\00

The reply to this request will have a header field with a status field for overall status of the request (it will fail if any of the fields fail).

Header
Entry	Value
size	4 char decimal
object	'list'
cmd	'createbin'
id	msg id decimal
Data
status	Acnet status in hex


Example:
0030,list,createbin,7,0x0000;\00

Considerations:

Server could reformat data into requested format. No data formatting is implemented currently.
Byte order: this might be important for cross platform, all other is in ascii which should not be a problem. Byte order is not implemented currently.
Maybe its better to go completely binary. All headers and so on could be binary. Big endian is preferable because of LabVIEW default.

List ReplyBinary

Reply with readings of the devices in a list:

Header
Entry	Value
size	4 char decimal
object	'list'
cmd	'replybin'
id	msg id decimal
Data
status	Acnet status in hex
time	clink time decimal
entries	num of devices

Repeated for each device:

Device
Entry	Value
status	Acnet status in hex
size	total size (bytes)
data	binary data

The binary data can have any character even the special characters that are unprintable. Since TCP expects to transport printable ascii, certain characters could cause unexpected results. This could include TCP failure to transmit. (?) Such unprintable characters could appear randomly in the data.


Example:
0065,list,replybin,7,0x0000,964191179,2,0x0000,2,@#,0x0000,2,$%;\00

List CreateWErrs

Identical to List Create, but produces different results from the server.

The response to a plain List Create is failure if any of the devices were unknown (bad name) or if the Server was in any other way not able to handle the request.

The response to a List CreateWErrs is again failure if any of the devices were unknown (bad name). However, with "CreateWErrs", the server *will* process the list if other types of errors were found (property errors, etc). Since List Reply tells you the error status of each device in the list, you can determine which device has problems. You will continue to get data on any good items in the list. (There may be a timeout in the server, which stops partially-bad lists after a while.)

The device list that is created will come back in List Reply packets, exactly the same as above. Except for the "cmd" word, the request is identical to List Create:

Header
Entry	Value
size	4 char decimal
object	'list'
cmd	'createWErrs'
id	msg id decimal
Data
ftd	update rate in hex
entries	num of devices

Create a list with devices to read at periodic intervals.
Repeated for each device:

Device
Entry	Value
name	8 char device name
property	'prread/prset/prbsts'
index	decimal
#elem	decimal


Example:
0072,list,createWErrs,1,0x0000,2,
t:ibeam,prread,0,1,t:tbeam,
prread,0,1;\00

Header
Entry	Value
size	4 char decimal
object	'list'
cmd	'createWErrs'
id	msg id decimal
Data
status	Acnet status in hex


Example:
0032,list,createWErrs,1,0x0000;\00

Do Set, Do SetBinary

Request to set an Acnet device to a decimal value or a binary value. Only one device per request is allowed. Only certain devices, from certain requestors, are allowed to be set.

Header
Entry	Value
size	4 char decimal
object	'do'
cmd	'set' or 'setbin'
id	msg id decimal

Device
Entry	Value
device	8 char device string
#elem	decimal
index	decimal
value	decimal or binary

Note the inconsistency in the order of number-elements and index with previous commands. Number of elements is ignored for 'setbin', but must be present.


Example:
0030,do,set,1,T:VAL,1,0,3.12;\00 
Example:
0034,do,set,1,T:VAL,2,0,3.12,4.5;\00

Reply to request for setting:

Header
Entry	Value
size	4 char decimal
object	'do'
cmd	'set' or 'setbin'
id	msg id decimal
Data
status	Acnet status in hex


Example:
0022,do,set,1,0x0000;\00

Do Control

Request to set the status of an Acnet device. Only one device per request is allowed.

Header
Entry	Value
size	4 char decimal
object	'do'
cmd	'control'
id	msg id decimal

Device
Entry	Value
device	8 char device string
value	'on/off/reset/neg/pos'


Example:
0031,do,control,1,T:BLTPOW,on;\00

Reply to request for control:

Header
Entry	Value
size	4 char decimal
object	'do'
cmd	'control'
id	msg id decimal
Data
status	Acnet status in hex


Example:
0030,do,control,1,0xffffed0e;\00

Security, Privacy, Legal