Configuring Cisco 79xx phones with Asterisk
This page documents how you configure a Cisco phone with Asterisk.
By default most Cisco VoIP phones come configured for Call Manager, which uses the 'Skinny' protocol -
SCCP.
Asterisk has 2 implementations for this channel (required for the 7910/20):
- Skinny? implements a very basic set of telephone functions and ships with asterisk.
- SCCP has implimented more of the SCCP protocol, so some class 5 features (hold, transer, forward, etc) should work.
However, the 7940/60 can be reconfigured to use
SIP (recommended for use with Asterisk):
http://cisco.com/en/US/tech/tk652/tk701/technologies_tech_note09186a0080094584.shtml Apparently the 7905/12 can also be reconfigured to use SIP:
"While the 7905 doesn't have Speakerphone, its SIP image has by far the
best user interface of all cisco SIP phones, plus it's nicely compact, and
the display even has a higher resolution than that of the 7960"
7912 is the same as the 7905, but with a built-in ethernet switch.
With the right
Cable, 79xx series phones can use standard POE injectors.
Cisco 7960 SIP Phone Software Images
Cisco's
SIP phone software images including versions 3.0, 4.4, 5.3, 6.x and 7.x work well with
Asterisk. Features have been implemented and caveats (earlier problems) corrected with each release. The v5.x and v6.x images have incorporated software security feature that make it impossible to revert back to earlier images. Version 6.0 SIP image has been very stable for many Asterisk users. The new version 7.x images are largely untested, but feature mainly bug fixes, not new features.
The v6.0 software has implemented:
- Alert-Info (play internal ring tones based on Alert-Info within the SIP header)
- Auto Answer (2-way paging conversation without picking up handset)
- DHCP? Option 66
- Directory Enhancements (user can add/change/delete entries in Personal Directory)
- DSP (new digital signal processor)
- DSP Alarms, Debugging Aids, and Logging (help diagnose problems)
- Enhanced Tone and Ring Support (support for more complex tones and ringing patterns)
- Hot Line / Speeddials (each line button can be programmed to act as a speeddial button)
- Local Call Forwarding (redirects incoming calls to another extension/URL)
- Message Waiting Stutter Tone
- Multiple Call Appearance (receptionist style, all lines have the same extension)
- Outbound Proxy Redesign (improves use of outbound proxy based on multiple DNS records)
- SIP Call Statistics (call statistics sent in BYE / 200 OK messages)
- Resolved Caveats (several previously documented problems have been resolved)
v7.0 and up:
- A new design approach is used to store the existing software base in the Cisco 7940 and Cisco 7960 telephones. The new approach utilizes a "run from flash" design to use the Flash and RAM memory available more efficiently.
- Bugfix: Media takes 0.4 sec to be set up (finally...)
- Bugfix: HTTP requests fail, sysbufs get hung
- Numerous other bug fixes, too many to mention (see release notes below)
Cisco SIP IP Phone Administrator Guide, Versions 6.x and 7.x
http://cisco.com/en/US/products/sw/voicesw/ps2156/products_administration_guide_book09186a00801d1978.html v7.0 Release Notes:
http://www.cisco.com/en/US/products/sw/voicesw/ps2156/prod_release_note09186a00802295b7.html v7.1 Release Notes:
http://www.cisco.com/en/US/products/sw/voicesw/ps2156/prod_release_note09186a008022c65e.html v7.2 Release Notes:
http://www.cisco.com/en/US/products/sw/voicesw/ps2156/prod_release_note09186a008029b053.html Latest Version: v7.3 Release Notes:
http://www.cisco.com/en/US/products/sw/voicesw/ps2156/prod_release_note09186a0080335cdc.html Note: Cisco software images are only available from Cisco's web site and are protected by copyright laws. Access to their web site requires an account be established. The easiest way to do that is to purchase a
Maintenance Agreement from Cisco for approximately $8 per year (US).
Software Upgrade Requirements
All software images are upgraded through a TFTP
? server at your location. If you don't have one, several free Unix and Windows packages are available via the Internet. The specific instructions as to exactly how to accomplish the upgrade should be reviewed from Cisco's web site as the exact steps (and possible backout steps) may change from version to version.
The TFTP server directory must include the following files as a minimium (most are upper/lower case sensitive):
- OS79XX.TXT (The content of this file is solely the software image filename stripped of the .bin, i.e. P0S3-06-1-00)(Contains the universal application loader image in 7.x)
Note:(The 7.1 image upload needs to be spelled P003-07-1-00 in the OS79XX.TXT and P0S3-07-1-00 in the SIPDefault.cnf)
- P003-xx-y-zz.bin (Nonsecure universal application loader for upgrades from pre-5.x images.)
- P003-xx-y-zz.sbn (Secure universal application loader for upgrades from images 5.x or later.)
- P0a3-xx-y-zz.loads (File that contains the universal application loader and application image, where "a" represents the protocol of the application image loads file 0-SCCP, S-SIP, M-MGCP.)
- P0a3-xx-y-zz.sb2 (Application firmware image, where "a" represents the application firmware image.)
- SIPDefault.cnf (Contains generic parameters for all Cisco phones at your location)
- SIP00036BAAD139.cnf (Where the last 12 hex digits is the MAC address of your Cisco phone) Sample php script to create the cnf file.
In addition, the following optional files may also be present in the TFTP directory:
- dialplan.xml (contains entries like "9,1...." that cause the phone to automatically dial after a match)
- RINGLIST.DAT (a list of ringing tones to be downloaded, like ringer1.pcm)
- ringer1.pcm (a ringing tone to be downloaded to the phone)
See also:
John Todd's examples See
reboot.pl. A perl script to handle remote rebooting of the 79xx class phones (useful for multiple-phone upgrades). Requires Net::Telnet.
So you blew up your 7940/7960 trying to load new firmware
Logo Displayed on 79XX Screen
A non-Cisco logo can be displayed on the 79XX screen. Cisco's documentation suggests the logo be a Windows Bitmap form (*.BMP) with 256 colors and 90 x 56 pixels in size. Only two colors are displayed, black or white. The image must be saved in greyscale format. In GIMP it is Image->Mode->Greyscale. If the size of the logo is larger then this specification, the phone will rescale to fit (within reason). Microsoft Paint and many other applications can be used to create the logo image.
Once the image is created, place the *.BMP file on any web site available to you (suggest /asterisk/mylogo.bmp, where the /asterisk directory is not freely advertised).
Modify the SIPDefault.cnt file entry to point to the web site:
logo_url: "http://www.mywebserver.com/asterisk/logo.bmp"
and reboot the Cisco phone.
Note: the smaller the logo file, the quicker it will load. Typcial logo files should be around 10k bytes.
Company Telephone Directory
The 79XX phones have four panel keys labeled as Messages, Services, Directories, and Settings. The Directory key can be programmed to view your company's telephone directory by displaying Names and Telephone Numbers that are stored on any web site available to you.
Modify the SIPDefault.cnf file entry to point to the web site:
directory_url: "http://www.mywebserver.com/asterisk/directory.html"
The phone must be rebooted in order to read the above file.
The web site file /asterisk/directory.html should include xml entries like:
<CiscoIPPhoneDirectory>
<Title>IP Telephony Directory</Title>
<Prompt>People reachable via VoIP</Prompt>
<DirectoryEntry>
<Name>Rich</Name>
<Telephone>3000</Telephone>
</DirectoryEntry>
<DirectoryEntry>
<Name>Todd</Name>
<Telephone>3001</Telephone>
</DirectoryEntry>
<DirectoryEntry>
</CiscoIPPhoneDirectory>
Note: Each time a user presses the Directory key and accesses the External Directory option from the menu, the phone will access the contents of this html file and display whatever text entries included in it. Therefore, changes to the html file do not require any futher rebooting of the Cisco phone. Cisco has published Cisco IP Phone Services Application Development Notes (CMXML_App_Guide.pdf ) that future explains options and file contents.
Asterisk Cisco 79XX XML Services
Services Button
The 79XX phones have four panel keys labeled as Messages, Services, Directories, and Settings. The Services key can be programmed to execute CGI scripts that are stored on any web site available to you. The CGI scripts can perform any action that you are capable of programming. None are provided by Cisco.
Modify the SIPDefault.cnf file entry to point to the web site:
services_url: "http://www.mywebserver.com/asterisk/myscriptpage.html"
The phone must be rebooted in order to read the above file.
The web site file /asterisk/myscriptpage.html should include entries for each service that you plan to make available to your phone users. The exact content and syntax is also documented in the Cisco IP Phone Services Application Development Notes (CMXML_App_Guide.pdf ) noted above.
Messages Button
When the Messages button is pressed, you can cause the phone to directly dial an extension in your asterisk dialplan. Just configure the phone as:
messages_uri: "<extension>" where <extension> is what you wish the phone to dial when the Messages button is pressed. You can then catch the call in either a standard VoiceMailMain() invocation a la
exten => _42,1,VoiceMailMain() or, be cute and bypass entry of mailbox number and password a la
exten => _42,1,VoiceMailMain(s<mbox num>) Asterisk Cisco 79XX XML Services
Ringtones
http://www.cisco.com/en/US/products/sw/voicesw/ps2156/products_administration_guide_chapter09186a0080087511.html#1042487 The Cisco SIP IP phone ships with two ring types: Chirp1 and Chirp2. By
default, your ring type options will be those two choices. However,
using the RINGLIST.DAT file, you can customize the ring types that are
available to the Cisco SIP IP phone users.
Step 1
Create a pulse code modulation (PCM) file of the desired ring
types and store the PCM files in the root directory of your TFTP server.
PCM files must contain no header information and comply with the
following format guidelines:
8000 Hz sampling rate
8 bits per sample
ulaw compression
240 - 16080 samples long ( 0.03 sec - 2.01 sec )
For example, to use sox to generate the tones, use
sox -t wav in.wav -t raw -r 8000 -U -b -c 1 - resample -ql out.raw
Step 2
Using a ASCII editor, open the RINGLIST.DAT file and for each
of the ring types you are adding, specify the name as you want it to
display on the Ring Type menu, press Tab, and then specify the filename
of the ring type. For example, the format of a pointer in your
RINGLIST.DAT file should appear similar to the following:
Ring Type 1 ringer1.pcm
Step 3
After defining pointers for each of the ring types you are
adding, save your modifications and close the RINGLIST.DAT file.
Controlling ring tones from Asterisk
By setting the
Asterisk variable ALERT_INFO before you call
Dial, Asterisk will add ringer tone info to the SIP invite that is sent to the phone.
exten => 3010,1,SetVar(ALERT_INFO=Bellcore-dr1) ; selects Ringer exten => 3010,2,Dial(SIP/3010,15)
Available ring tones by default
Bellcore-BusyVerify Bellcore-Stutter Bellcore-MsgWaiting Bellcore-dr1 Bellcore-dr2 Bellcore-dr3 Bellcore-dr4 Bellcore-dr5
DialPlan to allow dialing * and #
If you wish to have the hash and asterisk go through to asterisk, then use the following in DIALPLAN.XML
<DIALTEMPLATE> <TEMPLATE MATCH="#..." Timeout="5" User="Phone" /> <TEMPLATE MATCH="*" Timeout="5" User="Phone" /> </DIALTEMPLATE>
Asterisk Configuration File Examples
sip.conf
[3014]
type=friend ; This device takes and makes calls
host=dynamic ; This host is not on the same IP addr every time
username=3014 ; Username programmed into Cisco phone
secret=mypassword ; Password for device
context=from-sip ; Inbound calls from this phone go to this context
nat=yes ; nat=yes if this phone is behind a NAT box or firewall
callgroup=2 ; the group to which this phone belongs for *8 phone ringing pickup
pickupgroup=2 ; the pickup group allowed from this phone when *8 is dialed
mailbox=3014 ; Activate the message waiting light if this voicemailbox has messages in it
extensions.conf
exten => 3014,1,Dial(SIP/3014,15,t) ; see "show application dial" for options and formats
exten => 3014,2,Voicemail2(u3014) ; go to Voicemail2 if phone is "U"nanswered
exten => 3014,102,Voicemail2(b3014) ; go to Voicemail2 if phone is "B"usy
exten => 3014,103,Hangup ; and then hangup.
voicemail.conf
format=gsm
servermail=mail.myserver.com
attach=no
maxmessage=120
maxsilence=10
pbxskip=yes
fromstring=NPI VM
emailbody=\nVM for x ${VM_MAILBOX} from ${VM_CALLERID} dur: ${VM_DUR} \n
[default]
; Note: following sends a text message to a cell phone telling me someone left a voicemail
3014 => 3014,FirstName LastName,4015719329@vtext.com
Troubleshooting Phone Registration
From the asterisk command line, execute "sip show peers" and "sip show users" to display the current status of the Cisco phone. If no entries appear in the list for this phone, then review the "username=3014" and "secret=mypassword" in sip.conf to ensure they match the entries programmed into the Cisco phone.
*CLI> sip show peers Name/username Host Mask Port Status 3014/3014 67.11.89.61 (D) 255.255.255.255 5060 Unmonitored *CLI> sip show users Username Secret Authen Def.Context A/C 3014 mypassword md5,plaintext from-sip No
Troubleshooting Cisco Phone
The Cisco 79XX phones support telnet. To diagnose problems with the Company Directory function noted above (as an example), telnet to the phone's IP address using the login password provided in the SIP00036BAAD139.cnf file noted above. For example, to diagnose a possible http problem, do the following:
SIP Phone> debug http
Enabling bug logging on this terminal - use 'tty mon 0' to disable
debugs: http timestamp
SIP Phone> [11:39:39] Connect2WWWIPPort called IpAddr[0], port[80], hostName[www.mydomain.com]
[11:39:39] Connect2WWWIPPort Sending Request to IpAddr[207.212.93.75], port[80]
[11:39:39] HTTP RECV (ACK CMD)
[11:39:39] HTTP RECV (OPEN CMD)
[11:39:39]
HTTP Send [178] Bytes of Data
Data Packet is:
===============
GET /asterisk/directory.html?name=SIP00036BC38B88 HTTP/1.1
User-Agent: Allegro-Software-WebClient/3.10b1
Host: www.mydomain.com
Connection: Close
(Note: You can also reset the 7960 by pressing *+6+settings at the same time.)
(Note: additional technical data was displayed but it was clipped from this documentation.)
Check out:
http://www.cisco.com/en/US/products/sw/voicesw/ps2156/products_administration_guide_chapter09186a00801d1988.html ^ This site has all the information you will need to help you work with the phone in the telnet prompt! See also: