Events Handling System

The Event Handling Subsystem

There are a lot of sounds that should be played as a response to an event in the SvxLink system. To make these sounds as configurable as possible there is a programmable event handling subsystem. The programming language chosen for this is TCL (Tool Command Language). For each event in SvxLink there is a corresponding TCL function that is called when the event occurs. In this function the normal action is to play a sound or a couple of sound clips. It is of course also possible to use the full power of TCL to make all sorts of things happen. For example execution of an external application, reading files with information (e.g. DX, weather data etc), time based events (e.g. only do this when the time is…​).

The main TCL script can be found at /usr/share/svxlink/events.tcl. When this script is loaded by the SvxLink server at startup, it looks in a subdirectory called events.d. Any file that ends in ".tcl" in this directory will be read and should contain a TCL script. If you have a look in this directory you will find files like: Logic.tcl (common events for logic cores), RepeaterLogic.tcl (repeater logic events), SimplexLogic.tcl (simplex logic events), Module.tcl (common module events), Help.tcl (help module events), Parrot.tcl (parrot module events), EchoLink.tcl (echolink module events). There is a comment above each function that says what it does so have a look in these files and let your imagination flow.

You should not change these files directly but rather create a subdirectory under the events.d directory called "local". If you for example want to change something in the RepeaterLogic.tcl file, copy the RepeaterLogic.tcl file to the "local" directory. Then edit that file. All functions in this file will override functions in the original file. Remove all functions that you have NOT modified. Then the original version will be used and future updates will be less painful.

There are a couple of functions that can be used within a TCL function to make things happen in the SvxLink core.

playFile 'filename'

Play the specified file. The filename may be an absolute path or a path relative to the directory where the events.tcl script is stored. Supported formats are "raw" (16 bit signed samples 16kHz sampling rate), "wav" (16 bit signed samples 16kHz sampling rate) or "gsm".

playTone 'fq amplitude length'

Play a tone with the specified frequency (Hz), amplitude (0-1000) and length (milliseconds).

playSilence 'length'

Play the specified number of milliseconds of silence. This can be used to adjust the spacing between audio clips.

recordStart 'filename'

Start recording of received audio to a file. Only one recording at a time can be active.

recordStop

Stop a previously started recording.

There are also a couple of convenience functions implemented in TCL:

playMsg 'context name'

This function also plays a file. It actually uses the playFile function to play the file. The path to the file to play is formed as follows: event.tcl directory/sounds/language/context/name.\{raw,wav,gsm}. If no matching sound clip is found in the directory specified by "context", the Default directory will be searched.

playSubcommands 'context basename header'

Play a range of subcommand description files. The file names must be in the format <basename><command number>[ABCD{star}#]. The last characters are optional. Each matching sound clip will be played in sub command number order, prefixed with the command number. context - The context to look for the sound files in (e.g Default, Parrot etc). basename - The common basename for the sound clips to find. header - A header sound clip to play first.

spellWord 'word'

Spell the specified word using a phonetic alphabet.

playTwoDigitNumber 'number'

Say the specified two-digit number (00 - 99).

playThreeDigitNumber 'number'

Say the specified three-digit number (000 - 999).

spellNumber 'number'

Spell the specified number digit by digit.

playNumber 'number'

Say a number as intelligently as posible.

playTime 'hour minute'

Play the specified time. For example "playTime 13 35" will produce "One Thirtyfive PM", when using an English language pack and "tretton trettiofem" with a Swedish language pack.

playDtmf 'digits amplitude length'

Play DTMF digits, amplitude (0-1000) and length (milliseconds).