Setting Up a Specific VoIP Connection

To use VoIP for alarm notifications, you must take the following steps:

  • Get a virtual phone number from a VoIP service provider. (ie. voip.ms)

  • Test it with a digital phone (a "softphone", ie. MicroSIP)

  • Configure VTScada to enable VoIP calls

  • Set up a roster tag

  • Test your configuration to ensure it works as expected.

In this topic we will set up a specific VoIP connection step-by-step, including testing and troubleshooting.

Get an Account with voip.ms

Get a virtual phone number from this paid service provider. This is the phone number VTScada will use to place calls and send texts. You must add funds to your account. The current minimum being $15USD. You may already have a VoIP phone number that is being used in another application. Be advised that using the same number or same account across multiple VTScada applications at the same time can lead to incoming calls and SMS messages being routed incorrectly. It is a best practice to use a separate account with a fresh phone number for each application. In the case of voip.ms you are able to create separate sub-accounts to avoid this complication.

Your SIP number is located on the Home Page:

This number is important, write it down and keep it handy.

Order a Phone Number (DID)

A virtual phone number is called a DID (That stands for Direct Inward Dialing). DIDs place calls from virtual devices through the telecommunications network to other devices or to real phones; If you have a DID assigned to your VoIP account, you can set it up to forward incoming calls (from VTScada) to another phone number such as a mobile phone or landline (ex. an operator's cell phone.)

A DID is like a virtual phone number

Find "Order DID(s)" in the DID Numbers menu at the top of the page.

From the menu, select an area. This will narrow down your options for phone numbers to local, familiar area-codes. You can select country, state/province/territory and city but beware, some smaller municipalities will not have phone numbers immediately available. You can still purchase one but it will be back-ordered and you must wait. Consider choosing another area such as a larger nearby municipality.

"Order Numbers" that are Carrier Order will be back-ordered. "View Numbers" means there is immediate availability.

You must select a server that will serve as an access point for your virtual number to the broader telecommunications infrastructure. These are called POP servers (Point of Presence) and may be referred to as a DID POP. It is a best practice to select one that is close to your actual location.

Appearances may vary

Your page might look something like this. Costs and locations displayed will vary depending on your selections and market conditions.

The last section, Routing Settings, can be left with default settings:

Confirm your order

View your DID number(s) and their current settings by navigating to "Manage DID(s)"

Set Up Call Display

Navigate to Account Settings

Find the General tab and for the CallerID Number field select "Use one of my DIDs"

Configuring a Password (OPTIONAL)


Note on Passwords: Customer Portal Password is the password you used to set up this voip.ms account. It works for logging into voip.ms AND accessing the SIP account UNLESS you configure Main SIP/IAX Password. If you configure a Main SIP/IAX Password, this will be the password you must provide to MicroSIP and VTScada during configuration. The reason one may take the extra step of creating a Main SIP/IAX Password is to try to resolve authentication errors.

Set Traffic to Encrypted

Navigate to the Advanced Settings. Change "Encrypted SIP Traffic" from No (Default) to Yes. Click "Apply All" to save.

Set up SMS (Texting) for your DID

To find the SMS/MMS settings menu go to Manage DID(s)

Find your DID and click the orange symbol to open "Edit DID"

Scroll to the very bottom to find a short section called "Message Service (SMS/MMS). Click "Enable SMS/MMS" to expand the section and reveal more options:

With SMS/MMS enabled, there are two more settings that must be configured.

  1. Link the SMS received to this DID to a SIP Account. Enable. Main account should be selected by default.

  2. If you are in North America, dialing Mode for SMS (3CX/API) must be set to NANPAClosed.

Once you have set up your account with voip.ms you should have the following:

  1. SIP Number (a six-digit number, ex. 413555)

  2. Password

  3. DID POP Server Name (ex. Montreal1.voip.ms)

Verify and Debug with MicroSIP

We have just obtained a phone number using a VoIP service provider. To test it, we want to make a phone call with it. So we will use an application to act as a phone that has been assigned this phone number.

MicroSIP is a lightweight, open-source VoIP softphone application that can allow users to make voice calls and send texts over the internet using the SIP standard.

The latest version of MicroSIP can be found at https://www.microsip.org/downloads

There are two settings that must be changed:

  1. Change Source Port to 5061

  2. Change RTP Ports to 10000 and 20000

We are going to add an account to our MicroSIP application that we will connect to our VoIP phone number. This account will contain the credentials needed to use this phone number and some configuration settings. Back in the MicroSIP drop-down menu select "Add Account..."

Click save and the window should close. If it is not closing you may have a typo. Check the bottom of the MicroSIP dial-pad for hints. It may say "wrong password" if your SIP number or password is incorrect. When everything has been filled out correctly and the encryption settings have been configured it will show a green phone with a padlock and the word "Online":

To test your configuration:

  1. Place a call on MicroSIP - This is placing a call with the phone number you purchased on VoIP.ms

  2. Send a text with MicroSIP - This is sending a text from the phone number you purchased on VoIP.ms

  3. Call the virtual phone number from another phone.

  4. Text the virtual phone number from another phone.

If you are unable to successfully send and receive calls and texts, do not proceed. Start from the beginning of these instructions and check each setting one at a time to ensure they have been successfully duplicated and saved. Some of the most common problems at this stage are either a typing error in a form field or unsaved settings on voip.ms.

When you are finished with MicroSIP, you must disconnect it. From the MicroSIP drop-down menu you will see "Make Active" with a little check-mark next to it. Click it to uncheck. The dialpad will no longer display "Online" in the bottom left corner, only a grey phone symbol next to the word "MicroSIP".

VTScada VoIP Settings

For an in-depth understanding of VTScada's role in setting up a specific VoIP connection see Using VoIP for Alarm Notification

To use VoIP for alarm notification you will need to configure three parts:

  1. Application configuration - to enable VoIP and manage application-wide VoIP settings.

  2. Create a roster tag - to catalog those who will receive a call/SMS and set a trigger event.

  3. User account settings - to set ID codes for each person who may receive a voice call.

VoIP Application Configuration

Open the application configuration menu, navigate to "Edit Properties" and, in Basic Mode, find the Alarms tab. Scroll to the bottom to find VOIP Settings. Here is a functional example of these settings configured:

  • Note that it is a best practice to select a workstation and not leaving the setting as "Default"

  • In VTScada, your SIP identity is formatted "MyID <sip:YourSIP#@YourDIDPOPServerName>"

  • Your SIP login user ID is simply your six-digit SIP Number.

  • Your SIP password is the password needed for VTScada to log into voip.ms (Unless you have configured a main SIP/IAX Password on voip.ms as described in this topic)

For some Advanced Configuration, switch to Advanced Mode and find the property called "VOIPPickUpDelay" This property sets the time interval from when a VoIP call is initiated until speech starts. The default is 10 seconds. You may wish to copy this property, assign to the VoIP workstation and set a shorter delay (ex. 2 seconds)

Create a Roster Tag

For more information about Roster Tags see: Roster Tags

  • ID tab: Fill in a Name, Area and Description.

  • Contacts tab: Select "[+] Add contact" from the bottom. Work through the options as they appear from left to right. See the Roster reference page for more detail.

  • Settings tab: You must set an activation trigger to tell the roster tag when to activate.

For testing purposes, start by configuring the roster tag to send one text and one voice call to a nearby device. In the following example, a delay has also been added to space the calls out.

In the settings tab, change the delay before notifying priority 1 and 2 alarms to 5 seconds during configuration to facilitate a speedy test cycle and then lengthen it back to a reasonable delay for regular use.

User Account Settings

If the user receives a text, it will include a one-time code that may be used to acknowledge the alarm. However, if the user receives a voice call they must enter an ID code to access the ability to acknowledge the alarm. This ID code is set in each user's account.

  • Navigate to Accounts from the title bar.

  • Select a user who will be on the roster.

  • Click on the ellipse [...] next to "Alternate Identification"

  • Set a numerical pin, ex. "5555"

  • Apply changes

  • Repeat for every user on the roster and provide them with their pin.

For more information see Accounts and Roles

Testing and Troubleshooting

Quick-Build a Test Page

Confirm the configuration can send voice and text alerts that can be acknowledged by the recipient. There is a widget that will generate a false alarm and widgets for monitoring the process. In Idea Studio, create a new page and add these five widgets:

  1. Roster Alarm Test - Found in Basic Components > Specialty > Roster Control. Link to roster tag.

  2. Export Comm Log Button - Found in Analytics > Diagnostics. Helpful for troubleshooting.

  3. Alarm List - Found in Tools > Alarm Tools. Change the database drop-down to "System Alarm DB"

  4. Alarm List - Same as before. Change the database drop-down to "System Event DB"

  5. Call Manager Status - Found in Tools > System Status Tools.

Check the "Roster Alarm Test" box and wait. Watch the System Alarm DB Alarm List to see the mock alarm and the System Event DB Alarm List to see events happening in real time. Keep your device handy to acknowledge the alarm. Ensure you try this with both voice and text.

VoIP Testing and Troubleshooting Page Example

Troubleshooting

If Roster Alarm Test places a call but the call fails, click "Comm Log". This will create a folder, VTScada > TraceFiles > VOIPLogs. Every time you click "Comm Log" a text file will be generated in this location containing logs. Search for "401" or "403". These are error codes for Unauthorized or Forbidden and may indicate two possibilities:

  • The log-in credentials haven't been typed correctly somewhere along the way. If MicroSIP was able to place a call but VTScada was not, try retyping the VOIP Settings in your VTScada configuration dialog. It is not possible to see the password as it is typed. If you are in a secure location, consider typing the password in a text editor (like notepad) where you can see that it is typed correctly and then copy and paste it into VTScada.

  • MicroSIP is still active and it is blocking VTScada's access to voip.ms.

If you can send a text but cannot acknowledge the alarm via text:

  • The TLS Settings are incorrect.

  • If you are sharing an account or a DID number with another application it may cause routing errors.

You're getting Authentication Errors

  • See the section of this topic about passwords. Try setting a Main SIP/IAX Password.

If it still doesn't work:

  • Use someone else's device to call your test device. It is possible that your location may impact your phone's ability to receive calls and texts.

  • Use this step-by-step guide as a checklist to revisit each setting. Pay special attention to saving/applying settings in voip.ms and VTScada. The most common errors are typing errors and save errors where the fields have all been filled out but they have not successfully saved.

  • Before submitting a support request: In Idea Studio, go to the properties dialog of the Export Comm Log Button widget and check "System Logs". Attempt a voice and text call-- which will still fail-- to populate the log. This will gather helpful information for the support team.

Related information:

Using VoIP for Alarm Notification

Roster Tags

Export Comm Log Widget

Alarm List

Call Manager Status Widget

Roster Alarm Test Widget