Data Streams

A DataStream definition contains three major parts:

1. The source specifies where and how the bytes, sent by the remote system, are read from.

2. The PacketDefinition describes how to group these bytes into packets for parsing.

3. The configuration on how to transform bits and bytes from input packets into scaled samplesd for processing in OXYGEN can be found in the Channels element.

DataStream name

element string

Parent: Receiver Optional identifier of the data stream. No two streams in a single file may use the same name.

Sources

One of the source elements defined below has to be used to receive data in a stream.

UDP

UDPSource opens the specified UDP port and processes the payload of all incoming packets. Since UDP is packet oriented already, it may be used without an additional PacketDefinition. All incoming packets are unconditionally parsed in this case.

UDPSource	Element	Parent: DataStream
ip_mode	´auto´, ´v4´, ´v6´	Selects the IP protocol version to use. In mode ‘auto’ the format of the first IP address found determines the version (defaulting to v4 if no IP is specified)
address	IP address	Selects the network adapter to receive data from. Use ´0.0.0.0´, ´::´ or omit the attribute to bind to all installed adapters.
Port	unit16	Specifies on which port to listen for incoming packets
multicast_group	IP address	Optional address of the multicast group to join. If omitted or empty, only unicast UDP packets are received. Port must match the sender configuration, and the specified network adapter has to properly support multicast.

AcceptFrom is an optional element that can limit which packets are accepted and added to the stream. Can be used multiple times in the same source to accept data from different hosts.

AcceptFrom	Element	Parent: UDPSource
host	IP address	IP source address of the packet.

Packet Description

PacketDefinition defines how a single stream of bytes in segmented into packets for further processing. Additionally, it is possible to perform some basic validity checks in order to filter out packets that should not be parsed.

The following algorithm is used to extract packets:

• Fixed length and nothing else: split stream into fixed size segments

• Fixed bytes: search for byte sequence; if found subtract offset to find start of packet (all elements must match!)

Once the packet start is known, its lenght in bytes is determined by one of the following:

• Length for fixed length

• The result of evaluating the VariableLength element and its embedded NumericValue.

PacketDefinition	element	Parent: DtaStream
lenght	uint32	If set, packets are defined to have a fixed lenght in bytes. Incoming bytes are always grouped into packets of this size.
maxlength	uint32	If set, any discovered packets are truncated to this size.

All FixedPacketBytes must match in order to successfully detect a valid packet. This element can be used to filter based on a protocol header or a specific packet type field.

FixedPacketByte	element	Parent: DataDefinition
offset	uint32	Offset of the byte within the packet (0 is the first byte)
value	uint8	Expected value of the byte (use prefix 0x for hex values)

Using the VariableLenght element it is possible to correctly detect packets that contain an embedded lenght identifier. This element contains a NumericValue element (optionally followed by scaling) as a child which is used to calculate that value.

Synchronization Description

In case of Synchronization a DataStream needs to contain a single Synchronization element, which contains the definition and decoding information for the timestamp information. Timestamping information needs to be a sample within the stream packets, defined within a child element described below. Additionally, such a sample might be also decoded as a distinct Channel, as shown in the examples. If Synchronization is used, the received timestamping information determines the position of the samples on the OXYGEN acquisition timeline.

Note, that a given timestamp is only accepted as valid if within a range of 10 seconds around OXYGEN’s current acquisition time and if it is advanced to any timestamp processed prior.

Keep in mind: The OXYGEN acquisition time is not necessarily in sync with the operating system time. Therefore, synchronization of operating system times does not imply that sample data is synchronized over multiple OXYGEN systems. Especially in longer running measurements, the OXYGEN acquisition time of multiple systems will drift apart if there is no OXYGEN synchronization (e.g. TRION sync, IRIG, …) established.

RelativeTimestampChannel

A RELATIVETIMESTAMPCHANNEL holds the sample information for a timestamping method which is based relatively to a fixed time of day. It is needed to contain a sub-item defining a Sample which holds the actual decoding information.

RelativeTimestampChannel	element	Parent: Synchronization
base	string	Definition of the time of day where the channel is based relatively. This item is required and has to be equal to one of the following pre-defined values: midnight
unit	string	Defines the time unit of the timestamp information. This item is required and has to be equal to one of the following pre-defined values: ms
offset	int32	It has to be noted that OXYGEN timestamp is based on absolute UTC timestamps. Therefore, a correction value might be applied here to fix clock deviations like time-zone issues or fixed delays and offsets.

Channel Description

A DataStream contains a single Channels element which contains decoding information for extracting its channels from a data packet. In addition, it is possible to define SelectorValues that may be used for conditional decoding of channel, for example depending on a packet type identifier.

Channels

Channel	element	Parent: Channels
name	string	Name that is used to identify the channel. It has to be unique within a single configuration file.
unit	string	The unit of the physical value that is measured by the channel. SI units and prefixes should be used if possible.
description	String	An optional textual description of the channel and/or the interpretation of its values.
type	´double´, ´utf8´	Describes the format of the channel that will be generated in OXYGEN. Double: Creates a scalar channel that contains numeric samples. These values are parsed and scale according to the rules specified in the NumericValue element before being written to the channel. UTF-8 identifies a channel where each sample is a Unicode string of arbitrary length. A ByteBlockValue specifies the relevant byte range which is then interpreted as a string.

Sample specifies the processing steps that generate the final channel value.

Sample		Parent: Channel, RelativeTimestampChannel
valid_if	string (expression)	Can contain a logical expression which is evaluated to determine if the sample be read for a specific packet. If omitted or left empty it is always considered true. Each condition has the following format: <SelectorName>=<Value> e.g´type=4´ Multiple conditions can be combined using the && (logical AND) and || (logical OR) operators like this: ´type=4 || type=5´

Numeric value describes how to derive a floating-point channel sample from a number of input bits in the packet. The offsets and length attributes select the range of bits that are to be processed. These bits are then interpreted depending on the selected type and the ordering attributes to get the unscaled raw number. This number is then scaled to the final value based on the scaling parameters provided as children.

NumericValue		Parent: Sample, SelectorValue, VariableLength
byte_offset	uint32	Offset of the first interesting byte in the packet.
bit_offset	uint8	Offset, relative to byte_offset, of the first interesting bit.
bit_length	uint8	Number of interesting bits.
type	´unsigned´, ´signed´, ´float´	Specifies how the input bits are interpreted as a numeric value: Unsigned: bits are in a sequence of arbitrary length and interpreted positionally depending on the order attributes. Signed: an unsigned value is parsed and interpreted as a two complement signed value. Float: interpreted as an IEEE floating point value. This type only supports values of 32 and 64 bits length.
byte_order	‘msb_first’, ‘msb_last’	Selects the interpretation of bytes if bit_length > 8.
bit_order	‘msb_0’, ‘lsb_0’	Selects the interpretation of bit offsets and bit values.

NumericValue can be followed by a LinearScaling element that converts the parsed raw numeric value to the final value that is handed over to OXYGEN. It uses the formula final_value = raw_value * scale + offset.

LinearScaling	element	Parent: Sample
scale	double	Default value is 1.
offset	double	Default value is 0.

Using the ByteBlockValue element it is possible to extract a byte sequence of fixed length from the input packet. This sequence can be interpreted as string or an NMEA sentence (see Channel.type) and stored in a matching channel.

ByteBlockValue	element	Parent: Sample
byte_offset	uint32	Offset of the first byte within the packet
byte_length	uint32	Number of bytes to use, starting from the first byte

Setting a display range for a numeric channel helps when using it in OXYGEN. The default range of certain instruments is influenced by these settings for example.

DisplayRange	element	Parent: Channel
min	double	Lower bound of the expected output range of the channel.
max	double	Upper bound of the expected output range of the channel.
resolution	uint8	Indicates the number of significant digits (of the scaled value) after the decimal point. This value is currently not used in OXYGEN.

Selectors

SelectorValues can be defined in the Channels element and referenced in Channel/Sample.valid_if if conditional decoding is required. It contains a NumericValue element which describes how the selectors actual value is extracted from the packet. valid_if conditions are true if the the compared values are equal.

SelectorValue	element	Parent: Channels
name	string	Name of the selector value.