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 : Jul 24 2014
  • 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 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 (matrix rows) and the number of samples per chunk (matrix columns) 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. 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

Easiest way to test the box is to connect to the socket of the box with 'telnet' 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.

Miscellaneous

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

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.