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.
Operation
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.
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.
- call
- 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"
- answer
- 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
- hangup
- 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
- 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"
- speak
- 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"
- stop
- Terminate any play or speak command immediately and clear
the queue. This serial command takes no arguments.
Example: line #0:stop
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.
Configuration
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.
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.