SPA3102 and FreePBX HOWTO

The target configuration

The target configuration for this HOWTO is an SPA3102 connected to the same LAN as the PBX, or at least a routed but non-NATted situation(we use this same configuration for an SPA3102 across a VPN). The SPA3102 will be connected to the LAN through the 'INTERNET' port, and to the PSTN through the 'LINE' port. Setting up the phone port is very easy, and you should look for another tutorial for this. If you decide to use the 'ETHERNET' port for something, that's fine, but you're on your own there too.

Why another howto?

Why another howto for getting the SPA3102 to play with FreePBX? Because the howtos I've seen just don't work for me. There was one I found once, actually, that was excellent: It walked you through steps, just as any other howto would, but broke it up into separate sections where the user would complete a set of steps and then do some tests to make sure that particular functionality was working before moving on. That works well for a user who's not an expert, but wants to narrow down what he has to debug at each step. I tried to follow this approach here. Suggestions welcome!

Audience

I'm quite familiar with UNIX, so it's natural for me to ssh in and run commands at the shell or to edit files. I'm not as familiar with VOIP, but I like to learn. If you know a little UNIX, and you're trying to learn about VOIP, then maybe this tutorial is for you! If you really prefer a cookbook recipe for how to do this and will rely on community support when things go wrong, another author, wiseoldowl on freepbx.org, recommends his excellent HOWTO to you.

I also assume you have a working FreePBX installed, and have set up an extension before, and generally know your way about the menus.

Quick links

LinkSys SPA3102 support page

SPA3102 IVR configuration menu documentation

Sipura dial plan documentation

ATA Administration Guide This 250 page manual covers several devices. It has a whole section on configuring the SPA3102 FXO port.

3am Systems' World PSTN Tone Database has disconnect (and other) tones from many countries. The raw information is available for free, and you can get the information in Asterisk and Sipura format, ready for cut and paste, if you register, which is free of charge, but requires you submit some information about yourself.

Another source for tone information is the International Telecommunication Union, who publish a PDF on this page: "VARIOUS TONES USED IN NATIONAL NETWORKS".

There's a giant thread about disconnect tones here on the Voxilla forums; the basic formula they supply is "f1@-30,f2@-30;n(t1/t2/1+2)", where f1/f2=frequencies in HZ (the same if only one tone), n=number of repetitions of the pattern, t1=seconds of frequency, t2=seconds of silence.

wiseoldowl's HOWTO on freepbx.org contains additional configuration options that you should consult after getting the basic setup working here. His has additional information about adjusting gain levels and other settings that might cause problems.

Planning

You'll need to have/decide the following things:

• FreePBX's IP address; in this example, 192.168.7.6
• SPA3102's IP address; in this example, 192.168.7.50
• DNS names work in place of IP addresses, if desired
• Make up a user name and password for the trunk; in this example, 'pstn' and 'pstnpass'
• Choose an extension number and password for Line 1; in this example, '100' and 'line1pass'

Before you start

Before anything, you'll have to get the SPA3102 actually on your network.

1. The SPA3102 should already be powered on with 'LINE', 'PHONE', and 'INTERNET' ports connected. The 'INTERNET' port should be plugged into your LAN.
2. Reset the SPA3102 to factory default for good measure, since this tutorial depends on default settings being untouched. With the handset, dial '****', and wait for the IVR to begin. Dial '73738#' ('RESET#'), and '1' to confirm.
3. Temporarily connect your workstation's NIC directly to the SPA3102's 'ETHERNET' port. Your workstation should grab an IP address from the SPA3102. Navigate to http://192.168.0.1/admin/advanced and use the username 'admin', password 'admin'. If you didn't get to your adapter's configuration page, check your network settings to be sure your NIC has an IP address on the 192.168.0.x subnet.
4. Now's a good chance to update the firmware. As of 2008/11, the latest is 5.1.7, and these instructions are written for that firmware.
5. Choose a static IP for the adapter on your LAN. Go to the "Wan Setup" tab.
   • In "Internet Connection Settings" select "Connection Type" "Static IP".
   • In "Static IP Settings" enter the static IP, the netmask, and the gateway. In this example, we'll choose '192.168.7.50'.
   • In "Remote Management" select "Enable WAN Web Server" "yes".
   • Leave other settings as is, and click "Submit All Changes".
6. Connect your workstation's NIC back to your LAN. You can leave the SPA3102's 'ETHERNET' port unplugged from now on. You should be able to visit the adaptor's configuration page through the 'INTERNET' port through this URL (change the IP to match the one you chose): http://192.168.7.50/admin/advanced
7. If this didn't work, go back and check your configuration. The IVR may be helpful to find out what's going on too; see the IVR link in the 'Quick Links' section above.
8. Make sure you know how to log into your FreePBX system and get to the Asterisk command line with

   bash-3.1# asterisk -vvvr
   [...]
   bell*CLI>

Set up syslog on your PBX

Syslog is a handy way to debug the SPA3102.

1. On the SPA3102 configuration page, 'Voice' tab, 'System' subtab,
   • Set the 'Syslog Server' and 'Debug Server' to the IP of your
     FreePBX, 192.168.7.6 in this example.
   • Set 'Debug Level' to 2 or higher.
2. On your FreePBX host,
   • Append the following to /etc/syslog.conf:

     # save messages from SPA3102
     local2.debug,local3.debug                /var/log/spa3102.log

   • Add a '-r' to the syslogd command line. On CentOS (incl. Trixbox), edit /etc/sysconfig/syslogd, and edit this line:

     SYSLOGD_OPTIONS="-m 0 -r"

   • Restart syslogd; on CentOS (incl. Trixbox):

     bash-3.1# service syslog restart

   • Make sure syslogd is listening on UDP 514:

     bash-3.1# netstat -ulnp | grep 514
     udp        0      0 0.0.0.0:514        0.0.0.0:*           1064/syslogd

   • Watch the log:

     bash-3.1# tail -f /var/log/spa3102.log &

Set up line 1

You'll need line 1 working for testing. If you already have another extension set up that you'd rather use, then skip this section.

1. In FreePBX, add a SIP extension.
   1. Set the extension number, '100' in this example.
   2. Set a password, 'line1pass' in this example.
   3. You can configure the Display Name, Voicemail, etc. now if desired.
   4. "Submit" and "Apply Configuration Changes".
2. On the SPA3102, navigate to the 'Voice' tab, 'Line 1' sub-tab.
   1. Under "Proxy and Registration", set "Proxy" to your FreePBX's IP, 192.168.7.6. Also set both "Make Call Without Reg" and "Ans Call Without Reg" to Yes.
   2. Under "Subscriber Information" enter the extension number '100' as "User ID" and password 'line1pass' as "Password".
   3. Under "Dial Plan", set the "Dial Plan" to "([*x]x.)". This routes every number that begins with '*' or '0'-'9' to the PBX. See the dial plan documentation link in 'Quick Links' above.
   4. Click "Submit All Changes"
3. Still under the 'Voice' tab, navigate to the 'Regional' tab, and clear out all the *XX entries under 'Vertical Service Activation Codes'. With these in place, the feature codes will be intercepted by the SPA3102 and never make it to the PBX.
4. At the asterisk prompt now, verify that the SPA3102 has registered using

   bell*CLI> sip show peers
   Name/username              Host            Dyn Nat ACL Port     Status
   [...]
   100/100                    192.168.7.50     D   N      5060     OK (15 ms)
   5 sip peers [Monitored: 4 online, 1 offline Unmonitored: 0 online, 0 offline]

5. Try dialing an extension to make sure it's really working. If you set up voicemail, you can dial *97 to test.
6. If you don't see the extension registered or can't dial the PBX, check your settings and get this working before going on.

Configure the PSTN

Next step, the hard part, and the main goal of this tutorial: Configure the FXO port of the SPA3102.

Configure outgoing calls

We'll configure outgoing calls first.

1. In FreePBX, configure a new SIP trunk.
   1. Set the 'Trunk Name', in this example, 'pstn'. This is the trunk user name you chose in the 'Planning' section above.
   2. Set 'Maximum Channels' to '1', since there is only one PSTN line.
   3. Set the 'PEER Details' as follows (you can leave out comments preceded by ';'):

      canreinvite=no
      context=from-pstn
      host=192.168.7.50
      nat=no
      port=5061
      user=pstn   ; set the same user name as the trunk user name
      secret=pstnpass
      type=friend
      qualify=yes
      dtmfmode=rfc2833

   4. Set your "Dial Rules" if you like, or just leave blank.
   5. Click "Submit Changes", and "Apply Configuration Changes".
2. On the SPA3102 "Voice" tab, "PSTN Line" subtab,
   1. Under "Proxy and Registration",
      1. Set the "Proxy" to FreePBX's IP address
      2. Set "Make Call Without Reg" and "Ans Call Without Reg" to Yes

      

   2. Under "Subscriber Information", set "User ID" to the FreePBX 'Trunk Name' above, 'pstn', and the 'Password' to the FreePBX trunk's 'secret', 'pstnpass'.
   3. Click "Submit All Changes"
   4. Check the Asterisk command line and make sure the SPA3102 has registered:

      bell*CLI> sip show peers
      Name/username              Host            Dyn Nat ACL Port     Status
      [...]
      pstn/pstn                  192.168.7.50     D          5061     OK (7 ms)
      100/100                    192.168.7.50     D   N      5060     OK (7 ms)
      5 sip peers [Monitored: 4 online, 1 offline Unmonitored: 0 online, 0 offline]

   5. If you don't see the 'pstn/pstn' registration, go back and check your settings.
   6. Back in FreePBX, create a new Outbound Route.
      1. Set the route name, perhaps to 'pstn' or something more specific.
      2. Set the 'Dial Patterns', using the wizard, or creating your own custom patterns.
      3. Set the 'Trunk Sequence' to your new trunk, 'SIP/pstn'.
      4. Click 'Submit Changes' and "Apply Configuration Changes".
      5. Try making an outgoing PSTN call. If it doesn't work, check the output at the Asterisk command line and the Syslog.

Configure incoming calls

1. On the SPA3102 'Voice' Tab, 'PSTN Line' again,
   1. Scroll down to the 'PSTN-To-VoIP Gateway Setup' section.
      1. Set 'PSTN Ring Thru Line 1' to No
      2. Set 'PSTN Caller Default DP' to 2

      

   2. Scroll back up to 'Dial Plans', and set 'Dial Plan 2' to 'S0(<:01082113130>)', replacing '01082113130' with your inbound DID number. This routes all incoming calls to 01082113130@pbx.ip.ad.dr. See the dial plan documentation link in 'Quick Links' above.
2. On the FreePBX page, add an inbound route:
   1. 'Description' could be 'pstn'
   2. 'DID Number' should be exactly the same as the DID in your 'Dial Plan 2', '01082113130' in the example
   3. Scroll down to 'Set Destination' and set to extension '<100>' for now so we can test.
3. Call your PSTN DID from your cell, and cross your fingers that extension 100 rings!
4. If it didn't ring, look at the Asterisk command line output, along with the syslog.

Other configuration

The following configurations are recommended, and the first and second should be considered mandatory.

1. On the SPA3102 'Voice' tab, 'Sip' subtab, 'RTP Parameters' section, set 'RTP Packet Size' to '0.020' instead; check here for a discussion on this.
2. Change the SPA3102's user and admin passwords in the 'Voice' tab, 'System' sub-tab.
3. Add dialing rules for the trunk, if desired.
4. China: disconnect?
5. SPA3102, 'Voice', 'PSTN Line':
   1. 'Subscriber Information' section, set 'Display Name' to something like 'LOCAL PSTN CALL' to send this string as caller ID when no caller ID is provided by the PSTN.
   2. PSTN-To-VoIP Gateway Setup', set 'PSTN CID For VoIP CID' to Yes to support caller ID
   3. 'FXO Timer Values (sec)' section, set 'VoIP Answer Delay' to between 2 and 5 to give the caller ID signal a chance to come through
   4. 'PSTN Disconnect Detection' section, set 'Disconnect Tone' if you're not in the US, and the SPA3102 has difficulty detecting when the PSTN caller has hung up. See the 3am Systems link in the 'Quick Links' section above. In China, set the string to

      450@-45,450@-45;4(0.35/0.35/1+2)

6. SPA3102, 'Router', 'WAN Setup':
   1. Add a hostname and domain information. Why? Because it's cool.
   2. Add DNS information, especially if the WAN connection type is set to 'Static IP' rather than 'DHCP'.
   3. Add NTP servers so that the time is always synchronized. See http://www.pool.ntp.org/ for a list of servers in your region. DNS must be configured for this to work.

   

Troubleshooting and Debugging

I had all kinds of trouble getting this to work, even though it's a fairly simple setup. As all the other guides will tell you, it's best if you can start from defaults: clear out your trunk and in/outbound route definitions, reset the SPA3102 to factory defaults, and start from scratch, only changing the minimum number of settings. You can enable the fancier settings later on, but they really can mess you up if you try setting them too early without an initial working configuration.

After writing the main part of this article, I then went to repeat these instructions for a remote Sipura at the office. Outgoing calls worked fine, but incoming calls wouldn't pick up. I went through and checked all the SPA3102 settings very carefully, over and over, but nothing helped. Finally I went to the Asterisk side and did some SIP debugging over there. After a few hours of tracing the FreePBX dialplans and comparing them to my home setup, well, it turned out the difference was that I'd turned on NVFAX fax detection early on when I created the inbound route, and forgot all about it. This is an example of why you should keep it vanilla until you have a working configuration.

The way to debug is to log onto your Asterisk box, and use the Asterisk commandline:

bash-3.1# asterisk -vvvr
Asterisk 1.4.20-1 RPM by vc-rpms@voipconsulting.nl, Copyright (C) 1999 - 2008 Digium, Inc. and others.
[...]
bell*CLI>

Enable SIP debugging for your SPA3102:

bell*CLI> sip show peers
sip show peers
Name/username              Host            Dyn Nat ACL Port     Status
pstn/pstn                  192.168.7.50                5061     OK (11 ms)
100/100                    192.168.7.50     D   N      5060     OK (7 ms)
[...]
4 sip peers [Monitored: 4 online, 0 offline Unmonitored: 0 online, 0 offline]
bell*CLI> sip set debug peer pstn
sip set debug peer pstn
SIP Debugging Enabled for IP: 192.168.7.50:5061
bell*CLI>

In this script trace, we listed all peers using the 'sip show peers' command, where we saw
our trunk, 'pstn'. Then we enabled SIP packet tracing with 'sip set debug peer pstn'. This causes all SIP packets to be dumped out on the commandline. There may be copious output, so make sure the scrollback on your terminal software is set large enough to capture everything you need.

To stop the debugging, use 'sip set debug off'. The way I debug is to get everything ready to test, then turn on debugging the very moment before I initiate the call. Once the call fails, I then quickly turn off debugging so that all of the output is relevant.

A typical SIP session goes as follows. I will show the trace from a PSTN to VOIP call, with the SPA3102 initiating:

• SPA->*: INVITE sip:01082113130@192.168.7.6 SIP/2.0
  • The Sipura 'invites' Asterisk to initiate a call.
  • sip:01082113130@192.168.7.6 is the SIP URL on the asterisk side; the 010...3130 is matched with the 'DID' on the incoming route.
  • Asterisk should output a message like "Found peer 'pstn'" that shows it recognizes the Sipura.
• *->SPA: SIP/2.0 407 Proxy Authentication Required
  • This is only if you have passwords configured. I think. I set up two indentical Sipura and FreePBX configurations, but one was Trixbox (Asterisk 1.4), the other PIAF (Asterisk 1.6). Trixbox asks for Proxy Authentication, but PIAF doesn't. I don't know why, yet.
• SPA->*: ACK sip:01082113130@192.168.7.6 SIP/2.0
  • The Sipura acknowledges the '407 Proxy Auth Required' message.
• SPA->*: INVITE sip:01082113130@192.168.7.6 SIP/2.0
  • The Sipura sends a new invite; this time, there is a 'Proxy-Authorization' header with a username and MD5 password digest.
  • Again, Asterisk should output "Found peer 'pstn'"
  • It will also print some information about audio codecs, RTP ports, etc.
• *->SPA: SIP/2.0 100 Trying
  • If Asterisk didn't send a 407 Proxy Auth Required, this would have been next after the Sipura's initial INVITE message.
  • Asterisk notifies the Sipura that it is attempting to establish the call.
  • At this point, you should see the normal Asterisk dialplan tracing going on; you can follow along in your files if the problem lies here.
  • Asterisk prints out: "Executing [s@ivr-4:7] Answer [...] in new stack"; everything checks out, and it will begin the call.
• *->SPA: SIP/2.0 200 OK
  • Asterisk sends an 'OK' along with some data about its own RTP stream.
• SPA->*: ACK sip:01082113130@192.168.7.6 SIP/2.0
  • The Sipura acknowledges the OK message.
  • At this point, Asterisk and the Sipura have finished setting up the call, and should be exchanging voice data via the negotiated RTP stream.

If you have enabled Sipura debugging through your syslog, you should be able to see an abbreviated version of the Sipura's status.

And that's the basics for debugging. Call set up should go through this basic sequence, which is actually pretty simple, despite the large amount of output. Google is your friend here when deciphering deviations from this sequence.