Changes in 4.6.0 Update 1 Provisioning for Polycom

Overview

4.6.0 Update 1 introduces support for Polycom 4.0 firmware. It also discontinues support for firmware revisions below 3.1, as well as for phones SPIP 300 and 500. Update 1 also introduces the ability to configure multiple versions of Polycom firmware. Configuration support for VVX 500 and 600 models is also introduces as part of this update.

SPIP 300/301, 500/501 models

4.6.0 Update 1 discontinues support for firmware older than 3.1. However models SPIP 300 and SPIP 500 will continue to work with sipXecs. Most probably in a future release, support for those phones will be removed.

Models SPIP 301 and 501 are able to work with firmware up to 3.1.8, thus they are still supported.

Administrators will have to specify the phone version when adding/configuring a new or existing Polycom model. Firmware versions currently defined are 3.1.X , 3.2.X and 4.0.X. In the future maybe finer grained versioning will be defined if necessary. In earlier sipXecs versions all Polycom phones are defined as having firmware version 2.0. There are both an automatic and a manual procedure to migrate the phones to the new system and to the correct firmware version. Both are described below.

Multiple Polycom firmware versions can be activated simultaneously. An administrator can define multiple phones or groups of phones with different versions. Firmware applications together with whatever files packed in the zip archive downloaded from Polycom site will be unpacked in specific folders in tftproot. In previous releases of sipXecs only a single version of Polycom firmware could be active at one time.

Note that by multiple versions we understand at most one firmware per major version defined. For instance we will not be able to have 3.2.6 and 3.2.7 versions deployed at the same time, since they would both go to tftproot/polycom/3.2.X folder.

Paired models in 4.6.0 and earlier

In 4.6.0 and earlier releases of sipXecs some phones were defined as paired models, since they had the same configuration. In 4.6.0 Update 1 the models have been split. On migration to 4.6.0 Update 1, phones will be able to automatically pick up the correct model. Also a combo box was added in the phone's page for the specific models, in order for an admin to be able to manually choose the correct phone model.

The models are (all phones are SPIP):

300 / 301
500 / 501
600 / 601
550 / 560
320 / 330
650 / 670

Before you update

Here are some things you need to know before upgrading 4.6.0 to 4.6.0 Update 1. All of them will be explained in more detail in this wiki page

All Polycom device files installed will be deleted. You will need to re-upload them.
After update all Polycom phones will reboot twice in order for configuration database to be updated with the correct firmware revision installed on them (and model if it's the case), and generate the correct profiles for them.
Provision role must be enabled and firewall rules must allow phones to contact provision port (8185) for the automatic procedure to take place.
In case automatic update procedure fails you will be able to manually update phones via phones page, or using groups.
It is important that you install different firmware revisions in their respective folders.
While not forbidden, it is not recommended to have multiple bootroms deployed at any one time.
It is possible to have different phones with different firmware revisions installed, however you must exercise caution since a phone will pickup latest bootrom deployed if it is compatible with the phone, and some SIP images are not compatible with some bootroms (for instance 3.2 image is not compatible with Upgrader). In this scenario we recommend deploying a bootrom only when needed (for instance when a phone is added to the system). On the same note, a phone with 4.0 revision will not downgrade itself to 3.2.

Installing firmware

Older Polycom Device Files

Please note that Polycom device files installed in 4.6.0 (be it active or inactive) will be deleted on upgrade. Admins are advised to re-add the device files for the wanted firmware.

The Device files interface for Polycom firmwares has not changed visually, except for adding a new Version field - a combo with "3.1.X", "3.2.X" and "4.0.X" values. An admin should choose the correct version of the firmware installed. By doing that the admin will ensure the firmware will be unpacked in the correct folder.

Phones and versions are connected through the phone's Firmware version field. A phone that has "3.2.X" version will look for the SIP application in the tftproot/polycom/3.2.X folder - the [MAC].cfg file is configured to accommodate this. Configuration files are kept in the tftproot folder just like before 4.6.0 Update 1.

Admins can deploy multiple (major) firmware versions. You can have a 3.1.X, a 3.2.X and a 4.0.X firmware deployed for the situation in which there are multiple phones with different firmware versions.

Installing bootrom

Deploying Multiple Bootroms

While not disallowed by sipXecs, it is strongly discouraged to have multiple bootroms deployed.

To install a bootrom you need to upload and activate the bootrom in any of your Polycom device files or create a separate device file for it. Bootrom files will be unpacked in tftproot folder, and not in a firmware folder (like polycom/3.2.X). The reason for that is that a phone will look only in the root folder for the bootrom.

Migrating from 4.6.0

Please note that Polycom device files installed in 4.6.0 will be deleted after upgrade in 4.6.0 Update 1. This is due to the fact in the new schema device files would go to a version specific folder, and sipXecs would have no way of knowing what version of firmware is deployed. Administrators are advised to reupload the Polycom device files.

Automatic migration

After updating to 4.6.0 Update 1 phones will reboot twice. The first time the [MAC].cfg will be changed in order to instruct the phone to contact the provisioning servlet. The provisioning servlet will read the correct firmware installed on the phone (using the User Agent header of the phone's request) and then via a sipXconfig REST service will update the phone's firmware version in the database. On second reboot sipXconfig will generate the correct config files which phones will pick up. Both reboots are scheduled after 1 minute to give phones time to register.

Auto-provisioning Role and Firewall

Phone Auto-Provisioning role must be enabled in order for the automatic migration to take place.
Also make sure that firewall rules do not prevent phones from contacting provisioning server which by default runs on port 8185.

Manual migration

If somehow the automatic procedure fails for some of the phones (for some reason the phones could not have been rebooted, for example they were not registered at the time of the migration) admins may try to manually reboot the phones (listed in the failed jobs table). Phones should pick up the correct version and configs.

If, for instance some phones are behind a network and firewall rules prevent them to reach auto-provisioning servlet, or the auto-provisioning role is disabled, the phones might not function properly (they might keep rebooting), and admins will have to take some actions to bring the phones back up. The most important is to generate the correct profiles for the phones. In order to do so, admins will have to choose the correct firmware the phones have installed or upgrading to a greater version (check out below to see how to bulk upgrade a group of phones). For particular models admins must choose correct model first, in order for the list of the supported firmwares.

Bulk updgrading Polycom firmware on phones

The easiest way to do this is by using phone groups and a newly introduced setting "Group Firmware". Suppose you have a bunch of phones - say 50 SPIP 335s all with 3.2.6 firmware - you can place them in a group (or use existing groups the phones are in), click on a Polycom model (any model), edit the group and go to "Group Firmware". Here select the correct version in the Group Firmware > Firmware version update - 4.0.X and hit Apply. On Apply, all phones in the group will be saved. After that, you need to send profiles to the phones; 4.0.X configurations are created which phones will pick up on reboot.

It is important to note that you need to change "Firmware version update" and not the field "Firmware version" since the latter is not saved in the group settings and it is used to present correct settings based on the selected phone model. (For instance different models might have different set of codecs.)

In the scenario where you already have a group with phones that have different firmwares, create different groups for all the versions and then use the above procedure to update the phones firmware versions. You may delete the groups after doing that.

Applying a version to a group will update all the phones in the group with the specified version. You might not want to do that if you have phones with different versions in the group.
If you do not want phones firmware to be updated just leave the Firmware version update field blank (select blank option).

If in a group there is a phone that does not support the chosen version, its version will not be changed.

Upgrading to 4.0

In order to upgrade a phone to 4.0.X firmware you must deploy a special bootrom and, of course, the 4.0 firmware. The special bootrom is called Upgrader, and the latest 4.0 firmware is 4.0.3F (use split and not combined!). You can download them from Polycom site:

http://support.polycom.com/PolycomService/support/us/support/eula/ucs/UCagreement_combined_4_4_0_upgrader.html

http://support.polycom.com/PolycomService/support/us/support/voice/polycom_uc/polycom_uc_software_support_center.html#4.0.3F

After deploying the 2 items, when restarting the phone, the phone will pickup the new bootrom and sip.ld and will upgrade to the new firmware.

You must change the phone version to 4.0.X in order for a phone to be upgraded. Failing to do so might render the phone unable to start due to the fact it will pickup the new bootrom and try to find a suitable sip.ld in a folder other than 4.0.X, however any other sip.ld is incompatible with the phone new bootrom. you might get "Image is incompatible with the phone" error on the phone.

Downgrading

Downgrading is currently not a supported procedure on sipXecs 4.6.0. It can be done and the procedure is documented on Polycom site. Basically, in order to downgrade a phone from 4.0 to 3.2 one must deploy another special SIP application called Downgrader which will downgrade the phone to 3.3.5 firmware revision, and only after that deploy a 3.2 firmware.

You can follow these steps:

Download the downgrader from Polycom site. You can find it here: http://support.polycom.com/PolycomService/support/us/support/voice/polycom_uc/polycom_uc_software_support_center.html
Deactivate all Polycom device files.
Create a new Polycom "Device files" and upload the Upgrader on the SIP Application (zip) field and under 4.0.X firmware (we assume all phones needed to be downgraded are at 4.0.X firmware revision). (Leave the Bootrom field blank.) (Use common sense, if phone is actually 3.2.X in sipXconfig database, upload it under 3.2.X firmware.)
Reboot phones. NOTE: if you have phones with 4.0 firmware which you do not want to downgrade, make sure you do not reboot them.
Phones will pickup the new bootrom and firmare (3.3.5).
Create another Device files (or activate it if you already have one) with 3.2 firmware. I used 4.3.1 bootrom, and 3.2.6 firmware. Make sure you set the correct firmware version (3.2.X).
Change the phone(s) firmware version (either from phone or from group).
Send profiles to the phone(s).
Phone(s) will reboot and pickup the bootrom and firmware.

NOTE: phones might reboot a couple of times after it gets new bootrom / SIP app / configuration. I don't know exactly if there is a pattern, but just keep this in mind.

Important

If you have a phone compatible with 4.0 but you DO NOT WANT TO UPGRADE it to 4.0 and keep it to 3.2 (or 3.1) version, you must make sure you do not keep the Upgrader deployed. If you do so, on reboot the phone will pickup the new bootrom and try to find a compatible image in the 3.2.X or 3.1.X folder. Those images are not compatible with the upgrader, and you will get a "Image is incompatible with the phone" error.

Upload as many bootroms as you like, but do not keep any of those deployed except when you are upgrading a phone or a group of phones. This will prevent unwanted phone upgrades.

Auto provisioning a phone out of the box

An out of the box phone (or any phone that has not been configured in sipXecs), will contact the server to download the configuration file, and, if since this is not found will download the Polycom master configuration file (000000000000.cfg). In this file the default firmware revision for Polycom phones is 4.0. Thus phones will try to download the sip.ld file corresponding to that revision.

<APPLICATION
               APP_FILE_PATH="polycom/4.0.X/sip.ld"
...
</APPLICATION>

For this, administrators must make sure that they have a 4.0 revision deployed together with a compatible bootrom.

Phones that are not compatible with 4.0 revision are defined in specific sections of the master configuration file.

Phone	Revision
SPIP 300	3.1
SPIP 301	3.1
SPIP 500	3.1
SPIP 501	3.1
SPIP 4000	3.1
SPIP 600	3.1
SPIP 601	3.1
VVX 600	4.1

Above notes apply also for a phone that has been formated.

Common problems (and solutions)

Problem: Phone keeps rebooting and displays "Misc file error"
Solution: On phones page choose correct model, installed firmware, apply changes and send profiles
Problem: Phone keeps rebooting and displays "Image is incompatible with the phone"
Solution: Bootrom and sip.ld are incompatible. Most likely Upgrader is deployed as bootrom, and phone is set to 3.1.X or 3.2.X. On phone's page choose 4.0.X and reboot the phone. Make sure a 4.0 image is deployed (active).

Experimental 4.1 support

We have introduced in 4.6.0 Update 1 support for phones using 4.1 firmware revision. It is possible to upload 4.1 device files in their folders. The configuration profiles are generated based on 4.0 profiles.