Desk Phone Module for Asterisk (DPMA)

Overview

There are myriad VoIP phones on the market that people use with Asterisk. None of them are built specifically for Asterisk, so they don't take any particular advantage of Asterisk's applications. And, each one of them is too difficult to use.

Sangoma has designed phones to provide a superior user experience for everyone; from the person making the calls, to the person setting up the phone. Phones aren't hard, like everyone thinks they are, and they're not dumb terminals; instead, they're simple and smart.

A Sangoma phone can communicate with Asterisk, or with any other SIP-based system. In this respect, a Sangoma phone is somewhat like other SIP phones. In order to provide more than just the capabilities of a regular SIP phone, Sangoma makes available the Desk Phone Module for Asterisk (DPMA). DPMA is a binary Asterisk module that provides a means of secure communication between Sangoma phones and Asterisk. This secure means provided by DPMA is used by Asterisk to provision and manage Sangoma phones, and by the phones to directly access Asterisk's internals - leading to a richer set of phone applications, and happier users.

DPMA: What is it?

DPMA is a binary Asterisk module that provides a means of secure communication between Sangoma phones and Asterisk. This secure means is used to provision and manage the phones and to provide direct access to Asterisk's internal applications. DPMA is not required to use Sangoma phones, but offers a number of significant advantages. A single, free license is required for each Asterisk system running DPMA. For more information on installation and configuration, please see the support pages for Sangoma phones.

DPMA Compatibility and Requirements

DPMA is compatible with Asterisk 19, 18, 17, 16, 15, 14, 13, 12, 11, the open source Certified Asterisk releases of Asterisk 1.8, beginning with the asterisk-1.8.11-cert1 release, and with the "-digiumphones" branch of Asterisk 10, beginning with Asterisk 10.5.0. DPMA is not compatible with any other open source version of Asterisk.

Because Asterisk 10, 12, 14, and 15 have reached EOL status, new releases of DPMA are not being made against them. Users should consider upgrading to a supported version of Asterisk.

The features outlined here are compatible with the latest releases of Asterisk, and the latest Sangoma phone firmware releases.

Requirements

1 - Presence function within DPMA requires the PRESENCE_STATE Asterisk function. If the function is not available, you will likely see a question-mark person icon on the phone's primary line and you will see a WARNING on the Asterisk CLI.

[May 23 05:01:26] WARNING[2554] presencestate.c:181 ast_presence_state_helper: No provider found for label CustomPresence

2 - DPMA requires both Avahi client and daemon to be installed on your distribution. Most distributions are already provided with these.

Attempting to load DPMA binary modules on a system without the Avahi client libraries installed will present the following Asterisk ERROR message:

Avahi Not Present Error

[May 23 05:01:26] WARNING[2554] loader.c: Error loading module 'res_digium_phone.so': libavahi-client.so.3: cannot open shared object file: No such file or directory
[May 23 05:01:26] WARNING[2554] loader.c: Module 'res_digium_phone.so' could not be loaded.

DPMA binary modules will not provide any indication that the Avahi daemon is not installed or running; rather, phones will not see the Asterisk server when it is running.

To install the Avahi client libraries and server daemon for a RedHat/CentOS-based system, run, from the Linux CLI:

sudo yum install avahi avahi-devel

To install the Avahi client libraries for an Debian/Ubuntu-based system, run, from the Linux CLI:

sudo apt-get install libavahi-client3 avahi-daemon

Attempting to load DPMA binary modules into an Asterisk instance that was not compiled with the XML development libraries will present the following Asterisk ERROR message:

Asterisk not compiled with XML development library

[Feb 20 15:28:58] WARNING[494]: loader.c:414 load_dynamic_module: Error loading module 'res_digium_phone.so': /usr/lib/asterisk/modules/res_digium_phone.so: undefined symbol: ast_xml_node_get_children
[Feb 20 15:28:58] WARNING[494]: loader.c:882 load_resource: Module 'res_digium_phone.so' could not be loaded.
Unable to load module res_digium_phone.so
Command 'module load res_digium_phone.so ' failed.

3 - DPMA requires XML-parsing libraries to be installed on your distribution. Most distributions are already provided with them and a typical compilation of Asterisk includes XML development libraries.

To install the XML development library for a RedHat/CentOS-based system, run, from the Linux CLI:

sudo yum install libxml2-devel

To install the XML development library for a Debian/Ubuntu-based system, run, from the Linux CLI:

sudo apt-get install libxml2-dev

Once the XML development libraries have been installed, Asterisk will need to be configured to use it. This involves re-running the ./configure utility, make and make install from the Asterisk source directory. For more information about the configuration and installation of Asterisk, please see other sections of this wiki.

4 - DPMA also requires Asterisk's standard voicemail application, app_voicemail.

PJSIP Version Requirements

In versions of Asterisk prior to 12, DPMA is used only with chan_sip. Asterisk 12 introduced support for chan_pjsip, based on pjproject. DPMA 2.0 was released for Asterisk 12 and operates with both chan_sip and with chan_pjsip built on pjproject version 2.1. DPMA 2.1 was released for both Asterisk 12 and Asterisk 13. Because of API changes made within pjproject, DPMA 2.1.1 and greater require pjproject version 2.3 or greater.

Beginning with Asterisk 13.8.0, the supported method of PJSIP installation is the bundled method. Using it removes the complexity of installing and configuring PJSIP.

Use of an incorrect version of pjproject may result in unexpected behavior.

To ensure that you are using the correct version of pjproject with DPMA, please refer to the DPMA's Changes wiki page, or the CHANGES and UPGRADE.txt files distributed with the DPMA binary tar ball.

Limitations

DPMA is not compatible with versions of CentOS prior to 6.0.

The DPMA is a licensed Sangoma product and is tied to the system's MAC addresses at the time the "register" utility was run. Once generated, you can't move the license file to another system and changing MAC addresses on a currently licensed system (such as when a network card is replaced) will cause the license validation to fail. It's also possible that adding or removing VLANs, bridges, bonds and other virtual network interfaces could cause the license validation to fail since it's not always easy for the licence validation process to distinguish between physical and virtual interfaces. In these cases, you should re-run the "register" utility to generate a new license file. If you encounter issues with this process, contact Sangoma Technical Support.

Certified Asterisk and DigiumPhones Branches

DPMA is currently compatible with mainline releases of Asterisk 17, 16, 15, 14, 13, 12 and 11, but is not compatible with any previous mainline releases because of the release policies of open source Asterisk. Per release policy, once a branch of Asterisk, e.g. 1.4, 1.6.2, 1.8, 10, etc. is created, bugs are fixed, security vulnerabilities are closed, but new features are not added. Over time, this has proven to be an effective policy at limiting the introduction of regressions and making upgrades between branch versions an easy process.

Because the Desk Phone module for Asterisk requires new features - APIs, SIP messaging infrastructure, voicemail changes, etc. - that are currently only available in Asterisk 19, 18, 17, 16, 15, 14, 13, 12, 11 - and because Sangoma phones will require new changes in the future as additional phone applications are provided, new branches of earlier, but still supported versions of Asterisk, were required. For Asterisk 1.8 users, all of the code necessary to support DPMA, as well as changes to Asterisk applications, such as voicemail, parking, user presence, etc. is available in the Certified Asterisk releases, beginning with the asterisk-1.8.11-cert1 release. For more information about Certified Asterisk, please see the overview on the Asterisk website. Support for Asterisk 10 was provided in the "-digiumphones" branch of Asterisk 10. This branch tracks the mainline branch of Asterisk with respect to features and bugfixes, but also supports DPMA. As with any other branch of Asterisk, both Certified Asterisk and -digiumphones branches are licensed under the GPLv2 and are made available for download via subversion, as tarballs, and as packages.