Reference Manual

MN912078EN, version 6

BlueTree Master
Protocol
Documentation for part number P-SMPR-4401.
For use with SMP Gateway software version 7.0 or later.
All brand and product names appearing in this document are the trademark or registered trademark
of their respective holders.

© 2016 Eaton – All rights reserved.

The information in this document is subject to change without notice.

Eaton’s Energy Automation Solutions

1990 5th Street
Suite 220
Levis, Quebec
Canada G6W 5M6
Phone: +1.418.830.5800
Fax: +1.514.227.5256
Email: [email protected]
Web: http://www.cooperpower.com

Technical Support: [email protected]

MN912078EN, version 6
 EAS-SA QF-MKT-02 Rev.02

Contents
1 Introduction 1
1.1 Getting Assistance .................................................................................................1

2 Features 3
2.1 Communication .....................................................................................................3
2.2 Supported AT Commands .....................................................................................3
2.3 Supported Report Payload .....................................................................................3

3 Configuration Settings 5
3.1 General Settings ....................................................................................................5
3.2 Analog Input Settings ............................................................................................7
3.3 Binary Input Settings .............................................................................................7
3.4 Binary Output Settings ..........................................................................................8

4 Implementation Details 9
4.1 Related components...............................................................................................9
4.2 Startup Sequence ...................................................................................................9
4.3 Modem Configuration ......................................................................................... 10
4.4 Communication Failure ....................................................................................... 10
4.5 Communication through a NAT-Enabled Router ................................................ 10

5 Troubleshooting 13

BlueTree Master Protocol Reference Manual ●i

 EAS-SA QF-MKT-02 Rev.02

Tables
Table 2-1 Supported AT commands ............................................................................................. 3
Table 2-2 Supported report payload subfields .............................................................................. 4
Table 3-1 General settings ............................................................................................................ 7
Table 3-2 Analog input settings .................................................................................................... 7
Table 3-3 Binary inputs settings ................................................................................................... 8
Table 3-4 Binary outputs settings ................................................................................................. 8
Table 5-1 Troubleshooting .......................................................................................................... 13

BlueTree Master Protocol Reference Manual ● iii

 EAS-SA QF-MKT-02 Rev.02

1 Introduction

This manual provides the information required to install and set up a BlueTree master protocol
component in an SMP Gateway.
This protocol component is used to retrieve I/O information from BlueTree 4000 and 5000 series
modems running firmware BlueX v.2.0 or newer. It can also be used to control outputs of such
devices.
You need to be familiar with the SMP Gateway environment, the master protocol concepts, the
BlueTree Event Reporting Protocol specification and the BlueTree AT commands before
proceeding with this document. You can get this information by reading the following documents:
 IO Management and Event Reporting for the BlueTree 4000 and 5000 Series, Version 1.0,
BlueTree Wireless Data Inc.
 Protocol Common Concepts Reference Manual, MN912003EN, Eaton.
 SMP Gateway User Manual, MN912001EN, Eaton.

1.1 Getting Assistance

If you have any question regarding the performance, application or testing of any component of
this SMP product, do not hesitate to contact us. Our staff will be pleased to assist you.
Technical Support
Eaton’s Energy Automation Solutions

Email: [email protected]
Phone: +1.763.595.7775
Toll Free: +1.800.815.2258

Business hours are from 8 a.m. and 5 p.m. CST, Monday to Friday.

BlueTree Master Protocol Reference Manual •1

 EAS-SA QF-MKT-02 Rev.02

2 Features

This chapter enumerates the features provided by the BlueTree master protocol component.

2.1 Communication
The BlueTree master protocol component will use TCP/IP communication links to send AT
commands to configure the BlueTree modems. The modem will also use TCP/IP to send back
event reports to the SMP Gateway

2.2 Supported AT Commands

The following table illustrates which AT commands can be sent by the BlueTree master protocol
component:

AT Command Description
AT+BDOSET Set Digital Output.
Change the state of the modem outputs (used in control request).

AT+BEVENT Define Event.

AT+BEVRPR Define Report Message

AT+BRPRDS Define Reporting Destination

AT+BEVDIS Define Digital Input Signal.

AT+BEVAIS Define Analog Input Signal.

Table 2-1 Supported AT commands

2.3 Supported Report Payload

The BlueTree master protocol component uses BlueTree Event Reporting Protocol (BT ERP) to
retrieve input/output state from the modem. Hence, message payload of reports coming from the
modem should only contain an I/O Information (format 1) subfield. However, the BlueTree master
protocol component will also parse Modem Information (format 1), RF Information (format 1) and
GPS Information (format 1) subfields, but those subfields will be ignored. The following table
summarizes the subfields supported by the BlueTree master protocol component:

BlueTree Master Protocol Reference Manual •3

EAS-SA QF-MKT-02 Rev.02

Payload Format Comment

Subfield
Modem Information 1 Parsed but ignored.

RF Information 1 Parsed but ignored.

I/O Information 1 Binary representation of the inputs and outputs states.

GPS Information 1 Parsed but ignored.

Table 2-2 Supported report payload subfields

4● Chapter 2: Features
 EAS-SA QF-MKT-02 Rev.02

3 Configuration Settings

This chapter enumerates the configuration settings you have to specify for each BlueTree master
protocol instance. The SMP Config software program is generally used to define these settings.
Only the settings specific to the BlueTree protocol are described here. The settings common to all
master protocol components are described in the Cooper Power Systems document
entitled Protocol Common Concepts Reference Manual.

3.1 General Settings

Every instance of this master protocol component contains general settings, which set the general
behavior of the component. The following table shows the general settings that are specific to the
BlueTree master protocol.

Setting Description
Integrity Report Interval The interval between two consecutive integrity reports. Those reports are
used to refresh analog input values, to verify communication link status and
to detect if the modem lost its configuration.
Setting a short interval will increase the rate at which we receive analog
inputs state but will require more data to be exchanged between the modem
and the SMP Gateway. Setting a long interval will decrease network usage
but analog input values may be inaccurate since they are updated less often.
Range: 1 to 65,000 seconds
Default value: 900 seconds

Report Timeout Time to wait after next expected report before declaring a communication
failure. If such timeout occurs, the BlueTree master will try to reconnect to
the modem to set back its configuration.
For example, if a modem is configured to send integrity report each 900
seconds and this parameter is set to 915,000 milliseconds, the protocol will
declare a communication failure with the device if no report is received in
1,815 seconds.
Range: 1 to 900,000,000 milliseconds
Default value: 915,000 milliseconds

BlueTree Master Protocol Reference Manual •5

EAS-SA QF-MKT-02 Rev.02

Setting Description
Rx Timeout Timer The amount of time to wait, in milliseconds, for the remote device response
before attempting any retries. This timer is started after AT command
transmissions to the modem.
Setting a short reception timeout may cause the link to operate erratically
(timeout declared even though the response is still coming). Setting a long
reception timeout may cause inefficiencies, with a considerable amount of
bandwidth wasted when communication errors occur.
Range: 350 to 30,000 milliseconds
Default value: 10,000 milliseconds

Rx Retry Count The number of times the master protocol component will try to retransmit an
AT command when a bad response (or no response) is received from the
modem. If that number of retransmissions is reached without receiving a
valid response, a communication failure is declared and an attempt is made to
re-initialize the AT command communication link.
Range: 0 to 10
Default value: 3

Connection Retry Count Maximum number of connection retries to the AT commands TCP/IP port,
before communication with the modem is considered to have failed.
Range: 0 to 14
Default value: 3

Connection Retry Delay Amount of time to wait between connection retries.

Range: 0 to 14
Default value: 3

Reconnection Delay Delay to wait after a failed connection retry sequence (i.e. maximum
connection retry count reached without success) before attempting a new
connection sequence. This parameter is only used when the AT command
communication link is in “communication failed” state.
Range: 0 to 2,147,483,647 milliseconds.
Default value: 120,000 milliseconds (2 minutes)

GI Retry Delay Delay to wait between modem reconfiguration when the event report
communication link is in "communication failed" state.
In fact, this parameter defines at which interval we send a control request on
the “___ForceGI” binary output of the BlueTree master protocol component
to force the transmission of initialization AT commands to the modem when
there is a problem with the event report reception.
Range: 1 to 1,000,000,000 seconds
Default value: 120 seconds (2 minutes)

6● Chapter 3: Configuration Settings

 EAS-SA QF-MKT-02 Rev.02

Setting Description
Local IP IP address to which event reports will be sent by the modem. If this
parameter is left empty, the system will automatically use the local IP address
of the SMP Gateway configured with this parameter file.
This field is useful to override destination IP address of that modem’s event
reports. For example, if there is a Network Address Translation (NAT)
enabled router between the SMP Gateway and the modem, you might want to
use the public IP address exposed by the router instead of the private SMP
Gateway IP address.
Range: empty or any valid IP address
Default value: empty (automatic)

Local Port TCP/IP port number used on the SMP Gateway to receive event reports
coming from the modem.
By default, a single port number is shared by all BlueTree master protocol
instances, to receive the reports originating from their associated modem. In
that case, the source IP address is used to associate each incoming modem
connection to the right protocol instance.
Range: 1 to 65,535
Default value: 46,810

Table 3-1 General settings

3.2 Analog Input Settings

Each instance of the master protocol component contains several analog input points, each one
referring to an analog input pin on the modem. Analog input settings tell the component how to
process data retrieved from the device. The following table shows the analog input settings that are
specific to the BlueTree master protocol.

Setting Description
Label Label used to uniquely identify the analog inputs of the modem.
Labels: PWR (voltage level of positive alimentation)
AI1 (analog input pin #1)
AI2 (analog input pin #2)
AI3 (analog input pin #3)

Table 3-2 Analog input settings

3.3 Binary Input Settings

Each instance of the master protocol component may contain several binary input points, each one
referring to the state of a digital input or output pin on the modem. For digital output pins, the
binary input will represent the current state of the output as provided by the modem. Binary input
settings tell the component how to process data retrieved from the device. The following table
shows the binary input settings that are specific to the BlueTree master protocol.

BlueTree Master Protocol Reference Manual •7

EAS-SA QF-MKT-02 Rev.02

Setting Description
Label Label used to uniquely identify the digital input or output of the modem.
Labels: DI1 (digital input pin #1)
DI2 (digital input pin #2)
DI3 (digital input pin #3)
DI4 (digital input pin #4)
IGN (ignition sense input)
DO1 (digital output #1)
DO2 (digital output #2)
DO3 (digital output #3)

Table 3-3 Binary inputs settings

3.4 Binary Output Settings

Each instance of the master protocol component may contain several binary output points, each
one referring to a digital output pin on the modem. Binary output settings tell the component how
to control the device using those points. The following table shows the control output settings that
are specific to the BlueTree master protocol.

Setting Description
Label Label used to uniquely identify the digital input or output of the modem.
Labels: DO1 (digital output #1)
DO2 (digital output #2)
DO3 (digital output #3)

Table 3-4 Binary outputs settings

8● Chapter 3: Configuration Settings

 EAS-SA QF-MKT-02 Rev.02

4 Implementation Details

4.1 Related components

The BlueTree master protocol component uses many SMP Gateway features to cover all the
functionalities needed by the protocol. Hence, for each BlueTree master protocol instance
configured in SMP Config, the SMP Gateway will contain automatically-generated instances of
various related components:
 A BlueTree master protocol instance to configure the modem and to control its digital outputs.
 A BlueTree Event protocol instance to receive and process event reports coming from the
modem. That instance will use the same name as the BlueTree protocol instance with the text
“_Event” added at the end.
 A TCP/IP slave connection that the BlueTree Event protocol instance will use to receive event
reports. The name of the connection is identical to the BlueTree Event protocol instance
name.
 An Automation Functions instance that is used to force the BlueTree protocol instance to
reconfigure the modem when the BlueTree Event protocol instance has not received any valid
report for a specified amount of time. Note that all BlueTree and BlueTree Event protocol
instances will share the same Automation Functions instance. The name of that single
instance is “BlueTree_Generated”.
Each of these instances will be shown in SMP Log, SMP Stats and SMP Trace tools, in their
respective category.

4.2 Startup Sequence

The protocol component does the following on startup:
 Parses the configuration file.
 Initializes the various logs, traces and statistics.
 Creates all I/O points and marks them as invalid (communication failure).
 Initializes the communications links.
 Configure the modem using various AT commands.
 Wait for event reports.

BlueTree Master Protocol Reference Manual •9

EAS-SA QF-MKT-02 Rev.02

4.3 Modem Configuration

At startup and after some exceptional event, the BlueTree master protocol component will
configure the modem so that the SMP Gateway will be able to monitor its state. That configuration
sequence consists in the following steps:
 Clear all events previously configured in the modem (using multiple “at+bevent=…”
commands)
 Set the report destination to the SMP Gateway (using “at+brprds=…” command). By
default, all report will be sent using TCP/IP to port number 46,810.
 Configure a report that will include I/O information (using “at+bevrpr=…” command)
 Define a digital input signal for each enabled digital input (using “at+bevdis=…”
command)
 Define an event for each digital input signal created in the previous step so that a report is sent
each time a digital input state changes (using “at+bevent=…” command)
 Ask the modem to immediately send a report to retrieve the initial state of every modem input
and output (using “at+bevais=…” and “at+bevent=…” commands)
 Define an event based on a timer signal for the cyclic transmission of integrity reports (using
“at+bevent=…” command)
After that configuration sequence, the modem will be configured to send reports to the
SMP Gateway at a specific rate (based on the Integrity Report Interval parameter, see “General
Settings”) and each time a digital input changes. The connection with the modem is then closed
and the system starts listening for event reports.

4.4 Communication Failure

If at some point the modem seems to stop sending its cyclic reports, all I/O points are tagged as
being defective due to communications failure. The system will then try to reconfigure the modem
using the sequence detailed above.
Analog and binary input points will become valid again when a valid event report is received from
the modem. Binary output points become valid again as soon as the communication link used to
send AT commands to the modem is considered active

4.5 Communication through a NAT-Enabled

Router
The BlueTree modems need to establish a connection with the SMP Gateway in order to send their
event reports. However, if the SMP Gateway is behind a Network Address Translation (NAT)
enabled router, the BlueTree modem might not be able to reach the SMP Gateway using its local
IP address.
In that case, the router must be configured so that event reports coming from the public network
are forwarded to the SMP Gateway on the private network. The steps required to perform that
reconfiguration should be explained in the router’s documentation.
Since the NAT-enabled router is hiding the SMP Gateway on the private network from hosts on
the public network, the modem needs to send event reports to the router’s public IP address
instead of sending them to the unreachable SMP Gateway IP address. This can be done by using

10 ● Chapter 4: Implementation Details

 EAS-SA QF-MKT-02 Rev.02

the “Local IP” general parameter to override the destination IP address of event reports (see
"General Settings" for more details).

BlueTree Master Protocol Reference Manual • 11

 EAS-SA QF-MKT-02 Rev.02

5 Troubleshooting

The following table enumerates solutions to common problems experienced with the BlueTree
master protocol component:

Problem Solution
The SMP Gateway is not This problem can be due to one of the following:
communicating with my
 One of the reasons discussed in the Protocol Common
device.
Concepts Reference Manual.
 Service TCP port problem: The SMP Gateway cannot connect to the to
the service TCP port of the modem. Be sure the modem service TCP
port number matches the one configured in the TCP/IP connection of
the BlueTree master instance. Also verify the modem’s configuration
to ensure that the service port is accessible by the SMP Gateway.

The BlueTree modem This problem can be due to one of the following:
does not send reports to
 Unreachable SMP Gateway: if the SMP Gateway is behind a Network
the SMP Gateway.
Address Translation (NAT) enabled router, the modem might not be
able to reach the SMP Gateway using its local IP address. Either
disable the NAT or reconfigure the system so that event reports get
routed to the SMP Gateway. See section 4.5, “Communication through
a NAT-Enabled Router” for more information on this topic.

The link to my modem This problem can be due to one of the following:
keeps resetting.
 One of the reasons discussed in the Protocol Common
Concepts Reference Manual.
 Reception timeout problem: The configured Rx Timeout Timer
general setting is too small.

Table 5-1 Troubleshooting

BlueTree Master Protocol Reference Manual • 13