
Digium Phone Module for Asterisk (DPMA) README for Version 1.x modules
==============================================================================

  Digium provides a line of SIP phones that are designed to operate with
  Asterisk. When used with the Digium Phone Module for Asterisk (DPMA),
  Digium's phones provide a number of enhanced provisioning and application
  capabilities. To read more about the DPMA, please visit the following
  web address:

  http://www.digium.com/phones

  No-charge license keys for the DPMA are available from Digium's webstore at 
  the following web address:

  http://store.digium.com/productview.php?product_code=804-00032

  Follow the instructions below to download and install the Digium Phone
  Module for Asterisk (DPMA).



==[ Installation Overview ]===================================================

  Once you have a DPMA license key, there are two primary tasks to perform
  in order to install the DPMA software.

      1)  Download and execute the 'register' utility to generate a valid
          license.

      2)  Download and install the 'res_digium_phone' binary that is built for
          your platform.

  The steps to complete these tasks are described in the Installation
  Procedure section.

  The register utility may be downloaded from:
  http://downloads.digium.com/pub/register

  The DPMA binary may be downloaded from:
  http://downloads.digium.com/pub/telephony/res_digium_phone

  Notes:

  - Supported software builds are provided for 32-bit, 64-bit coming soon, 
    x86 platforms, and are optimized for a variety of processor types. Choose
    the directory that closest matches your Asterisk version and processor
    type.



==[ Installation Procedure ]==================================================

1)  Download and execute the register utility to generate a valid license.

1.1)  Download the register utility to the root home directory of your
      Asterisk server. First, log in as the user "root".

      Command-line Example for 32-bit Linux:

        # cd /root
        # wget http://downloads.digium.com/pub/register/x86-32/register

1.2)  Change the permissions of the /root/register file to r-x------.

      Command-line Example:

        # chmod 500 /root/register

1.3)  Run the register utility and follow the interactive instructions. The
      registration utility will prompt you for your DPMA license key.

      Command-line Example:

        # /root/register

      Notes:

      - Internet access is required from your Asterisk server in order to
        register your DPMA key for licensed use. Outgoing network traffic to
        TCP port 443 (SSL) must be allowed in order for the register utility
        to successfully communicate with Digium's license server and complete
        the registration process.


2)  Download and install the res_digium_phone binary that is built for your
    platform.

    There is currently a single version for releases of Certified Asterisk 
    beginning with 1.8.11-cert1. Take note that these modules are *not* 
    loadable in prior releases of Asterisk, and will only load in the specific
    version for which they are designed. Be sure that you download the correct
    version
    of the DPMA binary for your Asterisk version.

    In addition, updated builds of the DPMA binary are frequently released.
    Each build has a 'version number'. This version number is part of the
    filename, and is also included in the copyright/license message that is
    displayed when the module is loaded into Asterisk. In this document, 
    build number '1.0.8' has been used as an example. Keep in mind that the
    build number may be newer when you read this document.

3.1)  Download DPMA to the root home directory of your Asterisk server,

      Command-line Example for 32-bit Linux:

        # cd /root
        # wget http://downloads.digium.com/pub/telephony/res_digium_phone/\
          asterisk-1.8.11-digiumphone/x86-32/\
          res_digium_phone-1.8.11_1.0.8.tar.gz

3.2)  Expand the res_digium_phone archive and copy the res_digium_phone.so 
      file to the 
      /usr/lib/asterisk/modules directory.

      Command-line Example for 32-bit Linux:

        # tar xzvf res_digium_phone-1.8.11_1.0.8.tar.gz
        # cp /root/res_digium_phone-1.8.11_1.0.8/res_digium_phone.so /usr/\
          lib/asterisk/modules

3.3)  The DPMA binary must now be loaded.
      (See General Notes to use multiple licenses on
      one server.)

      Command-line Example for new installs:

        # asterisk -rx "module load res_digium_phone.so"

      Command-line Example for a DPMA upgrade:

        # asterisk -rx "module reload res_digium_phone.so"

3.4)  Verify that the DPMA is licensed and operating. This can be verified
      by issuing "digium_phones license status" in the Asterisk CLI.

      Command-line Example:

        # asterisk -rvvv
        *CLI> digium_phones license status
        OK, Valid product license found


4)  Copy the generated license files to a safe place as described in the
    Backup Procedure section.



==[ Backup Procedure ]========================================================

  It is extremely important that you backup all of the files located in the
  /var/lib/asterisk/licenses directory. This directory contains the Host-ID
  specific license files for your system. These license files are tied to the
  MAC address of all the ethernet devices installed in your system. Creating a
  backup of this directory will allow you to restore your DPMA license file
  in case you need to reinstall your operating system. This will help prevent
  the need to contact Digium to request authorization to increment your DPMA
  key and from needing to freely order a new DPMA key if you exceed the 
  maximum number of DPMA key increments allowed.



==[ General Notes ]===========================================================

  -  A DPMA key must be re-registered if any of the Ethernet devices in your
     Asterisk server are changed, added, or removed. The unique DPMA license
     file which is located in your /var/lib/asterisk/licenses directory is
     tied to the MAC address of all the Ethernet devices installed in your
     system. A DPMA key can only be re-registered once without authorization
     from Digium. Digium must be contacted by phone in order to request
     authorization to have your DPMA key incremented. Digium reserves the
     right to deny authorization for having a DPMA key incremented.

  -  It is not required or suggested to specify a load line in the
     /etc/asterisk/modules.conf for the res_digium_phone.so file. Asterisk
     will automatically load it using the autoload option. The autoload 
     option is set on by default.


==[ Asterisk Usage Notes ]===================================================

  In order for the DPMA to function properly, the following configuration
  settings MUST be in your SIP configuration, e.g. sip.conf.

  In the [general] section you must set:

1) accept_outofcall_messages = yes
   
   Digium phones send out-of-call MESSAGEs to Asterisk in order to retrieve
   configuration and in order to execute some of their built-in applications.

2) auth_message_requests = no
  
   Digium phones will not respond to authentication challenges to out-of-call
   MESSAGE requests.

3) outofcall_message_context = dpma_message_context
  
   Digium phones will create custom dialplan extensions in this context. 



==[ Asterisk CLI Commands ]===================================================

  The DPMA binary provides the following Asterisk CLI commands:

  "digium_phones license status"
  "digium_phones reconfigure all"
  "digium_phones reconfigure phone <phone identifier>"
  "digium_phones show firmware"
  "digium_phones show lines"
  "digium_phones show line <phone identifier>"
  "digium_phones show phones"
  "digium_phones show phone <phone identifier>"
  "digium_phones show sessions"
  "digium_phones show settings"
  "digium_phones show version"



==[ Technical Support ]=======================================================

If you have any questions or concerns, contact Digium Technical Support by
phone, either toll-free within the US at 1.877.DIGIUM.1(1.877.344.4861) or
directly at +1.256.428.6000.  You may also contact Digium Technical Support by
visiting http://www.digium.com/support.

==============================================================================
