chan_unistim

This is a channel driver for the UNISTIM (Unified Networks IP Stimulus) protocol. It provides UNISTIM server services that you can use to drive Nortel i2002, i2004, i2007 and i2050 phones.
The following features are supported:

• Transfer
• Threeway call
• Call Forward
• Message Waiting Indication (MWI)
• Distinctive ring
• Call History
• Send/Receive CallerID
• Redial
• (Dynamic) SoftKeys
• SendText()
• Music On Hold

Available on all version of Asterisk.

Install :

For Asterisk 1.6:
chan_unistim is included in the official Asterisk source tree

- Download the correct version at http://mlkj.net/UNISTIM/ :

For Asterisk 1.4.4 and higher:
wget http://mlkj.net/UNISTIM/chan_unistim-1.0.0.5d.tar.bz2
tar xvjf chan_unistim-1.0.0.5d.tar.bz2 && cd chan_unistim-1.0.0.5d
make && make install && make config

For Asterisk 1.4.0 to 1.4.3 :
wget http://mlkj.net/UNISTIM/chan_unistim-1.0.0.5b.tar.bz2
tar xvjf chan_unistim-1.0.0.5b.tar.bz2 && cd chan_unistim-1.0.0.5b
make && make install && make config

For Asterisk 1.2 :
wget http://www.mlkj.net/UNISTIM/chan_unistim-1.0.0.4c.tar.bz2
tar xvjf chan_unistim-1.0.0.4c.tar.bz2 && cd chan_unistim-1.0.0.4c
make && make install && make config

For Asterisk 1.0 :
wget http://www.mlkj.net/asterisk/chan_unistim-0.9.2.tar.bz2
tar xvjf chan_unistim-0.9.2.tar.bz2 && cd chan_unistim-0.9.2
make && make install && make config

- edit /etc/asterisk/unistim.conf
- (re)start asterisk

Install procedure for trixbox :

Update your system with yum -y update
Type asterisk -r
You should see something like Connected to Asterisk 1.2.9.1 svn rev XXXXXX currently running on asterisk1 (pid = 31770)
cd /usr/src
Replace XXXXXX with the svn rev number (obtained previously)
svn checkout http://svn.digium.com/svn/asterisk/branches/1.2 asterisk-1.2 --revision XXXXXX
(may take a while)
mv asterisk-1.2 asterisk
cd asterisk
make
ln -s /usr/src/asterisk/include/asterisk/ /usr/include/asterisk
Go to Install chapter for the rest of the procedure.

Trixbox 2.4:

yum install subversion gcc gcc-c++
cd /usr/src
svn checkout http://svn.digium.com/svn/asterisk/branches/1.4 asterisk
cd asterisk
./configure
make
ln -s /usr/src/asterisk/include/asterisk/ /usr/include/asterisk
cd ~
Go to Install chapter for the rest of the procedure.

Alternative for Trixbox 1.2 (also for 2.4):

a. Do 'yum -y update' to update all the packages.
b. Do 'yum -y install asterisk-devel' to install all the necessary asterisk headers
c. Follow the rest of the instructions in the INSTALL section.

How to configure i2004 phones :

- Power on the phone
- Wait for message "Nortel Networks"
- While the "Nortel Networks" splash is showing, quickly press each the four softkeys just below the LCD screen, in sequence from left to right. (you can do it real easily with your four fingers as if on a piano - one-two-three-four). This is known as 'swiping' a phone.
- If you see "Locating server", you weren't fast enough. Power off (or reboot the phone - see below) and try again
- DHCP : 0
- SET IP : a free ip on your network
- NETMSK / DEF GW : netmask and default gateway
- S1 IP : ip of the asterisk server
- S1 PORT : 5000
- S1 ACTION : 1
- S1 RETRY COUNT : 10
- S2 : same as S1

i2002 phones :

These phones have a smaller screen than the i2004. Takao Takahashi wrote a modified version with a better support of i2002.
ftp://ftp.voip-info.jp/asterisk/channels/1.4/chan_unistim-1.0.0.5c-i2002-r1.tar.gz
Follow the same installation procedure described previously.
Original page : http://voip.gapj.net/wiki2/index.php/Nortel_i2002

How to place a call :

The line=> entry in unistim.conf does not add an extension in asterisk by default. If you want to do that, add extension=line in your phone context.
if you have this entry on unistim.conf :
[violet]
device=006038abcdef
line => 102

then use exten => 2100,1,Dial(USTM/102@violet)

You can display a text with :
exten => 555,1,SendText(Sends text to client. Greetings)

Distinctive ring (since version 0.9.4) :

You need to append /r to the dial string.
The first digit must be from 0 to 7 (inclusive). It's the 'melody' selection.
The second digit (optional) must be from 0 to 3 (inclusive). It's the ring volume. 0 still produce a sound.
Select the ring style #1 and the default volume :
exten => 2100,1,Dial(USTM/102@violet/r1)
Select the ring style #4 with a very loud volume :
exten => 2100,1,Dial(USTM/102@violet/r43)

Country code (since version 0.9.4) :

You can use the following codes for country=
us fr au nl uk fi es jp no at nz tw cl se be sg il br hu lt pl za pt ee mx in de ch dk cn
(since version 1.0.0.0) If you want a correct ring, busy and congestion tone, you also need a valid entry in indications.conf and check if res_indications.so is loaded.
language= is also supported but it's only used by Asterisk (for more informations see Asterisk multi-language ). The end user interface of the phone will stay in english.

Bookmarks, Softkeys (since 1.0.0.2)

- Layout :
|--------------------|
|  5            2    |
|  4            1    |
|  3            0    |
- When the second letter of bookmark= is @, then the first character is used for positioning this entry
- If this option is omitted, the bookmark will be added to the next available sofkey
- Also work for linelabel (example : linelabel="5@Line 123")
- You can change a softkey programmatically (since 1.0.0.4) with SendText(@position@icon@label@extension) ex: SendText(@1@55@Stop Forwd@908)

Autoprovisioning (since 1.0.0.2)

This feature must only be used on a trusted network. It's very insecure : all unistim phones will be able to use your asterisk pbx.

autoprovisioning=yes

You must add an entry called [template]. Each new phones will be based on this profile.
You must set a least line=>. This value will be incremented when a new phone is registred.
device= must not be specified. By default, the phone will asks for a number. It will be added into the dialplan. Add extension=line for using the generated line number instead.
Example :
[general]
port=5000
autoprovisioning=yes

[template]
line => 100
bookmark=Support@123 ; Every phone will have a softkey Support

If a first phone have a mac = 006038abcdef, a new device named USTM/100@006038abcdef will be created.
If a second phone have a mac = 006038000000, it will be named USTM/101@006038000000 and so on.

autoprovisioning=tn

In this mode, new phones will ask for a tn, if this number match a tn= entry in a device, this phone will be mapped into.
Example:
[black]
tn=1234
line => 100

If a user enter TN 1234, the phone will be known as USTM/100@black.

History (since 1.0.0.4) :

- Use the two keys located in the middle of the Fixed feature keys row (on the bottom of the phone) to enter call history.
- By default, chan_unistim add any incoming and outgoing calls in files (/var/log/asterisk/unistimHistory). It can be a privacy issue, you can disable this feature by adding callhistory=0. If history files were created, you also need to delete them. callhistory=0 will NOT disable normal asterisk CDR logs.

Forward (since 1.0.0.4) :

- This feature requires chan_local (loaded by default)

Generic asterisk features (since 1.0.0.0)

You can use the following entries in unistim.conf
- Billing : accountcode amaflags
- Call Group : callgroup pickupgroup (untested)
- Music On Hold : musiconhold
- Language : language (see section Coutry Code)
- RTP NAT : nat (control ast_rtp_setnat, default = 0. Obscure behaviour)

Trunking :

It's not possible to connect a Nortel Succession/Meridian/BCM to Asterisk via chan_unistim. Use either E1/T1 trunks, or buy UTPS (UNISTIM Terminal Proxy Server) from Nortel.

Issues :

- As always, NAT can be tricky. If a phone is behind a NAT, you should port forward UDP 5000 (or change [general] port= in unistim.conf) and UDP 10000 (or change [yourphone] rtp_port=)
- Only one phone per public IP (multiple phones behind the same NAT don't work). Setup a VPN if you want to do that.
- If asterisk is behind a NAT, you must set [general] bindaddr= (0.9.2) or public_ip (0.9.4) with your public IP. If you don't do that or the bindaddr is invalid (or no longer valid, eg dynamic IP), phones should be able to display messages but will be
unable to send/receive RTP packets (no sound)
- Don't forget : this work is based entirely on a reverse engineering, so you may encounter compatibility issues. At this time, I know three ways to establish a RTP session. You can modify [yourphone] rtp_method= with 0, 1 , 2 or 3. 0 is the default method, should work. 1 can be used on new firmware (black i2004) and 2 on old violet i2004. 3 can be used on black i2004 with chrome.
- If you have difficulties, try unistim debug and set verbose 3 on the asterisk CLI. For extra debug, uncomment #define DUMP_PACKET 1 and recompile chan_unistim.
- In unistim.conf, don't add new configuration directive after line=> , except bookmark. It will be ignored.

---

Diagnostics mode on Nortel IP sets

All diagnostic functions begin with the 'lead sequence':

• mute key
• up arrow button
• down arrow button
• up arrow button
• down arrow button
• up arrow button
• mute key

Followed immediately by one of the following sequences:

• 0 key - Display Firmware hard version
• 1 key - RAM check
• 2 key - DTIC check
• 3 key - EEPROM check
• 4 key - Xmt, Rcv, Attenuation levels
• 5 key - TCM loop back test, between i2004 and CE equipment
• 6 key - unassigned
• 7 key - Display Firmware hard version
• 8 key - TCM BERT test
• 9 Release key - Reset set/power cycle
• * 2 key - RUDP on/off check. If RUDP is off, power cycle the set (9 Release).
• * 0 key - Display Firmware soft version

---

How to configure i2050 software phone

- The i2050 can be provisioned in unistim.conf just like a regular i2004.
- The trick is the MAC address, the i2050 generates it's own MAC address instead of using the PC's MAC address.
- To get the i2050 MAC address

• Just try to register the phone with asterisk, it'll fail and the phone's 'LCD' display will show it's MAC.
• Got to 'Nortel Networks > i2050 Software Phone> Diagnostics'. Scroll down to 'System Data (All Users)', see the row 'Hardware ID:' The MAC address is the middle block of 12 hex digits separate by dashes. Ignore the two 4 hex digit block before and after the 12 digit block.

- i2050 settings

• 'Communication server': set your server IP manually and set the port to 5000 (which corresponds to SL-100 in the drop down list).
• 'Server type' doesn't make any difference.

- Issues

• The phone works OK, but the soft key displays are messed up.

- Version tested Release 1.3 Version 1.0

---

chan_unistim Quick Tutorial

Thought I should share my experience with chan_unstim to help others who are having difficulties.

Install

- Follow the instructions at the top of this page.
- Copy unistim.conf from the chan_unistim-0.9.2 folder to /etc/asterisk

Configuration

- Edit /etc/asterisk/unistim.conf

• For each phone you want to provision, you need to add 1 section to unistim.conf. You can use the built-in [violet] section as a template.
• Cut and paste [violet], then edit the name between the brackets. For example to provision a phone called i2004, you should have a new section like this:

 [i2004]  
 device=[MAC Address]
 line => 100

• Substitute [MAC Address] with the MAC of the phone. On my i2004, it's a small sticker with 6 pairs of hex-digits stuck at the back of the phone. Copy everything excluding the space separating each digit pair. For the i2050 software phone, refer to the i2050 section elsewhere on this page to get the MAC address.
• Each phone should have a unique line number.

- Edit /etc/asterisk/extensions.conf

• For the purpose of this tutorial, I'll be using the standard extensions.conf installed by make samples.
• Locate the [default] section
• Add a new extension for our i2004, from the previous example, with a line like this:

 exten => 2100,1,Macro(stdexten,2100,USTM/100@i2004)

- (Optional) Server IP address binding issues (should be solved in 0.9.4)

• I've discovered that chan_unistim WILL NOT load if it doesn't get an IP address other than 127.0.0.1 when doing a reverse lookup of the hostname. A reverse lookup should work if your network has it's own local DNS. You know it failed if you see this on your Asterisk console: 'Unable to get IP address for <hostname>, UNISTIM disabled'.
• You can get around this problem in 2 ways:
• Uncomment the bindaddr line in unistim.conf and insert your host IP, OR
• Edit /etc/hosts
• Add a line similar to this to your /etc/hosts, replace 192.168.0.1 with your Asterisk server's IP and callmanager with the server's hostname

 192.168.0.1 callmanager

• Also make sure that the line in /etc/hosts that starts with 127.0.0.1, doesn't include the hostname.

- That's it. Restart asterisk. Power up your phone. In a short while you should see "Device 'i2004' successfuly registered" on your Asterisk console.

---

Automatically Locate Call Server via DHCP ('full DHCP")

If you're planning to deploy many i2004 phones, you can use this trick and set your phones to "DHCP (Full)" when installing them:
- Prerequisite

• ISC DHCP daemon (tested with 3.0.1-12)

-Steps

• Edit /etc/dhcpd.conf
• Add the following line near the top of the file

option nortel_ipt code 128 = string;

• Add the following line within the subnet for your phones

option nortel_ipt "Nortel-i2004-A,iii.iii.iii.iii:ppppp,aaa,rrr;iii.iii.iii.iii:ppppp,aaa,rrr."

Note:
iii.iii.iii.iii = IP address of call server
ppppp = Signaling port of call server
aaa = Action, currently must be 1
rrr = Retry count, any value. 10 is fine
The repetition of this whole section is for a second server, and is optional.

Take care to enter all the punctuation marks correctly. There's a colon (:) between the IP and the Port, commas (,) between the other fields, a period (.) at the end, and, to keep DHCP happy, a semi-colon (;) after the closing quote.

For example, to connect to call server at 172.16.1.1:5000, use:
option nortel_ipt "Nortel-i2004-A,172.16.1.1:5000,1,10;172.16.1.1:5000,1,10.";

• Restart dhcpd
• Configure phone to use Full DHCP and reboot the phone.

(I presume that "partial DHCP" would allow you to use a locally-picked address for the phone and a hard-coded address for the server, which might be good for a roaming phone, but I have not tried this).

Note: If you're using an older ISC DHCP such as that found on e.g., OpenBSD 4.0, omit the option type line (ending in String) and use this line in the subnet section:
option option-128 "Nortel-i2004-A,172.16.1.1:5000,1,10.";

---

See also:

• Nortel Phones
• Asterisk cmd sendtext

---