A Device Model defines a specific hardware device, like the vendor, model name, the number of keys and their capabilities. For example a Cisco SPA504G has 4 keys, which can be used for private lines, shared lines (SLA) and busy lamp field (BLF). If you have an additional attendant console, you get 32 more buttons, which can only do BLF.

In this example, we will create a Cisco SPA504G with an additional Attendant Console.

Expand the Device Models row and click Create Device Model.

First, you have to select the reseller this device model belongs to, and define the vendor and model name.

Figure 60. Create Device Model Part 1

In the Line/Key Range section, you can define the first set of keys, which we will label Phone Keys. The name is important, because it is referenced in the configuration file template, which is described in the following sections. The SPA504G internal phone keys support private lines (where the customer can assign a normal subscriber, which is used to place and receive standard phone calls), shared lines (where the customer can assign a subscriber which is shared across multiple people) and busy lamp field (where the customer can assign other subscribers to be monitored when they get a call, and which also acts as speed dial button to the subscriber assigned for BLF), so we enable all 3 of them.

Figure 61. Create Device Model Part 2

In order to also configure the attendant console, press the Add another Line/Key Range button to specify the attendant console keys.

Again provide a name for this range, which will be Attendant Console 1 to match our configuration defined later. There are 32 buttons on the attendant console, so set the number accordingly. Those 32 buttons only support BLF, so make sure to uncheck the private and shared line options, and only check the busy lamp field option.

Figure 62. Create Device Model Part 3

The last two settings to configure are the Front Image and MAC Address Image fields. Upload a picture of the phone here in the first field, which is shown to the customer for him to recognize easily how the phone looks like. The MAC image is used to tell the customer where he can read the MAC address from. This could be a picture of the back of the phone with the label where the MAC is printed, or an instruction image how to get the MAC from the phone menu.

The rest of the fields are left at their default values, which are set to work with Cisco SPAs. Their meaning is as follows:

Finally press Save to create the new device model.

Figure 63. Create Device Model Part 4

A device model can optionally have one or more device firmware(s). Some devices like the Cisco SPA series don’t support direct firmware updates from an arbitrary to the latest one, but need to go over specific firmware steps. In the device configuration discussed next, you can return the next supported firmware version, if the phone passes the current version in the firmware URL.

Since a stock phone purchased from any shop can have an arbitrary firmware version, we need to upload all firmwares needed to get from any old one to the latest one. In case of the Cisco SPA3x/SPA5x series, that would be the following versions, if the phone starts off with version 7.4.x:

So to get an SPA504G with a firmware version 7.4.x to the latest version 7.5.5, we need to upload each firmware file as follows.

Open the Device Firmware row in the Device Management section and press Upload Device Firmware.

Select the device model we’re going to upload the firmware for, then specify the firmware version and choose the firmware file, then press Save.

Figure 64. Upload Device Firmware

Repeat this step for every firmware in the list above (and any new firmware you want to support when it’s available).

Each customer device needs a configuration file, which defines the URL to perform firmware updates, and most importantly, which defines the subscribers and features configured on each of the lines and keys. Since these settings are different for each physical phone at all the customers, the Cloud PBX module provides a template system to specify the configurations. That way, template variables can be used in the generic configuration, which are filled in by the system individually when a physical device fetches its configuration file.

To upload a configuration template, open the Device Configuration row and press Create Device Configuration.

Select the device model and specify a version number for this configuration (it is only for your reference to keep track of different versions). For Cisco SPA phones, keep the Content Type field to text/xml, since the configuration content will be served to the phone as XML file.

For devices other than the Cisco SPA, you might set text/plain if the configuration file is plain text, or application/octet-stream if the configuration is compiled into some binary form.

Finally paste the configuration template into the Content area and press Save.

Figure 65. Upload Device Configuration

The templates for certified device models are provided by Sipwise, but you can also write your own. The following variables can be used in the template:

Within the configuration template itself, you can use any Template Toolkit directive and any own variables you like (just make sure to not override any of the ones specified above). For documentation on the syntax, please refer to the Template Toolkit Manual.

	In order to change the provisioning base IP and port (default 1444), you have to access /etc/ngcp-config/config.yml and change the value host and port under the autoprov.server section.

When the customer configures his own device, he doesn’t select a Device Model directly, but a Device Profile. A device profile specifies which model is going to be used with which configuration version. This allows the operator to create new configuration files and assign them to a profile, while still keeping older configuration files for reference or roll-back scenarios. It also makes it possible to test new firmwares by creating a test device model with the new firmware and a specific configuration, without impacting any existing customer devices.

To create a Device Profile for our phone, open the Device Profile row in the Device Management section and press Create Device Profile.

Select the device configuration (which implicitly identifies a device model) and specify a Profile Name. This name is what the customer sees when he is selecting a device he wants to provision, so pick a descriptive name which clearly identifies a device. Press Save to create the profile.

Figure 66. Create Device Profile

Repeat the steps as needed for every device you want to make available to customers.

These rules are the most important ones, as they define which number formats the PBX subscribers can dial. For the break-out code of 0, the following rules are necessary e.g. for German dialplans to allow pbx internal extension dialing, local area calls without area codes, national calls with area code, and international calls with country codes.

Figure 68. Inbound Rewrite Rule for Callee

When a call goes to a PBX subscriber, it needs to be normalized in a way that it’s call-back-able, which means that it needs to have the break-out code prefixed. We create a rule to show the calling number in international format including the break-out code. For PBX-internal calls, the caller name will be shown (this is handled by implicitly setting domain preferences accordingly, so you don’t have to worry about that in rewrite rules).

Figure 69. Outbound Rewrite Rule for Caller

Create a new Rewrite Rule Set for each dial plan you’d like to support. You can later assign it to customer domains and even to subscribers, if a specific subscriber of a PBX customer would like to have his own dial plan.

Go to Settings→Customers and click Create Customer. We need a Contact for the customer, so press Create Contact.

Figure 70. Create PBX Customer Part 1

Fill in the desired fields (you need to provide at least the Email Address) and press Save.

Figure 71. Create PBX Customer Contact

The new Contact will be automatically selected now. Also select a Billing Profile you want to use for this customer. If you don’t have one defined yet, press Create Billing Profile, otherwise select the one you want to use.

Figure 72. Create PBX Customer Part 2

Next, you need to select the Product for the PBX customer. Since it’s going to be a PBX customer, select the product Cloud PBX Account.

Since PBX customers are supposed to manage their subscribers by themselves, they are able to create them via the web interface. To set an upper limit of subscribers a customer can create, define the value in the Max Subscribers field.

	As you will see later, both PBX subscribers and PBX groups are normal subscribers, so the value defined here limits the overall amount of subscribers and groups. A customer can create an unlimited amount of subscribers if you leave this field empty.

Press Save to create the customer.

Figure 73. Create PBX Customer Part 3

Once the customer is created, you need to create at least one Subscriber for the customer, so he can log into the web interface and manage the rest by himself.

Click the Details button on the newly created customer to enter the detailed view.

Figure 74. Go to Customer Details

To create the subscriber, open the Subscribers row and click Create Subscriber.

Figure 75. Go to Create Subscriber

For your pilot subscriber, you need a SIP domain, a pilot number (the main number of the customer PBX), the web credentials for the customer to log into the web interfaces, and the SIP credentials to authenticate via a SIP device.

In a PBX environment, customers can create their own subscribers. As a consequence, each PBX customer should have its own SIP domain, in order to not collide with subscribers created by other customers. This is important because two customers are highly likely to create a subscriber (or group, which is also just a subscriber) called office. If they are in the same SIP domain, they’d both have the SIP URI office@pbx.example.org, which is not allowed, and the an end customer will probably not understand why office@pbx.example.org is already taken, because he (for obvious reasons, as it belongs to a different customer) will not see this subscriber in his subscribers list.

To handle one domain per customer, you should create a wild-card entry into your DNS server like *.pbx.example.org, which points to the IP address of pbx.example.org, so you can define SIP domains like customer1.pbx.example.org or customer2.pbx.example.org without having to create a new DNS entry for each of them. For proper secure access to the web interface and to the SIP and XMPP services, you should also obtain a SSL wild-card certificate for *.pbx.example.org to avoid certification warnings on customers' web browsers and SIP/XMPP clients.

So to create a new domain for the customer, click Create Domain.

Figure 76. Go to Create Customer Domain

Specify the domain you want to create, and select the PBX Rewrite Rule Set which you created in Section 14.1.2, “Preparing PBX Rewrite Rules”, then click Save.

Figure 77. Create Customer Domain

Finish the subscriber creation by providing an E.164 number, which is going to be the base number for all other subscribers within this customer, the web username and password for the pilot subscriber to log into the web interface, and the sip username and password for a SIP device to connect to the PBX.

The parameters are as follows:

Figure 78. Create Pilot Subscriber Part 1

Figure 79. Create Pilot Subscriber Part 2

Once the subscriber is created, he can log into the customer self-care interface at https://<your-ip>/login/subscriber and manage his PBX, like creating other users and groups, assigning Devices to subscribers and configure the Auto Attendant and more.

As an administrator, you can also do this for the customer, and we will walk through the typical steps as an administrator to configure the different features.

Go the the Customer Details of the PBX customer you want to configure, e.g. by navigating to Settings→Customers and clicking the Details button of the customer you want to configure.

Since a stock device obtained from an arbitrary distributor doesn’t know anything about your system, it can’t fetch its configuration from there. For that to work, you need to push the URL of where the phone can get the configuration to the phone once.

In order to do so, click the Sync Device button on the device you want to configure for the very first time.

Figure 88. Go to Sync Device

	As you will see in the next step, you need the actual IP address of the phone to push the provisioning URL onto it. That implies that you need access to the phone to get the IP, and that your browser is in the same network as the phone in order to be able to connect to it, in case the phone is behind NAT.

Enter the IP Address of the phone (on Cisco SPAs, press Settings 9, where Settings is the paper sheet symbol, and note down the Current IP setting), then click Push Provisioning URL.

Figure 89. Sync Device

You will be redirected directly to the phone, and the Provisioning URL is automatically set. If everything goes right, you will see a confirmation page from the phone that it’s going to reboot.

Figure 90. Device Sync Confirmation from Phone

You can close the browser window/tab and proceed to sync the next subscriber.

	You only have to do this step once per phone to tell it the actual provisioning URL, where it can fetch the configuration from. From there, it will regularly sync with the server automatically to check for configuration changes, and applies them automatically.

Open the music_on_hold row and click Upload on the music_on_hold entry. Choose a WAV file from your file system, and click the Loopplay setting if you want to play the file in a loop instead of just once. Click Save to upload the file.

Figure 92. Upload MoH Sound File

Create a Sound Set and upload the Sound Files for it as described below. Afterwards in the Subscriber Preferences view, set the Customer Sound Set preference to the Sound Set to be used. To do so, click Edit on the Customer Sound Set preference and assign the set to be used.

Uploading Auto-Attendant Sound Files

When configuring a Call Forward to the Auto Attendant, it will play the following files:

	The sound files only define the general structure of what is being played to the caller. The actual destinations behind your options are configured separately in Configuring the Auto Attendant Slots Section 14.1.7.3, “Configuring the Auto Attendant Slots”.

An example configuration could look like this:

Figure 93. Upload Auto Attendant Sound File

The illustration below shows the sequence of voice prompts played when Auto Attendant feature is activated and a caller listens the IVR menu.

Figure 94. Flowchart of Auto Attendant

In the Auto Attendant Slots section, click the Edit Slots button to configure the destination options.

Click Add another Slot to add a destination option, select the Key the destination should be assigned to, and enter a Destination. The destination can be a subscriber username (e.g. marketing), a full SIP URI (e.g. sip:michelle.miller@customer1.pbx.example.org or any external SIP URI) or a number or extension (e.g. 491234567 or 101).

Repeat the step for every option you want to add, then press Save.

Figure 95. Define the Auto Attendant Slots

Once the Sound Set and the Slots are configured, activate the Auto Attendant by setting a Call Forward to Auto Attendant.

To do so, open the Call Forwards section in the Subscriber Preferences view and press Edit on the Call Forward type (e.g. Call Forward Unconditional if you want to redirect callers unconditionally to the Auto Attendant).

Select Auto Attendant and click Save to activate the Auto Attendant.

Figure 96. Set a Call Forward to Auto Attendant

	As with any other Call Forward, you can define more complex forwarding rules in the Advanced View to only forward the call to the Auto Attendant during specific time periods, or as a fallback if no one picks up the office number.

The call queue configuration is available at the path: Subscribers → select one → Details → Preferences → Cloud PBX.

Following configuration parameters may be set for call queueing:

In order to change the actual setting, press the Edit button in the relevant row.

Figure 97. Call Queue Configuration

Queued callers first hear a greeting message then information about their position in the queue and finally a waiting music / signal.

The following illustration shows which voice prompts are played to the caller when the call gets into a queue.

Figure 98. Flowchart of Call Queue

The Cisco SPA phones can connect to the provisioning interface of the PBX via HTTP and HTTPS. When perform secure provisioning over HTTPS, the phones validate the server certificate to check if its a legitimate Cisco provisioning server. To pass this check, the provisioning interface must provide a certificate signed by Cisco for that exact purpose.

The following steps describe how to obtain such a certificate.

First, a new SSL key needs to be generated:

$ openssl genrsa -out provisioning.key 2048
Generating RSA private key, 2048 bit long modulus
...+++
...............................................................+++
e is 65537 (0x10001)

Next, a certificate signing request needs to be generated as follows. Provide your company details.

	The Common Name (e.g. server FQDN or YOUR name) field is crucial here. Provide an FQDN which the phones will later use via DNS to connect to the provisioning interface, for example pbx.example.org. Cisco does NOT support wild-card certificates.

	Leave the password empty when asked for it (press Enter without entering anything).

$ openssl req -new -key provisioning.key -out provisioning.csr
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.

Country Name (2 letter code) [AU]:AT
State or Province Name (full name) [Some-State]:Vienna
Locality Name (eg, city) []:Vienna
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Sipwise GmbH
Organizational Unit Name (eg, section) []:Operations
Common Name (e.g. server FQDN or YOUR name) []:pbx.example.org
Email Address []:office@sipwise.com

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

Finally, compress the provisioning.csr file via ZIP and send it to our Cisco sales representative. If in doubt, you can try to send it directly to ciscosb-certadmin@cisco.com asking them to sign it.

	Only send the CSR file. Do NOT send the key file, as this is your private key!

	Ask for both the signed certificate AND a so-called combinedca.crt which is needed to perform client authentication via SSL. Otherwise you can not restrict access to Cisco SPAs only.

You will receive a signed CRT file, which Sipwise can use to configure the PBX provisioning interface.

If a client connects via HTTPS, the server also checks for the client certificate in order to validate that the device requesting the configuration is indeed a legitimate Cisco phone, and not a fraudulent user with a browser trying to fetch user credentials.

Initial Bootstrapping

Figure 99. Initially bootstrap a PBX device

Subsequent Device Resyncs

If one of the subscribers configured on a PBX device is registered via SIP, the system can trigger a re-sync of the phone directly via SIP without having the customer enter the IP of the phone again. This is accomplished by sending a special NOTIFY message to the subscriber:

NOTIFY sip:subscriber@domain SIP/2.0
To: <sip:subscriber@domain>
From: <sip:subscriber@domain>;tag=some-random-tag
Call-ID: some-random-call-id
CSeq: 1 NOTIFY
Subscription-State: active
Event: check-sync
Content-Length: 0

In order to prevent unauthorized re-syncs, the IP phone challenges the request with its own SIP credentials, so the NOTIFY is sent twice, once without authentication, and the second time with the subscriber’s own SIP credentials.

Figure 100. Resync a registered PBX device

Initial Bootstrapping

Panasonic provides a zero-touch provisioning mechanism in their firmwares, which causes the factory-reset phones to connect to a Panasonic web service at https://provisioning.e-connecting.net to check if a custom provisioning URL is configured for the MAC address of the phone. If an association between the MAC and a provisioning URL is found, the web service redirects the phone to the provisioning URL, where the phone connects to in order to obtain the configuration file.

Figure 101. Initially bootstrap a Panasonic phone

The CloudPBX module ensures that when an end customer creates a Panasonic device, the MAC address is automatically provisioned on the Panasonic web service via an API call, so the customer’s phone can use the correct provisioning URL to connect to the auto-provisioning server of the CloudPBX.

As a result, no customer interaction is required to bootstrap Panasonic phones, other than just creating the phone with the proper MAC on the CloudPBX web interface.

Factory Reset

For already provisioned phones, the end customer might need to perform a factory reset:

The default username for factory-reset phones is admin with password adminpass.

Subsequent Device Resyncs

The same procedure as with Cisco SPA phones applies, once a subscriber configured on the phone is registered.

Initial Bootstrapping

Yealink provides a zero-touch provisioning mechanism in their firmwares, which causes the factory-reset phones to connect to a Yealink web service at https://rps.yealink.com to check if a custom provisioning URL is configured for the MAC address of the phone. If an association between the MAC and a provisioning URL is found, the web service redirects the phone to the provisioning URL, where the phone connects to in order to obtain the configuration file.

If both Cisco SPA and Yealink phones are used, an issue with the Cisco-signed server certificate configured on the provisioning port (1444 by default) of the CloudPBX provisioning server arises. Yealink phones by default only connect to trusted server certificates, and the Cisco CA certificate used to sign the server certificate is not trusted by Yealink. Therefore, a two-step approach is used to disable the trusted check via a plain insecure http port (1445 by default) first, where only device-generic config options are served. No user credentials are provided in this case, because no SSL client authentication can be performed. The generic configuration disables the trusted check, and at the same time changes the provisioning URL to the secure port, where the Yealink phone is now able to connect to.

Figure 102. Initially bootstrap a Yealink phone

The CloudPBX module ensures that when an end customer creates a Yealink device, the MAC address is automatically provisioned on the Yealink web service via an API call, so the customer’s phone can use the correct insecure bootstrap provisioning URL to connect to the auto-provisioning server of the CloudPBX for the generic configuration, which in turn provides the information on where to connect to for the secure, full configuration.

As a result, no customer interaction is required to bootstrap Yealink phones, other than just creating the phone with the proper MAC on the CloudPBX web interface.

Factory Enable Yealink Auto-Provisioning

Older Yealink firmwares don’t automatically connect to the Yealink auto-provisioning server on initial boot, so it needs to be enabled manually by the end customer.

Subsequent Device Resyncs

The same procedure as with Cisco SPA phones applies, once a subscriber configured on the phone is registered.

Initial Bootstrapping

An Audiocodes device provides a zero-touch provisioning mechanism in its firmware which causes a factory-reset device to connect to the URL built into the firmware. This URL is pointing to the NGCP provisioning server (in case of NGCP Carrier: web01 node) listening on TCP port 1444 for HTTPS sessions.

The prerequisites for the device provisioning are that the device has a routable IP address and can reach the IP address of the NGCP provisioning interface.

The Audiocodes device should request the firmware file or CLI configuration file from the NGCP platform. The firmware versions and CLI config versions are decoupled from each other; the NGCP can not enforce specific version of the firmware on the device. Instead, it should be requested by the device itself. In other words, provisioning is a pull and not a push process.

NGCP expects the provisioning request from the Audiocodes device after SSL handshake and serves the requested file to the device if the device provides valid MAC address as the part of the URL. The MAC address is used to identify the device to the NGCP platform. The firmware and CLI config files are provided at the following URLs:

where 001122334455 should be replaced with the actual device’s MAC address and <NGCP_IP> with IP address of the NGCP provisioning interface.

Figure 103. Initially bootstrap a Mediant gateway

Device management basics

The list of device models, firmwares and configurations are global to a reseller and are available for end customer. This data is initially provided by Sipwise as bulk upload of all supported phone models. The firmwares and settings are stored in the database on the DB node pair(s). The NGCP leverages the Cloud PBX module with its template system to generate the configurations and firmware files from database on the fly. Please refer to the following chapters in NGCP handbook for the current information on how to perform device management:

Parameterizing the Device Configuration Template

The device-specific parameters are filled in by the system individually when a physical device fetches its configuration file. Parameters from the NGCP panel:

The produced CLI config file has the following structure:

Specific CLI parameters are:

which are used at the following configuration parameters:

Audiocodes ISDN gateways and eSBCs are devices used to connect legacy (ISDN) PBX and IP-PBX to the Sipwise NGCP platform and maintain their operations within the Operator’s network. Sipwise NGCP offers a SipConnect 1.1 compliant signaling and media interface to connect SIP trunks to the platform. In addition to this interface, the Sipwise NGCP provides an auto-provisioning mechanism to configure SIP endpoints like IP phones, media gateways and eSBCs.

Provisioning URL

An Audiocodes device needs to obtain the provisioning URL of the Sipwise NGCP in one way or the other to request its device configuration and subsequently download specific firmwares, obtain SIP credentials to connect to the network facing side, and configure the customer facing side for customer devices to connect either via ISDN or SIP. Typical ways of obtaining the provisioning URL for a SIP endpoint are:

The assumption is that Audiocodes devices are supplied with a firmware (and all required SSL certificates) being pre-configured and the provisioning URL pointing to an Operator URL the Sipwise NGCP is serving, before handing the devices over to field service engineers doing the truck rolls.

Field Configuration

The Sipwise NGCP provides a SipConnect 1.1 compliant interface on the network side for the Audiocodes devices. This interface clearly defines the numbering formats of the calling and called party, the SIP header mechanisms to provide CLI restriction, the RTP codecs, etc.

On the customer facing side, however, those variables might be different from deployment to deployment:

The assumption here is that a field service engineer is NOT supposed to change the Audiocodes configuration in order to make the customer interface work, as this will lead to big issues in maintaining those local changes, especially if a replacement of the device is necessary. Instead, the Audiocodes configuration must ensure that all different kinds of variants in terms of SIP headers, codecs and number formats are translated correctly to the network side and vice versa. If it turns out that there are scenarios in the field which are not handled correctly, temporary local changes might be performed to finish a truck roll, but those changes MUST be communicated to the platform operator, and the server-side configuration templates must be adapted to handle those scenarios gracefully as well.

For deployments with ISDN interfaces on the customer facing side of the Audiocodes, different Device Profiles with specific Device Configurations per Device Model must exist to handle certain scenarios, specifically whether the ISDN interface is operating in Point-to-Point or Point-to-Multipoint mode. Configuration options like which side is providing the clock-rate are to be defined up-front, and the PBX must be reconfigured to adhere to the configuration.

Network Configuration

On the network facing side, both the ISDN and eSBC style deployments have to be designed to obtain an IP address via DHCP. The definition of the IP address ranges is up to the Operator. It may or may not be NAT-ed, but it is advised to use a private IP range directly routed in the back-bone to avoid NAT.

On the customer facing side, networking is only relevant for the eSBC deployment. In order to make the IP-PBX configuration as stream-lined as possible, a pre-defined network should be established on the customer interface of the Audiocodes device.

The proposal is to define a network 192.168.255.0/24 with the Audiocodes device using the IP 192.168.255.2 (leaving the 192.168.255.1 to a possible gateway). The IP-PBX could obtain its IP address via DHCP from a DHCP server running on the Audiocodes device (e.g. serving IP addresses in the range of 192.168.255.100-254), or could have it configured manually (e.g. in the range of 192.168.255.3-99). Since the Audiocodes device IP on the customer side is always fixed at 192.168.255.2, the IP-PBX for each customer can be configured the same way, pointing the SIP proxy/registrar or outbound proxy always to this IP.

The customer facing side is outside the Sipwise demarcation line, that’s why the network configuration mentioned above only serves as proposal and any feedback is highly welcome. However, it must be clearly communicated how the customer facing network is going to be configured, because the Sipwise NGCP needs to incorporate this configuration into the Audiocodes configuration templates.

Pre-Configuration on Sipwise NGCP platform

Installation

Once the above requirements are fulfilled and the customer is created on the Sipwise NGCP, the Audiocodes device can be installed at the customer premise.

When the Audiocodes device boots, it requests the configuration file from the Sipwise NGCP by issuing a GET request via HTTPS.

For authentication and authorization purposes, the Sipwise NGCP requests an SSL client certificate from the device and will check whether it’s signed by a Certificate Authority known to the Sipwise NGCP. Therefore, Audiocodes must provide the CA certificate used to sign the devices' client certificates to Sipwise to allow for this process. Also, the Sipwise NGCP will provide an SSL server certificate to the device. The device must validate this certificate in order to prevent man-in-the-middle attacks. Options here are to have:

Once the secured HTTPS connection is established, the Sipwise NGCP will provide a CLI style configuration file, with its content depending on the pre-configured Device Profile and subscriber association to the device’s MAC address.

The configuration includes the firmware version of the latest available firmware configured for the Device Model, and a URL defining from where to obtain it. The configuration details on how the Audiocodes devices manage the scheduling of firmware updates are to be provided by Audiocodes or its partners, since this is out of scope for Sipwise. Ideally, firmware updates should only be performed if the device is idle (no calls running), and within a specific time-frame (e.g. between 1 a.m. and 5 a.m. once a certain firmware version is reached, including some random variation to prevent all devices to download a new firmware version at the same time).

Device Replacement

If a customer requires the replacement of a device, e.g. due to hardware issues or due to changing the number or type of ISDN interfaces, a new association of the new device MAC, its Device Profile and the subscriber must be established.

In order to make the change as seamless as possible for the customer, a new device is created for the customer with the new MAC, a proper Device Profile, but the same subscriber as used on the old device. Once the new device boots at the customer premise, it will obtain its configuration and will register with the same subscriber as the old device (in case it’s still operational). For inbound calls to the customer, this will cause parallel ringing to take place, and it’s up to the customer or the field engineer when to re-configure or re-cable the PBX to connect to one or the other device.

Once the old device is decommissioned, the old MAC association can be deleted on the Sipwise NGCP.

IP Phones

Analog Adapters

Extension Boards

IP Phones

IP Phones

IP Phones

Analog Adapters

Extension Boards

SPA301

1) Soft keys

Not available.

2) Hard keys

3) Line keys

Not available.

4) VSC

SPA303

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

SPA501G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

SPA502G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

Not available.

4) VSC

SPA504G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

SPA512G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

Not available.

4) VSC

SPA514G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

SPA509G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

SPA508G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

SPA525G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

T19P

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

Not available.

4) VSC

T20P

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

T21P

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

T22P

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

T23P

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

T23G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

T26P

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

T28P

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

T32G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

T38G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

T41P

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

T42G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

T46G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

T48G

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

W52P

1) Soft keys

Idle:

Idle with missed calls:

Call:

Call on hold:

Ringing:

2) Hard keys

3) VSC

KX-UT113

1) Soft keys

Idle:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

Not available.

4) VSC

KX-UT123

1) Soft keys

Idle:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

Not available.

4) VSC

KX-UT133

1) Soft keys

Idle:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

KX-UT136

1) Soft keys

Idle:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

KX-UT248

1) Soft keys

Idle:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

IP222

1) Soft keys

Idle:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

IP232

1) Soft keys

Idle:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

IP111

1) Soft keys

Idle:

Call:

Call on hold:

Ringing:

2) Hard keys

3) Line keys

4) VSC

IP240

1) Soft keys

Not available.

2) Hard keys

3) Line keys

4) VSC

The 3rd Party Sign-Up Form is a website the app shows to the end user when he taps the sign-up link on the app Login Screen. There, the end customer usually provides his contact details like name, address, phone number and email address, etc. After validation, the website creates an account and a subscriber in the sip:carrier via the API.

After successfully creating the account and the subscriber, this site needs to construct a specially crafted URL, which is sent back to the end customer via a side channel. Ideally, this channel would be an SMS if you want to verify the end customer’s mobile number, or an email if you want to check the email address.

The sip:phone app registers a URL schema handler for URLs starting with sipphone://. If you start such a link, the app performs a Base64 decoding of the string right after the sipphone:// prefix and then decrypts the resulting binary string via AES using the keys defined during the branding step. The resulting string is supposed to be

username=$user&server=$domain&password=$password.

Therefore, the 3rd Party Sign-Up Form needs to construct this string using the credentials defined while creating the subscriber via the sip:carrier API, then encrypt it via AES, and finally perform a Base64 encoding of the result.

	Up until and including version mr5.1.2 of the sip:carrier, the SIP login credentials are used here. Future versions will connect to the REST interface of the sip:carrier using the web credentials first and fetch the SIP credentials along with other settings from there.

An example Perl code performs encoding of such a string. The AES key and initialization vector ($key and $iv) are the standard values of the sip:phone app and should work until you specified other values during the branding process.

#!/usr/bin/perl -w
use strict;
use Crypt::Rijndael;
use MIME::Base64;
use URI::Escape;

my $key = 'iBmTdavJ8joPW3HO';
my $iv = 'tww21lQe6cmywrp3';

my $plain = do { local $/; <> };
# pkcs#5 padding to 16 bytes blocksize
my $pad = 16 - (length $plain) % 16;
$plain .= pack('C', $pad) x $pad;

my $cipher = Crypt::Rijndael->new(
        $key,
        Crypt::Rijndael::MODE_CBC()
);
$cipher->set_iv($iv);
my $crypted = $cipher->encrypt($plain);
# store b64-encoded string and print to STDOUT
my $b64 = encode_base64($crypted, '');
print $b64, "\n";
# print to STDOUT using URL escaping also
print uri_escape($b64), "\n";

This snippet takes a string from STDIN, encrypts it via AES, encodes it via Base64 and sends the result to STDOUT. It also writes the second line with the same string, but this time, the URL is escaped. To test it, you would run it as follows on a shell, granted it’s stored at /path/to/encrypt.pl.

echo -n 'username=testuser&server=example.org&password=testpass' \
  | /path/to/encrypt.pl

This command would result in the output strings CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI/Wv/VaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg== and CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI%2FWv%2FVaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg%3D%3D. The sip:phone can use the former string to automatically fill in the login form of the Login Screen if started via a Link like sipphone://CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI/Wv/VaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg==.

Here is the same code in PHP.

#!/usr/bin/php
<?php
$key = "iBmTdavJ8joPW3HO";
$iv = "tww21lQe6cmywrp3";

$clear = fgets(STDIN);
$cipher = fnEncrypt($clear, $key, $iv);

echo $cipher, "\n";
echo urlencode($cipher), "\n";

function fnEncrypt($clear, $key, $iv) {
        $pad = 16 - strlen($clear) % 16;
        $clear .= str_repeat(pack('C', $pad), $pad);
        return rtrim(base64_encode(mcrypt_encrypt(
                MCRYPT_RIJNDAEL_128, $key, $clear,
                MCRYPT_MODE_CBC, $iv)), "\0");
}
?>

Similar to the Perl code, you can call it like this:

echo -n 'username=testuser&server=example.org&password=testpass' \
  | /path/to/encrypt.php

However, a URL with the sipphone:// schema is not displayed as a link in an SMS or an Email client and thus can not be clicked by the end customer, so you need to make a detour via a regular http:// URL. To do so, you need a 3rd Party Launch Handler to trick the phone to open such a link.

Therefore, that the 3rd Party Sign-Up Form needs to return a link containing a URL pointing to the 3rd Party Launch Handler and pass the URL escaped string gathered above to the client via an SMS or an Email. Since it is the regular http:// link, it is clickable on the phone and can be launched from virtually any client (SMS, Email, etc.), which correctly renders an HTML link.

A possible SMS sent to the end customer (via the phone number entered in the sign-up from) could, therefore, look as follows (trying to stay below 140 chars).

http://example.org/p?c=CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI
%2FWv%2FVaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg%3D%3D to launch sipphone

An HTML Email could look like this:

Welcome to Example.org,
<a href="http://www.example.org/sipphone?c=CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI
%2FWv%2FVaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg%3D%3D">
click here
</a> to log in.

That way, you can do both: verify the contact details of the end customer, and send the end customer the login credentials in a secure manner.

The URL http://www.example.org/sipphone mentioned above can be any simple script, and its sole purpose is to send back a 301 Moved Permanently or 302 Moved Temporarily with a Location: sipphone://xxxxxxxxxxxx header to tell the phone to open this link via the sip:phone app. The xxxxxxxxxxxx is the plain (non-URL-escaped) string generated by the above script.

An example CGI script performing this task follows.

#!/usr/bin/perl -w
use strict;
use CGI;

my $q = CGI->new;
my $c = $q->param('c');
print CGI::redirect("sipphone://$c");

The script simply takes the URL parameter c from the URL http://www.example.org/sipphone?c=CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI%2FWv%2FVaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg%3D%3D crafted above and puts its content into a Location header using the sipphone:// schema, and finally sends a 301 Moved Permanently back to the phone.

The phone follows the redirect by opening the URL using the sip:phone app, which in turn decrypts the content and fills in the login form.

	Future versions of the sip:carrier will be shipped with this launch handler integrated into the system. Up until and including the version mr5.1.2, this script needs to be installed on any webserver manually.

If the mobile push functionality is enabled and there are no devices registered for a subscriber, the call-flow looks as follows.

Figure 105. Mobile Push Workflow

In the case of a time-out (no registration notification within a particular time), the application server rejects the call request with an error.

Follow this checklist to make sure you’ve completed all the steps. If you miss anything, the service may not work as expected.