HomeVisionXL Voice over IP Plug-in

The voice over IP plug-in implements a SIP user agent which is controlled by Homevision. In the plug-in you can specify a macro to run when a call comes in. The macro code can check the caller ID and take actions based on it. You can play wav files to the caller under control of your schedule and even report variables and other information using TTS.

The speech from the other party can be saved to a file so it will be possible to attach the voicemail message to the email that you can have HomeVisionXL send you using the sendmail plug-in.

It is even possible to setup a complete voice response system, allowing the caller to perform actions (like switching lights on and off) by sending DTMF digits.

Finally, you can also trigger the SIP plug-in from your schedule to call you and inform you of situations that may require your attention. In emergencies it can call to several numbers at the same time and report the situation to the first one who answers.


The plug-in can handle multiple accounts. Each account is assigned a line number. A summary screen displays a progress bar for each account indicating the remaining registration time. The current state of the line is also indicated. If something goes wrong in your schedule, the context menu on the status screen allows you to manually terminate a call.

VoIP line status
Each account can be linked to two homevision macros and a variable.
Incoming call macro
This macro will be executed when a call is received. Before the macro runs, the caller ID information is loaded into homevision. This makes it possible to perform actions based on the caller's number. The caller ID information consists of two parts: the callers number and the callers name. If the name of calling party is provided in the SIP message it will always be loaded into the callers name part of homevision's caller ID information. Due to limitations of the homevision CID conditions, the callers number part should only contain digits. If the user name of the calling party contains other characters, the callers number part of homevison's caller ID information will be set to "Private".

Answer macro
This macro will be executed for an outgoing call when the remote party answers the call. This macro can be used to start playing or speaking a message to the other party. But it is also ideal for housekeeping, like enabling the periodic event that monitors the DTMF variable and stopping a timer that would cancel the call if it had not been answered within a reasonable amount of time.

DTMF Variable
When a the plug-in detects that the other party pressed a DTMF key, this variable will be set to the number of the key, or 10 for the * key, and 11 for the # key. Note that no macro will be executed to trigger your schedule that the variable has been set, so another method will be needed to detect that. One possibility is to check the variable in a periodic event running every loop. Initially, and after processing a DTMF key, you should set the variable to a value that is different from any possible DTMF value, like 255.
From within the homevision schedule the different accounts are being addressed by their line number. Line number 0 is an alias for the most recently used line. All serial commands for controlling the plug-in look like "line #<num>:<cmd> [<arg>]". The following commands are available:
The plug-in will place a call to the telephone number provided in the argument. The telephone number has to be enclosed in double quotes. If multiple comma separated telephone numbers are specified, the plug-in will setup calls to all numbers simultaneously. The first destination that answers will be connected. The calls to all other desitinations are terminated.

Example: line #1:call "5551234"

If a call is coming in, this serial command will cause the plug-in to answer the call, establishing a speech path. If there is no incoming call when this command is issued, nothing happens. This serial command takes no arguments.

Example: line #0:answer

Terminate a call. This can be used to end a call that has been setup from either end (incoming or outgoing call). It can also be used to cancel an outgoing call if the other party does not answer, or to decline an incoming call. If non of the described conditions are true, this command has no effect. If play or speak commands are in progress, the hangup command will be placed in the queue and the call will be terminated after those other commands have finished. This serial command takes no arguments.

Example: line #3:hangup

Play a wav file to the other party. The wav file must have been created in 8000 Hz, mono, A-law or u-law format. This command will only play the file if a speech path has been established and the speech path is idle. If another file is playing, a speech command is in progress, or the connection is still being established, the command is queued until the speech path becomes available. This command requires one argument, specifying the wav file to play.

Example: line #0:play "welcome.wav"

If a TTS system is available, this command will read out the provided string to the other party. This command will only read out the string if a speech path has been established and the speech path is idle. If a file is currently playing, another speech command is in progress, or the connection is still being established, the command is queued until the speech path becomes available. This command requires one argument, the string to read out to the other party.

Example: line #0:speak "The temperature is 23 degrees"

Terminate any play or speak command immediately and clear the queue. This serial command takes no arguments.

Example: line #0:stop

The plug-in will queue commands if necessary. This makes it very easy to send simple messages because the commands can just be issued without any consideration for timing and interaction with the other party. For example the following sequence will be enough to have HomeVisionXL call you and report an event:

line #1:call "5551234,5556677"
line #1:play "hello.wav"
line #1:speak "The alarm has been disarmed"
line #1:hangup

First, the plug-in will call both 5551234 and 5556677. When one of the two numbers answers the other call is cancelled. The person who answered will hear the hello.wav file followed by the text message. When the text message is finished the call is terminated.


On the account configuration screen the information about the account can be specified. A unique name for the account must be specified and a line number must be selected. The account can easily be enabled and disabled using the state checkbox.

Account configuration
The information for the next group of setting should have been provided to you by your SIP service provider. If the service provider has not specified a STUN server, switch off the checkbox for using STUN and specify your local IP address. If you are not behind a NAT device, you also should not specify a STUN server. Most of the time a service provider will not indicate a registration period. In that case you can leave the setting at the the default of 3600 seconds.

The supported codecs setting configures which codecs may be used and in which order they will be offered during codec negotiation. Normally this setting can be left at its default, but it can be changed to resolve certain problems with some service providers. For instance, VoipBuster does not allow renegotiation of codecs. Therefor you must be sure to get it right during the initial negotiation. If all your wav files are A-law encoded, you may want to set this to "A-law only". The linux TTS system only generates speech encoded as u-law. So, if you use TTS on linux it may be better to select "u-law only". But most service providers will happily allow you to switch codecs during the call and this setting is not very critical.

The audio recording setting determines if the speech data received from the remote party will be saved to file. If enabled, the files will be created in the log directory as 8000 Hz, 16 bits mono PCM WAV files. The created WAV files are called voip-YYYYMMDDHHMMSS.wav, where YYYYMMDDHHMMSS is the timestamp of the start of the call. For convenience the plug-in also maintains a link to the last file created for each account. The link name is Profile.wav, where Profile is replaced by the account name.

The DTMF decoding setting will switch the inband DTMF detection on or off. Switching inband DTMF detection on will result in quite a bit of processor intensive processing of the incoming speech. Normally it should not be necessary to switch this setting on as most SIP services will report DTMF tones using RTP-events, as specified in RFC 2833.

The DTMF payload type determines the payload identification to offer for DTMF RTP-events according to RFC 2833 when setting up a call. This setting can almost always be left at its default of 101.


The plug-in is provided as is in the hope that it will be useful. Hoewever, use of the plug-in is the sole responsibility of the user. The author of the code will not accept any responsibility for call charges, conflicts with service providers or other parties, or any other situations arising from the use of this software.

Last modified: 13 August 2008, 23:16 CEST