Snom Service Hub

Content

Page tree

Index:


Introduction

PhoneLink for Asterisk (currently PJSIP is supported) is an auto-provisioning app (by Snom), which is loading dynamic and static settings (like remote registrar, username and password) from Asterisk into the Snom Provisioning System (SRAPS).

These settings are combined with predefined profile settings from the application and the settings are stored in SRAPS (Secure Redirection and Provisioning Service), a service hosted by Snom in Frankfurt am Main, Germany.


The main principle behind PhoneLink for Asterisk is to leave the existing system completely intact. There is no need to develop anything, and you do not need to create any additional secure infrastructure, since this is all provided by Snom.

Both PhoneLink for Asterisk and phone provisioning by SRAPS are available for free.



Use Cases

  • PhoneLink for Asterisk connects your Asterisk / PJSIP with SRAPS to make auto-provisioning of Snom device possible. So if you are running an Asterisk (or any Asterisk derivate) you can profit from PhoneLink for Asterisk to get a generalized and supported configuration tool for all the Snom devices you own.

  • If the phones are behind a Firewall you will have to enable them to connect to SRAPS. Generally, if the network is allowing devices to reach the public internet they are able to download their configuration, after a strong authentication over HTTPS. If that is not possible for any reason, you can follow the steps written in this article (about SRAPS Proxy) to make SRAPS available for the phones.

  • Using PhoneLink for Asterisk makes auto-provisioning lighter, since it is connecting to your backend, gathers data, and updates SRAPS without creating a complicated XML structure for any of the above mentioned devices.


Backends

The used backend is defined by the configuration file, therefore it is not possible to use multiple backends.

Asterisk Manager

At the moment we only support PJSIP and its configuration, for testing we used Asterisk 1.6, Manager 2.8.0.

From the convention, the MAC Address (and the IPUI for DECT handsets) are configured in the phoneprovr section, as it is described in the Asterisk Wiki. 

[1000]
type = phoneprovr
endpoint = endpoint_1000
MAC = 000413928b88
IPUI = 0x0328D661AB
PROFILE = snom
OTHERVAR = othervalue

Currently, the only variables supported are endpoint, MAC and IPUI (for DECT handsets). PhoneLink will loop through all phoneprovr entries and will create a configuration. Other settings, like SIP Accounts and transport are set dynamically within PhoneLink for Asterisk.

Settings can be placed in different files, since these configuration files are read by Asterisk / res_pjsip and combined together into one big configuration. This is what PhoneLink (through the AMI) reaches out to.

Generated events of Asterisk are handled only for some basic operation. The configuration of PJSIP is reloaded (and with this SRAPS is updated) once the res_pjsip.so module gets restarted. This also happens once the timeout of refresh value of the configuration is reached.

PostgreSQL

PhoneLink for Asterisk is using two tables:

  • One for the devices and
  • one for the buttons (only FKeys with D7C are supported).

This data source does not use any event driven mechanism to reload the data. Once the query is completed the cursor is closed therefore the configuration is reloaded according to the refresh value.


Supported types of buttons are defined in the pgsql.py:

BUTTON_TYPES = (
    'none',
    'dest',
    'blf',
    'speed',
    'line',
    'none',
    'park'
)

Important remarks for buttons

  • Every button (see pgsql.py / FKEY_MAX) are default to "none" (which is an empty button). 
  • If the type of the key is set to "line" an extra identity is created (with increased index), the SIP Settings (transport, user_name, user_pname) are provided, and the context of the function key is set to that additional identity.


Step-by-Step Instruction

  1. Register to SRAPS
    The registration is simple. You can find the registration form here.

  2. You will have to configure PhoneLink for Asterisk to work with your Asterisk or PostgreSQL Backend.
    For AMI, you will need a user, which can - at least - read configuration and receive events. More details on the configuration file can be found in our Gitlab repository.

  3. Start PhoneLink for Asterisk 


Requirements

We use Python 3.8.
Apart from this, the modules from the requirements.txt are also needed and these Python Modules can be installed by using pip3. We strongly advise to start PhoneLink for Asterisk within a Docker Container. For this purpose the Dockerfile is also available in the GitLab repository.

The easiest way is to start the build.sh which will create the Docker Volume and the Container. This makes sure you have the required versions of Python modules.


Remarks

D-Series

Snom desk phones are fully supported. Depending on the backend however different configurations can be provisioned. Since Asterisk does not have a place for the configuration of function keys (fkey), this feature is only supported for PostgreSQL.
Generally speaking:

  • Authentication information (from the [ auth ] section) is used for authentication purpose. Here we store the SIP Username and Password, as well as the realm if any. In addition, LDAP Username, Password and Base DN are stored in the PGSql backend.
  • Endpoint configuration (from the [ endpoint ] section) contains some settings which are relevant for the basic settings. Here Asterisk defines which inbound authentication and also which transport is used. These are then used for the phone to build up the remote settings, where the phone is connecting to and with which credentials the phone should connect. 
  • PostgreSQL contains also configuration for the FKeys and they can be configured for desk phones as well as for the expansion module 111676591.

Multiple accounts are supported. You can associate the MAC address with multiple endpoints. In this case additional endpoints are going to be created for the phone as line identity. The numbering of identities starts from 1. 

You must maintain the order of the Identities within the Asterisk configuration, or in the PostgreSQL. Best practice is to create a view, which defines the order of identities, since PhoneLink does not maintain the previous configuration and, if the results from the backend differs from the order of SIP accounts, they will be created in different order as they were created before.

The button table (supported only with PostgreSQL) may contain a "line" type key. This must be equipped with SIP credentials and treated as a new identity. The buttons, starting from 2, are assigned in order of appearance in the table to the newly created Identity.

M-Series

Currently supported models are M900, M700 and M300.

For the M-Series you can define the MAC addresses for the different endpoints. PhoneLink will recognize the type of the device, and if the device is an M-Series device an extra line will be created. If IPUI is not defined, it is set to 0xFFFFFFFFF.

You must maintain the order of the Identities within the Asterisk configuration, or in the PostgreSQL. Best practice is to create a view, which defines the order of identities, since PhoneLink does not maintain the previous configuration and, if the results from the backend differs from the order of SIP accounts, they will be created in different order as they were created before.

M-Series cannot exchange Handset behind a SIP Identity and this leads to a problem when the configuration in Asterisk and in SRAPS differ to the settings within the Base Station.

Exchange or remove handsets

Handsets cannot be exchanged straightforward. This is due to the restriction of DECT pairing a handset to a base station. To exchange or remove a handset from the base station you will have to reprovision the extension with an empty IPUI.

You can either remove the IPUI from the [ phoneprovr ] section, or set it to 0xFFFFFFFFFF. This will disassociate the handset from that extension and makes the slot ready to be paired with an another handset.

C520 conference phone

This device can be provisioned just like any other device from SRAPS and supports only SIP Line Extensions. 


Licence

PhoneLink for Asterisk is released under the BSD 3-Clause Licence:

BSD 3-Clause License Copyright (c) 2021, Snom Technology GmbH All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


Further Information


Related articles