Saturday, May 16, 2009

adsi.conf

This is the Analog Display Services Interface Configuration file for Asterisk. (Not to be mistaken with DISA, which is something completely unrelated).


1.1. Introduction to ADSI:

The file is located in the /etc/asterisk/ directory.

ADSI (Analog Display Services Interface) is a protocol for enabling alternate voice and data services over the analog telephone network, such as sending data to a display at the ADSI phone

It also allow for running simple interactive scripts on the ADSI phone, such as Call Waiting Deluxe, an application that displays the name and number of an incoming call while you are on the phone.
Not only will the phone display the number, it will also ask you what to do with it, including switching to the new call, forwarding the new call to your voice mail, putting the new caller on hold, playing a recorded message, or dropping the current call and switching to the new call.

Other ADSI applications include:

- Visual voice mail: the display of telephone voice mail menu options and a list of your voice mail messages
- Visual directory: a service that allows you to locate the telephone number of an individual or business and, possibly at extra charge, to download the address of that individual to your screen phone
- E-mail browsing: allowing you to send and receive e-mail messages via an ADSI-enabled device.
- Schedule-based services: faxing abilities, notification of incoming e-mail messages, home banking, ticket purchasing, and access to train and plane schedules.


1.2. Prequisites

- Asterisk
- a configured TDM card, fxo card or combination of channel bank and E1/T1 card.
- ADSI Capable phone



1.3. ADSI capable phones:

- Sayson/Aastra 390/480e
Cybiolink P-1 ADSI analog phone
- Nortel Vista 350/380

- Lucent Technologies' ADSI SpeakerPhone 980
- CybioTronics CY-2135-BH CybioLink

- Fanstel ST2112

(If you know more, please leave a comment and we will add them).

1.4. Configuration of asterisk for ADSI

Saddly, we don't have an ADSI phone in our lab, so all the information here is gathered on the internet and untested.

The main ADSI configuration file is called ADSI.conf, a sample ADSI script is included in the asterisk sources as asterisk.adsi.

To use ADSI, you need to enable ADSI on this specific zaptel line.
(So first you will need to read up on how to configure zaptel for your card and then enable ADSI on the channel your phone is connected to by adding the line adsi=yes to the configuration for this channel in zapata.conf.

; ADSI (Analog Display Services Interface) can be enabled on a per-channel
; basis if you have (or may have) ADSI compatible CPE equipment
;
;adsi=yes



I don't think you need to touch anything in adsi.conf, the sample configuration file looks as the snippet below:

;
; Sample ADSI Configuration file
;
[intro]
alignment = center; alignment on the screen, valid values are: l(eft), r(ight) i(indent?). All others are recognized as centered.
greeting => Welcome to the ; Some greeting, don't know when its shown on the phone
greeting => Asterisk
greeting => Open Source PBX
maxretries = 3 ; number of times to retry sending to the ADSI phone
[speeddial]
--please look at res_adsi.c

For the speeddial option, you will need to look at the res_adsi.c source code, i suppose its name,number or number,name.


1.5. ADSI scripts

Asterisk comes with two ADSI scripts included,
asterisk.adsi
telcordia-1.adsi

These scripts need to run on the phone, asterisk can upload them to the phone for you.
To do so, you will need to create a specific extension, which will call the ADSIProg application. When you call this extension with your phone, asterisk will upload the script to the phone.

exten => 1234,1,ADSIProg(telcordia-1.adsi);
exten => 1234,2,Hangup;


If no parameter is giving to ADSIProg, it will upload the default script, asterisk.adsi.

Before you upload any scripts, you might need to alter them and change two values for you specific phone:

SECURITY 0X9BDBF7AC ; Security code
FDN 0x0000000F ; Descriptor number


For a list with codes, have a look here

If your phone has multiple slots, you can upload one script per slot. (each slot will have a different FDN).


1.6. Other ADSI related features

1.6.1.: Voicemail

The comedian mail has some support for ADSI, if you want to use this with your phone, you will need to alter the codes again, but this time in the sources for comedian mail.
static char *adapp = "CoMa"; --> this value is the FDN as seen before
static char *adsec = "_AST"; --> this value is the security code as above.

This means that if you change the brand of phone, you will need to alter this again and recompile. And you probably will be unable to use different brands of phones at the same time.


1.6.2.: Send text to an ADSI phone

If you have a look at this google cache, you will find an application to send messages to your ADSI phone from the asterisk dialplan.


1.6.3.: Call Parking

Asterisk can send some information to your ADSI phone when you park a call, to enable this, edit features.conf and type the line adsipark = yes




See also:
- ADSIProg
- zapata.conf



References:

ADSI definition on techtarget.com
ADSI questions for a 390 ADSI Phone - part 1
ADSI questions for a 390 ADSI Phone - part 2
some more info on ADSI
ADSI FAQ
Another mail archive
ADSI unlock codes
Application to send text to the ADSI Phone
ADSI programming guide - WebSphere Voice Response for AIX V3.1 Programming for the ADSI feature
thread with some more info on locking codes

extensions.conf

extensions.conf - this is the configuration file, where have to make your dial plans

The extensions.conf file is one of the most used and most important configuration file in Asterisk PBX - it contains the dialplan. What is a dialplan? The dialplan , or we can say "the heart of the Asterisk System", defines how Asterisk PBX will handle incoming and outgoing calls, it also contains all extension numbers. The dialplan is divided in sections called contexts. Every context consists from more than one extensions. What is an extension? The extension is the telephone number, it can be numbers, letters or both. Every extension has a priority and an application. With the help of contexts we can organize our dialplan.

In general a dialplan looks like this:

[general]
--> some settings go here

[globals]
--> definition of some global variables go here

[context1]
-->extension 1, priority 1, application
-->extension 1, priority 2, application

--> extension helpdesk, priority 1, application
...
[context2]
--> extension 999, priority 1, application
--> extension 999, priority 1, application



2. Contexts

2.1 [general]

The first context in the extensions.conf file is [general], 3 configuration options can be set here:
static= yes | no - For now only the option yes is implemented, (so setting it to no won't have any effect) and if static=yes and writeprotect=no , then you can save dialplan from the CLI command 'save dialplan'.

More on this in the (upcoming) tutorial on the CLI commands. (The CLI is the interactive asterisk shell, where you could a.o. change your dialplan and save it without altering the extensions.conf file.)

writeprotect = yes | no - This option is require if you want to have ability to save dialplan changes from the CLI command.
autofallthrough=yes|no - If this option is set, after finishing with things to do, Asterisk will hang up the call. If not set, Asterisk will wait for another extension to be dialed. It is highly recommended this option to be set to yes.


2.2 [globals]

In context [globals] you can specify your own variables,
that can be used later in extensions. Note that a global variable
name is not case sensitive, so ${MYVAR} and ${mYvaR} are the same.
The way to write global variable in section [globals] is:

The_name_of_my_variable => The_variable's_value


Example:

[general]
static=yes
writeprotect=no

[globals]
MyMusicOnHold => /mp3/Mozart.mp3


2.3 "Real" call contexts

With the exception of [general] and [globals] everything else is consider as call contexts. The basic look of contexts is:

[context_name]
exten => some_exten_number,priority,application(arg1,arg2,...)
exten => some_exten_number,priority,application,arg1|arg2...
exten => some_pattern,priority,application(arg1,arg2,...)


But what is the purpose of the 'context' ? Inside a context, you could build an IVR menus (Interactive Voice Response) using extensions, you could define a specific context for every department of you company (Accounting, Support, etc)

Using different contexts, the Accounting team would call to their supervisor john when hitting 123, and the support team would call head of support 'alice' when pressing 123.

The support team might be able to do outgoing calls, but the account team could be restricted to only internal calls.

Or incoming calls from clients could be all sent to a waiting Queue, while internal calls between collegues will go straight to the collegue without queing.

So with the help of the contexts it's very easy to manage all assigned telephone numbers.

Example:
[general]
; ...skip...

[globals]
; ...skip...


[Helpdesk]
exten => 323206,1,Dial(SIP/Helpdesk_agent01)
; ...skip...

[Accounting]
exten => 443307,1,Dial(IAX2/Accounting_agent01)
; ...skip...


IVR menu example:

[default]
exten => steve,1,Dial(SIP/steve);
exten => mark,2,Dial(SIP/mark);

[mainmenu]
exten => s,1,Answer
exten => s,n,Background(thanks) ; "Thanks for calling press 1 for sales, 2 for support, ..."
exten => s,n,WaitExten
exten => 1,1,Goto(submenu,s,1)
exten => 2,1,Hangup

[submenu]
exten => s,1,Ringing ; Make them comfortable with 2 seconds of ringback
exten => s,n,Wait,2
exten => s,n,Background(submenuopts) ; "Thanks for calling the sales ;department. Press 1 for steve, 2 for..."
exten => s,n,WaitExten
exten => 1,1,Goto(default,steve,1)
exten => 2,1,Goto(default,mark,2)


Lets have a closer look at what the lines above do exactly.

Any call arriving in the mainmenu context, will first go to the s extension. (why ? Read on and you will find the answer below in the predefined extensions section)

exten => s,1,Ringing:
The first priority in this s extension is extension 1, this will just provide some ringing sound to the caller.


exten => s,n,Wait,2:
The second priority in extension s, is the wait application with parameter 2, which would just wait for 2 seconds, and as a result give ringing for 2 seconds before playing the audio file "submenuopts" to the caller as defined in the 3rd priority. (exten => s,n,Background(submenuopts))


exten => s,n,WaitExten:
The 4th priority will wait for the caller to enter some digits, (such as press 1 for steve, press 2 for mark), the keys pressed by the caller will be the new extension. (if the person presses 1, the call will go to extension 1, priority 1, if the person presses 2, the call would go to extension 2, priority 2)


Lets assume the caller pressed 2:

exten => 2,1,Goto(default,mark,2):
The caller pressed 2 and the call flow will now go to the default context, extension mark, priority 2.


exten => mark,2,Dial(SIP/mark);
In this last step, it would dial the sip user mark. (as defined in sip.conf)



3. Extension

Extension = telephone number? Yes, in general it is true.There are three types of extensions : litteral, predifined and pattern.

The litteral extensions can contain in their name: numbers (0-9), letters A,B,C,D (some hardphones have these letters) or all letters (a-z). Are extension names case sensitive? Yes and no. They are case sensitive when Asterisk have to match a user dialed extension to the extensions that are defined in a context. Extension names are not case sensitive when you try define two extensions (in one context) with same name but different case (you can not do this).

There are several predefined extension names:
- i - Invalid
- s - Start
- h - Hangup
- t - Timeout
- T - AbsoluteTimeout
- o - Operator


Example:
some example


If extension name starts with '_', it is consider as pattern.
For the extension that use pattern, some characters have special meaning:
- X - any digit from 0-9
- Z - any digit from 1-9
- N - any digit from 2-9
- [12679] - any digit in the brakets (in the example: 1,2,6,7,9)
- . - (dot) wildcard, matches everything remaining
( _1234. - matches anything strating with 1234 excluding 1234 itself).


Note: Do not use '_.', because it will match everything even the predefined extensions!!!

Example:
_359ZXXXXXX - This will match all dilaed extensions that start with 359, and are 10 digits long( including 359)
_0XXX. - This will match all dialed extensions that begin with 0 and are minimum 5 digits long (including 0)


So you can see that with help of patterns you can group calls as national, international or local, the only thing you must do is to write the pattern.

4. Other very useful stuff included in extensions.conf

4.1 ignorepad

Another option that can be set is ignorepat. This option instructs drivers
to not cancel dialtone upon receipt specified pattern:
Example:
ignorepat => 8 - dialtone will remain after pressing 8

4.2 switch
Switch option permits a server to share his dialplan with
another server (ServerA>ServerB). Note that reciprocal switch
statements are not allowed (ServerA>ServerB and ServerB>ServerA).

switch => IAX2/:[]@/

Note that and need to be declared in iax.conf
of the remote server ().

4.3 include

You can include all numbers from one context to another context. To do that use:
include => some_context_to_be_included

Except context you can include another configuration file. To do this you have to use '#include':

#include "some_file_to_be_included.conf"