Dial plans are the scheme that the SPA3102 uses to define call routing for a given incoming call to an output voice gateway. They are also a bit more than this, allowing dialled numbers to be manipulated as well as interpreted by the SPA3102. The interpretation capability is almost mandatory, since in most cases there will be more than one applicable voice gateway for any call on the handset, or on either (any - other units) of the SPA3102 VoIP and PSTN ports. Somehow a choice must be made. Of course, one could specify a fixed voice gateway, but that approach somewhat obviates the need for the SPA3102. A much simpler VoIP adapter could have been chosen.
The manipulation capability is not compulsory, but is very useful. This allows, among other things, the capability to specify a single number prepended to the dialled number as a voice gateway selector. Clearly operating in this way requires the addition of the prepended digit, but letting this extra digit out onto the phone network would only confuse things. In that example the SPA3102 must interpret, but also remove the digit.
The manual for the SPA3102, is actually a reasonable reference for the construction of dial plan specification strings. You may prefer to use that document to inform you about the construction of them. The document is here. It is a .pdf, and the guide for dial plans is on page 61. We provide our own guide here mainly for completeness. Whan I was struggling to figure this thing out, I just wanted one place to get all the information. The example below is the dial plan used in the setup description;
A complete dial plan is always enclosed in parenthesis. Within the brackets token groups are separated by the | (pipe) symbol. Each token group represents a dialed number. In simple call plans nothing is specified outside the brackets. When you connect with the SPA3102, typically when you lift the handset, the SPA3102 will select a dial plan string, and will evaluate each token group against the number as it is dialed. Hopefully when you complete dialing, one of the dial plan token groups will match. If not the call will not progress. The count of digits in the token group is critical, and so each token group is usually, mainly, about the use wildcards.
Interdigit Long and Short timers are used to determine how long the SPA3102 will wait whilst evaluating the digit stream it receives from a caller during dialing. Each timer is reset and starts counting down every time a digit is dialed. When each timer reaches zero, the SPA3102 will make a decision.
The short timer will only activate if one of the token groups in the dial plan matches the dialed number. When zero, the short timer will trigger dialling of the number. By contrast, the long timer is always active if no number has actually been dialed. When the long timer expires the caller is released, and the call ended. Clearly, the long timer should always be set to a value greater than the short timer, or it will not be possible to dial a number that actually makes a connection.
Some of the usable tokens in the token groups can invoke a pause test, and this may impact on the Long and Short interdigit timeouts. These timers do have default values set in controls on the Regional sub-tab, and these are used if there is nothing outside the parenthesis of the dial plan. There can be more than one dial plan, accessed by different call sources. Some call plans may require longer interdigit timeouts because of variations in the use of the pause test capability. To solve this problem there is another mechanism for controlling the interdigit timeouts. This method involves specifying the timeouts as a part of the dial plan. These controls appear outside the parenthesis of the dial plan.
The table below shows the syntax for controlling (and overriding) the default interdigit timeouts. This is done on a case by case basis for each of the dial plans. Specification of these parameters is by no means mandatory, and in most cases unnecassary. They will likely only be required where long pause tests are used in one or more token groups of a dial plan;
Interdigit Timer control
Specifies the long interdigit timeout as "time" seconds.
Specifies the short interdigit timeout as "time" seconds.
The table below outlines each of the individual tokens that can make up a token group inside the parenthesis of the dial plan;
0 1 2 3 4 5 6 7 8 9 0 * #
Each of these tokens directly represents a dialed digit.
This represents any single dialed digit.
Square brackets can be used to surround a group of the previous tokens, any one of which can match a single dialed digit.
The period matches the previous token (not the previous match) any number of times.
The angle brackets provide a way to conditionally replace or remove digits. They can also insert digits. The "dialed" field must be matched, although it can be empty and will then (always) match the space between dialed digits at it's position. Matched digits will be replaced by the "substituted" field. The "substituted" field can also be empty and then the matching "dialed" digits will be removed. There is no obvious purpose in having both fields empty.
Comma will cause a tone to be played at it's position. (This does not seem to work for me and I can imagine why it might not. It's in the manual so it's here too.)
The exclamation mark bars the token group. If that sequence is matched, the number will be rejected.
S0 or L0
Reduce the interdigit timers (Short and Long) to zero. This can be used to bring forward the evaluation of the dialed number against the dial plan. Dial/hangup immediately.
Pause allows a pause of "time" seconds to be tested. This can be useful for expanding the quantity of dialer options. If there is a pause longer than "time" seconds during dialing, then the token group is acceptable. The "number" field is optional and can be used to automatically insert the specific "number" digits after "time" seconds.
An important consequence of the angle brackets is that they can be used to substitute in the name of a voice gateway at the end of a dialed number. As an example;
<:@gw1> maps to @gw1
This same scheme can also be used to allow quick specification of known SIP providers. The caller can dial the SIP number, followed by a replacement code for the alphanumeric part of the address. It would not be possible to enter this on the telephone handset any other way. For example;
This pattern could be used to match a seven digit SIP number, and the *1 / *2 suffix codes used to select between the blahblah and bunglebob SIP providers.
I'm not going to put up more examples here. The potential to make descriptive mistakes is great, and the likelihood of providing an example that matches everyones need is already covered in the setup pages. The manual linked above has many examples of dial plans, and if you have any doubts I would recommend it as a good reference, in respect of the dial plans.
Please don't forget to include a dial plan token group that allows dialing to the emergency services over the analogue line. The emergency number field on the Line 1 page merely disables hook flash. Unless you include such a token group in your dial plan you will be unable to contact the emergency services. If you need them, the last thing you want is to be fiddling with your phone.