Lua Stimulator

Summary

Doc_BoxAlgorithm_LuaStimulator.png
  • Plugin name : Lua Stimulator
  • Version : 1.1
  • Author : Yann Renard
  • Company : INRIA
  • Short description : Generates some stimulations according to an Lua script
  • Documentation template generation date : Apr 30 2021

Description

This box gives a fast control over stimulation streams thanks to Lua scripts.

Scripts are very simple programming languages. They are usually easy to understand, fast to write and reasonably fast to execute. They are used for high level operations and do not need compilation. There are a number of scripting languages around. Lua is one of those scripting languages. It is know for its execution speed and it's ease of use. It can be used on a large number of platforms. For all those reasons, Lua is widely used in the video game industry. If you want more information about Lua, feel free to visit their website at http://www.lua.org and on their documentation website http://www.lua.org/manual/5.1

This box has a variable number of inputs and outputs. The author is able to add as many of them as necessary. The box automatically decodes the incoming streams and automatically encodes the outgoing streams, leaving the interesting part to the script : doing something with input stimulations and produce output stimulations.

The script should be divided in three functions :

The whole script behavior should be executed in a single execution of the process function. Thanks to this, the script code is made a lot more easy to understand than the usual C++ boxes. Of course, in case it is necessary, the script can yield, letting the kernel perform a new step of execution.

A simple API is proposed allowing the script to :

During the process function, you can also :

  • LuaScriptAPI_get_current_time
  • LuaScriptAPI_get_stimulation_count
  • LuaScriptAPI_get_stimulation
  • LuaScriptAPI_remove_stimulation
  • LuaScriptAPI_send_stimulation
  • LuaScriptAPI_sleep

NOTE: people using the deprecated unstable API would be interested in the LuaScriptAPI_upgrading_from_unstable section.

initialize(box)

This function is called by the box at IBox::initialize phase. It is up to the script developer to implement this function. In case you don't want to do anything at initialization phase, just ignore this function.

  • the box parameter enables the script developer to access the API described hereafter.

uninitialize(box)

This function is called by the box at IBox::uninitialize phase. It is up to the script developer to implement this function. In case you don't want to do anything at uninitialization phase, just ignore this function.

  • the box parameter enables the script developer to access the API described hereafter.

process(box)

This function is called by the box at the first IBox::process phase. It is up to the script developer to implement this function and this function is mandatory. It is executed only once, meaning that if that code must be run on a long duration, it must release some CPU cycles using the box:sleep() function.

  • the box parameter enables the script developer to access the API described hereafter. Among others, it will let the script get some usefull information about the box topology (number of inputs, number of outputs, number of settings etc...)
  • the box parameter also enables the script developer to access all the runtime functions such as receiving stimulations, sending stimulations etc...

box:get_input_count()

This function returns the number of inputs the box has.

box:get_output_count()

This function returns the number of outputs the box has.

box:get_setting_count()

This function returns the number of settings the box has, including the script filename itself.

box:get_setting(setting_index)

This function returns a string containing the value of a given setting in the box. This setting value may be expanded using the configuration manager thanks to a box:get_config(token) ; This function uses the configuration manager to expand a configuration token. The configuration token ; are listed in the openvibe.conf file and can contain valuable information about the OpenViBE ; environment. ; - token can be any string containing configuration variables (e.g. ${Path_Data}/scenarios/signals/my-experiment). ; ; call.

  • setting_index can range from 1 to n if the box has n settings.

box:log(log_level, line_of_text)

This function sends a string to the log manager. This message may be printed in the console for the user or may be popped up to him if this is important enough. In any case, it will appear in the log file.

  • log_level the log level which you want to use to print this line of text. This is represented in string and can take the following values : Debug, Trace, Info, Warning, ImportantWarning, Error and Fatal. If you use an invalid value, then Debug is used.
  • line_of_text can be any line of text you want to print

box:set_filter_mode(active)

By default the Lua scripting box works in a clock-driven mode: it runs with a certain frequency, and each time the process code is run, it outputs a stimulus chunk. When the filter mode is active (=1), the input stimulation stream drives the output chunk generation instead. In filter mode, you can copy input stimulations to the output while keeping their exact timestamps.

Explanation: Lua box generates a stimulation chunk stream [t1,t2[, [t2,t3[, [t3,t4[, ... , with a high frequency (small chunks). The t are the start and end times of each chunk. ; However, the input stream may have chunks with a bigger granularity such as [t1,t3[, [t3,t5[, ..., and so on. ; Now if the box receives stimulation tagged at time t1 from such a bigger granularity input stream, it will have already sent out the chunk [t1,t2] as the current time by then is at least t3 as chunk [t1,t3[ was received. ; Hence the stimulation at t1 must be dropped as OpenViBE stimulation stream guarantees that if a stimuli tagged at time t has not been received by the time a chunk with its beginning timestamp greater than t is received, there will never be a stimuli at t. ; ; Note that for the filter mode operation it is necessary that the upstream generates a meaningful stimulation stream. If not, the box will not output stimulations when the filter mode is active. ; ;

box:get_config(token) ; This function uses the configuration manager to expand a configuration token. The configuration token ; are listed in the \c openvibe.conf file and can contain valuable information about the OpenViBE ; environment. ; - \c token can be any string containing configuration variables (e.g. <em>${Path_Data}/scenarios/signals/my-experiment</em>). ; ; \subsection LuaScriptAPI_get_current_time box:get_current_time() ; This function returns the elapsed time in seconds since the scenario started. The returned value is a float. ; - \b WARNING: this function should only be called while in the \ref LuaScriptAPI_process callback. ; ; \subsection LuaScriptAPI_get_stimulation_count box:get_stimulation_count(input_index) ; This function returns the number of pending stimulation on a specific input given with \c input_index. ; - \c input_index can range from 1 to \e n if the box has \e n inputs. ; - \b NOTE: if you call this function on an unexisting input, it returns 0. ; - \b WARNING: this function should only be called while in the \ref LuaScriptAPI_process callback. ; ; \subsection LuaScriptAPI_get_stimulation box:get_stimulation(input_index, stimulation_index) ; This function returns the details of a specific pending stimulation for a specific input given with \c input_index. ; - \c input_index can range from 1 to \e n if the box has \e n inputs. ; - \c stimulation_index can range from 1 to \e m if the valid input \c input_index has \e m inputs. ; ; The result is in the form of a 3-tuple containing : ; - the stimulation code as an integer ; - the stimulation date as a float ; - the stimulation duration as a float ; ; If you call this function with an \c stimulation_index bigger than what \c get_stimulation_count would have returned for ; the \c input_index input, then the Lua script sleeps until enough stimulation arrived and this function can return. ; ; - \b WARNING: if you call this function on an unexisting input, the behavior is undefined ; - \b WARNING: this function should only be called while in the \ref LuaScriptAPI_process callback. ; ; \subsection LuaScriptAPI_remove_stimulation box:remove_stimulation(input_index, stimulation_index) ; Removes a pending stimulation on a specific input given with \c input_index. ; - \c input_index can range from 1 to \e n if the box has \e n inputs. ; - \c stimulation_index can range from 1 to \e m if the valid input \c input_index has \e m inputs. ; ; If you call this function with an \c stimulation_index bigger than what \c get_stimulation_count would have returned for ; the \c input_index input, then the Lua script sleeps until enough stimulation arrived and this function can return. ; ; After this call, the pending stimulations order is changed, stimulations \c stimulation_index+1, \c stimulation_index+2, ... ; being moved to \c stimulation_index, \c stimulation_index+1, ... respectively. ; ; - \b WARNING: this function should only be called while in the \ref LuaScriptAPI_process callback. ; ; \subsection LuaScriptAPI_send_stimulation box:send_stimulation(output_index, stimulation_identifier, stimulation_date, opt:stimulation_duration=0) ; Sends a stimulation with code \c stimulation_identifier, date \c stimulation_date and duration \c stimulation_duration on output ; - \c output_index. ; - \c output_index can range from 1 to \e n if the box has \e n outputs. ; - \c stimulation_identifier is an integer with the identifier of the stimulation to send. See \ref Doc_Stimulations for stimulation codes. ; - \c stimulation_date is a float (in seconds) with the date of the stimulation. The box will take care of buffering the stimulation if needed before ; actually sending it. However, you can't send a stimulation in "the past". ; - \c stimulation_duration is a float (in seconds) with the duration of the stimulation. It is usually unused so if you don't know what to ; put here, just ignore this parameter, or let it be 0. ; - \b WARNING: this function should only be called while in the \ref LuaScriptAPI_process callback. ; ; \subsection LuaScriptAPI_sleep box:sleep() ; ; Pauses the script execution. The box then continues its execution, so the kernel can perform an additional step. Next time the box ; is executed, it will restore the script execution so you can eventually continue or sleep again. ; ; - \b NOTE: The \e current \e time is affected by this call ! ; - \b WARNING: this function should only be called while in the \ref LuaScriptAPI_process callback. ; ; If you want to wait until a fixed date, just use this simple Lua function : ; \code ; function wait_until(box, time) ; while box:get_current_time() < time do ; box:sleep() ; end ; end ; \endcode ; ; If you want to wait for a fixed duration, just use this simple Lua function : ; \code ; function wait_for(box, duration) ; wait_until(box, box:get_current_time() + duration) ; end ; \endcode ; ; *

Outputs

1. Stimulations

  • Type identifier : Stimulations (0x6f752dd0, 0x082a321e)

Settings

1. Lua Script

  • Type identifier : Script (0xb0d0db45, 0x49cbc34a)
  • Default value : [ ]

Examples

Miscellaneous