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
• down-sampling

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: Every time a sample is received from a node
• Node-write: Every time a sample is sent to a node
• Path: Every time 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		yes	yes	yes	stable	Calculate average over some signals
cast					stable	Cast signals types
decimate		yes	yes	yes	stable	Downsamping by integer factor
dp		yes	yes	yes	alpha	Transform to/from dynamic phasor domain
drop	yes	yes			stable	Drop messages with reordered sequence numbers
dump		yes	yes	yes	stable	Dump data to stdout
ebm					alpha	Energy-based Metric
fix	yes	yes			stable	Fix received data by adding missing fields
jitter_calc		yes			stable	Calc jitter, mean and variance of GPS vs NTP TS
limit_rate		yes	yes	yes	stable	Limit sending rate
lua		yes	yes	yes	stable	Lua scripting support
pmu_dft		yes	yes	yes	stable	Caluclate the phasor on a sample window
pps_ts		yes	yes	yes	stable	Timestamp samples based on a PPS signal/edge within the sample
restart	yes	yes			stable	Call restart hooks for current node
round		yes	yes	yes	stable	Round floating point and complex signals to decimal digits
rms		yes	yes	yes	stable	Calculate the RMS value of a signal
scale		yes	yes	yes	stable	Scale signals by a factor and add offset
shift_seq		yes	yes		stable	Shift sequence number of samples
shift_ts		yes	yes		stable	Shift timestamps of samples
skip_first		yes	yes	yes	stable	Skip the first samples
stats		yes			stable	Collect statistics for the current path
ts		yes	yes	yes	stable	Overwrite origin timestamp of samples with receive timestamp
print		yes	yes	yes	stable	Print the message to stdout

Writing custom hook functions

ToDo

This still needs to be written.