Introduction
Digium phones have typically been configured as defined in DPMA's res_digium_phone.conf; or, separately, by eschewing DPMA's built-in apps / provisioning capabilities and using XML-based configuration instead. This page describes a method that allows the configuration of Digium's phones using DPMA as a transport mechanism, requiring only limited DPMA configuration, in conjunction with XML-based sheets for the bulk of phone settings.
Consumers of this page should have a good working familiarity with both DPMA and XML-configuration of Digium's phones.
Why This Matters
DPMA's res_digium_phone.conf configuration system is key-value pair-driven. Digium phones are, even when connected to DPMA, configured via XML-styled configuration files. Much of DPMA's code is built merely to turn those keys and values into XML-styled configurations. In order to manage phones, what DPMA does present in key-value mappings has, over time, become quite complex. There are, at present, at least 8 object types that DPMA's config handle parser, including: line, ringtone, alert, application, multicastpage, network and phone. Each of these has to be manipulated and properly added to a phone, in order to achieve a desired configuration.
When new features are added to phones, as features are driven by XML configuration options set in the phone's configuration file, creating those XML configuration options via DPMA requires additional key-value pairs, and sometimes additional object types, to be added to DPMA's configuration parser. Users of phones with DPMA are thus beholden to DPMA's understanding of a key-value pair, in order to use a capability that may already be present in their phone firmware. This situation is needlessly complex. The benefits of using simple key-value pairs are outweighed by the flexibility of XML and the ability for users to more quickly integrate new phone capabilities. Users shouldn't have to wait for new versions of DPMA to be released to use a phone capability.
Further, one of the biggest benefits of DPMA is that it provides server discovery as well as a secure and reliable method for delivering a phone's configuration, without requiring external daemons to accomplish the delivery. Digium phones use Multicast discovery in order to find DPMA servers on a network. The found servers are organized into a list, from which the user can choose. Upon choosing a server, a phone can be provisioned directly based on MAC, or the user can select their phone from DPMA's phone list, and can input their PIN code, which is not their SIP endpoint password. Phones that don't use DPMA don't have this capability.
When XML configuration is used, outside of Asterisk, typically via an HTTPs daemon, the phone must first be provisioned to point to a configuration file. This bootstrapping process provides an opportunity for the location of the configuration file, or the username and password used to retrieve it, to be disclosed - someone has to configure it in DHCP Option66 or type it into the phone's keypad manually. Phone configuration is simpler and better when DPMA delivers chunked XML configuration to a phone that is encrypted inside the DPMA protocol.
Also, many phone provisioning systems are built to create and manage XML-style configurations. A method that allows those systems to more easily integrate Digium's phones, including the D80, while still allowing the use of built-in DPMA-native applications enhances the value of Digium's phones for users of those systems.
Traditional DPMA Configuration, Simplified
Assuming a pre-existing PJSIP endpoint definition for an endpoint named 101 with the wholly insecure password of 1234, let's examine a simplified DPMA configuration for a phone. The brief res_digium_phone.conf sample would look like:
[general] globalpin=1234 userlist_auth=disabled config_auth=disabled mdns_address=asterisk.example.com mdns_port=5060 service_name=Asterisk service_discovery_enabled=yes [mynetwork] type=network alias=My Default Network cidr=0.0.0.0/0 registration_address=asterisk.example.com registration_port=5060 [101] type=line digit_map=[0-8]xx line_label=Bobby J [101] type=phone line=101 network=mynetwork full_name=Bob Jones
In this sample, we have set DPMA general settings to allow any Digium phone to connect and retrieve a phone config, without any needed PIN code, we have created a network and a line, and then we roll those up into a phone object. The result is a phone, 101, Bobby J, with digit mapping [0-8]xx, set to register to asterisk.example.com at port 5060.
Traditional XML Configuration, Simplified
A simplified configuration, 012345678abc.cfg, for an XML-defined phone, which doesn't take advantage of any built-in DPMA apps or otherwise utilize DPMA's provisioning, and which depends on , would look something like:
Here, we've attached Bobby J's account to the phone directly, and we've defined the account credentials and the primary registration server, asterisk.example.com on port 5060.
Combined Configuration, Simplified
Now, let's look at a scenario under which we utilize DPMA to authenticate the phone, but not to configure it. All of the configuration of the phone will be done in the phone's XML configuration file, served up by DPMA itself, not by any external daemon. Here's a sample res_digium_phone.conf:
[general] globalpin=1234 userlist_auth=disabled config_auth=disabled mdns_address=asterisk.example.com mdns_port=5060 service_name=Asterisk service_discovery_enabled=yes file_directory=/var/lib/asterisk/digium/phones [101] type=phone config_file=012345678abc.cfg full_name=Bob Jones
In it, we're no longer defining a network, a line, a digit map, or a line label for the phone. Instead, we're defining only the phone, and we're only passing in the phone's configuration file, 012345678abc.cfg, loaded from /var/lib/asterisk/digium/phones (as set by file_directory):
In the XML config, things remains the same, except for the inclusion of the config_server_url setting, pointed at the DPMA server, and the server_environment setting, indicating to the phone that it'll be operating in a DPMA environment.
Words of Warning
Before continuing, some words of warning. You cannot mix and match traditional DPMA configuration with the config_file phone object parameter. If you specify a config file for a phone, none of the DPMA configuration options that pertain to phone config, except those in the general section and those discussed on this page, because they pertain to internal DPMA objects and permissions, are valid.
One of the nice things that traditional DPMA configuration is that it uses internal Asterisk configuration hooks to do certain things; in particular, traditionally-configured DPMA can go retrieve PJSIP endpoint information and will properly construct the phone's configuration so that passwords are correct. When you write your own phone XML configuration file, you are responsible for use the proper account credentials, that you keep synchronized with PJSIP.
XML Configured Phones and DPMA Apps
Having done a very basic configuration, you'll notice that calls work. That's great. Try and load the status application. You'll see something like:
Why? This is seen because the phone, and DPMA, don't know how to correlate application requests made by the phone to things happening inside of Asterisk. In Switchvox environments, phones are configured to talk to the Switchvox API. The Switchvox API understands requests, users, and permissions. Asterisk itself doesn't have these concepts for users. DPMA acts as a router, understanding requests from the phone, and tying them to core functionality inside of Asterisk. To this end, additional configuration is needed for both the phone and for DPMA in order for the phone's applications to function.
Status Application
Let's make Status work.
Voicemail Application
Next, press the voicemail button on your phone. If it's a D80, it's not yet configured to do anything. If it's one of Digium's other models of phones, you'll see something like this:
Like the Status application, the Voicemail application needs to be configured. Let's have a look at the options.
Parking Application
Next, place an incoming call to your phone. Answer it. You'll see a screen like:
On this screen, you'll see only the Conference and End Call soft keys. You don't see the Parking soft key. This is because the Parking application is disabled, and because the default key mapping for the phone does not tie the Parking app to any softkey. Let's enable the Parking app.
Queues Application
Now, we'll walk through the Queues application on the phone.
Other Topics
Call Recording
Digium phones can also perform on-the-fly call recording. These call recordings are stored by the phone in the Cust5 voicemail folder, which DPMA remaps as the Recordings folder. The call recording capability is enabled on the phone by adding:
to phone's account object. And, were the phone configured normally via DPMA, the Call Recording functionality would be added in the key mapping to the connected and connected/conference call states, e.g.:
Other Applications
Other applications, such as the Contacts or LogOut applications should be configured similarly to how we've shown apps to be configured in this page. Docs for them can be found on the various, versioned XML Config phone wiki pages.
Putting It All Together
Now that we've been through the various sections, what do things look like when we put them all together?
Closing
TTFN!