Documentation

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
  • 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. With described fature set available in Asterisk 11. For 1.8 and 10 can be downloaded as patches.

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:

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:

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

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:

– 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

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:

– 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:

– This feature requires chan_local (loaded by default)

Generic asterisk features:

You can use the following entries in unistim.conf
– Billing : accountcode amaflags
– Call Group : callgroup pickupgroup
– 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.

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.

 

 

  • Tamás Németh

    Hi,

    Don’t you know if it’s possible to call a number from an asterisk controlled nortel phone without pressing the “Call” button (i.e.: by just entering the numbers)?

    • There is much options here:
      – You can use option ‘sharpdial’ to end dial by pressing #
      – You can setup option ‘interdigit_timer’ and when time hits number shopuld be dialed
      – You can also build your dialplan to properly match dialed number, then when full number entered it should be dialed in same moment without waiting timeout or pressing additional keys

  • Tamás Németh

    I have a new problem, however:

    Using this new version of chan_unistim, my Nortel phones are malfunctioning 🙁 When I call them from another phone, they start sending RTP packets IMMEDIATELY even before picking up the receiver.

    This doesn’t cause problem if Ipick up the receiver, speak with the caller and then put it down, because in this case the RTP stream stop after the conversation.

    However, if I don’t pick up the receiver of the Nortel phone, then it keeps sending the RTP packets indefinitely, even after Asterisk informs it that the caller has put down the receiver. So, the Nortel phone remains in such a state that it keeps bombing the Asterisk server with RTP packet, and when I call it next time or I initiate a call from it, then unistim signaling still seems to work but there is no audio 🙁

    This is a huge problem, since an unanswered call on a Nortel phone renders it useless. This problem didn’t appear in earlier Asterisk versions (e.g. 1.8 or even 10), but those versions didn’t handle the dialplan and sharpdial or interdigit_timer options as I described previously. What do you think? Is it a feature or a bug? And if it’s a bug, where can i report it?

    Thank you in advance.

    • This is definetly bug. You can describe problem to me directly (to email) or report to Digium bugtracker, actually I need CLI comands output: ‘unistim show info’, ‘unistim show devices’ and output of moment when receiver opicked up with ‘unistim set debug on’. If this output wouldnt have device infomation, I need to know your exact model phone (from label below) and if possible network capture in the moment when receiver picked up and down.

  • ChaKmaN

    Hi, how i can enable the pickup call using chan_unistim?

    • Hello, do you mead pickup using pickupgroup option or direct pickup by dialpan application? Pickupgroup is channel independent and must work as configured in features.conf

      • ChaKmaN

        pickup using pickupgroup, for pickup and incoming call from the extension

        • Have you tried to specify pickupgroup/callgroup for unistim device? What happends when you try to use pickup? This option read by chan_unistim and implemented in asterisk core.

          • ChaKmaN

            yes i set the pickupgroup/callgroup
            i get Nothing to Pick up

          • ChaKmaN

            thanks igor is working!
            pickupgroup = 15
            callgroup = 15
            line => 1234
            line => 1234

  • Pert Wat

    Dear Igor,
    I tried to contact you about two years ago, but no reply. chan unistim as compiled on 11.20 (11.23 starts to break because ooh323 doesn’t connect to legacy phone systems, whereas the discontinued h323 does, so we need the earlier 11.20) on a raspberry pi, and banana, and orange, never closes UDP ports. I presumed this was an issue with the unknown cpu type, but no. I’ve compiled it correctly with all modern dependencies on a genuine intel P4 system… Same problem. Every call, or operation involving RTP ports leaves them stuck indefinitely on the host system. I have a manually-set narrow udp range, but the asterisk default of nearly 65543 ports probably means most, no else sees this behaviour between reboots. I did a force into the current stable 11.23 as from Digium to make chan_h323 compile, thinking chan_unistim would be fixed, but it’s not. It still leaves udp ports open, with data sitting in their rx or tx buffers.

    Is there a way to fix this? Or why is this major bug still in the accepted current long term stability build from Digium? I’d be happy to modify the chan_unistim.c source if it’s a matter of some changes…

    Thanks for your time.
    This is truly frustrating, as the Nortel sets are immensely better than any SIP set on the market. (Perhaps barring the aastra ones built for nortel?)

    • Hi Pert. Sorry, but I am not able to find any of your prev messages. There is two short questions about your issue:
      1. Have you created issue at asterisk.org JIRA or have information about similar issue, that already exists there?
      2. What commands do you use to check what RTP ports are left open?

      • Pert Wat

        Hi Igor,
        1) I initially didn’t create one on asterisk.org as I was on a pi, and didn’t think it would be taken seriously. Now duplicated on x86 I will.
        2) Using simply netstat -l (for listening) and the port range as defined in rtp.conf (I use 31000 31099 for example), calls grab a pair, then fill up, two by to. At 100 ports, it runs out soon, and nothing then gets a udp port. eg:

        udp 4288 0 x.x:31028 *:*
        udp 0 0 x.x:31029 *:*
        udp 12864 0 x.x:31038 *:*
        udp 0 0 x.x:31039 *:*
        udp 4288 0 x.x:31072 *:*
        udp 0 0 x.x:31073 *:*
        udp 12864 0 x.x:31078 *:*
        udp 0 0 x.x:31079 *:*
        udp 4288 0 x.x:31090 *:*
        udp 0 0 x.x:31091 *:*

        I made 5 test calls.

        • Pert Wat

          I just compiled the latest Asterisk 14 release. Same thing: UDP ports are left hanging around until asterisk restart. So it’s not an ARM issue.

          This is a xubuntu Debian stable standard machine too. Nothing out of the ordinary. I’m amazed nobody else has seen this. I guess people leave port usage at 65534 available and then don’t have to know. .
          Unless this is a phone firmware issue. But I have tried this on three versions of the 2002i. Purple, black, phase 2…Odd.

  • Pert Wat

    Igor,
    I have been trying to contact you for years via published e-mail addressesd on your own site, never with a reply. Would you please check their respective spam folders? I do not use public (free) e-mail providers, and am usually dumped into a spam folder I am guessing. Thank you.

    • Hi. I have received your email, that was sent to igorg@igorg.ru and find other email in gmail spam folder. I’ll reply to you by email at the beginning of the week.

  • MarK

    Hi Igor,

    I am using some Nortel i2002 phone that are connected and can call each other or any sip client. but as soon as I dial an external number I have

    WARNING[4439][C-00000001] pbx.c: Channel ‘USTM/10@10-0x94b2cd0’ sent to invalid extension but no invalid handler: context,exten,priority=default,0XXXXXXX,1

    I can recive calls and call form a sip phone.

    Could you point me in the right direction I am a little bit lost ?

    thanks

    • It is not possible to definitely tell what is the reason for this without having [default] context content. But:
      1) Most probably you have no external numbers pattern in your default context
      2) It is really bad idea having external number dialing in default context
      3) In some situation pattern with callerid match (_0XXXXXXX/_XXX) wont work as expected with chan_unistim

      • Mark

        Thanks very much !
        Looked for the context of my sip phones, used it instead of default and it worked.
        Thanks a lot for your help Igor, I have been trying to understand it for a very long time…