Linux Tutorial Web Site


Keith's Software and Tutorials Home Page
Knowledge Is Power

An Easy To Build
Telecom Speak-Back Box



It's not uncommon for telephone technicians in corporate environments to come across a live phone jack. Rather than tracing wires and toning pairs it's often a lot easier just to plug a test set into the jack and call someone that has a display telephone and ask them what number is coming up on the Caller ID. However, there are often times when no one answers or you get the impression that you're being a PITA. There used to be a stand-alone unit that you could connect to a Nortel CS1000 digital TN that you could call and it would answer and speak back the number you were calling from. That unit faded away after Nortel stopped making the chip the unit was based on.

While not as convenient as a stand-alone unit, this page tells you how to set up a PC to do the same thing. The good news is you can use any old PC that you thought was destined for a landfill. The software takes up less than 3 gigabytes of hard-drive space and the low processing requirements means you don't need a lot of memory or a powerful CPU. A Pentium 4 with 512 meg of RAM (and a DVD-ROM drive) will suffice.

The PC will run the CentOS Linux distribution, a sophisticated open-source software PBX called Asterisk, and a GUI management interface for Asterisk called FreePBX. Luckily all three are contained in one convenient, easy-to-install package called AsteriskNOW.

You will need one special piece of hardware, a special type of modified modem PCI card commonly referred to as an FXO card. It's also referred to as an "X100P card." This card has an RJ-11 jack and interfaces an analog telephone line to a PC running Asterisk.
NOTE:  When shopping for an interface card don't confuse an FXO module with an FXO card. An FXO card is the modified modem card we just mentioned. An FXO module is a small daughter board that plugs into a TDM400P clone card. The TDM400P card has four RJ-11 jacks which can be configured as either FXO or FXS ports depending on the modules that you install on the card. The 4-port TDM400P clone card is more common on eBay these days but you have to make sure the one you get includes an FXO module.
There are X100P clone cards out there. However, my recommendation is to get an actual X100P card rather than an X100P clone. You'll reduce the chance of having driver problems and compatibility issues with your analog line. Actual X100P cards are available at:

www.x100p.com/products/FXO.php

NOTE:  You don't need to know this to set up a speak-back box but FXO and FXS ports are ports for analog devices connected to an Asterisk PBX server. An FXO port is a port that connects to a POTS line and this POTS line is used as an analog "trunk" to the outside world. An FXS port is a port that you connect analog devices to, such as when you want to connect analog phones and fax machines to your Asterisk PBX. This brings up a curious point. Some X100P cards are in fact modified modem cards, so much so that they have the two RJ-11 jacks on them labeled Line and Phone. You plug a POTS line into the Line jack of the X100P card and that port is configured as an FXO port. While you can plug an analog phone into the Phone jack on the X100P card and it will work, it will not be a phone that is under the control of Asterisk, it will only be getting dial tone from your analog trunk resulting in potential conflicts. Only analog devices plugged into FXS ports can be controlled by Asterisk.

Another FYI is that when you're dealing with analog devices in Asterisk you'll frequently encounter the terms dahdi and zaptel or zapata. Zap* was the earlier software standard Asterisk used to communicate with analog devices and lines. Dahdi (Digium/Asterisk Hardware Device Interface) is the current standard and there are dahdi command-line utilities that you can use to aid in troubleshooting.
Even with the special hardware the process is pretty simple and can be done in less than an hour once you've got the hardware:
  1. Acquire an old PC and FXO card and install the card in the PC
  2. Download the AsteriskNOW DVD ISO image and burn it to a DVD.
  3. Boot the PC off of the DVD and install AsteriskNOW.
  4. Use the FreePBX GUI management tool to configure a trunk and a route.
  5. Modify the Asterisk dialplan configuration file using a text editor.


Download AsteriskNOW

You can download the latest AsteriskNOW DVD ISO image from here. Naturally if you're going to be using an older PC you'll want to download the 32-bit version.

www.asterisk.org/downloads/asterisknow


Install AsteriskNOW

NOTE that installing AsteriskNOW will wipe out whatever is currently on the hard-drive.

The DVD you created using the image you downloaded is called a "Asterisk distribution" because it includes everything, the Linux operating system (CentOS), the Asterisk server application, the Apache Web server application to serve up the FreePBX Web pages, etc. etc. etc. Installing the software off of this one DVD will give you a complete Asterisk PBX server.

Granted, it does seem like a bit of overkill to set up what is technically a server (even though it may be just an old desktop PC) just to talk back telephone numbers, but this is the cheapest and easiest way I've found to accomplish this.

FreePBX Boot Menu
Screen shot courtesy of the AsteriskNOW Installation Page

Boot off the DVD and the AsteriskNOW installation menu will appear. With Full Install under the newest version already highlighted press Enter.

Linux IP Configuration
Screen shot courtesy of the AsteriskNOW Installation Page

The next screen requiring input is the "Configure TCP/IP" screen. If you're not accustomed to navigating text-based screens you'll want to press the tab key to move the small highlight to the asterisk in front of "Enable IPv6 support" and press the space bar to de-select it. (There's an advantage to using DHCP with the IPv4 selection that I'll cover later.) Then press the tab key again to highlight OK and press Enter.

Linux Time Zone Configuration
Screen shot courtesy of the AsteriskNOW Installation Page

Likewise on the "Time Zone Selection" screen, press the tab key to highlight the list of time zones and use the up and down arrow keys to find yours. You typically won't find "Eastern" or "Central" so you have to select a city (such as Chicago for US-Central). Once you have your time zone city selected tab to OK and press Enter.

Linux Root Password
Screen shot courtesy of the AsteriskNOW Installation Page

Next you are prompted for a password. You will be prompted for two passwords during the installation and setup. This is the first one and it is for the Linux root account. On a Linux system root is the super-user account, like Administrator is on a Windows machine. You need this password to log into the system itself so don't forget what you enter here.
The second password you'll be asked for is for the FreePBX GUI management application. You'll not only be prompted for a password but for a user name as well. There's no reason you can't use "root" for that user name and the same password.
At this point your work is done for the software installation part of the setup. All of the Linux, Asterisk, and FreePBX application packages will be installed automatically. The installation may seem like it hangs at various points, especially if you're using an older PC. Just be patient.

When the software installation completes the DVD will eject and the system will reboot. Be sure to grab the DVD out of the tray before the system reboots to prevent the system from booting off the DVD again and wiping out the installation you just completed.

After rebooting the installation routine pulls down application updates. It says it'll take a couple minutes but it actually takes considerably longer even with a fast Internet connection so if you have a slow connection it'll take awhile.

Once the updates are complete you'll be at the Linux login: prompt. At that prompt type in root and hit Enter and then type in the password that you entered during the software installation.

Linux Console
Screen shot courtesy of the AsteriskNOW Installation Page

Once you log in you'll be at what's called a "shell prompt" which is the Linux operating sytem waiting for you to enter a command. We'll be entering commands later but for now notice that just above shell prompt is the "Interface eth0 IP" address. This is the IP address the system got via DHCP during the install process. (eth0 is Linux-ese for the PC's ethernet network adapter. Linux starts numbering things at zero.) This is the IP addres you'll use to manage the system using the FreePBX GUI management interface.


Configure a Trunk and Route

Go over to a Windows system that's on the same network as the speak-back box, open a Web browser, and in the browser address line enter the speak-back system's eth0 IP address we just mentioned above. This will pull up the FreePBX management GUI. This is where you have to enter that second password we talked about earlier. The very first time you go to this address you'll be prompted to enter a user ID, password and admin e-mail address for the FreePBX application. As mentioned earlier, feel free to use root as the user name and the same password you used earlier if you want.
While using duplicate user names and passwords may not seem very secure consider this, once the setup is done there's no reason this PC has to be connected to a network. It simply needs to have a telephone line plugged into the FXO card. Therefore, the only people who would be able to access this PC are those who have physical access to it and it can be located anywhere there's a jack or punch-down block (and an AC outlet). In addition, once the setup is done there's no reason to leave a monitor or keyboard connected to this PC. What you'll have is a PC with only a power cord and a telephone line plugged into it.

Note that if you do plan to run the PC "headless" most PCs will hang during boot-up with an error when there's no keyboard detected but there's typically a "no keyboard" setting in BIOS that you can set to prevent that. (You may also want to see if there's a BIOS setting that tells the system to power back up after a power failure rather than staying off.)

This brings up the advantage of using DHCP. If you boot the system with no network cable plugged in the system won't be able to pull an IP address so it bring up the eth0 interface.
Once an ID, password, and email address are entered a menu of applications is presented.

FreePBX Icons
Screen shot courtesy of the AsteriskNOW Installation Page

Click on the FreePBX Administration icon and you'll be prompted to enter the user name and password that you just created. A System Overview page will then appear. (You can bring up this same page at any time by pointing to Reports on the top menu bar and clicking on System Status.)

FreePBX Menu

The FreePBX menu is along the top of the page. Point to Connectivity and click on Trunks. In the upper-right area of the Trunks page you should see Channel g0 (dahdi). This is the analog trunk that was created automatically during the installation process when your FXO card was detected.

Again point to the Connectivity menu item and click on Inbound Routes. This brings up a page to add a new inbound route. Near the top of the page in the Description field enter Analog Line In.

Scroll to the bottom of the page to the "Set Destination" area. In the drop-down select Trunks and a second drop-down should appear with the DAHDI/g0 trunk showing. If it's not showing it should be selectable in the second drop-down.

FreePBX Inbound Routes

Click on the Submit button under the Trunks drop-down. A red Apply Config button will appear next to the menu at the top of the page. Don't click on this until we're done with our setup.

Point to the Connectivity menu item and select DAHDI Config. A pop-up window appears advising you of the Write Disabled status of the Dahdi configuration files. Near the bottom-right of this window click on the Enable button.

The page will list all digital and analog (FXO and FXS) ports. If you have an X100P card all you'll have listed is one FXO port with an Edit link next to it. Click on this link to open the edit window and replace whatever may be in the "Context" field to speakback. Then click on the Save button.

FreePBX Dahdi Configuration

Click on the "Reload Asterisk Dahdi Module" button under the FXO/FXS port listing.

Now you can click on that red Apply Config button at the top of the page (which will reload the Asterisk application on the Linux system). Then click on the logout button at the top-right of the page.


Modify the Dialplan

We have to forget the GUI management tool for a minute and manually edit one of the Asterisk configuration files by going back to the Linux PC that you logged into earlier and left at the shell prompt. Chances are likely the screen went into power save mode so just hit that backspace key to bring it back.

At the shell prompt type in the following command and press Enter to get into the asterisk configuration file directory:

cd /etc/asterisk

If you want to see how many configuration files there are type in ls and press Enter. You'll see a file named extensions_custom.conf. This is the file we're going to edit. As of now it's just an emply text file.

Recall that we specified the speakback context when we edited the Dahdi config above. Now we're going to create that context by editing the Asterisk dialplan file. At the shell prompt type in the following command and press Enter to open the dialplan file in the nano text editor.

nano extensions_custom.conf

and type in the following lines. Be careful because we're using paranthesis, braces, and brackets so make sure you type these commands in accurately including case sensitivity.

[speakback]
exten=>s,1,Answer
exten=>s,n,Wait(1)
exten=>s,n,SayDigits(${CALLERID(num)})
exten=>s,n,Wait(1)
exten=>s,n,Hangup

Press Ctrl-X to exit and press the y (yes) key to confirm saving the file and press Enter to confirm the file name and you'll return the shell prompt.

Decoding The Code

The real power of Asterisk is in its dialplan file, extensions.conf. It's not just a configuration file but also a script-type of file and there are dozens of commands (they call them applications) that you can use. You can arrange the statements to accomplish virtually any behavior you want. The exten=> statements are grouped into [contexts] to control what gets executed when. The exten=> statements have an extension ID (usually the number that's dialed to reach someone). In our case there is no extension number.

In the code above the extension ID of s means that if this context is referenced but no extension number is specified then run these statements. Basically it indicates that this is the default extension for the context. The 1 and n characters are the priority, i.e. the numerical order in which to execute the statements for a given extension. You must specify which statement is the number 1 priority but after that you can either use numbers or the n character, in which case the statements will get executed in the order they are listed. The advantage of the n is you can add and remove statements in the middle of the extension and you don't have to renumber the other priority values.

The keywords (Answer, SayDigits, Hangup, etc.) are the applications. Some applications take arguments and some don't. So the basic syntax is:
[context]
exten=> id, priority, application(argument)

Program an analog TN on your PBX and plug one end of a line cord into the jack that's connected to that TN. Plug the other end of the line cord into the Line jack on the FXO card on the back of the Linux PC.
NOTE:  On a Nortel CS-1000 you'll need a CLASS Modem card (NT5D60) to enable Caller ID on analog TNs. You'll also need to enable Caller ID on the individual TN by setting CNIA, CNUA and CNAA in the CLS as well as have an available CLASS license for each TN.
Now reboot the PC by typing in the following command at the shell prompt:

shutdown -r now

If you ever want to power down your PC intead of reboot it simply replace the -r with -P (that's an upper-case P).


Testing and Troubleshooting

Pick up a phone and dial the number you programmed on the TN and your speak-back box should answer, speak back the number you're calling from, and then hang up. If it does all you need to do is unplug the network cable, monitor, and keyboard and slide the PC back into a corner. (If you move the PC to a new location try powering it up with just a power cable and phone line attached and verify that it still works by giving it a call.) If it doesn't answer the phone and speak back the number you've got some troubleshooting to do.

Naturally if you've got issues you'll want to leave the keyboard, monitor and network cables attached. Your biggest asset in troubleshooting is Asterisk's command-line interface. Log into the Linux system with the root account and at the shell prompt type in:

asterisk -rvvvvvv

Asterisk is already running as a process. The -r indicates that you want to connect to this process. The multiple v characters (enter 5 to 8 of them) indicates that you want a high level of verboseness, i.e. that you want Asterisk to give you as much feedback as possible. When you hit enter you'll be in Asterisk's shell with a *CLI> prompt. This is Asterisk waiting for you to enter a command but it will also display feedback messages when an action is taken. (Type in quit when you want to exit the Asterisk CLI.)

With the Asterisk CLI up, call the number you programmed for the box and see if lines start scrolling on the CLI display. It's important if lines do appear because it indicates that the call is making it through the analog channel and your dahdi configuration is at least partly correct. This eliminates half the potential issues right there.

These lines will tell you what Asterisk is doing about the call and may give you an error indicating what the problem is, particularly if it's a syntax issue because you mis-typed one of the lines we entered earlier in the extensions_custom.conf file. Your best friend in this situation is Google. Enter any error exactly and within quotes so Google searches for it as a continuous string. Some errors may not be anything service affecting but others may tell you what you need to correct.

If no text scrolls in the CLI interface you can start with the traditional stuff, unplugging the phone line from the FXO card and into a test set to make sure you've got dial tone and a ring signal. If that's good then you have to start looking at your dahdi configuration. About half-way down on the Web page below is a section on "user space" dadhi tools.

www.voip-info.org/wiki/view/DAHDI

In this case tools are command-line utilities that you run. That means you enter the commands at the Linux shell prompt. Not the Asterisk CLI shell prompt. (Type in quit to exit the Asterisk CLI.)
Some problems may be specific with your system. For example, in creating this page I had a problem that I was never able to solve. The system would work great when it was plugged into a phone jack several floors above the PBX room. However, if I would take the PC down to the PBX room the system would answer but then immediately hang up. The error ("non-zero exit") I was getting wasn't specific enough to identify the issue. The only thing I can think of is that it was an issue with my China-made FXO card, that upstairs the lower voltage levels on the FXO jack due to the voltage loss over hundreds of feet of infrastructure cabling were acceptable, but the voltage levels were too high when the FXO card was plugged into a jack that was literally next to the PBX. Everything else, polarity, jack wiring, jack type, etc. were the same in both locations. I even tried recreating the system from scratch in the PBX room to no avail.
It is beyond the scope of this page to address every possible issue that you could encounter. No one page could do that. However, most problems should be solvable with some research and you'll learn some new things along the way.

Check out my page on building a free conference bridge using Asterisk.


Keith's Home Page





Powered by Apache On Debian Linux


Contents, diagrams, and images    Copyright © 2004-2015    Keith Parkansky    All rights reserved.
Certain graphics, symbols, and terms used on this site and in its documents are registered trademarks
of their respective owners and are contained herein for identification purposes only.
No endorsement of this site, its contents, or its documents by these owners is expressed or implied.

LIABILITY
IN NO EVENT WILL KEITH PARKANSKY BE LIABLE TO ANY PARTY (i) FOR ANY DIRECT, INDIRECT, SPECIAL, PUNITIVE OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF PROGRAMS OR INFORMATION, AND THE LIKE), OR ANY OTHER DAMAGES ARISING IN ANY WAY OUT OF THE AVAILABILITY, USE, RELIANCE ON, OR INABILITY TO USE THE INFORMATION, METHODS, HTML OR COMPUTER CODE, OR "KNOWLEDGE" PROVIDED ON OR THROUGH THIS WEBSITE OR ANY OF ITS' ASSOCIATED DOCUMENTS, DIAGRAMS, IMAGES, REPRODUCTIONS, COMPUTER EXECUTED CODE, OR ELECTRONICALLY STORED OR TRANSMITTED FILES OR GENERATED COMMUNICATIONS OR DATA EVEN IF KEITH PARKANSKY SHALL HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, AND REGARDLESS OF THE FORM OF ACTION, WHETHER IN CONTRACT, TORT, OR OTHERWISE; OR (ii) FOR ANY CLAIM ATTRIBUTABLE TO ERRORS, OMISSIONS, OR OTHER INACCURACIES IN, OR DESTRUCTIVE PROPERTIES OF ANY INFORMATION, METHODS, HTML OR COMPUTER CODE, OR "KNOWLEDGE" PROVIDED ON OR THROUGH THIS WEBSITE OR ANY OF ITS' ASSOCIATED DOCUMENTS, DIAGRAMS, IMAGES, REPRODUCTIONS, COMPUTER EXECUTED CODE, OR ELECTRONICALLY STORED, TRANSMITTED, OR GENERATED FILES, COMMUNICATIONS, OR DATA. USE OF THIS SITE CONSTITUTES ACCEPTANCE OF ALL STATED TERMS AND CONDITIONS.