Soft Phone Troubleshooting and Diagnostics

Theory of Operation

The soft phone is implemented as a Web page that is served by the HQ Web site that also provides Director and Shoreware Web Access. The PC running the soft phone becomes an IP phone endpoint, and both TCP and UDP connectivity must exist between the PC and Shoreline switches.

Opens a window with the Internet Explorer ActiveX control. This window runs within the PCM process. A crash in either the EyeP control or IE, therefore, can bring down PCM. The EyeP control is serviced by an independent thread in PCM. If EyeP or IE hangs, the soft phone may become unresponsive but PCM will continue to function.

Once the soft phone window is open, the contents are loaded as a Web page. Problems with HQ server or network connectivity can prevent the page from being loaded.

The soft phone page contains the EyeP ActiveX control. This object attempts to reach the Call Agent(s) configured in Director. If a Call Agent is successfully contacted, the soft phone buttons are enabled.

When the Call Agent is contacted, Director detects that a new IP phone is being registered. Depending on licensing and IP phone port availability, a new port is automatically created the configuration database. The soft phone then appears under Individual IP Phones in Director.

If the Anyphone option is enabled, then PCM waits for several seconds for a corresponding IP phone port to appear in the configuration database after the soft phone window is created. If this times out, a warning message is displayed in the soft phone status bar that PCM was unable to Anyphone the user to the IP phone.

When the soft phone window is closed, or PCM is closed, the Anyphone operation is reversed to return the user to their home port. Even if the user was Anyphoned somewhere else before invoking the soft phone, they are still returned to their home port.

Troubleshooting

“Soft Phone” disabled in the PCM menu.
Ensure user is enabled to use soft phone on the Individual Users page.

After launching soft phone, buttons are grayed out. If the phone is disabled, PCM is unable to Anyphone the user.
The soft phone is disabled when it is unable to connect to a Call Agent. This is typically due to network connectivity. The soft phone does not work across firewalls and NAT. It should work across VPN if it is configured properly. If a machine has more than one IP address, the correct one may have to be manually selected. This can be done by clicking the Options button and examining the Network tab.

It is also possible that the soft phone cannot connect to a Call Agent because no switches are configured as call agents in the Director System Parameters page.

After launching soft phone, buttons are enabled. PCM is unable to Anyphone the user.
Buttons are enabled when the soft phone has connected to the Call Agent switch. However, an IP phone port must also be created for PCM to Anyphone the user. The reason an IP phone port cannot be created may be due to IP Phone licensing, lack of Call Agent for the IP phone’s site. Note that an IP address map may be placing the  The Windows Event Log indicates that there was a problem creating a phone port with event ID 2705 or 2706.

After launching the soft phone, buttons are disabled with no labels.
Buttons may be disabled because Javascript is not enabled in Internet Explorer. If the customer wants to restrict Javascript for general browsing (Internet zone), then the HQ Web site can be added to the list of trusted sites in the Internet Options Security tab.

After launching soft phone, buttons are enabled but no calls can be placed.
PCM and the Web browser may have established connectivity using TCP, however NAT, VPN, or other firewall issues may be blocking UDP. Open the soft phone Options dialog, go to the Network tab and ensure that Status is “Full internet access”. Ensure that the IP address shown on the Network tab has bidirectional connectivity to Shoreline switches and servers. For example, with VPN the external address being used by the soft phone may not have connectivity with Shoreline switches on the trusted LAN.

After launching the soft phone, display is blank or shows browser error.
The soft phone is served as a Web page by the HQ IIS server. If the IIS server is down or not configured properly, the soft phone page will not get loaded at all.

Phone calls are terminated after about 1 minute or less.
This may occur if there are separate Shoreline installations that are controlling the same phone. This can be verified if the same soft phone IP address appears in the Individual IP Phones page for more than one system. This situation may occur if a soft phone had failed to Anyphone, and the user then switched to a different system. Note that when the soft phone is launched from a URL, a port is automatically created for the anonymous phone. This soft phone port should be manually deleted when the phone is no longer in use. When launched using PCM, the soft phone port is deleted when the phone is closed.

Soft phone hangs, but PCM is still active.
As a workaround, try closing the soft phone window and re-opening it. If either EyeP control or IE are hung, this will restart them.

PCM on-hook dialing doesn’t work.
Intercom doesn’t work.
Both these features require programmatic hook-switch control via MGCP. This is not currently supported by the soft phone. The suggested workaround is to use a headset in hands-free mode and leaving the phone off-hook.

Changing soft phone options don’t work.
If the soft phone is not idle when option changes are made, they do not change current phone settings. This is because applying option changes require that the soft phone be reset – which would drop existing calls. The options changes are saved, and will take effect the next time the soft phone is started – for example, by closing and re-opening the soft phone window.

Calls not received at home port.
If were a crash or network outage that prevents normal shutdown of the soft phone window, then the user may still be Anyphoned to the soft phone port even though the soft phone is no longer running. The soft phone may also remain in the configuration database, and continue to use an IP phone license. The simplest workaround is to re-open and close the soft phone window which will re-home the user and remove the soft phone port.

Unused soft phone IP phones listed in configuration database.
This may occur if there is a crash or network outage as described above, and furthermore that the IP address of the machine using the soft phone changes. This may occur if a DHCP address is reassigned when a machine is rebooted. Then opening and closing the soft phone window will not clear out the old address. Manual deletion of unused ports is required in this case. Unused ports may also appear if the soft phone is launched using the raw URL. This automatically creates an anonymous IP phone port in the configuration database.

Soft phone rings using speakers even when USB headset is selected.
The soft phone always plays a ring tone using the “Windows preferred audio device”. This behavior is by-design and supports smooth operation when both speakers and headset are available. If ringing were played to the headset or handset, it is likely that the user would not be able to hear it.

If there is more than one audio device, such as when a USB headset is installed, the Audio tab of the Options dialog can be used to choose which device is used for telephony conversations. The device selected in the soft phone Options is always used for conversations.

The Windows preferred audio device is changed using the “Sounds and Multimedia” control panel:

For example, if the user wants all audio including ringing to be played using the headset. The preferred audio device can be set to the headset, and the soft phone Audio options can be set to use the same preferred audio device.

Microphone volume setting changes or is reset.
The user may adjust the volume level for the microphone and later find out that the volume level has changed. The soft phone provides automatic gain control (AGC) for the microphone. When AGC is in operation, the volume slider for the microphone is automatically adjusted by the soft phone.

AGC can be disabled by going to the Audio tab and selecting “Telephone” as the Device Type. Note that PC audio is poorly standardized. The default AGC setting works OK for many PCs, but manual setting may be required in some cases.

Collecting Diagnostics

When the soft phone window is the active window, a diagnostic window is available by hitting ctrl-F12. The contents of this window can be sent via email if a MAPI client (such as Outlook) is installed on the machine. If not, the contents of the window can be copy-and-pasted as text into a file.

A sample debug window is shown below:

If the soft phone window does not come up under PCM, it may be useful to run the soft phone from the raw URL. The URL is http://<hqserver>/shorewaresoftphone. If the URL works, then the problem lies in how the soft phone window is launched by PCM. Note that the soft phone IP port corresponding to the PC should be deleted manually after this test is completed.

Soft Phone Crashes

The EyeP control typically catches its own exceptions and displays a dialog box that looks like:

If the crash dialog references any module beginning with “EMM”, then this indicates an EyeP crash.

With any kind of crash, it is important that Dr. Watson be enabled. This can be done by running the following from the command line: “drwtsn32 –i”.

Running Dr. Watson with no command line parameters displays the following dialog. The location of crash dump files is indicated by the dialog.

EyeP Monitor Tool

The soft phone vendor provides a tool to collect traces. It is installed using a conventional Windows install program. After it is installed, the PC must be rebooted.

By default, the trace depth provided by the tool is 40000. With RTP media streams, this is only about 4 seconds of traces. For startup or shutdown problems without media, the default is usually enough. The default can be changed using the Options | Buffer Size menu. 500000 is a reasonable setting with modern machines that have a lot of memory.

When collecting a trace, first clear the buffer with File | Clear Buffer. Then open the soft phone window. This captures the phone initialization in the trace. Perform the test, and then save the buffer. The saved trace is just a text file and can be compressed considerably using ZIP.

This tool is available from: \\bigsur\installs$\Engineering\EyeP\Monitor

Manual Version Update

When the soft phone window is launched initially, an ActiveX control is downloaded and cached when the user accepts the security dialog. To ensure that a fresh copy of the control is installed the cached copy can be removed by opening IE | Internet Options…
On the General tab, open Settings under Temporary Internet files. Then open View Objects… Select EMMgcp Class and delete it.