Introduction

Linksys makes a popular line of ATA devices (Analog Terminal Adapters) which allow connection of traditional analog phones to a SIP network.  Two of these devices, the SPA2102 and SPA3102 are directly supported by Sipx, and appear on the device menu as ata2101 and ata3102 respectively.
These devices can be used for a variety of purposes, such as to add a special-purpose analog phone to a SIP system, to implement an external gateway to analog phone lines for backup (SPA3102 only, see Linksys Sipura FXS Gateways ), or, in residential-type applications to connect a set of analog phone jacks to a SIP service.

The Sipx implementation for these devices is complete, allowing all relevant parameters to be managed in the Sipx web interface.  However, at the time of this writing, there are some bugs in the implementation.  See issues  XX-7869, XX-7534, XX-7533, XX-9809, XX-9091 in the SIPFoundry JIRA bug tracking system.

This document includes general information and some workarounds for these issues, until they are fixed.

Change of models

In May 2012 Cisco/Linksys stopped manufacturing the SPA2102 device (they still make the SPA3102).  They sell a new model, the SPA122, which is not currently supported by Sipx, but which can be used with a few minor workarounds because the profile that Sipx generates for the ata2102 device is sufficiently compatible with the new device.  Making it work primarily requires some minor changes to the provisioning sequence.  See notes below under the relevant sections.

Provisioning

Profile

Provisioning on these ATA devices works as follows (assuming you have a retail version of the device, rather than one which has been bulk-purchased and custom configured).  

From the factory, the device is configured to look for a default TFTP server based on a value provided by DHCP.  If you use the default ISO install of Sipx and let it provide DHCP, this will happen automatically.  It then looks for an initial configuration file in the root of the TFTP directory with the name “model.cfg”, where “model” is the model name of the device in lower case, such as “spa2102.cfg” or “spa3102.cfg”.  

Those files in turn contain a provisioning rule that tells the device to look for a device-specific configuration file at the root of the TFTP server, whose filename starts with spa, followed by the MAC address of the device followed by “.cfg”, for example “spa000E08D3244A.cfg”.  Note that the filename, which is generated by SIpx when you send the profile for the device, has all of the letters in the MAC address as upper case.  On versions before 4.2.1, there were problems relating to this (see XX-7534).

This device-specific config file contains the full set of configurable options for the device, which are generated from the values visible in the Sipx web interface for the device.

Like all Sipx device profiles, these values consist of (1) the default values that Sipx ships with, with (2) any modifications to those defaults that were made in the device profile in the “Phone Group” that contains this device, plus (3) any modifications made in the device itself after creating it in the Sipx web interface.  The Linksys device loads this profile, and reboots itself, leaving it ready to operate.

For SPA122

By default, the SPA122 will look for a file called "spa122.cfg" in the root of the TFTP directory.  That file does not exist by default in Sipx, so it must be created manually.  To do this, go to the directory /var/sipxdata/configserver/phone/profile/tftproot and copy the file "spa2102.cfg" as "spa122.cfg".  This only needs to be done once per server to support any number of SPA122 devices.

If you prefer not to make changes on the server, you can instead change the provisioning rule on the SPA122 device.  In the web interface of the device, go to the page Provisioning under the Voice section.  The field Provisioning Rule is set by default to "/spa$PSN.cfg" (which is what tells it to load the file spa122.cfg).  Change this field to the string "/spa$MAU.cfg" and that will instruct the device to directly load the profile generated by Sipx (the macro $MAU gets expanded to the device's MAC address with letters in upper case, which is how Sipx names the profile).  This would need to be done manually on each SPA122 device.

Firmware

If desired, the device can also be configured to automatically update its firmware.  To do so on Sipx, place an appropriate firmware file into the Sipx TFTP root directory (/var/sipxdata/configserver/phone/profile/tftproot/).  For example, the current firmware at the time of this writing (version 5.2.10) might be in a file named spa2102-5-2-10.bin.

To instruct the device to check its firmware and update if necessary, you must enter a value in the field Upgrade Rule on the screen Firmware_Upgrade.  Normally you would do this in the phone group settings for the device, so that all devices would inherit this behavior, although it is advisable to first test it by modifying the setting for one device.

The value in this field could be a complex script that returns a TFTP URL based on various conditions, but the simplest is to just enter a plain TFTP URL for the firmware file in the form tftp://<server>/<filename>.  

You can explicitly specify the server (“tftp://sipx.mycompany.com/spa2102-5-2-10.bin”), or potentially you could use one of the Linksys macro values $SERV or $SERVIP for a potentially more robust configuration (“tftp://$SERV/spa2102-5-2-10.bin”).  I have not tested using these macros.

For more information, see the Cisco Small Business IP Telephony Provisioning Guide.

Provisioning Workflow

An approach that seems to work well for bringing new ATA devices into service is as follows:

1. Use the default setting to allow the SPA device to receive its addresses via DHCP. You can optionally configure your DHCP server to give the device a known IP address, or just let it get one at random.   If you choose random, and want to get access to the device’s web interface for some reason, see the troubleshooting section below.
2. In the Sipx web interface, create a user (if necessary) then create the device by using the Add New Phone pulldown, and selecting "Linksys ata2102" or "Linksys ata3102" (for the SPA122 device, choose "Linksys ata2102"). Enter the "Serial Number" (i.e MAC address) which is shown on a sticker on the device.  Attach the user to one of the lines on the device.  If you are using a VLAN for your phone/ATA devices, be sure to enable VLANs and configure the VLAN ID in the profile on the page VLAN_Settings. Send the profile for the device. 
3. Plug in the ATA device to the network, ensuring that it is on a port capable of reaching the Sipx server via TFTP.  If using tagged or static VLANs, ensure that the the port you are plugged into to is configured to support your phone VLAN.
4. Power on the device.  It should load its profile from Sipx and restart itself.  If you have configured it to also provision firmware updates, it may also load a new firmware version and restart again.  DO NOT interrupt this process (which takes up to 2 minutes on my system). When it’s complete, you should see 3 steady lights on the device, and it should offer you a dial tone when you attach a phone and go offhook.  You should be able to see the device’s registration on the Sipx Diagnostics / Registration screen. 
5. If things don’t work as expected, see Troubleshooting below.

Message Waiting Indicator (MWI)

The Linksys devices are capable of alerting the end user when they have unheard messages in their voicemail inboxes.  The alerts occur in two forms:

Audible (MWI) - When the user picks up their phone, they hear a brief “stutter” in the dial tone if a message is waiting.

Visual (VMWI) - Some analog phones are equipped to receive a signal over its analog connection to the ATA device, which indicates that it should enable or disable its Message Waiting light.  This behavior seems to vary a lot between models and brands of phones, but there does not seem to be any way of configuring it--it either works or it doesn't.

Message Waiting Indication is is not enabled by default in the current Sipx default profile for these devices. To enable it, make the following changes in your configuration (either at the Phone or Phone Group level): 

1. On page Control_Timer_Values__sec_, set field VMWI Refresh Intvl to "30" 
2. For a particular Line, on page Supplementary Service Settings set the field Message Waiting to "enabled" 
3. For a particular Line, on page Proxy and Registration, set the field Voice Mail Server set to the string "$USER@$PROXY".   This literal string makes use of the built in macros on the Linksys Device "$USER" and "$PROXY" to create a properly formatted value that should work for any user, and which can be placed in the Phone Group*.  Alternatively you could enter a literal value, such as “1001@mycompany.com” or “1001@192.168.100.1”.

*NOTE: there is currently a bug (XX-9091) that keeps this Voice Mail Server value from being settable in the Phone Group.  The bug report indicates a workaround.

Troubleshooting

If there are problems with the device successfully registering, you may want to check to see if TFTP is working for the profile.  See this message for info on enabling and viewing TFTP logging.  

You can also get a variety of information from the ATA device through its phone interface, as explained.  See this page for information on phone commands, a copy of which is reproduced below:
To enter this command mode, power up the ATA device, and plug a phone into one of its Line jacks.  Pick up the phone and enter **** on the keypad.   You should hear it speak  a greeting, then it will wait for a command.  Enter a command code as shown above, followed by #.

Accessing Device’s Web Interface

 The ATA devices each include both an “Ethernet” (LAN) and “Internet (WAN) port.  You can connect to the web interface of the device through either one, but the technique is different.

• LAN Port - In this mode, you would run a cable from the ethernet jack on your computer to the LAN port on the ATA device.  By default, the ATA device should automatically supply your computer an address via its built-in DHCP server.  To find out the address assigned to the ATA device, first plug in a telephone to one of the Line jacks, pick up the phone, and press ****.  If you then press “210” it will speak the current LAN IP address.  You can type in this IP address into a web browser and access the web interface.
• WAN Port - In this mode, the ATA device would be connected to an ethernet switch through its WAN port, and your workstation would also be connected to a switch port on that same switch, or elsewhere on the network that can connect to it.  To find out the address assigned to the ATA device, first plug in a telephone to one of the Line jacks, pick up the phone, and press ****.  If you then press “110” it will speak the current WAN IP address (which, by default, it should have picked up via DHCP).  Remember this address.

By default, web access is disabled through the WAN or “Internet” port, but if you want to get access this way, you can enable this through the phone by typing ***, then press *7932#, then *1#, then *1.  After that, you can enter the IP address from the previous step into a web browser and access the web interface. 

NOTE: If you want to permanently enable web access through the Internet port, be sure to set the field Enable WAN Web Server to “enabled” in the page Remote Management of the device’s configuration in Sipx.  You may also want to enable admin access and set up user and admin passwords for the web interface on the page System Configuration.  If using the phone interface and a password is set, you can enter the password when requested using the phone DTMF keys that correspond with the letters in your password (so be sure to use only letters or numbers).

Initiating Device Resync or Reboot

You can initiate a manual restart or a reload of the profile on a Linksys ATA device by entering appropriate URLs for the device through a web browser.  If an administrative password has been set, you will be prompted to enter the username (usually “admin”) and password (see note above to set it, default should be "admin") before the request will take effect.  Assuming an IP address for the ATA device of "192.168.1.100, the URLs are:

Reboot:

http://192.168.1.100/admin/reboot

Resync:

http://192.168.1.100/admin/resync

You can optionally include a URL of a specific profile to resync to (although this rarely makes sense in a Sipx deployment), for example:

http://192.168.1.100/admin/resync?tftp://192.168.1.200/basic.txt

If you omit the URL parameter, the device will follow whatever provisioning settings are currently configured on the device.

You can also initiate reboot, or reset the ATA device to factory defaults through the telephone interface, using the commands shown in the table above.