Introduction

Sangoma 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.  Sangoma 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.  Sangoma 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.

General Configuration to XML mappings

In the examples below, and where applicable for a give context the following mappings (conf -> xml) apply:

line id/name -> account_id

phone's id/name, line's userid, or line id/name depending on context -> username

line's authname, or line id/name if authname not specified -> authname

line's secret, phone's pin, or global pin depending on context -> password

line's secret -> passcode

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:

In this sample, we have set DPMA general settings to allow any Sangoma 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:

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.

 Configuring the Status Application

First, update the phone's XML configuration file so that it looks something like:

What did we do?  First, we defined an appconfig for the appscreen.  The appscreen appconfig controls what applications are seen on the phone's applications menu.  Here, we're declaring that we'd like to see the status application.

Next, we set an appconfig for the status application itself.  First, for this application, we defined its account parameters.  Here, DPMA and the phone's application are concerned with its account_id and username (match the SIP endpoint identifier), and its password (match the SIP endpoint password), as well as the location of the appserver (set to "dasp:// asterisk.example.com /json") and the apiformat (set to json).

Then, within the account definition, we'll add the subscription_extension parameter and set it to auto_hint_101.  DPMA auto-creates magic presence + device state hints in the format "auto_hint_endpointname."

Then, update your res_digium_phone.conf file so that it includes a line definition, e.g.:

The line definition is important for DPMA so that it understands which SIP endpoint it's dealing with, inside of Asterisk.

Then, reload DPMA (module reload res_digium_phone.so), and reconfigure the phone (digium_phones reconfigure phone 101), load the status app again, and you'll see:

et voilà!

Status App usage Notes

Return SIP response 486

One of the advantages of Digium's phones having a built-in presence application is that it allows the creation of Asterisk dial plan that can query the presence state before delivering a call to the phone, so that phones aren't even rung when someone's declared they're in DND.  For phones historically configured only via DPMA, to make life easier on existing platforms that don't want to write updated dial plan, Digium's phones have returned a SIP 486 message when called while they're in either the DND or Extended Away presence states.  This is affected by passing in send_dnd options to the status application appconfig, e.g.:

Custom Presence States

It is also possible to configure DPMA to send custom presence lists to the phone. This is accomplished by defining your own list of presences and substatuses and adding those to the phone. To do this, configure and attach them to the phone type in res_digium_phone.conf, e.g.:

In doing so, we end up with something on the phone that looks like:

This concludes our overview of the Status application when used inside a DPMA+XML mixed configuration environment

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.

 Configuring the Voicemail application

We'll start with our simplified XML configuration, and we'll add in what we need for the voicemail app, like so:

What did we do? First, we defined the voicemail application for the appscreen, so that we'll see it in the apps menu on the phone.

Next, we set an appconfig for the  voicemail  application itself.  First, for this application, we defined its account parameters.  Here, DPMA and the phone's application are concerned with its  account_id (match the line id/name) and  username  (match the SIP endpoint identifier), and its  password  (match the SIP endpoint password), as well as the location of the  appserver  (set to "dasp:// asterisk.example.com /json") and the  apiformat  (set to  json ).

Then, we define an event handler for digium.incomingCall.voicemail. When the phone is accessing the voicemail app functionality and it's playing back a voicemail, DPMA is directing Asterisk to make a call into the telephone, and it's sending that call in with a special header that we trap with this event handler, and we direct to the voicemail application. This allows the phone to stay inside the voicemail app and not consider the voicemail playback an incoming call.

In the account definition, we turn on visual_voicemail and then we set a permission on the account called use_voicemail. Together, these let the phone know that we should use the full functionality of the voicemail app and that we shouldn't grey-out the voicemail buttons on-screen.

As with the status application, we need to update our res_digium_phone.conf file so that it includes a line definition, e.g.:

And that line definition must be applied to the phone that is associated with it. The line definition is important because it ties the phone to a PJSIP endpoint, wherein one must have defined a single mailboxes, e.g., in the pjsip.conf file:

Then, reload DPMA (module reload res_digium_phone.so), and reconfigure the phone (digium_phones reconfigure phone 101), load the voicemail app again, and you'll see (this account already has some voicemails present on it) something like:

Success!

Voicemail App Usage Notes

Send to Voicemail

Beyond simply loading the voicemail application, there are some additional voicemail-related configuration items that can be set. First, there's an option that allows incoming calls to be sent directly to voicemail. For D80 model phones, this option is configured as an account permission, like so:

When send_to_voicemail is true, D80 phones will enable the send to voicemail button on incoming call cards. For non-D80 phones a key mapping must be set in order to display the functionality on a key. This is handled in keymap for the incoming call state, e.g.:

Note the inclusion of the send_to_vmail action.

Voicemail PIN

Another option that can be configured is the option to require a user to enter their voicemail PIN prior to loading the voicemail application into the background. This is accomplished with the require_password voicemail appconfig setting, e.g.:

When this item is true, the phone will display a prompt for the password whenever the voicemail application is foregrounded, e.g.:

The password matches the appconfig account password, e.g. 1234, in this case.

Voicemail Translations

Sangoma phones retrieve the names of Voicemail folders from the server itself. As such, the phones do not have built-in translation strings for those folders. Instead, the server provides the folder name to the phone. To use non-English folder names requires the configuration of voicemail folder translation lists within DPMA itself, and the application of that translation to a voicemail type application. These must then be loaded onto the telephone. This is accomplished res_digium_phone.conf, e.g.:

Here, we first created a translation mapping of the English folder names to German names. Then, we created a voicemail type application that referenced that translation. Finally, we applied that application, voicemail_de_DE to the phone object itself. Thus, when the phone loads the voicemail application and views its folders, it should see something like:

Note that in this example, we didn't otherwise change the language settings for the phone, thus "Select" and "Refresh" are still in English.

Solicited MWI

Commonly, Asterisk is configured so as to send an unsolicited MWI NOTIFY to a registering endpoint. In those cases, the mailboxes parameter is defined for the PJSIP endpoint. However, if your prefer Asterisk to only respond to solicited, or SUBSCRIBEd MWI, the mailboxes parameter is instead defined on the AOR, and not the endpoint; e.g.:

In this case then, the phone needs to be configured to SUBSCRIBE for MWI, which it doesn't do by default. This is accomplished, again referencing our simple XML config, like:

The needMwiSubscription account parameter controls the behavior of the phone, with respect to MWI subscription.

This concludes our overview of the Voicemail application when used inside a DPMA+XML mixed configuration environment.

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.

 Configuring the Parking Application

First, we'll get the application going on the phone. To do that, let's have a look at our simplified XML configuration, modified with what we'll need for Parking:

What did we do? First, we defined the parking application for the appscreen, so that we'll see it in the apps menu on the phone.

Next, we set two parameters that are used only by the D80. The first, parking_lot_extension defines where parked calls are to be transferred into. The second, parking_lot_enable_blind_transfer defines the type of transferring done (attended or blind). The D80 only does blind.

Next, we set an appconfig for the parking application itself.  First, for this application, we defined its account parameters.  Here, DPMA and the phone's application are concerned with its account_id and username (match the SIP endpoint identifier), and its password (match the SIP endpoint password), as well as the location of the appserver (set to "dasp:// asterisk.example.com /json") and the apiformat (set to json). In this appconfig, we also set the parking app to auto_start, otherwise, the phone won't show the key as functional later when we map them.

Then, we define an event handler for digium.parkingLot.parked. When DPMA needs to send the phone a message to let it know that a call has been parked, it sends along this NOTIFY event. The phone receives that into its Parking application.

In the account definition, for all models, including the D80, which also requires the phone-level settings, we set parking_lot_extension and parking_lot_enable_blind_transfer.

As with the other application, we need to update our res_digium_phone.conf file so that it includes a line definition, e.g.:

Note also the inclusion of show_call_parking.  This parameter, in addition to some older control of phone XML, also alerts DPMA whether or not it should push a NOTIFY to the phone about the parked call.  Setting this to yes will cause the NOTIFY to be sent.  Setting this to no will cause NOTIFYs not to be sent.

For the D80, that's all you need. For other models of phones, we need to add the parking key to the phone's key mapping. To accomplish this, we'll be adding the Parking application to the phone's idle state, so we can quickly get to our Parked calls, as well as auto the phone's connected state, so we can park a caller that we're talking to. To accomplish this, our key mapping will look something like:

Here you'll see that for key 2 in the idle state, we have set a show_application, with the label _PARKED_CALLS, which is a built-in phone translation key to handle "Parked Calls" in English and other languages, and we're passing in the argument parking.

Then, for the connected state, we've set key 1 to perform the action park_call.

Now, reload DPMA (module reload res_digium_phone.so), and reconfigure the phone (digium_phones reconfigure phone 101). Call into it, and you'll have a Park softkey, like:

which, after pressing, will show:

and, which after pressing Show will show:

Ta-dah!

Parking App Usage Notes

Multiple Parking Lots

If you want the phone to be able to track more than a single parking lot, then additional DPMA configuration must be made. In this case, let's assume we have defined two parking lots in res_parking.conf, parkinglot_sales, and parkinglot_support. In res_parking.conf, they might look like:

To go along with this, we'd need to add modify res_digium_phone.conf to track those two lots, by using the parking application type, and we'd need to add it to the phone object, such as:

And then, in this case, we'd have to reset our config to point to one of these new lots for parking, e.g.

This concludes our overview of the Parking application when used inside a DPMA+XML mixed configuration environment.

Queues Application

Now, we'll walk through the Queues application on the phone.  

 Configuring the Queues Application

The Queues application is used to log in, out of, or pause ones' self within a queue.  Configuring the application to run on the phone requires modification of the phone's XML configuration file, as well as modification to the res_digium_phone.conf file.

The XML modifications for our simple example to enable the Queues application are simple:

What did we do? First, we defined the queues application for the appscreen, so that we'll see it in the apps menu on the phone.

Then, we set an appconfig for the queues application itself.  First, for this application, we defined its account parameters.  Here, DPMA and the phone's application are concerned with its account_id and username (match the SIP endpoint identifier), and its password (match the SIP endpoint password), as well as the location of the appserver (set to "dasp:// asterisk.example.com /json") and the apiformat (set to json). In this appconfig, we also set the parking app to auto_start, otherwise, the phone won't show the key as functional later when we map them.

That's it.

The real control is defined from within DPMA's res_digium_phones.conf configuration file, where we'll set queue, device location, member name, and other options in a queues type application that we'll apply to the phone object, e.g.:

Here, we declared a queue type application, for the sales-queue queue, where our membername is something that we'll see in the app itself.  We've also defined the location of the member as their PJSIP endpoint, PJSIP/101.  We've also declared ourselves as a member of the queue, as opposed to being just a watcher, and we've set our permission level to details, so that we can see what's going on with the queue as a whole.

Further, in Asterisk's queues.conf, to control the Queue, we'll want to enable the setinterfacevar, setqueueentryvar, and setqueuevar, parameters, e.g.:

Now, reload DPMA (module reload res_digium_phone.so), and reconfigure the phone (digium_phones reconfigure phone 101). We'll have the Queues app available in the app menu and it'll be functional.

This concludes our overview of the Parking application when used inside a DPMA+XML mixed configuration environment.

Other Topics

Call Recording

Sangoma 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?

 An Example of Most Everything

Here's our sample DPMA configuration, res_digium_phone.conf:

This sample config sets the phone config pin to 1234, adds status applications for the basic status elements to the phone, adds a queue application to the phone, attaches line 101 (so that DPMA knows how to map the phone to something in PJSIP), and sets the config file to 012345678abc.cfg.

The corresponding 012345678abc.cfg file would look something like:

You'll want to review the XML sample before you use it. Notably, it uses a lot of https transports for file downloads. If you're doing HTTPs, you'll want to pay attention to "SSL Considerations" on the Provisioning wiki page. Good luck!

Closing

TTFN!