Hook-types

Sometimes forwarded sample data shall be modified or filtered. VILLASnode supports hooks for this purpose. Hooks are simple callback functions which are called whenever a message is processed by a path.

There are several built-in hooks for:

• collecting, show & reset statistics
• drop reordered messages
• verify message metadata
• handle simulation restarts
• remapping values of a sample
• overwriting / updating timestamps
• converting data-types
• downsampling

But main goal of this mechanism is to provide extensibility for the end user. Example applications for hooks might be:

1. Filter sample values
2. Manipulate sample values: FIR
3. Transform sample values: FFT, DCT
4. Update network emulation settings based on sample values

Hooks can be added to the processing pipeline in three places:

• Node-read: Everytime a sample is received from a node
• Node-write: Everytime a sample is sent to a node
• Path: Everytime a sample is processed within a path

Some hooks are built-in hooks which are by default enabled without a corresponding section in the configuration file. Usually, built-in hooks have no configurable options.

Currently, the following node-hook-types are supported:

Type	Built-in	Node-read	Node-write	Path	State	Comment
Average signal values		yes	yes	yes	stable	Calculate average over some signals
Cast signal values					stable	Cast signals types
Decimate sample rate		yes	yes	yes	stable	Downsamping by integer factor
Dynamic Phasor calculation / DFT		yes	yes	yes	alpha	Transform to/from dynamic phasor domain
Drop reordered samples	yes	yes			stable	Drop messages with reordered sequence numbers
Dump sample data		yes	yes	yes	stable	Dump data to stdout
Energy Based Metric calculation					alpha	Energy-based Metric
Fix missing metadata	yes	yes			stable	Fix received data by adding missing fields
Calculate Jitter		yes			stable	Calc jitter, mean and variance of GPS vs NTP TS
Limit rate		yes	yes	yes	stable	Limit sending rate
Lua scripting		yes	yes	yes	stable	Lua scripting support
Handle restarts	yes	yes			stable	Call restart hooks for current node
Scale and offset signals		yes	yes	yes	stable	Scale signals by a factor and add offset
Shift sequence numbers		yes	yes		stable	Shift sequence number of samples
Shift timestamps		yes	yes		stable	Shift timestamps of samples
Skip First Samples		yes	yes	yes	stable	Skip the first samples
Statistic collection		yes			stable	Collect statistics for the current path
Timestamp		yes	yes	yes	stable	Overwrite origin timestamp of samples with receive timestamp
Print sample data		yes	yes	yes	stable	Print the message to stdout

Writing custom hook functions

Todo:

This still needs to be written.