Remote Control  

Message Types

  [Related Topics]   

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) 

 
 
Name Type Containing
hdr   T_MESSAGEHDR obligatory message header identifying this message type  
ecStatus   E_ERROR_CODES      status code sent by server
 
     


 
 T_ENCODED_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
 
     


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  
 
     




Related Topics:   
   [Support]