FTPMAN Protocol

March 23, 1998 Glenn C. Johnson Carl Schumann

General Comments

The Fast Time Plot protocol is transmitted as the data of an ACNET packet. This protocol uses the ACNET data representation.
The front-end process which handles Fast Time Plot requests connects to ACNET with the Rad-50 handle FTPMAN.
Two types of fast time plots must be supported: Continuous and Snapshot plots.
A continuous plot is a plot that updates in real time. The plot is updated at a minimum rate of 2 Hz, and data collection frequencies of up to 1440 Hz are supported. The most popular data collection rate is AUTO, in which a data collection rate appropriate for each device and the plot time window is automatically chosen.
Snapshot plots are used to plot at rates faster than those available with continuous plots. When an arm event occurs, 2048 data points are collected at a specified rate and stored in a front-end buffer. Because snapshots can be large (>8K bytes/device) and plotting them is not time-critical, snapshot data are returned in small pieces in response to single-reply requests from plotting tasks. Snapshots reequests do generate multiple replies, but these replies are for status only.
Plotting resources inside the front-end should be allocated on a priority basis. The plot priority is included in console request structures. Plots of lower priority must be terminated in order to release resources needed by a higher-priority request.
If a console is restarted, front-ends should cancel any outstanding continuous or snapshot plots associated with that console, thus releasing any resources allocated to that console. A front-end can detect a restart because a console will send an ACNET cancel in response to the multiple replies which contain an unknown requesting task id from the front-end. Previous statement assumes the requesting task id has not been reasigned which is possible.
Each plotting task is allowed to have only one continuous or snapshot plot active at one time. If a new request is received from a plotting task, any previous request from that task should be automatically canceled.
In the description of the packet formats below, all fields in the packets abut.

Request Plot Class Information, Typecode 1

Length (bytes)	Field Description	Type
2	Typecode = 1	2-byte unsigned integer
2	Number of devices requested	2-byte unsigned integer
12	Request packet for device 1	structure see below
---	---	---
12	Request packet for device N	structure see below

Before making requests to setup a continuous or snapshot plot, a plotting task makes a single-reply request to the front-end to retrieve plot class information for the devices to be plotted.
The class codes are used to retrieve a structure containing various information about the devices' plotting capabilities, such as collection rates and buffer sizes supported, which typecode to use, whether timestamps are returned, etc. This information does contain more than just maximum frequency. This information in the case of snapshot is contained within the code for the DIO routines for snapshot plotting and the snapshot secondary application. In the case of FTP this information is in the source code for the FTP console application. A new version of MOOC can avoid understanding the capabilities of these classes by having new codes assigned for it.

Plot Class Information Request Packet

Length (bytes)	Field Description	Type
4	Property-Device Index Pair	4-byte unsigned integer
8	SSDN	Array of 8 1-byte unsigned integers

Plot Class Information Reply

Length (bytes)	Field Description	Type
2	ACNET Error Status	2-byte signed integer
6	Class information for device 1	structure see below
---	---	---
6	Class information for device N	structure see below

Plot Class Information Reply Packet

Length (bytes)	Field Description	Type
2	ACNET Error Status	2-byte signed integer
2	FTP Class Code	2-byte unsigned integer
2	SNP Class Code	2-byte unsigned integer

FTP Class Code List

Code	Description	Max Continuous
11	C190 MADC channel	720 Hz
12	Internet Rack Monitor	1000 Hz
13	MRRF MAC MADC channel	100 Hz
14	Booster MAC MADC channel	15 Hz
15	15 Hz (Linac, D/A's etc.)	15 Hz
16	C290 MADC channel	1440 Hz
18	60 Hz internal	60 Hz
19	68K (MECAR)	1440 Hz

The above codes only support the typecode 6 setup request, which is shown below. The older typecode 2 has been retired.

SNP Class Code List

Code	Description	Max Snapshot
11	C190 MADC channel	~66 Khz
12	1440 Hz internal	1440 Hz
13	C290 MADC channel	~90 Khz
14	15 Hz internal	15 Hz
15	60 Hz internal	60 Hz
16	Quick Digitizer (Linac)	1-10 Mhz
17	720 Hz internal	720 Hz
18	New FRIG circ buffer	1 Khz
19	Swift Digitizer	800 Khz

The above codes only support the typecode 7 setup request, which is shown below. The older typecode 3 has been retired.

Setup a Continuous Plot, Typecode 6

Length (bytes)	Field Description	Type
2	Typecode = 6	2-byte unsigned integer
4	Requesting task name - RAD50	4-byte unsigned integer
2	Number of devices	2-byte unsigned integer
2	Return period in 15 Hz ticks	2-byte unsigned integer
2	Max data return buffer size in words(2-bytes)	2-byte unsigned integer
2	Data return reference word	2-byte unsigned integer
2	Start data return time in 15 Hz ticks	2-byte unsigned integer
2	Stop data return time in 15 Hz ticks	2-byte unsigned integer
2	Priority	2-byte unsigned integer
2	Current time (15 Hz) in TS(timestamp) cycle	2-byte unsigned integer
10	Zeroes (reserved)	---
22	Continuous plot request packet 1	structure see below
---	---	---
22	Continuous plot request packet N	structure see below

To start a continuous plot, a plotting task sends a multiple-reply request to the FTPMAN task on the appropriate front-ends.
A network cancel message is sent to stop the plot in progress.
The return period (in 15 Hz ticks) will be between 1(15 Hz) and 7(2.14 Hz), inclusive.
The "data return reference word", "start data return time", and "stop data return time" are associated with an unimplemented feature. The front-end should ignore the contents of these fields.
The plot priority is a number which is used to determine the relative priority of conflicting requests. A low priority request should be terminated if the resources it holds are needed by an incoming higher-priority request. A low number is a low priority. Currently, there are four priorities - 0(user), 1(other control room), 2(main control room), 3(sda).
The current time in timestamp cycle is provided for front-ends which do not have hardware to receive 02 events, so that they can synchronize with the 02 event.
The data return reference word specifies which clock event (or group of clock events) the "Start Data Return Time" and "Stop Data Return Time" are referenced to. Refer to ACNET Design Note 49.8 for more information on the structure of this word.

Continuous Plot Request Packet

Length (bytes)	Field Description	Type
4	Property-Device Index Pair	4-byte unsigned integer
4	Device Offset in bytes	4-byte unsigned integer
8	SSDN	Array of 8 1-byte unsigned integers
2	Data Sample Period in 10 usec units	2-byte unsigned integer
4	Zeroes (reserved)	---

Upon receipt of a continuous plot setup request, the front-end will first cancel any previous continuous or snapshot request from the requesting task.
If any one of the requested devices cannot be accommodated, the entire request is rejected. Note that this is diferent from snapshot which will consider the request successful if any individual device request succeeds.
The data sample period is the only means to specify when sampling occurs. FTP protocol does not support on event sampling. The FTP application uses RETDAT protocol to support on event sampling.
The length is not specified. The FTP application assumes the length is the default length in the device database, which will be 1, 2, or 4 bytes. The front-end will assume a length based on the device, which hopefully agrees with what the FTP application gets from the database.
Since an SSDN must be specified only properties which have an SSDN may be used. Some properties which have an SSDN do not make sense to plot, e.g., alarm blocks. Therefore the property will be either reading or setting.

First Reply to Continuous Plot Setup Request

Length (bytes)	Field Description	Type
2	ACNET Error Status	2-byte signed integer
2	Continuous Reply Type = 1	2-byte unsigned integer
2	ACNET Error Status for device 1	2-byte signed integer
---	---	---
2	ACNET Error Status for device N	2-byte signed integer

The first reply sent to the requesting task contains error codes and no plot data.
Subsequent replies contain plot data as shown below.
If the request cannot be honored, the first reply is also the last reply.

Continuous Plot Data Reply Structure

Length (bytes)	Field Description	Type
2	ACNET Error Status	2-byte signed integer
2	Continuous Reply Type = 2	2-byte unsigned integer
4	Reserved	---
6	Data Reply Packet for device 1	structure see below
---	---	---
6	Data Reply Packet for device N	structure see below
variable length	Array of "returned data points" for device 1 (elements sorted by time)	array of structures see below for structure definition
---	---	---
variable length	Array of "returned data points" for device N (elements sorted by time)	array of structures see below for structure definition

The length and positioning of the variable length arrays is specified in the fixed-length data reply packet structure.
The variable length arrays do not have to abut.

Continuous Data Reply Packet

Length (bytes)	Field Description	Type
2	ACNET Error Status	2-byte signed integer
2	Pointer to first data point	2-byte unsigned integer
2	Number of points returned	2-byte unsigned integer

Pointers are byte offsets from the beginning of the reply buffer.

Format of Returned Data Points

Length (bytes)	Field Description	Type
2	Timestamp	2-byte unsigned integer
2 or 4	Data value	various

Each data point includes an unsigned 16-bit timestamp which must have a resolution of 100 uSec, and must be reset by the occurrance of TCLK event 02.
The 2 or 4 byte data value can be in any format supported by the scaling routines. 1-byte data can be returned using a 2-byte data value and an appropriate PDB with padding.

Setup a Snapshot Plot, Typecode 7

Length (bytes)	Field Description	Type
2	Typecode = 7	2-byte unsigned integer
4	Requesting task name - RAD50	4-byte unsigned integer
2	Number of devices	2-byte unsigned integer
2	Arm and trigger selection word	2-byte unsigned integer
2	Priority	2-byte unsigned integer
4	Data sample rate in Hz	4-byte unsigned integer
4	Arm delay (uSec or sample periods)	4-byte unsigned integer
8	Arm clock events	Array of 8 1-byte clock events
4	Sample trigger clock events	Array of 4 1-byte clock events
4	Number of points	4-byte unsigned integer
4	arm device property-device Index Pair	4-byte unsigned integer
4	arm device Offset in bytes	4-byte unsigned integer
8	arm device SSDN	Array of 8 1-byte unsigned integers
4	arm device mask	4-byte unsigned integer
4	arm device value	4-byte unsigned integer
8	Zeroes (reserved)	---
20	Snapshot request packet 1	structure see below
---	---	---
20	Snapshot request packet N	structure see below

To setup a snapshot plot, a plotting task sends a multiple-reply request to the FTPMAN task on the appropriate front-ends.
A network cancel message is sent to delete an active snapshot request.
The requesting task name may not neccesarily be an ACNET handle. Tasks which need multiple snapshot plots, e.g., SDA, will accomplish this by using different task names even though the task has a single ACNET handle
The arm and trigger selection word is specified below..
The plot priority is a number which is used to determine the relative priority of conflicting requests. A low priority request should be terminated if the resources it holds are needed by an incoming higher-priority request. The priorities are the same as for FTP. Since FTP and snapshot share resources the a high priority plot of one type can prempt plots of the other type.
Data sample rate in Hz is only used when the arm and trigger selection word specifies trigger soure to be 0.
The meaning of the arm delay field depends on the plot mode specified in the arm and trigger selection word. For plot mode 2 (post-trigger) the arm delay is the number of microseconds after arming the front-end should wait before it begins collecting data on occurances of the trigger. For plot mode 3 (pre-trigger) the "arm delay" is the number of samples to be gathered after the arm condition occurs.
The Arm and Sample Trigger clock events are specified one event per byte, with the lowest event number first (unsigned). FF (hex) is used to designate no clock event.
Number of points is the number of data points, i.e., timestamp-value pairs, to be collected for each device.
The arm device fields are used to specify the arm condition when arm source 0 (device) is specified in the arm and trigger selction word. The arm condition is satisfied when the selected devices property value at the given offset bitwise anded with the mask equals the value given in the arm device field. The frequency with which the front-end monitors the arm device to check if the arm condition has been satisfied is not specified - the front-end can do whatever it wants. The length of the arm device is unspecified and should match the default length specified in the device database. The arm device must be serviced by the front-end receiving the request. The arm device property must be a property that as an SSDN. Typically the property is a basic status.

Snapshot Request Packet

Length (bytes)	Field Description	Type
4	Property-Device Index Pair	4-byte unsigned integer
4	Device Offset in bytes	4-byte unsigned integer
8	SSDN	Array of 8 1-byte unsigned integers
4	Zeroes (reserved)	---

Upon receipt of a snapshot request, front-ends will first cancel any previous continuous or snapshot request from the requesting task.
If any of the requested devices can be accommodated, the entire request is considered successfull. Note that this is diferent from FTP which will reject the entire request if an individual device request fails.
The front-end may change items in the request to match the capabilities of the front-end and the snapshot hardware. The actual values used are returned in the reply.

Arm and trigger selection word

Bit (15 is most-significant)
15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
zeros			TM			TS		zero	PM		AM			AS

Field	Value	Meaning
AS (Arm Source)	0	arm on device
	1	arm immediately
	2	arm on logical OR of arm clock events
	3	arm on external source specified by AM field
AM (Arm Modifier)		this is only used if AS = 3, and then must be a value between 0 and 3, inclusive
PM (Plot Mode)	0	invalid
	1	invalid
	2	post-trigger, i.e., collect "number of points" "arm delay" microseconds after arm
	3	pre-trigger, i.e., begin collection immediately stop "arm delay" samples after arm
TS (Trigger Source)	0	collect every "data sample period"
	1	invalid
	2	collect on logical OR of sample trigger clock events
	3	trigger on external event specified by TM field
TM (Trigger Mode)		this is only used if TS = 3, and then must be a value between 0 and 3, inclusive

Snapshot Setup Reply

Length (bytes)	Field Description	Type
2	ACNET Error Status	2-byte signed integer
2	Arm and trigger selection word	2-byte unsigned integer
4	Data sample rate in Hz	4-byte unsigned integer
4	Arm delay (uSec or sample periods)	4-byte unsigned integer
8	Arm clock events	Array of 8 1-byte clock events
4	Number of points	4-byte unsigned integer
18	Device reply packet for device 1	structure see below
---	---	---
18	Device reply packet for device N	structure see below

Device Reply Packet

Length (bytes)	Field Description	Type
2	ACNET Error Status	2-byte signed integer
4	Reference point number	4-byte unsigned integer
4	Snapshot arm time (seconds)	4-byte unsigned integer
4	Snapshot arm time (nanosecs)	4-byte unsigned integer
4	Zeroes (reserved)	---

The reference point number for the device is for pre-trigger plots only and indicates the first point collected after the arm event. It is an offset from the first point collected. This field will not be meaningful until the arm event has occured. The ACNET status will indicate if the plot is still waiting for the arm event to occur.
The snapshot arm time consists of two components: seconds since January 1, 1970, and nanoseconds within this second. It is expected that most front-ends will not support the nanosecond portion of this time.
The reply packet indicates what changes the front-end made to the request in order to service it.

Retrieve Block of Snapshot Data, Typecode 8

Length (bytes)	Field Description	Type
2	Typecode = 8	2-byte unsigned integer
4	Requesting task name - RAD50	4-byte unsigned integer
2	Item number of device	2-byte unsigned integer
2	Number of points requested	2-byte unsigned integer
4	Point number or -1	4-byte unsigned integer

Typecode 8 supports random access to the plot data.
The plotting task sends a single-reply request to the FTPMAN task.
Data is returned for 1 device only with each request.
The "item number of device" starts at 1 for the first device.
The "point number" must be in the range 0 to n, or -1 if sequential access is desired.
If the plot mode is post-trigger data can be retrieved while data collection is in progress. If the plot mode is pre-trigger data can not be retreived until all data has been collected.

Snapshot Return Data Reply

Length (bytes)	Field Description	Type
2	ACNET Error Status	2-byte signed integer
2	Number of points returned	2-byte unsigned integer
---	Data in Chronological Order	---

Some snapshot classes return data with timestamps. These snapshot classes return data in the first data return format as defined in the continuous plot protocol section. Other snapshot classes just return the data without timestamps. The presence or absense of timestamps is known by the snapshot requester by the snapshot class returned from the front-end.
Note that the ACNET status here should match the status returned in the status-only multiple reply.

Restart a Snapshot, Typecode 5

Length (bytes)	Field Description	Type
2	Typecode = 5	2-byte unsigned integer
4	Requesting task name - RAD50	4-byte unsigned integer
2	Subtype code = 1	2-byte unsigned integer

To restart, i.e., to rearm and get another plot, a snapshot, the plotting task sends a single-reply request to the FTPMAN task.

Restart Snapshot Reply

Length (bytes)	Field Description	Type
2	ACNET Error Status	2-byte signed integer

Reset Snapshot Retrieval Pointers, Typecode 5

Length (bytes)	Field Description	Type
2	Typecode = 5	2-byte unsigned integer
4	Requesting task name - RAD50	4-byte unsigned integer
2	Subtype code = 2	2-byte unsigned integer

To reset, i.e., re-read, snapshot data, a plotting task sends a single-reply request to the FTPMAN task.
The data retrieval pointers for the snapshot will be reset, and future "retrieve snapshot data" requests (typecode 8) will return data starting at the beginning of the snapshot data.

Reset Snapshot Retrieval Pointers Reply

Length (bytes)	Field Description	Type
2	ACNET Error Status	2-byte signed integer

Security, Privacy, Legal