Table of Contents
Advertisement
Quick Links
Digium Phone Module for Asterisk Users Guide v1.0.0
Overview
DPMA: What is it?
DPMA Compatibility
Certified Asterisk and DigiumPhones Branches
Provisioning
DPMA Concepts
DPMA Configuration
Authentication Options
Registration Server Options
mDNS Discovery Options
Firmware Update Options
Files Options
Other General Options
Phone Configuration Options
Line Configuration Options
External Line Configuration Options
Contacts
Loading a Contact List
Rapid Dial Keys
Contacts XML skeleton
Dial Plans
Ringing Types and Intercom
Firmware
Firmware configuration Management
XML Configuration
Setting Elements
Contacts Element
Accounts Element
Codecs Element
Ringtones Element
Firmwares Element
Public Firmwares Element
Appconfig Element
Digium phones when used with the DPMA
SIP Configuration
Voicemail Configuration
Parking
User Presence
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.
Digium 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 that are, and they're not dumb terminals; instead, they're simple and smart.
A Digium phone can communicate with Asterisk, or with any other SIP-based system. In this respect, a Digium phone is somewhat like other SIP
phones. In order to provide more than just the capabilities of a regular SIP phone, Digium makes available the Digium Phone Module for Asterisk
(DPMA). The DPMA is a binary Asterisk module that provides a secure communications channel for Digium phones and Asterisk. This secure
channel provided by the DPMA is used by Asterisk to provision and manage Digium 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?
The DPMA is a binary Asterisk module that provides a secure communications channel between Digium phones and Asterisk. This secure
channel is used to provision and manage the phones and to provide direct access to Asterisk's internal applications. The DPMA is not required to
use Digium phones, but offers a number of significant advantages. A single, free license is required for each Asterisk system running the DPMA.
For more information on installation and configuration, please see the support pages for Digium phones.
DPMA Compatibility
The DPMA is compatible with the open source Certified Asterisk releases of Asterisk 1.8, beginning with the asterisk-1.8.11-cert1 release. A
Advertisement
Table of Contents
Summary of Contents for Digium DPMA
- Page 1 The DPMA is a binary Asterisk module that provides a secure communications channel between Digium phones and Asterisk. This secure channel is used to provision and manage the phones and to provide direct access to Asterisk’s internal applications. The DPMA is not required to use Digium phones, but offers a number of significant advantages.
- Page 2 Asterisk, and because Digium phones will require new changes in the future as additional phone applications are provided, a new branch was required. For Asterisk 1.8 users, all of the code necessary to support the DPMA, as well as changes to Asterisk applications, such as voicemail, parking, user presence, etc.
-
Page 3: Authentication Options
external_line phone sections contain all settings for a phone profile. line sections contain all settings for a line to be applied to a phone external_line sections contain all settings for registration to an external SIP server, e.g. another Asterisk machine The phone and lines section of res_digium_phone.conf, are defined by a section identifier encapsulated in square brackets, and are user-definable. -
Page 4: Firmware Update Options
The General Section provides the following options related to mDNS / Avahi Service Discovery: Option Values Description service_name string, e.g. Digium The name of the service to be used in Avahi service discovery. Defaults to “Digium Phones Phones Config Config Server” when service_discovery_enabled, registration_address and registration_port Server are set. service_discovery_enabled yes / no If set to yes, will advertise the config server using Avahi. - Page 5 Using this option will direct the DPMA to serve up the specified file, as found in the file_directory defined directory, to the phone. For information about custom configuration files, see...
- Page 6 / yes By default, when using the Digium Phone Module for Asterisk, the phone's built-in Web UI is disabled. To override this and enable the Web UI anyway, which may result in unpredictable behavior if user settings conflict with the settings provided by the DPMA, enable this option.
- Page 7 Line Configuration Options Internal lines are SIP peers (friends), but there is Digium Phone-specific data associated with lines that does not otherwise exist in the sip.conf entry. Because of this, advanced line features must be defined separately from sip.conf, here, in res_digium_phone.conf. Advanced line configuration is not a requirement to get a line to work, it only acts as a method of setting advanced phone features to an already-defined sip.conf...
- Page 8 registration_retry_interval integer, e.g. The number of seconds to wait before retrying to register after registration fails. registration_max_retries integer, e.g. 5 The number of times the phone will attempt to retry registering after registration fails. Example In this example: the Digit Mapping for the phone is set to [0-8]xxx The Label for the line, as it appears on the phone is BobbyJ The Mailbox for the line is bob101 The Voicemail URI (number to be dialed) is 8000 at the 10.10.10.10 PBX.
-
Page 9: Rapid Dial Keys
XML files. Loading a Contact List Contacts files that the phone should load are defined in the phone's configuration XMl file and are served up by the DPMA. Contact file are specified for a phone configuration using the phone configuration parameter: contact as noted above. -
Page 10: Dial Plans
And, a more fleshed-out example looks like: XML Contact Example <phonebooks> <contacts group_name="PBX Directory" editable="0"> <contact prefix="Mr" first_name="Robert" second_name="Davis" last_name="Jones" suffix="III" contact_type="sip" organization="Digium" job_title="Direction Manager" location="East Texas" notes="" account_id="104" subscribe_to="sip:104@1.2.3.4" > <numbers> <number dial="104" dial_prefix="" label="Extension" primary="1" /> <number dial="8005551234" dial_prefix="9" label="Mobile" /> </numbers>... - Page 11 Note that the phone will attempt to immediately dial any pattern that does not have a matching rule Ringing Types and Intercom Digium phones support several different types of ringing: Normal Ringing - normal One Ring followed by automated Answer - ring-answer...
-
Page 12: Xml Configuration
DPMA will run from then on. Phones already configured with the DPMA before a firmware package change will have to be sent a reconfigure message or manually restarted to receive the firmware changes. - Page 13 <setting id="ringer_volume" value="5" /> <setting id="speaker_volume" value="5" /> <setting id="handset_volume" value="5" /> <setting id="headset_volume" value="5" /> <setting id="reset_call_volume" value="0" /> <setting id="default_ringtone" value="Digium" /> <setting id="active_ringtone" value="Digium" /> <setting id="headset_answer" value="0" /> <setting id="desi_strip_enable" value="1" /> <setting id="enable_blf_on_unused_line_keys" value="0" />...
- Page 14 <tone id="Techno" display="Techno" type="phone"/> <tone id="Theme" display="Theme" type="phone"/> <tone id="Tweedle" display="Tweedle" type="phone"/> <tone id="Twinkle" display="Twinkle" type="phone"/> <tone id="Vibe" display="Vibe" type="phone"/> </tones> <alerts> <alert alert_info="normal" ringtone_id="Digium" ring_type="normal" /> <alert alert_info="ring-answer" ringtone_id="Digium" ring_type="ring-answer" /> <alert alert_info="intercom" ringtone_id="" ring_type="answer" /> <alert alert_info="visual" ringtone_id=""...
-
Page 15: Setting Elements
<setting id="ringer_volume" value="5" /> <setting id="speaker_volume" value="5" /> <setting id="handset_volume" value="5" /> <setting id="headset_volume" value="5" /> <setting id="reset_call_volume" value="0" /> <setting id="default_ringtone" value="Digium" /> <setting id="active_ringtone" value="Digium" /> <setting id="headset_answer" value="0" /> <setting id="desi_strip_enable" value="1" /> <setting id="enable_blf_on_unused_line_keys" value="0" />... - Page 16 Sets the time source for the phone ntp_server Hostname or IP address, e.g. Sets the NTP server to which the phone will synchronize itself, defaults to 0.digium.pool.ntp.org 0.digium.pool.ntp.org ntp_resync Seconds as integer, e.g. 86400 Sets the interval between NTP synchronization...
- Page 17 If 1, volume changes made during a call do not persist to the next call, defaults to 0 default_ringtone Tone ID from <tones> provided to Sets the default phone ringtone, defaults to Digium phone active_ringtone Tone ID from <tones> provided to...
- Page 18 <contacts url="https://server.example.com/myfile.xml" id="internal" md5="abcd123" /> </config> Any number of contacts elements may be present directly under the config element. These <contacts> elements have attributes, most importantly url which allow contacts xml sheets to be downloaded via the DPMA. Option Values...
- Page 19 Only valid on account with index of 0. Only valid for phones provisioned by Switchvox or the DPMA. If this is set to 1 then the Msgs button action will open the voicemail app. Otherwise it will dial the voicemail extension.
- Page 20 Codecs Element Example <?xml version="1.0" ?> <config> <codecs> <codec id="PCMU" priority="255" packetization="20" jitter_min="0" jitter_max="0" jitter_target="0" enabled="1" /> <codec id="PCMA" priority="13" packetization="20" jitter_min="0" jitter_max="0" jitter_target="0" enabled="1" /> <codec id="G722" priority="11" packetization="20" jitter_min="0" jitter_max="0" jitter_target="0" enabled="1" /> <codec id="G726-32" priority="7" packetization="20" jitter_min="0" jitter_max="0" jitter_target="0"...
- Page 21 URL Alerts: Child element of <ringtones> Alerts Element Example Alerts Element Example <?xml version="1.0" ?> <config> <ringtones> <alerts> <alert alert_info="normal" ringtone_id="Digium" ring_type="normal" /> <alert alert_info="ring-answer" ringtone_id="Digium" ring_type="ring-answer" /> <alert alert_info="intercom" ringtone_id="" ring_type="answer" /> <alert alert_info="visual" ringtone_id="" ring_type="visual" />...
- Page 22 Option Values Description model D40, Model number of the Digium phone D50, version string Version string for the firmware. On boot, the phone will check the version string against an internal copy of the string, as previously loaded. If the strings differ, the phone will load the new firmware...
-
Page 23: Sip Configuration
SIP Configuration Configuration of a phone via the Digium Phone module for Asterisk alone is not enough to enable calling between the phone and Asterisk. As with any SIP device that connects to Asterisk, each Digium phone needs a corresponding entry in Asterisk's SIP configuration, e.g. sip.conf. Asterisk provides two types of entities within SIP: peers and friends. -
Page 24: Voicemail Configuration
When a Digium phone is not connected to the Digium Phone module for Asterisk, the Voicemail application simply dials a SIP URI, as configured, like any other SIP phone. However, if the Digium phone is connected to the DPMA and Asterisk is correctly configured, then the Msgs button will instead load a Visual Voicemail application that provides an enhanced user experience. - Page 25 User Presence When used with the DPMA, Digium Phones are capable of seeing both device status and user presence. Device status is simply the device state one can subscribe to over SIP SUBSCRIBE, that maps directly to a hint in the diaplan. User presence is an entirely new concept to Asterisk, and...
- Page 26 DPMA are capable of only Available and DND (Phone returns 486 to Asterisk) status. Digium Phones using the DPMA are capable of much more, with a Status application that allows users to change their presence on the server, opening up new methods for call routing based on user-presence, and not merely device presence.
- Page 27 Valid Options e: Both subtype and message fields are base64 encoded. This is necessary for complex strings containing commas and newline characters. When this option is used, the PRESENCE_STATE function knows it must first base64 decode the subtype and message fields before setting them on the CustomPresence provider.
- Page 28 The DPMA does all of the user presence manipulation of the CustomPresence providers behind the scenes. Phones subscribe to a set of user extensions to receive both device state and user presence updates. The DPMA is in change of defining the hints the phones subscribe to, and mapping those hints to the correct device state and presence state providers.
Need help?
Do you have a question about the DPMA and is the answer not in the manual?
Questions and answers