System Access

The Serial Box can be accessed via:

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

SSH: This is the command-line interface to the Linux operating system. It's rarely used.

General Terms

Serial Box: A device that allows communication between an on-premise serial-based PMS system and a Hosted Voice system

UC Hospitality: A hospitality-specific IP-based phone system. UC Hospitality is a Linux-based computer application that manages all phone calls for a hotel.

PBX: Private Branch Exchange, a general term for a system that allows calling without interfacing with the local telephone company. UC Hospitality is a hospitality-specific PBX.

PMS:  Property Management System. This is the main core computer system in a hotel. It manages all guest information and interfaces with other systems to send and receive guest-related data. UC Hospitality often interfaces with a PMS to receive check-in/out data and guest names; we also send the PMS information about billable calls a guest makes.

Networking Requirements

The Serial Box communicates with the UC Hospitality system on port 8080. Both firewalls (the on-prem and hosted) must have port 8080 open and ACLs set up to ensure only communication from trusted IPs is accepted.

Important: Opening port 22 is not normally needed and is a frequent point of attack. Never open port 22 without a strong Access Control List (ACL) in place.

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

A: Ensure the serial cables are connected, and the baud rate and related settings are set correctly.

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

A: Ensure that the settings.ini file has been set with the public IP of the Serial Box network. Also, ensure that the Additional Settings are in the correct IP address listed for the UC Hospitality system. Lastly, port 8080 must be open on both firewalls (hosted and on-prem) and port forwarding lists the correct local IP addresses.

To test that everything has been set up correctly, issue the SSH command "telnet <Proxy IP> 8080" from the hosted system using the IP of the Serial Box. If everything has been set 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, it's a bit out of scope. If you have a TCP/IP interface, you can typically connect it directly to the PBX, and there is no need for a Serial Box. However, if you need, below is how to set it up.

1. Set up the interface as Serial and select the correct protocols
2. Copy the lines of code listed below into the Additional Perpetrators box
3. Click save, restart, and then test as usual. 

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

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

Settings

Log in to UC Hospitality and go to the domain.

Navigate to Hotel → Serial Devices.

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

Serial Box Settings

Log in to the Serial Box at unconfigured-pmsi.local (must be on the same network) and set the UC Hospitality 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 UC Hospitality. The Serial Box's status should show as Online. Use the Test XMLRPC commands, listed below to ensure check-in messages are sent to UC Hospitality. 

XMLRPC

Psip communicates with UC Hospitality using a protocol called XMLRPC. More about this interface can be found using the below URL on any UC Hospitality system, swapping out the <ip> with the IP of the system. All XMLRPC interfaces for all versions of UC Hospitality are the same. 

http://<ip>/phonesuite/xml-rpc.php?action=PMS

Live logs of all XMLRPC calls can also be viewed from the command line interface with the below command.

ngrep -q -d any -W byline '' tcp port 8080

Call Accounting

UC Hospitality can connect to many different call accounting (CA) systems. Below is a description of the default HOBIS format. Some PMS vendors use the HOBIS method, while others have their own format. Use whatever protocol file best matches the PMS that is being interfaced with or HOBIS if there is no match found.

Following that there is a listing of all additional parameters that can be added to the CA interface to alter how data is sent to the PMS system.

HOBIS

This Interface Protocol is based on the original AT&T* HOBIS-to-PMS Interface and is employed by more than 90% of Property Management Systems.

With this protocol, records are sent in a typical Enquire-Acknowledge format (sometimes called ACK-NAK), with XOR checksum, as follows:

UC Hospitality sends:           <ENQ>      <STX><record><ETX><BLKCHK>

PMS responds:                   <ACK>                           <ACK

Where:

<ENQ> is the enquire character (05 hex, 5 decimal)

<ACK> is the acknowledge character (06 hex, 6 decimal)

<STX> is the start-of-text character (02 hex, 2 decimal)

<record> is an ASCII text string with data about a single call

<ETX> is the end-of-text character (03 hex, 3 decimal)

<BLKCHK> is the XOR checksum of all characters in <record> plus <ETX> (but not <STX>).

If the PMS does not reply with the <ACK> character when expected or replies with some other character (such as <NAK>, 15 hex, 21 decimal), the send will be re-attempted after a short 1-3 second delay; the total number of attempts is normally three but can be changed using the additional parameters box.

If the PMS does not reply to all attempts an event message (“NO RESPONSE FROM PMS”) will be sent to the email address listed in the Settings page item 27.

In the HOBIS Interface Protocol, the ASCII text string (<record>) is sent in the following format:

1. The Default Position shows the location of the first character in the field (the left edge of the field).
2. The counter field, CCCC, is a numeric counter in the first 3 positions, followed immediately (no space) by the letter A. When the counter “rolls over” to 000, the letter is incremented to B, and so on.
3. The Duration field is minutes only, 0 padded on the left, rounded up to the nearest whole minute.
4. The Cost field includes the dollar sign as part of that field.
5. The Description field is one character only and is taken from the “PMS Interface” field in the Rate Line (call accounting option 21).

 

 

Note: The column number ruler shown above the sample data does not print; it is included as an aid in determining where each field starts and ends.

Where the fields are:

Field	Field Name	Width	Default Position	Empty Spaces Filled With
CCCC	Counter	04	01	0 (in front of the digits)
PPP	Property Code	03	06	As in call accounting option 41
MM/DD	Date	05	10	0 (in front of any single digit)
EEEE	Extension	04	17	Space (in front of the digits)
HH:MM	Time	05	22	0 (in front of any single digit)
MMMM	Duration	04	28	0 (in front of the digits)
$DDD.CC	Cost	07	33	0 (in any empty space after $)
NNNNNNNNNNNN	Number Dialed	12	41	Space (after the digits)
D	Description	1	54	Space (if no description)

 

 

Micros

This Interface Protocol is based on the specification for input to a MICROS cash register/POS system, circa 1980s.

With this protocol, records are sent as follows:

UC Hospitality sends:        <ENQ>      <record><CR>

PMS responds:                <ACK>             <ACK>

Where:

• <CR> is the carriage return character (0D hex, 13 decimal)
• <record> is an ASCII text string with data about a single call

If the PMS does not reply with “ACK” when expected, the send will be re-attempted after a short 1-3 second delay; the total number of attempts is set within the protocol file and can be changed using the additional parameters box.

If the PMS does not reply to all attempts, an event message (“NO RESPONSE FROM PMS”) will be sent to the email address listed in the Settings page item 27.

In the Micros Interface Protocol, the ASCII text string (<record>) is sent in the following format:

ac01 EEEE DDDDCC NNNNNNNNNN

 

Where the fields are:

 

 

Field	Field Name	Width	Default Position	Empty Spaces Filled With
ac01	Start	04	01	N/A
EEEE	Extension	04	06	0 (in front of the digits)
DDDDCC	Cost	06	11	0 (in front of the digits)
NNNNNNNNNN	Number Dialed	12	18	0 (in front of the digits)

 

 

 

The Default Position shows the location of the first character in the field (the left edge of the field).

The Start field is a fixed field that literally contains “ac01” every time. This was defined and set by Micros in the design of their interface.

All fields are padded with “0” on the left side, including the Number Dialed field. The Number Dialed field is cut off at 10 characters, so only the first 10 digits dialed will be included for each call (including the initial “1” or “011” dialed); this means that longer phone numbers will lose the last digits dialed, while shorter phone numbers will have extra 0’s in front of the dialed digits.

The cost field is in dollars and cents and does not include a dollar sign.

Sample Data using the Micros Interface Protocol:

The column number ruler shown above the sample data does not print; it is included as an aid in determining where each field starts and ends.

 

 

Basic Message Format

UC Hospitality will interface with the PMS using the following Enguire-Acknowledge (ACK-NAK) protocol:

Sender:    <ENQ>      <STX><Message Text><ETX>

Receiver:       <ACK>                        <ACK>

Where:

Sender can be either UC Hospitality or the PMS, and the Receiver is the other side.

<ENQ> is the enquire character (005 ASCII)

<ACK> is the acknowledge character (006 ASCII)

<STX> is the start-of-text character (002 ASCII)

<Message Text> is the ASCII text string that contains the command, room status code, or other information as described below, with an optional Checksum

<ETX> is the end-of-text character (003 ASCII).

1. If the PMS sends an initial <ENQ> and UC Hospitality responds with <ACK> but receives no additional information within 1/10 second, UC Hospitality times out this transaction without sending any further response. If additional data follows after this time-out (other than another <ENQ>), UC Hospitality will send a <NAK> in response.
2. UC Hospitality will send a <NAK> character (021 ASCII) in any of the following cases:
   1. There is no <ETX> at the end of the message, within 1/10 second of the last character received.  
3. UC Hospitality will only send an <ACK> in response to a <Message Text> from the PMS if
   1. UC Hospitality receives the <STX> within 1/10 second of sending its <ACK> in response to the PMS’s <ENQ>
   2. and the <Message Text> is followed by <ETX> within 1/10 second
4. Any between-character delay of more than 1/10 second will cause the transaction to time out, and UC Hospitality will send a <NAK> (unless nothing follows the original <ENQ><ACK>).

This page describes the legacy method of connecting the Serial Box to UC Hospitality. For the updated method, see the UC Hospitality Setup and Installation section.

A serial box can be used on UC Hospitality with a straightforward setup. 

UC Hospitality Setup

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

Next, go to the Serial Devices tab. 

Click Add Serial Device.

Set the name to "Serial Box," enter the device's MAC address (no colons), and click save.

Once added, it should look like this:

Serial Box

Log in to the Serial Box and visit the PBX/CA Configuration page. 

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

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

Click Save ALL. 

If the Serial Box connects correctly, the Monitoring/Debug page should display the following lines when the service restarts.

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 UC Hospitality, and it should display as Connected.

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

Before you begin

• 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).

Installation and Setup

Serial Box Setup

1. Log in to 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 that these settings vary depending on how the PMS is configured. UC Hospitality cannot 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 UC Hospitality 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 to the Proxy UC Hospitality system.

Hosted UC Hospitality 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 - Ensure the PMS interface is enabled on the settings page - Click Save/Restart for the PMS interface.

Testing 

To test that everything has been set up correctly, issue the SSH command "telnet <Proxy IP> 8080" from the hosted system using the IP of the proxy system. If everything has been set up 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, verify that the message is received by the Serial Box, and ensure that the guest is visible on the hosted system.

Login

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 desktop with a static IP address of 192.168.1.50. Then, directly connect the computer to the serial box and navigate to https://192.168.1.223 or unconfigured-pmsi.local
2. Upon reaching the login screen, enter the username "admin" and the Password "password".

Important! After logging in, you must change the device's default password. See the Administration section for instructions on how to do this.

PBX / CA Configuration

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

Disabled / Enabled

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

Protocol

It allows for the selection of the different available protocols. Usually, there will be a protocol for the type of PMS being interfaced with (Opera, FOSSE, OnQ, etc.). Appendix A provides a complete description of the interfaces and a short description of each.

Port Selection

The serial box has two ports, 1 and 2. Usually, the PBX interface is plugged into port 1, and the CA into port 2. However, this can be changed here if needed.

Baud Rate

This is the connection speed. The speed must 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. It refers to how many data bits are in each character. 8 is the most common default; 7 is used only for ancient equipment or unusual setups. It's usually okay to assume this is set to 8.

Parity

Usually set to "None", sometimes referred to as "N". Parity is a way to check for errors in data transmission. If set to Odd, an extra data bit is sent with each character so 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 undetectable errors).

Stop Bits

Usually set to 1. The stop bit is sent at the end of every character so that both sides remain in sync and can pass data. It's usually 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.

More information about Serial Ports can be found here: Serial port.

Additional Settings

UC Hospitality Server URL

Here, the IP address of the hosted UC Hospitality system is set. The IP address (1.2.3.4 in this example) is the only thing to change, 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

Sometimes, additional settings or changes to defaults in the selected template file must 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 overridden for any PBX or CA interface section. This is very powerful; only a few examples of how those functions work are provided below. Note that you must enter "[ca-masks]" or "[pbx-masks]" on a separate line before the special parameters you wish to use.

Sometimes, PMS vendors use a comma, a slash, or a space to separate guest names. By default, most PBX interface protocols use a comma. Add the following to the additional parameters field and click Save ALL to change this.

[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 that 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, which works best with strip=True (above).
• incoming=1/0 [True/False] (i.e. incoming=1, default 0). If set to true, UC Hospitality 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. The 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 a drop-in message into a guest's mailbox 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

Interface Files

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 only 1 minute and generally only be done upon UC Hospitalities' instruction. If the button is clicked and no updates are available, all existing interface files will be preserved without changes.

Monitor / Debug

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 UC Hospitality)

The second number (01 and 03 in the above screenshot) will display 201 if an additional parameter is not understood. Look for this when adding additional parameters to ensure that Psip understands and is using the added information.

Debug & Test Commands

Many commands can be issued, along with an example of each:

• 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 standard commands, just the first letter of each command needs to be entered. For example, a test call can be created by typing "t c", and Are you there by typing "t s a". It's recommended that the more complex commands be fully spelled out.

Administration

This section is where network and password settings are changed.

Site Code

Enter the site's 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 device's IP address 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 address of the gateway 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 system reboot. Click okay and wait for the system to return online (a process taking 1-2 minutes).

VPN Settings

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

System Control

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.

When the system is restored to factory defaults, the network settings are lost, and the system reverts to DHCP. Access to the box reverts to unconfigured-pmsi.local.

User Settings

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. The new password and confirm password must match before the Save button will become active.

Save

Click here to apply the new password settings. After this operation, you will need to log back into the system.

SerialBox login:

SerialBox PBX/CA Configuration:

Enable the interfaces you will use. From the drop-down menu, select your protocol, which is the PMS you are connected to.

The next step is to select the serial port settings. The PMS company must provide these settings. Two standard defaults are 9600 bps Baud Rate, 8 Data Bits, None for Parity, and 1 for Stop Bits, which are already set. The second most common is 1200 bps Baud Rate, 8 Data Bits, None for Parity, and 1 Stop Bit. Ideally, you would get these settings from the PMS Company.

If you are using Call Accounting, you will also set the CA Interface by selecting "Enabled" and the Protocol from the drop-down options. The other CA settings are generally not changed.