 |
pdserv
3.4
Process data server
|
Loading...
Searching...
No Matches
|
pdserv
3.4
Process data server
|
The MSR data server is one means for a client to interact and communicate with a process encapsulated by the pdserv library, possibly running in real time.
The client attaches to the pdserv server via a TCP network socket, by default on port 2345. Communication is bi-directional.
The communication syntax between client and server follows an XML-like format.
Upon connection, the server sends an initial greeting and waits for commands from the client.
Commands are sent by the client to the server in a single XML element. The XML-like command format in BNF is:
command := '<' tag attribute* '/>' tag := name attribute := ' ' name '="' value '"' name := any character except the obvious (space, angled brackets, qoutes)
Example of setting a parameter value:
<write_parameter index="55" value="123457"/>
Unrecognized commands return a warning:
<silly/> <warn num="1000" text="unknown command" command="silly"/>
Unrecognized attributes are silently ignored.
There are state changing and query commands, and they may or may not generate a reply. Commands are processed in order of reception. It is not required to synchronize commands to replies, although the client will do that for its own purpose.
To determine whether a command was processed by the server, the id attribute is used within the command element. The reply (if one is generated) will have an id attribute with the same value. Additionally an <ack> element with the same id attribute value is sent immediately after command is processed.
For example, here are two commands sent in one line:
The first line contains two <rk> (query a signal) commands with an id attribute. The first is unsuccessful and produces no reply, however the <ack id="rk99"/> is replied before successfully processing the second query. Note the id attribute in <channel>.
This mechanism can be used to synchronize communication between client and server, especially when the commands do not produce a reply.
The reply stream is well formed XML that can be processed with a streaming XML parser like SAX or expat. A message is a single XML element that may contain child elements.
The communication from server to client is interleaved with solicited and unsolicited messages:
The client must carefully separate the return stream to distinguish between these message types.
The problem with unsolicited messages is that they occur at any point in time without any cause from the client. Thus the client has to monitor this stream continuously or run the risk of its input stream overflowing and thus being cut off by the server. For most clients (GUI's, etc) this is no problem, but for clients that want to excercise synchronous single threaded communication could choke. To alleviate this problem, unsolicited messages can be disabled using the <remote_host/> command.
When querying the server for its variables (signals or parameters), its data type and binary size (sizeof operator) is returned in the typ and datasize attributes respectively.
An example of quering a parameter:
The following table maps these types to the corresponding C data type.
| typ | datasize | c-type |
|---|---|---|
| TUCHAR | 1 | uint8_t |
| TCHAR | 1 | int8_t |
| TUSHORT | 2 | uint16_t |
| TSHORT | 2 | int16_t |
| TUINT | 4 | uint32_t |
| TINT | 4 | int32_t |
| TULINT | 8 | uint64_t |
| TLINT | 8 | int64_t |
| TFLT | 4 | float |
| TDBL | 8 | double |
| COMPOUND | n | struct {} |
The dimensionality of a variable is reflected in attributes when querying the variables.
Generally a variable can be scalar or non-scalar. Scalar variables contain only one of the data types as shown above (a compound can also be a scalar). If a variable contains more than one element, it is said to be non-scalar.
For non-scalar variables, the reply has the following additional attributes:
The data values are ordered in a C-like fasion. Adjacent values are the last dimension of a multi-dimensional array: for the
double array[4][5];
with 4 rows and 5 columns, the 5's will be adjacent (row major).
An example of a scalar:
An example of a vector:
An example of a matrix:
Incedentally, the dir flag in the last two examples show that there are more variables listed under its name (see the list command).
Binary values are transmitted in native machine format. Check the endian flag in the greeting.
MSR uses two methods of binary encoding:
This format simply walks though the value's entire memory space byte by byte and prints it as a 2-digit hex value.
Example: pi = 182D4454FB210940 on a little endian platform.
This representation is used between client and server interaction.
To query the value of a variable, set the hex boolean attribute in the command and the value is returned in the hexvalue reply attribute.
To set the value of a parameter, use the hexvalue instead of the value** attribute in the command.
The value is encoded as base64 string which is more efficient than hexdec (four base64 vs six hexdec characters per three bytes binary data).
Example: pi = GC1EVPshCUA= on a little endian platform.
This representation is used for streaming subscribed signals when the coding attribute is set to Base64
To support old clients that can only handle scalar variables, the server can atomize non-scalar variables in a path beneath it. This behaviour is set in the configuration file.
Atomized variables can cause an exponential explosion (think of a 10x10 matrix yielding 100 separate variables)
When requesting a directory list, use the attribute noderived to suppress listing of directories containing atomized variables only.
Ping the server. The server will reply with its current time. This function is used to detect network presence of the server.
Command attributes: none
Reply: <ping/> with attributes:
Example:
Alias: wp
Set the value of a parameter. The connection must be authorized, see access in remote_host
Command attributes:
*) One of index (dominant) or name is mandatory, otherwise nothing happens.
**) One of hexvalue (dominant) or value is mandatory, otherwise nothing happens.
Values are written until either the parameter's end is reached or input value is exhaused.
Reply: none (possibly a parameter update notification follows)
Example:
<wp index="6" hexvalue="DEADBEEF"/>
Alias: rp
Read a parameter's value value and attributes.
Command attributes:
*) If neither name (dominant) or index is specified, a complete parameter listing of all parameters is performed. The listing is enclosed in a <parameters></parameters> element with individual child <parameter/> elements.
Reply: <parameter/> with attributes:
*) These attributes are not transmitted when short attribute is set.
**) hexvalue is returned when hex attribute is set.
Example:
Subscribe a signals to the data stream sent by the server.
Command attributes:
Reply: none (but see the unsolicited `<data>` message)
Example:
<xsad channels="2,4" group="3" reduction="5" blocksize="10"/>
Removes signal subscription from a data transmission group.
Command attributes:
Reply: none
Example:
<xsod channels="4" group="3"/>
Version: after v3.0
Monitor parameters, transmitting the value on change.
Command attributes:
Reply: none (but see the unsolicited `<data>` message)
Example:
<xsap parameters="5,6"/>
Version: after v3.0
Cancel monitoring of parameter changes.
Command attributes:
Example:
<xsop parameters="6"/>
Unused
Alias: rk rc
Read the value and all attributes of a signal.
Command attributes:
*) If neither name (dominant) or index is specified, a complete signal listing of all signals is performed. The listing is enclosed in a <channels></channels> element with individual child <channel/> elements. Polling signal values is expensive, thus the value is not transmitted when a complete listing is performed,
Reply: <channel/> with attributes:
*) These attributes are not transmitted when short attribute is set.
**) hexvalue is returned when hex attribute is set. Supported since v3.
Example:
Alias: rpv
Return a list of all parameter values, sequencially sorted by index.
Reply: <param_values/> with attributes:
Example:
<read_param_values/> <param_values value="1.2;10;1;0;20;56746,1,0,0,0"/>
Version: since v3.0
Feature test: login
Perform SASL authentication dialog.
Command attributes:
Reply: <saslauth/> with attributes:
1) The first step is to obtain a list of supported mechanisms.
<auth/> <saslauth mechlist="DIGEST-MD5 CRAM-MD5 NTLM PLAIN LOGIN ANONYMOUS"/>
The list of mechanisms does not change. This first step is required only once upon initial connection by the client.
This step is not required if the mechanism is known apriori.
2) The client chooses a mechanism. Depending on the mechanism, the client library will start the conversation with some data or not. Supplying a mech** attribute initiates the server side of the conversation (client-send-first). Depending on the mechanism, the server may require more data or even signal success or failure.
<auth mech="PLAIN" clientdata="lkjsdlfjkl"/> <saslauth serverdata="lkjasdflkj" success="1"/>
The mech attribute may only be sent on initiation. Certain mechanisms may require more than one interaction. Subsequent commands will only have clientdata, until the server replies with a success attribute.
Version: since v2.0
Feature test: list
Return a list of parameters, signals and directories.
Command attributes:
Reply: <listing></listing> element with children:
Example:
Version: since v2.0
Feature test: polite
Command to set miscellaneous states.
Command attributes:
Example:
<remote_host name="myhostname" applicationname="GUI" access="1"/>
Alias: read_statics (no, this is not a spelling mistake) rs
Get information about other MSR clients connected to the server.
Reply: <clients></clients> element with <client/> child elements with attributes:
Example:
Feature test: history
Arguments:
Request the server to send past messages. Without attributes, the latest message including all active messages are sent enclosed in a <message_history></message_history> element in increasing order of sequence numbers.
With seq argument, the specific message with that sequence number is returned if it exists.
Reply:
Notes:
Typically this command is used to discover all past messages. To achieve this, first send
<message_history/>
and process all messages returned, taking note of the sequence numbers in the replies.
Then use
<message_history seq="XX" id="nn"/>
to retrieve individual messages, counting down from the highest sequence number. If a message does not exist, nothing is returned. Therefor the id tag should be used in this context to detect an empty reply.
Example of retrieving active messages:
The last message has sequence number 4220 (/Limit[0]) but it is inactive. Messages /Limit[1] and /Limit[3] still persist.
To regenerate the list, retrieve messages with sequence numbers counting down from the highest sequence number (4220): 4219, 4218... (possibly, but not necessarily skipping 4196):
Example of retrieving a specific message with sequence number 3220:
Message 3220 does not exist any more becuase it was purged by the server (in this example it keeps 1000 messages - see configuration file). The list is now complete as far as possible.
However, even though the history has been exhausted, message /Limit[3] with sequence number 150 is still known to be active.
This element is sent just after the reply to any command with an id attribute is processed. This feature can be used to synchronize communication with the server.
Element attributes:
Example:
This element is sent as a greeting upon connection to the server. It is used to greet the client with a information about the server, running process and a list of capabilities.
Element attributes:
Example:
A <data></data> element is a container enclosing child elements of values for signals that were subscribed using xsad.
Element attributes:
Child elements:
<F/> signal data of fixed decimation rate subscription as specified in xsad:reduction.
Attributes:
<time/>
Attributes:
d [uint64 array]: uint64_t array of size xasd:blocksize of time values when the sample was taken. Time is in nano-seconds since epoch. Coding is base64
This time is more accurate than data:time, since it contains the actual timestamp when a sample was taken and not one calculated backwards from data:time.
Example of event-based subscription (with group supported):
Notification to all clients of a parameter change. Clients interested in its value must then request it.
See also: xsap
Element attributes:
Example:
A client can subscribe to monitor parameter value changes using xsap. Upon change, the value is sent automatically by the server using a <parameter/> element upon value change.
Example:
A message is generated by the process when some event occurs. They have the following categories as tag name:
<reset/> is a special event element signalling that the event has been cancelled.
Attributes are:
| prio | Priority | Tag name |
|---|---|---|
| 0 | Emergency | crit_error |
| 1 | Alert | crit_error |
| 2 | Critical | crit_error |
| 3 | Error | error |
| 4 | Warning | warn |
| 5 | Notice | info |
| 6 | Info | info |
| 7 | Debug | info |
Example (since v3):
Example (until v3):
. -
pdserv developed by
Ingenieurgemeinschaft IgH GmbH
.
All rights reserved.