Serial Box

System Access

The Serial Box can be accessed via:

1. Web GUI: the web-based GUI is where all setup and configuration of the Serial box takes place.

2. SSH: This is the command line interface to the Linux operating system. It’s rarely used but some items in the How-To section refer to it. Phonesuite support can always be contacted to offer assistance in interfacing with the Linux OS if needed.

General Terms

• Serial Box: A device that allows communication between an on-premise serial based PMS system and a hosted Voiceware system

• Voiceware: A hospitality specific IP based phone system. Basically, Voiceware is a Linux based computer application that manages all phone calls for a hotel.

• PBX: Stands for Private Branch Exchange, general term used to refer to a system that allows calling without interfacing with the local telephone company. Voiceware is a hospitality specific PBX.

• PMS: Stands for Property Management System, this is the main core computer system in a hotel. This system manages all guest information and interfaces with other system as needed to send and receive guest related data. Voiceware often interfaces with a PMS to receive check in/out data and guest names, we also send to the PMS information about billable calls a guest makes.

Networking Requirements

                The Serial Box communicates with the hosted Voiceware system on port 8080. Both firewalls (the on prem and hosted) will need to have port 8080 open and have ACLs setup to ensure only communication from trusted IPs is accepted.

Open

Q: Checking in a guest does not display any data in the Serial Box debug screen

A: Ensure that the serial cables are connected and that the baud rate and related settings are set correctly. Remember that the Serial Simulator (a free program available on the Phonesuite website) can aid in testing serial cables.

Q: Checking in a guest displays in the Serial Box debug window but does not appear on the hosted Voiceware system.

A: Ensure that the settings.ini file has been set with the public IP of the network the Serial Box is connected to. Also ensure that the Additional Settings in the correct IP address listed for the hosted Voiceware system. Lastly ensure that port 8080 is open on BOTH firewalls (hosted and on prem) and that port forwarding lists the correct local IP addresses.

To test that everything has been setup correctly issue the SSH command "telnet <Proxy IP> 8080" from the hosted system using the IP of the Serial Box. If everything has been setup correctly you should see:

root@ip-10-169-89-240:~# telnet 12.34.56.78 8080

Trying 12.34.56.78...

Connected to 12.34.56.78.

If it does not work you should see:

root@ip-10-169-89-240:~# telnet 12.34.56.78 8085

Trying 12.34.56.78...

TCP/IP can be used with the serial box, however its a bit out of scope. If you have a TCP/IP interface you can normally just connect it directly to the PBX and there is no need for a Serial Box. However if you have a need below is how to set it up.

1. Setup the interface as Serial and select the correct protocols

2. Copy the below lines of code into the Additional Perpetrators box

3. Click save and restart then test as normal.

[pbx-method]
interface=client
server=1.3.5.7
port=5566
idlemax=300

[ca-method]
interface=server
port=5558
idlemax=300

Connectware Settings

Log into Connectware and to the domain.

Navigate to Hotel → Serial Devices

Add a new device using the devices local IP address as the name and the devices MAC address.

Open

Serial Box Settings

Log into the Serial Box at unconfigured-pmsi.local (must be on the same network) and set the Voiceware Server URL to https://phonesuite.connectware.cloud/api/serial/xml?mac=e45f01aaaaaa

Note that after configuration the access URL will change from “unconfigured-pmsi.local” to  “<sitecode>-pmsi.local” (i.e. blfce.pmsi.local).

Set the serial settings for the PBX and/or Call Accounting interface as defined by the PMS vendor.

Click Save & Restart to apply the changes.

Testing

Look in Connectware, the status of the Serial Box should show as Online. Use the Test XMLRPC commands found here PMS Interface to ensure that check in messages are sent to Connectware.

This page describes the legacy method of connecting the Serial Box to Connectware Hospitality, for the updated method see the Cloud Connect (MQTT) section.

A serial box can be used on Connectware Hospitality with a very simple setup.

Connectware Setup

Go to the domain and then the hotel tab for that domain.

Open

Next go to the Serial Devices tab.

Open

Click Add Serial Device.

Open

Set the name as “Serial Box” and enter the devices MAC address (no colons) and click save.

Open

Once added it should look like this:

Open

Serial Box

Log into the Serial Box and go to the PBX/CA Configuration page.

Under Additional Settings box enter the below URL replacing the MAC address at the end for the correct MAC address.

https://phonesuite.nlvlabs.com/api/serial/xml?mac=112233445566

Click Save ALL.

Open

When the service restarts the Monitoring/Debug page should display the below lines if the Serial Box connects correctly.

08:56:05 0 GENRL 01 XMLRPC clients use: https://phonesuite.nlvlabs.com/api/serial/xml?mac=112233445566
08:56:05 0 RPCCL 01 Checking for PSip XMLRPC Server...
08:56:05 0 RPSVC 03 Calling PSip with XMLRPC are_you_there(10001)
08:56:05 0 RPRSP 03 Result of XMLRPC call is 0

Next check in Connectware and it should display as Connected.

Open

Test a check in message and ensure that the correct name displays in the rooms page.

• Connect the Serial Box to the local network

• Connect the Serial Box to power

• Connect the Serial Box to at least one serial interface from the PMS

• Enter “unconfigured-pmsi.local” into a browser (note, you must be connected to the same network the Serial Box is connected to)

  • Note that after configuration the access URL will change from “unconfigured-pmsi.local” to  “<sitecode>-pmsi.local” (i.e. blfce.pmsi.local).

Serial Box Setup

1. Log into the Serial Box using “admin” and “password” as the login

2. Navigate to Administration and set the units Site Code and Static IP address settings

3. Once set log back into the Serial Box using “<sitecode>-pmsi.local”

4. Change the default password.

5. Navigate to PBX / CA Configuration and set the PBX and/or CA ports with the correct serial and protocol settings.

   1. Note these settings vary based on the how the PMS is configured, Phonesutie will not be able to determine what these should be set to, contact the PMS vendor.

6. Click Save ALL

7. Under additional settings enter http://<ip>/phonesuite/xml-rpc.php?action=PMS where <ip> is the IP address of the HOSTED Voiceware system (i.e. http://1.2.3.4/phonesuite/xml-rpc.php?action=PMS)

8. Click Save ALL

Local Firewall Setup

Add a rule to accept traffic from port 8080 and direct it do the Proxy Voiceware system.

Hosted Voiceware Setup

Edit the file /data/asgi/settings.ini - Under the section "[PMS]" change the IP address from 127.0.0.1 to the public IP address of the Serial Box - Disable both PBX and CA interfaces - Make sure the PMS interface is enabled on the settings page - Click Save/Restart for the PMS interface.

Testing

To test that everything has been setup correctly issue the SSH command "telnet <Proxy IP> 8080" from the hosted system using the IP of the proxy system. If everything has been setup correctly you should see:

telnet 12.34.56.78 8080

Trying 12.34.56.78...

Connected to 12.34.56.78.

If it does not work you should see:

telnet 12.34.56.78 8085

Trying 12.34.56.78...

To test simply check in a fake guest at the property and ensure that the message is received by the Serial Box then ensure that the guest is visible on the hosted Voiceware system.

The Serial Box ships set to DHCP and it’s recommended that the address be set to Static.

To log in:

1. Connect the Serial Box to a network using the 19.168.1.0/24 subnet.

   1. If a network setup with this subnet is unavailable set a laptop or desktops to have a static IP address of 192.168.1.50. Then directly connect the computer to the Serial box and navigate to the address of https://192.168.1.223 or unconfigured-pmsi.local

2. Upon reaching the login screen enter the username “admin” and password “password”.

Open

This page handles the setup of the serial PBX and CA (call accounting) interfaces.

Open

Disabled / Enabled

These buttons set the interface to active or inactive. There are situation where a hotel might have a PBX interface but not a CA interface. In that case the CA interface should be set to disabled.

Protocol

Allows selection of the different protocols available. Normally there will be a protocol for the type of PMS that is being interfaced with (Opera, FOSSE, OnQ, etc). A full description of the interfaces and a short description of each can be found in appendix A.

Port Selection

Each of the two ports on the Serial box are labeled, 1 and 2. Normally the PBX interface will be plugged into port 1 and the CA into port 2. If needed however this can be changed here.

Baud Rate

This is the speed of the connection. This much match what the PMS vendor has set for the interface on their end. Normally this is set for 1200 or 9600. Consult the PMS vendor for what baud rate should be selected.

Data Bits

This setting must match what the PMS vendor has set on their end. This setting refers to how many data bits are in each character. 8 is by far the most common default, 7 is used only for very old equipment or unusual setups. Its normally okay to assume this is set to 8.

Parity

Normally set to “None”, sometimes referred to as “N”. Parity is a way to check for errors in data transmission. If set to Odd then an extra data bit is sent with each character such that the number is always odd. Thus, if the data is received with the wrong number of 1s then the data is known to be corrupted. However, an even number of errors using this method is undetectable. The same is true for setting this to Even (along with an odd number of errors being undetectable).

Stop Bits

Normally set to 1. The stop bit is sent at the end of every character so that both sides remain in sync and able to pass data. Its normally okay to assume this is set to 1.

Reset

This button resets the values to default.

Save PBX/CA Only

This button saves only the PBX settings and resets the interface to apply the changes.

Save ALL

This button saves all changes on the screen and resets the interface to apply the changes.

Open

Voiceware Server URL

Here the IP address of the hosted Voiceware system is set. Note that the only thing to change is the IP address (1.2.3.4 in this example) leaving the rest of the string intact.

http://1.2.3.4/phonesuite/xml-rpc.php?action=PMS

Extra Parameters to be added at the end of the configuration file

At times additional settings, or changes to defaults in the selected template file need to be made. Examples include padding a leading 7 on otherwise three-digit room numbers for the call accounting interface or using a slash (/) character as the delimitator in guest names.

Additional parameters can be overrides to any section of the PBX or CA interface. This is very powerful and only a few examples of how those functions work is provided below. Note that you must enter “[ca-masks]” or “[pbx-masks]” on a separate line before the special parameters you wish to use.

At times PMS venders will use either a comma, slash, or space to separate guest names. By default most PBX interface protocols use a comma, to change this add the below to the additional parameters field and then click Save ALL.

[pbx-masks]

chkdelim=11 20 MASK_LITERAL /

namdelim=6 20 MASK_LITERAL /

If a space is being used add the following.

[pbx-masks]

chkdelim=11 20 MASK_LITERAL SPACE

namdelim=6 20 MASK_LITERAL SPACE

Common entries include:

• email=[address] (i.e. email=Admin@HolidayInnBlackCannyon.com). This email address is used to send billable calls should the call accounting interface become unavailable so the call can be posted to the guest record manually.

• strip=1/0 [True/False] (i.e. strip=1, default is 0). This will strip all leading 0 and 1 off the beginning of the number dialed.

• format=1/0 [True/False] (i.e. format=1, default is 0). This will format the dialed number into NPA-NXX-XXXX, works best with strip=True (above).

• incoming=1/0 [True/False] (i.e. incoming=1, default 0). If set to true Voiceware will pass incoming calls to the PMS.

• admin=1/0 [True/False] (i.e. admin=1, default 0). If set to true then Psip-PMS will send admin calls to the PMS. Default is false.

• zero=1/0 [True/False] (i.e. zero=1, default is 0). Setting this to true will send all zero cost guest calls to the PMS. For admin calls see admin= above.

• checkinmessage=n (i.e. checkinmessage=2). Automatically places drop in message two into a guests mail box upon check in. This is a PBX mask.

Once finished a set of parameters might look like this:

[pbx-protocol]

checkinmessage=1

[ca-protocol]

admin=1

incoming=1

Open

Each item in the Protocol list is a separate file describing the interface between Psip-PMS and the PMS system. These files can be updated by clicking on the Update Interface Files button. This update should take no longer than 1 minute and should generally only be done upon instruction of Phonesuite. If the button is clicked and no updates are available all existing interface files will be preserved without changes.

Open

This screen allows monitoring of the PMS interface or commands to be sent.

Pictured above is a recent PMS interface reset. Each color of text represents different functionality or information, they include:

• Green: System reset / log file read in.

• Yellow: System process

• Blue: communication between the Serial box and the outside world or setup of the interfaces.

• Pink: TCP/IP messages (port open, unable to connect, etc)

There are also numbers associated with each line item, they are:

• 0 – Main Process

• 1 – PBX-PMS process (listen for message from PMS)

• 3 – XMLRPC Server (listen for messages from Voiceware)

There are many commands that can be issued along with an example of each, they are:

• Test Serial Areyouthere

  • Test Serial Areyouthere

• Test Serial Dosynch

  • Test Serial Dosynch

• Test Serial Status <room> 0|1|2|…|9

  • Test Serial Status 101 1

• Test Serial Message <room> 0|1

  • Test Serial Message 101 0

• Test Call

  • Test Call

• TRACE (issue command again to turn off)

  • TRACE

• Test XMLRPC Areyouthere

  • Test XMLRPC Areyouthere

• Test XMLRPC Sync [0|1]

  • Test XMLRPC Sync 1

• Test XMLRPC Checkin <room> <[name]>

  • Test XMLRPC checkin 101 Frost, Emma

• Test XMLRPC Checkout <room>

  • Test XMLRPC Checkout 101

• Test XMLRPC Name <room> NAM0|NAM1|NAM2|NAM3 <name>

  • Test XMLRPC Name 101 NAM2 Frost, Emma

• Test XMLRPC Move <room> <newroom>

  • Test XMLRPC Move 101 205

• Test XMLRPC MWI <room> [0|1]

  • Test XMLRPC MWI 101 1

• Test XMLRPC Dnd <room> 0|1

  • Test XMLRPC Dnd 101 0

• Test XMLRPC Restrict <room> 0|1|2|...|9

  • Test XMLRPC Restrict 101 2

• Test XMLRPC Wakeup <room> <time>|9999

  • Test XMLRPC Wakeup 101 0830

Note that for common commands just the first letter of each command needs to be entered. For example, a test call can be created by typing “t c”, an are you there by typing “t s a”. It’s recommended to spell out the more complex commands fully.

This section is where network and password settings are changed.

Open

Site Code

Enter the sites code (sometimes called a property code) here. If no code exists make up a code for the hotel. Once set access to the system will be at <sitecode>-pmsi.local

Method

Select Static (recommended) or DHCP.

IP Address/Subnet (CIDR Format)

The IP address of the device should be entered here using the CIDR notation. For most networks this is a /24 or /16. For more information about CIDR formatting including calculators that will calculate a CDR notation for a given network see IP Subnet Calculator or Subnet Calculator - TunnelsUP .

Gateway

Enter the gateways address here.

DNS Server

Enter the DNS server or servers here. If entering more than one separate the individual IP addresses with a space as seen in the screenshot above.

Save

When finished click the save button. A popup will appear saying that any network changes require a reboot of the system. Click okay and wait for the system to come back online (a process taking 1-2 minutes).

Open

This section is not currently in use. Do not configure.

Open

Restart

Click this button to restart (reboot) the Serial Box. This process takes 1-2 minutes.

Factory Reset

Click this button to reset the system to factory defaults. This will require a system reboot.

Open

This section is used to change the system password.

Current Password

Enter the current password here.

New Password

Set the new system password here.

Confirm New Password

Confirm the new password here. Note that the new password and confirm password must match before the Save button will become active

Save

Click here to apply the new password settings. Note you will be required to log back into the system after this operation.