External Processing

Summary

Doc_BoxAlgorithm_ExternalProcessing.png
  • Plugin name : External Processing
  • Version : 1.0
  • Author : Alexis Placet
  • Company : Mensia Technologies SA
  • Short description : This box can communicate via TCP with an other program.
  • Documentation template generation date : Apr 11 2018

Description

Launches an external program which can then processes data. This box and the program communicate using TCP connection and a defined protocol.

This box allows to externalize data processing into an external program. It sends EBML data in chunks according to a specified protocol, the external application must respond with an EBML response following this same protocol.

A SDK for C++ and Python (Python NeuroRT Box) are provided in order to simplify the development of external boxes.

Settings

The External Processing box has several own settings. The first seven parameters are reserved for the box functionality and additional parameters will be passed to the external program.

1. Launch third party program

The first setting is the boolean check box that allows the author to launch, or not, a program when the pipeline starts. By default, it is activated. But it can be deactivated to launch the client program manually for debug purposes. In this case, you have some seconds to launch manually the client program before the timeout, according to the setting n°7.

  • Type identifier : Boolean (0x2cdb2f0b, 0x12f231ea)
  • Default value : [ true ]

2. Executable path

The second parameter is the path to the third party program to run. This parameter is only used if the first parameter is activated. This parameter must be an executable.

Example: In the case you want to run a Python script on Windows, the parameter must be the python.exe file's path: C:/Python/python.exe

  • Type identifier : Filename (0x330306dd, 0x74a95f98)
  • Default value : [ ]

3. Arguments

The third parameter is the arguments passed to the third party program. This parameter is only used if the first parameter is activated. This parameter will be given to the third party program as a list of arguments. These arguments are the first given to the third party program.

Example: In the case you want to run a Python script on Windows, the parameter must be the python script's path that you want to run: C:/MyProject/myprogram.py If you want to use a Python module or module you should type: -m mylibrary.mymodule.mybox

  • Type identifier : String (0x79a9edeb, 0x245d83fc)
  • Default value : [ ]

4. Port

The TCP port that the box is listening. It must be in the range 49152-65535. This plugin works on a TCP-IP stack, so, different boxes must work on different ports if they are running at the same time. The client must connect to this port. An argument, with the value of the port, will be given to the third party program (after the Arguments parameter ) as: –port PORT

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

5. Automatic connection identifier

Activate or not the generation of a connection identifier that the client must communicate to the box. When checked a connection identifier will automatically generated, otherwise the connection identifier will be the one set in the custom connection identifier setting. We advise you to always uncheck in runtime mode, and choose your custom connection identifier while testing your script. An argument, with the value of the connection id (custom or not), will be given to the third party program (at the end of the argument list) as: –connection-id CONNECTIONID

  • Type identifier : Boolean (0x2cdb2f0b, 0x12f231ea)
  • Default value : [ true ]

6. Custom connection identifier

Define a custom connection identifier. Only used in the connection identifier generation is deactivated.

  • Type identifier : String (0x79a9edeb, 0x245d83fc)
  • Default value : [ ]

7. Incoming connection timeout

Define a timeout, in seconds, for the incoming connection acceptance.

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

8. Generator

This setting should be set to true if the external box generates data without the need to receive some. By default, this setting is false and the box works as a filter. That is, each time it sends data, it will wait for a response, otherwise it will proceed and let the scenario advance.

If the box is a generator, then it will wait for the external program on each step. If the scenario is played in real-time, then the box will poll the external program at 16Hz. If the scenario is in fast-forward the refresh frequency of this box is 1Hz.

  • Type identifier : Boolean (0x2cdb2f0b, 0x12f231ea)
  • Default value : [ false ]

Examples

Miscellaneous

This box requires synchronization with the external program in order to process data correctly and in order. As the synchronization is a relatively slow process with regards to the duration of one update cycle (62ms) it is better to try to limit the number of chunks that are send between the box and the client application.

If you find that your scenario is too slow, try using time based epoching in front of it to make chunks of data larger.