RetourAsterisk
2008-01-22 14:51:06 (ID: 38, Parent: 33, Type: page)
Asterisk serveur de téléphonie Asterisk Serveur de Téléphonie (Asterisk PBX)
ASTERISK - mini FAQ
Brief index
A new player in the opensource telephony:
Posted by timothy on Wednesday February 23, @05:47AM
from the tin-can-and-string-compatible dept.
dsginter writes "It looks like Asterisk isn't the only open source PBX game in town anymore. sipX, as the name implies, is a SIP-only PBX project released under the LGPL. A noteworthy feature is the inclusion of an out-of-the-box web-based management console. Read more about the release over at Voxilla."
1 - What is asterisk and what I need to use it
2 - Installation and first start
3 - Extending Asterisk capabilities
3.1 - Applications
3.2 - Extending AGI capabilities
3.3 - AGI
3.4 - Manager
4 - Other source of documentation
6 - Tips and Tricks
7- Other telephony related stuff
1 - What is Asterisk and what I need to use it?
1.0 - What is Asterisk?
Asterisk is an OpenPBX software from Digium. That mean a phone central software.
1.1 - What is needed to install Asterisk?
A minimal hardware able to run linux. A distribution of linux running kernel 2.4.x, installed with the kernel source headers and some basic developpement tools.
The Asterisk source code. It can be downloaded by CVS access at the following URL.
1.2 - What hardware is needed?
No specific hardware is needed if you want to do IP telephony.
Specific telephony card is needed to use telephony hardware (line and/or phone).
1.3 - Where I can buy that telephony hardware in canada?
There is a list of hardware that can by used with asterisk. (excerpt from digium web site)
Also joined, some canadien resellers.
ZAPTEL (digium)
Wildcard TE410P Wildcard T400P Wildcard T100P Wildcard E400P Wildcard E100P Wildcard TDM400P Wildcard X100P
| A Quad-Span T1/E1 half-length 3.3 volt PCI card that supports both telephony and and data modes in T1 or E1 format on a port-selectable basis. |
| A Quad-Span T1 half-length PCI card which supports both telephony and data modes. |
| A Single-Span T1 half-length (available with 2U bracket) PCI card sporting the same features as the T400P. |
| A Quad-Span E1 half-length PCI card which supports both telephony and data modes. |
| A Single-Span E1 half-length (available with 2U bracket) PCI card sporting the same features as the T400P. |
| A one-to-four port modular PCI 2.2 card currently featuring FXS modules for interfacing with standard analog telephones. |
| A single port FXO PCI interface card for interfacing with a standard analog phone line. |
Canada
Dialogic Hardware (Intel)
D/41JCT-LS VFX/41JCT-LS D/120JCT-LS D/240JCT-1T1 D/300JCT-1E1 D/480JCT-2T1 D/600JCT-2E1
| Analog |
| 4-port analog + voice |
| 4-port analog + voice + fax |
| 12-port analog + voice |
| Digital |
| T1 + 24 voice |
| E1 + 30 voice |
| (2) T1 + 48 voice |
| (2) E1 + 60 voice |
Canada
| Ontario |
| CYGCOM Integrated Technologies |
Contact: |
Voice: 800 407 7928
E-mail:
WWW: www.cygcom.com |
Non-Zaptel & Non-Dialogic Hardware Internet PhoneJack Internet LineJack ISDN4Linux ALSA OSS
| QuickNet |
| Single FXS interface. Supports Linux telephony interface. DSP compression built-in. |
| Single FXS or FXO interface. Supports Linux telephony interface. DSP compression built-in. |
| Miscellaneous |
| Any ISDN terminal adapter supported by isdn4linux should provide connectivity. |
| Any ALSA compatible full-duplex sound card. |
| Any OSS compatible full-duplex sound card. |
2 - Installation and first start
2.0 - Installation Downloading and installing.
2.1 - Starting sequence
If everything is installed, the manual startup consist of:
loading the zaptel modules
/sbin/insmod zaptel
/sbin/insmod wcfxo
/sbin/insmod wcfxs
/sbin/ztcfg -vv
and finally starting the pbx
/usr/sbin/asterisk
3 - Extending Asterisk capabilities
3.0 - How to extend Asterisk functionnalities?
There are globally two methods that can be use to add functionnality to Asterisk PBX. The first one that is compiled to be run directly within the PBX can be called Functions (written in C/C++ and compiled as a module) and the second one that is called by Asterisk as an external program that is called AGI Asterisk Gateway Interface (Like CGI for the web).
3.1 - Quick start an application project
Note: the "show applications" asterisk command list all available applications.
If you have follow the instructions on the asterisk web site "how to retrieve source from cvs" you should have source installed under /usr/asterisk. GO into this directory. Descend under apps directory. Here we are.
1. Copy one of the file as a template for your work. As an example, I've copied app_record.c as app_imrecord.c. When this is done, edit the file.
2. At the beginning of the file, you should change the "tdesc", "app", "synopsis" and "descrip" values to represent your function.
3. You could also change the function name to follow your need. (in my example, the one which is "static int record_exec(struct ast_channel, void *data)" was renamed "imrecord_exec").
4. At the end of the file, there is a function named "load_module" that call the "ast_register_application" function with function name as argument. You must change the second argument accordingly with the function name you have gived to your code (step 3).
5. Edit the make file to include your new file (named at step 1). Just add it to the line beginngin with "APPS=" but change the extension from .c to .so.
APPS=app_dial.so app_playback.so app_voicemail.so app_directory.so app_mp3.so\
app_system.so app_echo.so app_record.so app_image.so app_url.so app_disa.so \
app_agi.so app_qcall.so app_adsiprog.so app_getcpeid.so app_milliwatt.so \
app_zapateller.so app_setcallerid.so app_festival.so \
app_queue.so app_senddtmf.so app_parkandannounce.so app_striplsd.so \
app_setcidname.so app_lookupcidname.so app_substring.so app_macro.so \
app_authenticate.so app_softhangup.so app_lookupblacklist.so \
app_waitforring.so app_privacy.so app_db.so app_chanisavail.so \
app_enumlookup.so app_transfer.so app_setcidnum.so app_cdr.so \
app_hasnewvoicemail.so app_sayunixtime.so app_cut.so app_read.so \
app_setcdruserfield.so app_random.so app_ices.so app_eval.so \
app_nbscat.so app_GetWave.so app_extenplay.so app_authen.so \
app_playwav.so ima_record.so
6. Make your coding
7. Go up one directory (to the /usr/src/asterisk) run make and make install.
8. Restart Asterisk to apply changes.
Here is my
app_imrecord.c file. This is a modified version of app_record which allow playback, rewind, forward, while recording. All commands are dtmf tones. Here is a list of tone and corresponding actions:
| 1- Rewind 3 seconds |
2- Play |
3- Forward 3 seconds |
| 4- Stop |
5-Record |
6-N/A |
| 7-Goto Start |
8-Play last 5 secondes |
9- Goto End |
| *-N/A |
0-N/A |
#-End of recording |
3.2 - Extending AGI CapabilitiesAll the agi functions are contained within the asterisk/apps/app_agi.c file. This file can be modified to include new features. I've extended them to support a more complete record/playback functionalities. I've made minimals changes to
app_agi.c and done almost all the work within
app_agi_ext.c.
The new feature name was IMRECORD and IMSTREAM FILE. They use the same parameters as RECORD and STREAM FILE.
The new record feature are called using the phone keyboard while recording and are defined as follow:
| 1- Rewind 3 seconds |
2- Play |
3- Forward 3 seconds |
| 4- Stop |
5-Record |
6-N/A |
| 7-Goto Start |
8-Play last 10 secondes |
9- Goto End |
| *-N/A |
0-N/A |
#-End of recording |
3.3 - Quick start an AGI project
AGI are simple external programs called by asterisk. From within this program you can call asterisk functions. The call to an AGI program is define thru the asterisk configuration files.
From my "extension.conf" file there is an example of AGI call.
exten => 5,1,agi,service.php|-s Radiologie
exten => 5,2,goto(default,s,1)
On dialing to extension five on an asterisk answered line, the control is given to the service.php program to handle the call. You could write your own in any language. I've used php as it is interpreted and don't need to be compiled. It also give simple database access and handle standard I/O.
To talk with the asterisk system, you simply talk on the standard input/output. Here are basics routines in php:
ob_implicit_flush(true);
set_time_limit(6);
$in = fopen("php://stdin","r");
// toggle debugging output (more verbose)
$debug = true;
////////////////////////////////////////////////////////////////////////////
// Do function definitions before we start the main loop
function __read__() {
global $in;
$input = str_replace("\n", "", fgets($in, 4096));
return $input;
}
function __write__($line) {
echo $line."\n";
}
////////////////////////////////////////////////////////////////////////////
// start by parsing agi headers into array
while ($env=__read__()) {
$s = split(": ",$env);
$agi[str_replace("agi_","",$s[0])] = trim($s[1]);
if (($env == "") || ($env == "\n")) {
break;
}
}
I've also done a "read number" function that play a sound file and wait for an input number ended by a pound sign.
function __readnumber__($file) {
__dump__("ReadNumber, stream file $file");
__write__("stream file ".$file." \"1234567890\"");
$value=__read__();
$digit=substr($value,11,2);
if ($digit!=0)
$number.=chr($digit);
while ($digit!=35)
{
__write__("WAIT FOR DIGIT -1");
$value = __read__();
$digit=substr($value,11,2);
if ($digit!=35)$number.=chr($digit);
}
__dump__("ReadNumber, received pound sign, value is $number");
return $number;
}
And also a debuging output information shortcut:
function __dump__($line) {
global $debug;
if ($debug)
{
echo "VERBOSE \"$line\" 2\n";
__read__();
}
}
I've also designed a basic php class that do all that stuff. It is available
here. Here is an example of how to use it:
<?php
include "asterisk.php";
AGI = new asterisk;
AGI->debug(1);
$value = AGI->ReadNumber(file);
?>
This example define an asterisk object named AGI. It set debug mode to verbose and after that, it play the file 'file.wav'and wait infinitly for a number ended with the pound sign (#).
The read/write function are used to send asterisk command and read the result. The availables commands are:
ANSWER
AUTOHANGUP <time>
CHANNEL STATUS [<channelname>]
EXEC <application> <options>
GET DATA <filename> [<timeout>] [<max digits>]
GET VARIABLE <variablename>
HANGUP [<channelname>]
RECEIVE CHAR <timeout>
RECORD FILE <filename> <format> <escape digits> <timeout> [BEEP]
SAY DIGITS <digit string> <escape digits>
SAY NUMBER <number> <escape digits>
SEND IMAGE <image>
SEND TEXT "<text to send>"
SET CALLERID <number>
SET CONTEXT <desired context>
SET EXTENSION <new extension>
SET PRIORITY <new priority number>
SET VARIABLE <variablename> <value>
STREAM FILE <filename> <escape digits>
TDD MODE <on|off>
VERBOSE <level>
WAIT FOR DIGIT <timeout>
Note: The "show agi" asterisk command list all available agi commands.
you can also extend this command set by modifying the app_agi.c file. See 3.2 - Extending agi capabilities for basic details.
Within this file, you find every command that are availables from a called agi script.
3.4 - Manager
Another way to extend Asterisk capability is to send it command via the manager.
You must enable it in the /etc/asterisk/manager.conf
;
; Asterisk Call Management support
;
[general]
enabled = yes
port = 5038
bindaddr = 0.0.0.0
[mark]
secret = mysecret
deny=0.0.0.0/0.0.0.0
read = system,call,log,verbose,command,agent,user
write = system,call,log,verbose,command,agent,user
permit=209.16.236.73/255.255.255.0
After that you can connect to asterisk on port 5038 tcp. On that connexion, you should firt login and after that you can send commands and you receive messages indicating all transaction that occurs.
A list of all availables commands can be obtain within asterisk console with show manager commands
Action Synopsis
Ping Ping
Events Contol Event Flow
Logoff Logoff Manager
Hangup Hangup Channel
Status Status
Redirect Redirect
Originate Originate Call
MailboxStatus Check Mailbox
Command Execute Command
ExtensionState Check Extension Status
AbsoluteTimeout Set Absolute Timeout
MailboxCount Check Mailbox Message Count
ParkedCalls List parked calls
Monitor Monitor a channel
StopMonitor Stop monitoring a channel
ChangeMonitor Change monitoring filename of a channel
IAXpeers List IAX Peers
ZapTransfer Transfer Zap Channel
ZapHangup Hangup Zap Channel
ZapDialOffhook Dial over Zap channel while offhook
Queues Queues
QueueStatus Queue Status
SetCDRUserField Set the CDR UserField To login you send:
Action: login\n
username: username_in_bracket_in_manager_dot_conf\n
secret: secret_password_in_manager_dot_conf_for_that_user\n
\n
The server normally respond with
Response: Success\n
Message: Authentication accepted\n
\n
I use that php script to connect to my asterisk manager and display a red or green led if it is still working or dead.
<?php
$fp = fsockopen("192.168.2.80", 5038, $errno, $errstr, 30);
if (!$fp)
{
echo "$errstr ($errno)<br />\n";
echo "<img src=\"php/led.php?state=off\"> Asterisk is K.O.<a href=\"/php/restart.php\">Restart</a>";
}
else
{
fgets($fp, 128);
$out = "Action: Login\r\n";
$out .= "username: username\r\n";
$out .= "secret: password\r\n";
$out .= "\r\n";
fwrite($fp, $out);
fgets($fp, 128);
fgets($fp, 128);
fgets($fp, 128);
$out = "Action: Ping\r\n";
$out .= "\r\n";
fwrite($fp, $out);
$t = fgets($fp, 128);
if (strstr($t,"Response: Pong"))
echo "<img src=\"php/led.php?state=on\"> Asterisk is OK";
else
echo "<img src=\"php/led.php?state=off\">Asterisk is K.O.<a href=\"/php/restart.php\">Restart</a>";
fgets($fp, 128);
fclose($fp);
}
?>
and here is my led.php script
<?php
Header("Content-type: image/png");
$state=$_GET['state'];
$image=ImageCreate(16,16);
$green1=ImageColorAllocate($image,0,255,0);
$red1=ImageColorAllocate($image,255,0,0);
$black=ImageColorAllocate($image,0,0,0);
ImageFilledRectangle($image,0,0,16,16,$black);
if ($state=="on")
{
ImageEllipse($image,8,8,12,12,$green1);
ImageFill($image,8,8,$green1);
}
else
{
ImageEllipse($image,8,8,12,12,$red1);
ImageFill($image,8,8,$red1);
}
ImagePNG($image);
ImageDestroy($image);
?>
There are doc on Asterisk Manager API available on line at:
http://www.voip-info.org/wiki-Asterisk+manager+API
4 - Other source of documentation
4.0 - Where I can find more documentation about Asterisk?
From the asterisk official web site
HERE and
HERE
There is also the
asterisk mailing list (
there is an archive talking about modems)
Some informations about the API on
Greg's Asterisk Page
4.1 - Where I can find articles and/or examples about Asterisk?
There is a french site about asterisk
Asterisk AGI Documentation
5 - Tips and Tricks
5.1 - Dialplan
5.2 - Zap
Config In the file zapata.conf you could set your phone immediate setting to yes, this will remove the dialtone and let you directly in the system.
Here are an example:
[channels]
;==================
;LIGNE TELEPHONIQUE
;==================
busydetect=1
busycount=7
relaxdtmf=yes
callwaiting=yes
callwaitingcallerid=yes
threewaycalling=yes
transfer=yes
cancallforward=yes
usecallerid=yes
echocancel=yes
echocancelwhenbridged=yes
rxgain=0.0
txgain=0.0
group=1
pickupgroup=1-4
immediate=no
context=outside
;context=home
signalling=fxs_ks
callerid=asreceived
channel=1
;===================
;INTERFACE TELEPHONE
;===================
immediate=yes
context=home
group=2
signalling=fxo_ks
mailbox=2468
callerid="Phone 1" <2468>
channel=2
6 - Other telephony related stuff
6.1 - Links
What is a T1?
Telephony basics
Digital Communications
Alt2600 telephony hacks
Telephony, TAPI etc links page
Bayonne a asterisk like open pbx
