TCP Writer

Summary

Doc_BoxAlgorithm_TCPWriter.png
  • Plugin name : TCP Writer
  • Version : 0.1
  • Author : Jussi T. Lindgren
  • Company : Inria
  • Short description : Send input stream out via a TCP socket
  • Documentation template generation date : Mar 20 2015
  • WARNING : this box has been marked as UNSTABLE by the developer. It means that its implementation may be incomplete or that the box can only work under well known conditions. It may possibly crash or cause data loss. Use this box at your own risk, you've been warned.

Description

This box works as a TCP server that writes its input stream out to a TCP socket with minimal header information and encoding.

The main motivation for this box is to allow external applications to receive information in a simple manner from OpenViBE without requiring unusual dependencies such as VRPN.

Output:

1) If the outputs of the box are raw numeric values, the box first sends every connecting client eight variables of uint32: version number (in network byte order), endianness of the stream (in network byte order, 0==unknown, 1==little, 2==big, 3==pdp), sampling frequency of the signal, the number of channels, the number of samples per chunk and three variables of padding, 8*4=32 bytes in total. The last 6 variables are in the byte order of the stream. Note that only those variables will be non-zero that are meaningful for the input in question.

1b) If the output is chosen as hex string or descriptive string (these are valid for Stimulation input only), no header is sent.

2) After the possible global header, the data itself is sent. The data is a stream of float64 for Signal and StreamedMatrix. The data orientation is [nSamples x nChannels], i.e. all channels for one sample are sent in a sequence, then all channels of the next sample, and so on (the matrix is a transpose of the usual OpenViBE signal orientation). For Stimulations, the data is uint64 if user chooses raw, or char strings otherwise.

Multiple clients can connect to the socket of the box. The box keeps sending data to each client until either the scenario is stopped or the client disconnects. The box does not guarantee that the client starts to receive the input stream from any particular location. When kernel calls box::process() at time t, all clients connected at time t get forwarded the chunks given to box::process() at t. However, if a client establish a connection during box::process(), it may get a partial chunk of t and the whole chunk of t+1 and so on.

Inputs

1. Input 1

The supported input stream types are StreamedMatrix, Signal and Stimulations. The stream type of the input can be changed by the user.

  • Type identifier : Streamed matrix (0x544a003e, 0x6dcba5f6)

Settings

1. Port

Port denotes the TCP port that will accept the client connections. Default is 5678.

  • Type identifier : Integer (0x007deef9, 0x2f3e95c6)
  • Default value : [ 5678 ]

2. Stimulus output

If the input is Stimulations, this setting can change the format the stimulations are sent in to the TCP socket. The choices are raw uint64, hex string, or a descriptive string. For other inputs, this setting is ignored.

  • Type identifier : Stimulus output (0x6d7e53dd, 0x6a0a4753)
  • Default value : [ Raw ]

Examples

There is an example application 'openvibe-examples-openvibe-to-tcpip' that can be used to receive data from this box. The application is intended to be used together with the 'tcp-writer.xml' box tutorial.

Another way to test the box is to connect to the socket of the box with a 'telnet' application and redirect the telnet output to a file.

It is also possible to use Acquisition Server's Generic Raw Telnet Reader to read data from the box. In that case, set Start Skip to 32 and header and footer skips to 0, and data format to float64. Remember to also set the number of channels and the sampling frequency correctly. This information is not read from the stream by the Generic Raw Telnet Reader.

Miscellaneous

The box performs no little-endian/big-endian conversions. The data is sent raw in the native format of the host system. The host endianness is encoded into the sent header.

The box sends signal data as chunks with the same chunk size as the stream has.

The box writes to all the sockets synchronously in the process() call and drops no data. If the connection is too slow to accommodate the data flow, the box will lag.

Detected transmission errors will cause a disconnection of the client.

Streamed Matrix can be recognized from the TCPWriter header by the sampling rate 0. If the stream is a signal, the sampling rate is a positive number.

Known issues: Note that it can be difficult to time-synchronize signals and stimulations exactly on the client side when the client receives data from two TCP Writer boxes. Maintaining such synchronization was not a design goal of this box. If you need synchronized streams, it is advised to build the connection with LabStreamingLayer: Use LSL Export box and include LSL support in the client.