Remote Control
|
Message Types
|
This part of the documentation describes the low level communication protocol necessary to remote control
SymPhoTime 64. Since its existence, we had to realize that it seems to be a little cumbersome for
non-PicoQuant-associates to get it implemented bug-free and stable. Subsequently we decided to provide a
library (shipped as DLL) with some simplifying functions, that encapsulate the whole low level protocol.
There are seven types of messages:
|
E_PQ_MESSAGE_TYPE (unsigned int8)
|
|
|
Symbol |
Code |
Meaning |
PQ_MSGTYP_DATAFRAME_SRVREQUEST
|
0x44 = 'D'
|
server request message
has to be answered with a server reply
(i.e. 'd'-typed message)
|
PQ_MSGTYP_DATAFRAME_SRVREPLY
|
0x64 = 'd'
|
answer on a server request
(must not be answered)
|
PQ_MSGTYP_DATAFRAME_SRVNACK
|
0x78 = 'x'
|
data frame sent by server
(must not be answered)
|
PQ_MSGTYP_ENCODED_STATUSMSG
|
0x43 = 'C'
|
status message
has to be answered with a status reply
(i.e. either 'c'-typed or 's'-typed message)
|
PQ_MSGTYP_ENCODED_STATUSREPLY
|
0x63 = 'c'
|
answer on a status message
(must not be answered)
|
PQ_MSGTYP_EXPLAINED_STATUSMSG
|
0x53 = 'S'
|
status message
enhanced by a free explaining text
has to be answered with a status reply
(i.e. either 'c'-typed or 's'-typed message)
|
PQ_MSGTYP_EXPLAINED_STATUSREPLY
|
0x73 = 's'
|
answer on a status message
enhanced by a free explaining text
(must not be answered)
|
|
|
|
|
|
All messages that deserve a reply (i.e. types 'D', 'C' and 'S')
need to be answered to within a certain time out period (currently 4000 msec).
Messages of the type server request ('D') are only sent by clients, messages of
the type server reply ('d') and server dataframe ('x') are only sent by servers.
The remaining message types may be sent by clients and servers as well.
The "…EXPLAINED
…"-types differ from the
"…ENCODED
…"-types only in an attached string
(uncoded text) preceded by one word of length specification.
The message type "PQ_MSGTYP_DATAFRAME_SRVREQUEST
":
This type of message is always sent by a client to request a server (SymPhoTime).
All data needed by the server to perform the measurement is transferred with
this request.
|
T_DATAFRAME_SRVREQUEST
|
|
|
Name
|
Type
|
Containing
|
hdr
|
T_MESSAGEHDR
|
obligatory message header
identifying this message type
|
rvRecVersion
|
T_REC_VERSION
|
for future record version management
current record version is 1.0.2.0
(i.e. 0x00, 0x02, 0x00, 0x01 on stream)
|
iMeasurementType |
E_PQ_MEAS_TYPE
|
type of requested measurement
|
iPixelNumber_X
|
int32
|
if type of measurement is image, this denotes the image width
|
iPixelNumber_Y
|
int32
|
if type of measurement is image, this denotes the image height
|
iScanningPattern
|
int32
|
0:
|
monodirectional
|
1:
|
bi-directional
|
|
fSpatialResolution
|
float32
|
if type of measurement is image, this denotes the size of the pixels in units of m.
|
iOptRecordCount
|
int32
|
number of optional data records to follow
|
odOptional
|
array [1..iOptRecordCount]
of T_OPTIONAL_DATA
|
optional data records, identified by name;
if the name is introduced, SymPhoTime will interpret the
data, otherwise treat it as comment to the measurement.
|
|
|
|
|
|
The message type "PQ_MSGTYP_DATAFRAME_SRVNACK
":
This type of message is always sent by the server (SymPhoTime) and gives
a feedback on several quality describing parameters during the measurement.
All parameters are sent as optional data records. How many and which parameters
are compiled to each message depends on the type of the running measurement
and may be subject to change without notice.
The emission of those messages is time triggered with an interval of ca.
1 sec but may vary depending on the processor load.
Clients must not answer this type of message to avoid slowing down the
running measurement process. To support the creation of log tables and the
detection of lost records on the client's site, the messages sent are
consecutively numbered.
|
T_DATAFRAME_SRVNACK
|
|
|
Name
|
Type
|
Containing
|
hdr
|
T_MESSAGEHDR
|
obligatory message header
identifying this message type
|
rvRecVersion
|
T_REC_VERSION
|
for future record version management
current record version is 1.0.2.0
(i.e. 0x00, 0x02, 0x00, 0x01 on stream)
|
iMeasurementType |
E_PQ_MEAS_TYPE
|
type of running measurement
|
iNACKRecNumber
|
int32
|
consecutive increasing record number
|
iOptRecordCount
|
int32
|
number of optional data records to follow
|
odOptional
|
array [1..iOptRecordCount]
of T_OPTIONAL_DATA
|
optional data records, identified by name;
if the name is introduced to the client,
it may interpret the record, otherwise it may skip it as unknown data.
But even then every client has all information to at least display or
print the data.
|
|
|
|
|
|
Types of Measurement:
|
E_PQ_MEAS_TYPE (int32)
|
|
|
Symbol |
Code |
Meaning |
PQ_MEASTYPE_POINTMEAS
|
0x00000000
|
point measurement
|
PQ_MEASTYPE_IMAGESCAN
|
0x00000001
|
image scan
|
PQ_MEASTYPE_TEST_POINTMEAS
|
0x00000080
|
test run for a point measurement;
no data will be stored in workspace
|
PQ_MEASTYPE_TEST_IMAGESCAN
|
0x00000081
|
test run for an image scan;
no data will be stored in workspace
|
|
|
|
|
|
Optional Data Records:
Even though some optional data records are predefined,
a client could send whatever it deems to be important for the documentation
of the measurement. Each optional data record satisfies one of the following
three format descriptions:
|
T_OPTIONAL_DATA (with data directly following)
|
|
|
Name
|
Type
|
Containing
|
cName
|
array [0..PQ_OPT_DATATYPE_NAME_MAXLEN]
of char
|
null terminated string
|
bType
|
E_PQ_OPT_DATATYPE
|
one of the following:
-
PQ_OPT_DATATYPE_FLOAT (4 bytes single precision)
-
PQ_OPT_DATATYPE_LONG (4 bytes integer)
-
PQ_OPT_DATATYPE_ULONG (4 bytes cardinal)
|
qbData
|
T_FOUR_BYTE_TYPES
|
four bytes of data
|
|
|
|
|
|
|
T_OPTIONAL_DATA (with array following)
|
|
|
Name
|
Type
|
Containing
|
cName
|
array [0..PQ_OPT_DATATYPE_NAME_MAXLEN]
of char
|
null terminated string
|
bType
|
E_PQ_OPT_DATATYPE
|
one of the following:
-
PQ_OPT_DATATYPE_FLOATS_ARRAY
-
PQ_OPT_DATATYPE_LONGS_ARRAY
-
PQ_OPT_DATATYPE_ULONGS_ARRAY
|
wCount
|
word
|
count of elements in array
|
arrData
|
array [1..wCount]
of T_FOUR_BYTE_TYPES
|
wCount elements of one of the following:
(wCount times four bytes of data, depending on bType)
-
PQ_OPT_DATATYPE_FLOAT (4 bytes single precision)
-
PQ_OPT_DATATYPE_LONG (4 bytes integer)
-
PQ_OPT_DATATYPE_ULONG (4 bytes cardinal)
|
|
|
|
|
|
|
T_OPTIONAL_DATA (with string following)
|
|
|
Name
|
Type
|
Containing
|
cName
|
array [0..PQ_OPT_DATATYPE_NAME_MAXLEN]
of char
|
null terminated string
|
bType
|
E_PQ_OPT_DATATYPE
|
PQ_OPT_DATATYPE_FIXED_LENGTH_STRING
|
wLen
|
word
|
count of characters in string
|
strText
|
char [0..wLen-1]
|
string with wLen characters
|
|
|
|
|
|
In the current version of SymPhoTime the names of the optional data records
may be up to PQ_OPT_DATATYPE_NAME_MAXLEN = 30
characters long. The unused space up to the PQ_OPT_DATATYPE_NAME_MAXLEN + 1st
character has to be filled with NULL characters.
Types of Optional Data:
|
E_PQ_OPT_DATATYPE (unsigned int8)
|
|
|
Symbol |
Code |
Meaning |
PQ_OPT_DATATYPE_FLOAT
|
0x00
|
floating point (4 byte, single precision)
|
PQ_OPT_DATATYPE_LONG
|
0x01
|
integer (4 byte)
|
PQ_OPT_DATATYPE_ULONG
|
0x02
|
cardinal (unsigned integer, 4 byte)
|
PQ_OPT_DATATYPE_FLOATS_ARRAY
|
0xF0
|
floating point array (n × 4 byte, single precision)
|
PQ_OPT_DATATYPE_LONGS_ARRAY
|
0xF1
|
integer array (n × 4 byte)
|
PQ_OPT_DATATYPE_ULONGS_ARRAY
|
0xF2
|
cardinal array (n × 4 byte)
|
PQ_OPT_DATATYPE_FIXED_LENGTH_STRING
|
0xFF
|
character array (n byte string)
it is recommended to be terminated with a NULL character
|
|
|
|
|
|
Predefined Optional Data Records
Following the currently introduced optional data records are named. These
are the records understood by SymPhoTime when received in server requests.
A controlling application may or may not send others than these, but they
will be treated as comments only and are semantically ignored.
For names and types of optional data records in data frames
sent by the server during a running measurement (a.k.a. NACK frames), refer
to the page on feedback values.
|
Name
|
Type
|
max. Count / max. Length
|
Containing
|
TimePerPixel
|
PQ_OPT_DATATYPE_FLOAT
|
1
|
time [s] required to measure a pixel
|
TimePerImageEstimated
|
PQ_OPT_DATATYPE_FLOAT
|
1
|
estimated time [s] for the measurement
|
Filename
|
PQ_OPT_DATATYPE_FIXED_LENGTH_STRING
|
255
|
name of the t3r-file to store the measurement without extension
|
Groupname
|
PQ_OPT_DATATYPE_FIXED_LENGTH_STRING
|
63
|
name of the group of measurements
|
Objective
|
PQ_OPT_DATATYPE_FIXED_LENGTH_STRING
|
255
|
description of the objective
|
Pinhole
|
PQ_OPT_DATATYPE_FIXED_LENGTH_STRING
|
255
|
description of the pinhole
|
MajorDichroic
|
PQ_OPT_DATATYPE_FIXED_LENGTH_STRING
|
255
|
description of the major dichroic
|
TimeStampArray
|
PQ_OPT_DATATYPE_FLOATS_ARRAY
|
512
|
time/pixel correction for nonlinear scanning
(reserved for future implementation)
|
Comment
|
PQ_OPT_DATATYPE_FIXED_LENGTH_STRING
|
65535
|
ad lib.
|
|
|
|
|
|
|
The message types
"PQ_MSGTYP_DATAFRAME_SRVREPLY
",
"PQ_MSGTYP_ENCODED_STATUSMSG
" and
"PQ_MSGTYP_ENCODED_STATUSREPLY
"
These types of message are sent by clients and server (SymPhoTime) as well.
They don't differ on a formal level but of cause send differently coded status values.
|
T_ENCODED_STATUSMSG (if sent by server)
|
|
|
|
|
|
|
|
|
T_ENCODED_STATUSMSG (if sent by clients)
|
|
|
|
|
|
|
|
The message types
"PQ_MSGTYP_EXPLAINED_STATUSMSG
" and
"PQ_MSGTYP_EXPLAINED_STATUSREPLY
"
These types of message are sent by clients and server (SymPhoTime) as well.
They don't differ on a formal level but of cause send differently coded
status values. They are very similar to the …ENCODED…
message types, with the exception, that they come with an explaining free text.
|
T_EXPLAINED_STATUSMSG (if sent by server)
|
|
|
Name
|
Type
|
Containing
|
hdr
|
T_MESSAGEHDR
|
obligatory message header
identifying this message type
|
ecStatus
|
E_ERROR_CODES
|
status code sent by server
|
usExpLength
|
word
|
length of explaining text
|
strExplanation
|
char [0..usExpLength-1]
|
explaining text
|
|
|
|
|
|
|
T_EXPLAINED_STATUSMSG (if sent by clients)
|
|
|
Name
|
Type
|
Containing
|
hdr
|
T_MESSAGEHDR
|
obligatory message header
identifying this message type
|
srStatus
|
E_STOPREASON_CODES
|
stop reason code sent by client
|
usExpLength
|
word
|
length of explaining text
|
strExplanation
|
char [0..usExpLength-1]
|
explaining text
|
|
|
|
|
|
Stop Reason Codes as sent by clients
|
E_STOPREASON_CODES (int16)
|
|
|
Symbol |
Code |
Meaning |
PQ_STOPREASON_CODE_CONTINUE_OK
|
0
|
no error detected
|
PQ_STOPREASON_CODE_FINISHED_OK
|
1
|
answer OK on finished server
|
PQ_STOPREASON_CODE_USER_BREAK
|
2
|
signalling an user break from client's site
|
PQ_STOPREASON_CODE_ERROR
|
−1
|
signalling an error situation on client's site
|
|
|
|
|
|
Error Codes as sent by server
|
E_ERROR_CODES (int16)
|
|
|
Symbol |
Code |
Meaning |
PQ_ERRCODE_NO_ERROR
|
0
|
no error detected
|
PQ_ERRCODE_MEASUREMENT_READY
|
1
|
server finished measurement without error
|
PQ_ERRCODE_USER_BREAK
|
2
|
signalling an user break from server's site
|
PQ_ERRCODE_MESSAGE_CORRUPTED
|
−1
|
signalling reception of a corrupted message
|
PQ_ERRCODE_SERVER_BUSY
|
−2
|
signalling server busy
|
PQ_ERRCODE_MESSAGE_TIMEOUT
|
−3
|
client didn't answer within timeout interval
|
PQ_ERRCODE_INVALID_REC_VERSION
|
−10
|
received message with invalid record version
|
PQ_ERRCODE_MEASUREMENT_TIMEOUT
|
−100
|
measurement timed out
|
PQ_ERRCODE_FIFO_OVERRUN
|
−101
|
FIFO overrun
|
PQ_ERRCODE_DMA_ERROR
|
−102
|
DMA error
|
PQ_ERRCODE_OSCILLOSCOPE_RUNNING
|
−103
|
oscilloscope still running
|
PQ_ERRCODE_HARDWARE_INIT
|
−104
|
couldn't initialise hardware
|
PQ_ERRCODE_TTTR_INIT
|
−105
|
couldn't initialise TTTR measurement
|
PQ_ERRCODE_TTTR_RUNNING
|
−106
|
TTTR measurement still running
|
PQ_ERRCODE_NO_WORKSPACE
|
−107
|
no workspace was opened
|
PQ_ERRCODE_FILE_EXISTS
|
−108
|
couldn't save measurement; file already exists
|
PQ_ERRCODE_FILE_CREATE
|
−109
|
error on creating measurement file
|
PQ_ERRCODE_GROUPNAME_TOO_LONG
|
−110
|
couldn't create new group: groupname too long
|
PQ_ERRCODE_FILENAME_TOO_LONG
|
−111
|
couldn't create new file: filename too long
|
PQ_ERRCODE_TIMESTAMP_ARRAY_TOO_LONG
|
−112
|
couldn't activate time correction: array too long
|
PQ_ERRCODE_INVALID_LICENSE
|
−999
|
request rejected: invalid license
|
PQ_ERRCODE_UNKNOWN_ERROR
|
−9999
|
unspecified error situation
|
|
|
|
|
|
[Support]