Voice Notification Profile (VNP) Configuration and Registration
Network is Unreachable: Datagram Send Failed
Dealing with Multiple NIC Addresses
Reviewing Network Traffic using Wireshark
Test Call Was Not Received By End User
alarm.Notifiation.Voice.CallManager
Issues during a Received Call by the End User
Using Telephony to Analyze VoIP Calls
Disclaimer: This troubleshooting guide does not cover all potential scenarios. This includes both the information and diagrams. Use this as a tool but understand that it's not guaranteed to provide you a solution.
This article will provide how to approach common issues related to the Voice Notification Module and its communication with VoIP Servers. It’s highly recommended to first familiarize yourself with basic VOIP terminology and concepts before reading this guide.
If you are attempting to understand the reason behind any thrown error during your test call’s execution, keep in mind that you are looking for where the test call’s execution process specifically fails based on the following steps:
- A Voice Notification Profile (VNP) is created in Ignition.
- Ignition’s VNP will attempt to register to the SIP gateway*.
- The SIP gateway will register with Ignition if configuration is correct*.
- Test call executed by user in Ignition.
- Ignition sends out a Session Initiation Protocol (SIP) request carried by UDP into the network.
- Here we are requesting the SIP gateway* to call users from a provided list of numbers.
- The SIP gateway* is able to receive the SIP request by listening to its open UDP port.
- The SIP gateway* notifies Ignition via SIP over UDP that it is going to dial out to users in the provided list.
- Once the call is established, Ignition streams Real Time Protocol (RTP) messages over UDP.
- This is where (Text-to-Speech) TTS scripts are passed with the appropriate audio conversions.
- If DTMF is configured properly between any intermediaries, DTMF presses should make it to the gateway from the caller.
Ignition loggers may or may not provide insight into failures at one or more of these steps. A Wireshark capture provides the most detailed information about possible response or network issues. However, it's important to perform all possible sanity checks during this entire execution process
Voice Notification Profile (VNP) Configuration and Registration
Regardless of any details in your VOIP troubleshooting, it’s important to first confirm that initial registration between your Ignition and VOIP server. Refer to the following flowchart to ensure that this is the case:
Network is Unreachable: Datagram Send Failed
One of the most common errors in the Ignition Diagnostic logs, Network Unreachable: Datagram Send Failed, is a result of a misconfigured Local Bind address. The Local Bind address determines the network interface used for establishing communication between Ignition and your SIP server. In order for a network interface to exist between the Ignition and your VoIP server, your overall network infrastructure must be configured to have an open UDP route between the VoIP server and at least one Network Interface Card (NIC) built into the Ignition server’s host machine.
Dealing with Multiple NIC Addresses
On your Ignition Gateway's Status Overview page, the right-hand side may display one or more available NIC addresses installed on the Ignition server's host machine. If multiple addresses exist, you must determine which one can reach your SIP server, as the VoIP Notification Profile (VNP) will choose one by default if a Local Bind address isn't specified. Depending on your network's scale, you may need to review the network infrastructure or consult a network administrator if you're unsure about the reachability of the available NICs on your host machine.
If network information isn't available, you might test all available NICs or use the tracert tool (assuming ICMP is enabled on your network) to see the route taken. These suggestions can quickly verify if the notification profile can register with the currently available NICs on your Ignition server.
Reviewing Network Traffic using Wireshark
The easiest thing to review from a wireshark capture is whether Inbound and Outbound traffic exists at all between your two endpoints.
- Outbound traffic is expected to be sent from the Ignition Gateway IP address.
- Inbound traffic is expected to be sent from the VOIP Server IP address.
The example above is a Wireshark capture of a successful test call where a single user was notified, the user answered, and acknowledged the call using a DTMF tone response before the call was ended. The capture filter for this example was specified as:
host {Public IP of Ignition Host Machine} and host {Public Hostname of VOIP Server}
Its important to note that RTP traffic is not presented in this example capture. Remember that without RTP traffic, no audio will be heard during the call.
When observing this capture, take note of the following:
- Lines 1 - 6 shows the initial INVITE request being sent by Ignition to a VOIP server (Outbound) and the VOIP server’s acknowledgement of that request (Inbound).
- Line 7 is an outbound message where Ignition is providing information about the user who will be notified (i.e. the user’s phone number).
- Line 8 is a typical outbound UDP message for the purpose of periodically “pinging” the VOIP server, unrelated to the test call execution process.
- Line 9 is an inbound message where the VOIP server is notifying Ignition that the call was ended.
Confirming the packets mentioned above will help you resolve any potential confusion on network interface or infrastructure misconfiguration. In the scenario of all monitored network interfaces containing little to no Inbound responses from your VOIP server, bring this information to your IT, network or VOIP server specialist to find out what else may be missing from your setup. Any issues with test calls after this confirmation will require a more in-depth look at your Wireshark capture.
Test Call Was Not Received By End User
Assuming your VNP was successfully registered to your VOIP server, you are ready to execute a test call. If your first test call is failing to reach end users, refer to following chart:
alarm.Notifiation.Voice.CallManager
In the event of an unsuccessful test call for any reason, check the Ignition logs for alarm.Notifiation.Voice.CallManager messages. Messages from this Ignition logger provide the most details of requests and responses between Ignition and the SIP Server that are expected during a phone call event as well as the most descriptive errors of this subsystem. Set this logger to TRACE before making a test call if you require the lowest level of details that Ignition can provide during its execution.
SIP Error Codes
Assuming your VNP is properly registered and a test call was attempted, any misconfigured properties from the notification profile are expected to result in SIP error messages that can be found in either Ignition Diagnostics logs or Wireshark captures. Please refer to this article for more information about response codes and their meaning.
Issues during a Received Call by the End User
Wireshark captures are required to assist you in narrowing down the details of an issue occuring during a call received by the end user. When inspecting a capture, keep in mind the three protocols mentioned earlier. They will contain information relevant to VOIP:
- UDP: Needed to confirm if transport layer messaging is successful.
- SIP: Needed for confirming initial VoIP registration and server requests.
- RTP: Needed for inspecting quality and transport of audio data and notification acknowledgement.
At this point in your troubleshooting, VNP should already be registered successfully and test calls should be making their way to end-users. If so, you will want to focus on any issues related to Text-To-Speech (TTS) or Real Time Protocol (RTP). This is because they are the fundamental pieces during phone call messages and end-user acknowledgements. Refer to the following chart if you are running into such issues:
Using Telephony to Analyze VoIP Calls
With a Wireshark capture monitoring a failed notification execution, you can begin investigating the time-stamped packets that occurred during various steps of the test call procedure. Wireshark has a useful feature for further analyzing the audio data by selecting Telephony > VoIP Calls. By selecting this tool, you have the option to playback the RTP stream, which is a recording of the audio message that is executed during the user’s phone call notification. This will help confirm if details such as TTS scripts and dial-tone acknowledgements are being sent through your network.
If you are planning to take a Wireshark capture with the intent of listening to an RTP stream, ensure that no capture filters are present before starting. This will ensure that any SIP, RTP, and UDP packets using one or more potential IP endpoints are visible for inspection. However, this will obviously make the entire capture harder to read if the VOIP related packets are not in focus. Specifying a Packet Filter for SIP or RTP packets only should help.
Media Debug Enabled
If you’re unsure if RTP is making its way between endpoints during a test call, setting the VNP settings Media Debug Enabled to true may help as one final confirmation of either VOIP or Ignition configurations preventing a successful call.
Media debug audio files are expected to appear in the Ignition directory after a successful RTP response from the SIP server. In terms of Ignition’s backend processes, MediaManager has an incomingRtpReader object which creates a file to hold the Media Debug recording. When incomingRtpReader starts, it should create the media file. This occurs once the MediaManager receives a successful response. If no media files are generated, you are more than likely failing to establish RTP communication. This can be verified with a wireshark capture.
Potential DTMF tone failure
If you run into the scenario of potential DTMF tone failure on the flowchart for this section, refer to the KBA on DTMF Troubleshooting for more information. The next section also includes other providers that may also help in isolating where the DTMF failure is occurring.
Poor Call Quality (Jitter)
Call jitter refers to inconsistencies in the amount of time it takes for voice data packets to reach their receiver. It is often confused with latency, but they are not the same. Latency is the overall delay before a transfer of data begins, while jitter refers to the variation in packet arrival times. This issue usually resides in the network between the caller and the recipient. To isolate which node in the network topology is causing the problem, utilizing other providers or recipient alternatives may provide further insights.
Calcentric is a free VOIP provider you can use (at the time of writing this article). This service is free when used with their own phone numbers.
Microsip is an open-source portable SIP softphone you can use to determine if the recipient's phone network is causing the issue. This software allows you to directly connect to any local or cloud SIP server.
While most jitter scenarios are network-related, there are times when the performance of the gateway or the host itself can impact packet delivery time, which will increase jitter. So it's important to make sure the host and gateway are overall healthy from a performance perspective.
Comments
0 comments
Article is closed for comments.