Digi XGI-20CZ7-E00-W0, XGI-20CZ7-EU7-W0 User Manual

Digi XBee® Industrial Gateway

User Guide

Revision history—90001542

Revision Date Description

A August 2017 Baseline release of this document.

Trademarks and copyright

Digi, Digi International, and the Digi logo are trademarks or registered trademarks in the United
States and other countries worldwide. All other trademarks mentioned in this document are the
property of their respective owners.

© 2017 Digi International Inc. All rights reserved.

Disclaimers

Information in this document is subject to change without notice and does not represent a
commitment on the part of Digi International. Digi provides this document “as is,” without warranty of
any kind, expressed or implied, including, but not limited to, the implied warranties of fitness or
merchantability for a particular purpose. Digi may make improvements and/or changes in this manual
or in the product(s) and/or the program(s) described in this manual at any time.

Warranty

To view product warranty information, go to the following website:

www.digi.com/howtobuy/terms

Send comments

Documentation feedback: To provide feedback on this document, send your comments to

[e-mail].

Customer support

Digi Technical Support: Digi offers multiple technical support plans and service packages to help our

customers get the most out of their Digi product. For information on Technical Support plans and
pricing, contact us at +1 952.912.3444 or visit us at www.digi.com/support.

Digi XBee Industrial Gateway

2

Contents

About Digi XBee Industrial Gateway

Regulatory information and certifications 9

RF exposure statement 9
FCC certifications and regulatory information (USA only) 9
Declaration of Conformity (DoC) 9
CE mark (Europe) 10
Industry Canada (IC) certifications 10

Safety statements 11

Warnings for Use of Wireless Devices 12
International EMC (Electromagnetic Emissions/Immunity/Safety) standards 12

Maximum power and frequency bands 13

XBee Industrial Gateway: Cellular 13

XBee Industrial Gateway: Ethernet 13
XBee Industrial Gateway Python application 13
XBee ZigBee Cloud Kit 13
Hardware interfaces 14
Configuration and management interfaces 14

XBee Industrial Gateway web interface 14

Remote Manager interface 14

RFGateway and Python remote device management solutions 15

Programming interface applications 15
Where to find more information 15

XBee Industrial Gateway hardware

Ethernet model 17
Ethernet model hardware specifications 18
Cellular model 20
Cellular model hardware specifications 21
XBee Industrial Gateway antennas 22
XBee Industrial Gateway LED descriptions 22

Signal strength LED (cellular models only) 23

Network LED 24

XBee LED 24

Power LED 25

Set up XBee Industrial Gateway

Setting up the XBee Industrial Gateway Cellular hardware 26

Verify your XBee Industrial Gateway Cellular components 26

Digi XBee Industrial Gateway

3

Connect the hardware 28

Connect XBee Industrial Gateway to the cellular network 28
Setting up the XBee Industrial Gateway Ethernet hardware 29

Verify your XBee Industrial Gateway Ethernet components 29

Connect the hardware 30

Connect XBee Industrial Gateway to the Ethernet network 31

Getting started with XBee Industrial Gateway

Set up XBee Industrial Gateway summary 32
Joining ZigBee networks 33

Joining XBee Industrial Gateway to an existing ZigBee network 34

Configuring XBee Industrial Gateway with a custom PAN ID 35
XBee Industrial Gateway and non-XBee ZigBee Devices 36

Administration and maintenance tasks

File management 37

File Management page in Remote Manager 37

File Management page in the XBee Industrial Gateway web interface 38
Back up or restore the configuration 39

Back up and restore files from Remote Manager 39

Back up and restore files from the XBee Industrial Gateway web interface 39
Update firmware 41

Update firmware from Remote Manager 41

Update firmware from the XBee Industrial Gateway web interface 42

About firmware files 44
Mobile device status 44

Displaying the mobile device status 44

Mobile Status page 45
Displaying the XBee Industrial Gateway End User License Agreement (EULA) 49
Rebooting XBee Industrial Gateway 50
Displaying system information 50
Disconnecting XBee Industrial Gateway from Remote Manager 50

About programming

Python 51
XBee ZigBee Cloud Kit web application source code 52
Programming calls through Server Command Interface (SCI) and Remote Command Interface
(RCI) 52
XBee Industrial Gateway file system 52

Important directories 52
Load applications onto XBee Industrial Gateway 53

Program XBee Industrial Gateway using Python

Find Python learning resources 55

Digi Python Programmer's Guide 55

Python support forum 55

Digi Wiki for Developers 55
Digi-specific Python modules for programming 55
Sample programs 55

Digi XBee Industrial Gateway

4

LED control 56

Watchdog 56

RCI callback 57

XBee functions 58
XBee Industrial Gateway Python application and Remote Manager 58

How does the XBee Industrial Gateway Python application work? 59

Key features and operations of the XBee Industrial Gateway Python application 59

XBee Industrial Gateway Python application requirements 60

Store status data for XBee lines in Remote Manager 60

Receive serial data from Remote Manager 64

Store serial data in Remote Manager 71

Manage XBee DIO lines though Remote Manager 74

XBee Industrial Gateway Python application configuration file 81

XBee Industrial Gateway Python application command errors 82
Configuring a Python application in the web interface 83
Digi ESP for Python 83

Access the program samples in Digi ESP 83

Install the Digi ESP for Python Development Environment 84
DIA software 87
Linux command shell (command-line interface) 87

User name and password for the Linux command shell 87

XBee Industrial Gateway ash shell reference documentation 87

Connect and log in to the XBee Industrial Gateway device 87

Log in to XBee Industrial Gateway through the Digi ESP for Python command-line interface 88

Configure XBee Industrial Gateway

Configure settings from Remote Manager 91

Basic configuration settings 91

Advanced configuration settings 91
Configure settings from the XBee Industrial Gateway web interface 92

Access the XBee Industrial Gateway web interface 92

Home page 92
Ethernet IP network settings 93

Default Ethernet settings 94

Configuring Ethernet Settings 94

Ethernet Configuration page 94

Ethernet Network Configuration page 95
Mobile Connectivity settings 97

Default behavior with the cellular network 97

Set up and configure a cellular device 97

Configure mobile settings 99

Mobile Configuration page 99

Mobile Connectivity Configuration page 100
Digi Mobile SureLink™ settings 101

Configuring Mobile SureLink settings 101

Mobile SureLink integrity monitoring settings 102

Link integrity test options 103
DNS settings 104

Configure Domain Name Server (DNS) 104

Domain Name Server (DNS) Configuration page 104
Mobile firewall settings 105

Configure mobile firewall settings 105

Enable or Disable Mobile firewall settings 105
Autostart settings for the Python Program 105

Digi XBee Industrial Gateway

5

Configure Python settings 106

Python settings 106
Configure Remote Manager connectivity settings 106

Configuring connectivity settings 107

Device Cloud Configuration page 108

Device Cloud client initiated connection page 109

Device Cloud network type page 109

Basic connectivity settings 110

Advanced connectivity settings for the web interface 111

Connect to a different instance of Remote Manager 113

Configure a proxy server 113
Ethernet SureLink™ settings 113

Configuring Ethernet SureLink settings 114

Ethernet SureLink settings 114
GPS static position settings 115

Configuring GPS Static Position settings 115

GPS Static Position page 115
Network Failover settings 116

Configure network failover on the XBee Industrial Gateway web interface 116

Configure network failover in Remote Manager 116

Link integrity test options and failover 117
Time settings 118

Configure time settings 118

Time Server Configuration page 119

Time Zone Configuration page 119

Time Configuration page 119

Configure XBee network settings

Configure XBee Networks page in Remote Manager 121
Configure XBee network settings in the web interface 122

XBee Configuration page 122

Device Details page 123
XBee network OTA firmware updates 125

Update the XBee network node firmware (OTA updates) from Remote Manager 125

Update the XBee node firmware (OTA updates) from the web interface 127
XBee Industrial Gateway network Python log file 128
XBee network troubleshooting resources 128

Learn more about XBee Industrial Gateway

Default startup and operation behaviors for XBee Industrial Gateway 129

Default behavior regarding NTP time server access 129

Default behavior regarding DNS 130

Firewalls and required open ports 130

Deploying devices over a network 130
Connect the XBee nodes to XBee Industrial Gateway 130

Configure XBee Industrial Gateway as a coordinator 130

Join nodes to the coordinator 131

Verify that XBee nodes are joined to the coordinator 132
Configure the ZigBee network addressing parameters for XBee nodes 133

Key addressing parameters 133

Configure the network addressing parameters 134
Explore serial I/O 134

Digi XBee Industrial Gateway

6

Understanding the process for configuring the serial I/O 134

Example serial I/O configuration 134

Configuring the serial I/O 135
Explore digital and analog I/O 135

Understanding the process for digital and analog I/O 136

Example digital or analog I/O configuration 138

Configuring the digital or analog I/O 138
View your device data 140

View device data from Remote Manager 141

View device data and events in the Python log file for XBee Industrial Gateway 141

Troubleshoot your XBee Industrial Gateway

XBee Industrial Gateway system log 146

XBee Industrial Gateway log files and contents 146

Displaying the system log 147
Cellular connection issues 148

Common configuring issues 148

Troubleshooting XBee Industrial Gateway GSM and LTE devices 149
Device Discovery troubleshooting tips 150
Rebooting XBee Industrial Gateway 150
Troubleshooting LEDs 150
Firewalls and required open ports 152
Cannot connect to NTP time server to get correct time 152
Cannot connect to DNS server to resolve the Remote Manager server address 153
Need more help? 153

Digi XBee Industrial Gateway

7

About Digi XBee Industrial Gateway

Digi XBee® Industrial Gateway provides a rugged, programmable gateway solution to connect
networks of XBee-enabled devices to IP networks in industrial environments, which potentially have
more extreme conditions, such as wide temperature and humidity variations.

With a simple, open-source Python™ development environment, this gateway enables custom
applications to run locally while interfacing across existing Ethernet and cellular networks for WAN
connectivity to cloud-based software applications. Automatic WANfailover functionality ensures
mission-critical data always reaches its destination. XBee Industrial Gateway Ethernet and Cellular
(GSM\LTE) models are available.

The XBee Industrial Gateway contains the XBeeZigBee product.

You can manage XBee Industrial Gateway products remotely via Digi Remote Manager®. Remote
Manager allows users to remotely manage thousands of deployed devices, supporting features like
remote firmware upgrades and event alarms.

XBee Industrial Gateway Cellular model XBee Industrial Gateway Ethernet

This guide describes how to get started with yourXBee Industrial Gateway. This guide is intended for
a developer or programmer. It covers the following information:

n XBee Industrial Gateway hardware

n Set up XBee Industrial Gateway

n Getting started with XBee Industrial Gateway

n Administration and maintenance tasks

n About programming

n Program XBee Industrial Gateway using Python

Digi XBee Industrial Gateway

model

8

About Digi XBee Industrial Gateway Regulatory information and certifications

n Configure XBee Industrial Gateway

n Configure XBee network settings

n Learn more about XBee Industrial Gateway

n Troubleshoot your XBee Industrial Gateway

Regulatory information and certifications

RF exposure statement

In order to comply with RF exposure limits established in the ANSI C95.1 standards, the distance
between the antenna or antennas and the user should not be less than 20 cm.

FCC certifications and regulatory information (USA only)

FCC Part 15 Class B

Radio Frequency Interface (RFI) (FCC 15.105)

This device has been tested and found to comply with the limits for Class B digital devices pursuant to
Part 15 Subpart B, of the FCC rules. These limits are designed to provide reasonable protection
against harmful interference in a residential environment. This equipment generates, uses, and can
radiate radio frequency energy, and if not installed and used in accordance with the instruction
manual, may cause harmful interference to radio communications. However, there is no guarantee
that interference will not occur in a particular installation. If this equipment does cause harmful
interference to radio or television reception, which can be determined by turning the equipment off
and on, the user is encouraged to try and correct the interference by one or more of the following
measures:

n Reorient or relocate the receiving antenna.

n Increase the separation between the equipment and receiver.

n Connect the equipment into an outlet on a circuit different from that to which the receiver is

connected.

n Consult the dealer or an experienced radio/TV technician for help.

Labeling Requirements (FCC 15.19)

This device complies with Part 15 of FCC rules. Operation is subject to the following two conditions: (1)
this device may not cause harmful interference, and (2) this device must accept any interference
received, including interference that may cause undesired operation.

If the FCC ID is not visible when installed inside another device, then the outside of the device into
which the module is installed must also display a label referring to the enclosed module FCC ID.

Modifications (FCC 15.21)

Changes or modifications to this equipment not expressly approved by Digi may void the user’s
authority to operate this equipment.

Declaration of Conformity (DoC)

Digi has issued Declarations of Conformity for the XBee Industrial Gateway concerning emissions,
EMC, and safety. For more information, see www.digi.com/resources/certifications.

Important note

Digi XBee Industrial Gateway

9

About Digi XBee Industrial Gateway Regulatory information and certifications

Digi customers assume full responsibility for learning and meeting the required guidelines for each
country in their distribution market. Refer to the radio regulatory agency in the desired countries of
operation for more information.

CE mark (Europe)

The XBee Industrial Gateway is certified for use in several European countries. For information, visit

www.digi.com/resources/certifications.

If the XBee Industrial Gateway is incorporated into a product, the manufacturer must ensure
compliance of the final product with articles 3.1a and 3.1b of the RE Directive (Radio Equipment
Directive). A Declaration of Conformity must be issued for each of these standards and kept on file as
described in the RE Directive.

Furthermore, the manufacturer must maintain a copy of the XBee Industrial Gateway user manual
documentation and ensure the final product does not exceed the specified power ratings, antenna
specifications, and/or installation requirements as specified in the user manual. If any of these
specifications are exceeded in the final product, a submission must be made to a notified body for
compliance testing to all required standards.

OEM labeling requirements

The CE marking must be affixed to a visible location on the OEM product.

CE labeling requirements

The CE mark shall consist of the initials “CE” taking the following form:

n If the CE marking is reduced or enlarged, the proportions given in the above graduated

drawing must be respected.

n The CE marking must have a height of at least 5mm except where this is not possible on

account of the nature of the apparatus.

n The CE marking must be affixed visibly, legibly, and indelibly.

Industry Canada (IC) certifications

This digital apparatus does not exceed the Class B limits for radio noise emissions from digital
apparatus set out in the Radio Interference Regulations of the Canadian Department of

Digi XBee Industrial Gateway

10

About Digi XBee Industrial Gateway Safety statements

Communications.

This device complies with Industry Canada’s licence-exempt RSSs. Operation is subject to the
following two conditions:

(1) This device may not cause interference; and

(2) This device must accept any interference, including interference that may cause undesired
operation of the device.

Le présent appareil numerique n’emet pas de bruits radioelectriques depassant les limites applicables
aux appareils numeriques de la class B prescrites dans le Reglement sur le brouillage radioelectrique
edicte par le ministere des Communications du Canada.

Le présent appareil est conforme aux CNR d'Industrie Canada applicables aux appareils radio exempts
de licence. L'exploitation est autorisée aux deux conditions suivantes:

(1) l'appareil ne doit pas produire de brouillage, et

(2) l'utilisateur de l'appareil doit accepter tout brouillage radioélectrique subi, même si le brouillage
est susceptible d'en compromettre le fonctionnement.

Safety statements

Important Safety Information

CAUTION! To avoid contact with electrical current, follow all safety items listed below.

n Never install electrical wiring during an electrical storm.

n Never install an Ethernet connection in wet locations unless that connector is specifically

designed for wet locations.

n Use caution when installing or modifying lines.

n Use a screwdriver and other tools with insulated handles.

n Wear safety glasses or goggles.

n Do not place Ethernet wiring or connections in any conduit, outlet or junction box containing

electrical wiring.

n Installation of inside wire may bring you close to electrical wire, conduit, terminals and other

electrical facilities. Extreme caution must be used to avoid electrical shock from such facilities.

Avoid contact with all such facilities.

n Ethernet wiring must be at least 6 feet from bare power wiring or lightning rods and

associated wires, and at least 6 inches from other wire (antenna wires, doorbell wires, wires

from transformers to neon signs), steam or hot water pipes, and heating ducts.

n Do not place an Ethernet connection where it would allow a person to use an Ethernet device

while in a bathtub, shower, swimming pool, or similar hazardous location.

n Protectors and grounding wire placed by the service provider must not be connected to,

removed, or modified by the customer.

n Do not touch uninsulated Ethernet wiring if lightning is likely.

Digi XBee Industrial Gateway

11

About Digi XBee Industrial Gateway Safety statements

n External Wiring: Any external communications wiring installed needs to be constructed to all

relevant electrical codes. In the United States this is the National Electrical Code Article 800.

Contact a licensed electrician for details.

Warnings for Use of Wireless Devices

CAUTION! Observe all warning notices regarding use of wireless devices.

Potentially Hazardous Atmospheres

Observe restrictions on the use of radio devices in fuel depots, chemical plants, etc. and areas where
the air contains chemicals or particles, such as grain, dust, or metal powders, and any other area
where you would normally be advised to turn off your vehicle engine.

Safety in Aircraft

Switch off the wireless device when instructed to do so by airport or airline staff. If the device offers a
‘flight mode’ or similar feature, consult airline staff about its use in flight.

Safety in Hospitals

Wireless devices transmit radio frequency energy and may affect medical electrical equipment. Switch
off wireless devices wherever requested to do so in hospitals, clinics, or health care facilities. These
requests are designed to prevent possible interference with sensitive medical equipment.

Pacemakers

Pacemaker manufacturers recommended that a minimum of 15 cm (6 inches) be maintained between
a handheld wireless device and a pacemaker to avoid potential interference with the pacemaker.
These recommendations are consistent with independent research and recommendations by Wireless
Technology Research.

Persons with Pacemakers

n Should ALWAYS keep the device more than 15cm (6 inches) from their pacemaker when turned

ON.

n Should not carry the device in a breast pocket.

n If you have any reason to suspect that the interference is taking place, turn OFF your device.

International EMC (Electromagnetic Emissions/Immunity/Safety) standards

This product complies with the requirements of following Electromagnetic Emissions/Immunity/Safety
standards.

There are no user-serviceable parts inside the product. Contact your Digi representative for repair
information.

Digi XBee Industrial Gateway

12

About Digi XBee Industrial Gateway Maximum power and frequency bands

Emissions Immunity Safety

EN 55022:2010 Class B
EN 61000-3-2:2004
EN 61000-3-3:2013
FCC 15.107:2015 Class B
FCC 15.109:2015 Class B
FCC 15.109(g):2015 Class B
IEC-003:2012 Class B
EN 301 489-07 V1.3.1:2005

EN 301 489-07 V1.3.1:2005
EN 55024:2010

Maximum power and frequency bands

This section contains the maximum power and frequency bands for the XBee Industrial Gateway.

XBee Industrial Gateway: Cellular

Maximum power Operating mode

Up to 2 W GSM/GPRS

Up to 0.5 W WCDMA/EDGE/LTE

Up to 6.3 mW XBee

Up to 63 mW XBee-Pro

IEC 60950-1:2005
EN 60950-1:2006
SCA C22.22 No. 60950-1

XBee Industrial Gateway: Ethernet

Maximum power Associated frequencies

6.3 mW 5 MHz channel spacing, beginning at 2405 MHz and ending at
2480 MHz

XBee Industrial Gateway Python application

The XBee Industrial Gateway Python application resides on XBee Industrial Gateway. Its key functions
include connecting your XBee modules to Remote Manager, enabling uploads of data to Remote
Manager, and receiving remote text and commands. The XBee Industrial Gateway Python application
is installed by default in your XBee Industrial Gateway device and automatically starts when the
gateway is initialized.

For more information on the XBee Industrial Gateway Python application, see XBee Industrial

Gateway Python application and Remote Manager.

XBee ZigBee Cloud Kit

Digi offers a development kit called the XBee ZigBee Cloud Kit.

The XBee ZigBee Cloud Kit is designed to make it easy to set up your XBee ZigBee hardware and
configure its sample web application. You can see sensor data from your development board on the

Digi XBee Industrial Gateway

13

About Digi XBee Industrial Gateway Hardware interfaces

web, as well as send data and commands from the web to your device. The components in this kit
allow you to create highly customized solutions for connected devices.

To order this kit, go to the XBee Gateway product page for ordering information. For setup
instructions, see the XBeeZigBeeCloudKit Getting Started Guide.

Hardware interfaces

XBee Industrial Gateway hardware interfaces include LEDs that indicate device state and status of
connections, and activity for Ethernet, cellular, and XBee network connections. You can control some
of these hardware features through programming.

For detailed information about hardware interfaces, see XBee Industrial Gateway hardware.

Configuration and management interfaces

To establish network connectivity with an XBee Industrial Gateway device, minimal configuration is
required in many environments. This means that you may not need to set or change configuration
settings from their factory defaults to begin developing with the device. There are several user
interfaces for interacting with XBee Industrial Gateway, for example to view or change configuration
settings or perform important administrative tasks such as updating firmware or rebooting the
device. These include:

n XBee Industrial Gateway web interface: A web-based interface for configuring, monitoring, and

administering Digi devices.

n Remote Manager interface: A web-based, remote-management interface.

XBee Industrial Gateway web interface

The XBee Industrial Gateway web interface, available via a local network connection to XBee
Industrial Gateway, provides an easy way to configure device settings and perform administrative
tasks. Device information displayed varies by model.

For more information, see Configure settings from the XBee Industrial Gateway web interface.

Remote Manager interface

Remote Manager is a software-as-a-service that empowers IT, network operations and customer
support organizations to conquer the challenges of managing the vast array of equipment in their
device networks. As a network grows, the complexity of effectively managing the network assets
grows exponentially.

When XBee Industrial Gateway powers up, the device automatically connects to Remote Manager.
Remote Manager provides the capabilities you need to manage a dynamic device network, including:

n Centralized control over large numbers of devices

n Reducing service complexity

n Maintaining high levels of security

n Configuring and decommissioning of equipment

n Adding functionality to device networks

In addition, you can use the Remote Manager Web Services (API) to provide seamless integration from
Digi gateways into customer back-office applications. You can access these Web Services via the API
Explorer tab of the Documentation tab of the Remote Manager interface. See Digi Remote Manager

Programmer Guide for more information.

Digi XBee Industrial Gateway

14

About Digi XBee Industrial Gateway Where to find more information

Some things to note about using Remote Manager:

n You must register devices on Remote Manager before you can access them from Remote

Manager.

n To minimize network traffic, Remote Manager uses caching. As a result, device settings can be

out-of-sync between the device and the settings viewed on the Remote Manager console.

n You can refresh device information on demand when the device is connected. The device

information refreshes automatically when a device connects.

For more information about configuring settings from Remote Manager, see Configure settings from

Remote Manager.

For more information on Remote Manager as a remote device network management solution, see
these resources:

n Digi Remote Manager User Guide

n Digi Remote Manager Programmer Guide

n Remote Manager tutorials and other documents available on the Digi Remote Manager

product page

Note To serve our customers most effectively, Digi International Inc. is consolidating its cloud

services, Digi Device Cloud and Digi Remote Manager®, under the Remote Manager name. This phased
process does not affect device functionality or the functionality of the web services and other
features. However, you will find instances of both Device Cloud and Digi Remote Manager in some
documentation, firmware, and user interfaces.

RFGateway and Python remote device management solutions

XBee Industrial Gateway includes Remote Manager functionality by default. This functionality allows
you to see your data in the cloud quickly and with minimal effort.

However, you can extend the system through the Python interpreter and customize the gateway to
connect directly to the environment of your choice. See the Digi XBee, RFGateway and Python

Resource page for more information.

Programming interface applications

XBee Industrial Gateway offers a variety of interfaces that produce and/or consume data. Developing
software programs for XBee Industrial Gateway products allows Digi customers to provide custom
logic to control the information to and from these interfaces.

For more information, see About programming.

Where to find more information

See the following topics in this guide for more information:

n Learn more about XBee Industrial Gateway

n About programming

The following documents are available on www.digi.com unless otherwise noted:

n For more information about features and operation of the XBee RF module mounted inside the

gateway, see XBee/XBee-PRO ZigBee RF Module User Guide.

Digi XBee Industrial Gateway

15

About Digi XBee Industrial Gateway Where to find more information

n The ConnectPort X2e Wiki page for additional programming content for ConnectPort X2e

products; information on this Wiki also applies to XBee Industrial Gateway.

n DIA library documentation

n Digi Remote Manager User Guide

n Digi Remote Manager Programmer Guide

n Datasheets and other documents on the Digi Remote Manager product page

Digi XBee Industrial Gateway

16

XBee Industrial Gateway hardware

This section provides hardware specifications for XBee Industrial Gateway.

n Ethernet model:

l Ethernet model

l Ethernet model hardware specifications

n Cellular model:

l Cellular model

l Cellular model hardware specifications

n Antennas: XBee Industrial Gateway antennas

n XBee Industrial Gateway LEDs: XBee Industrial Gateway LED descriptions

Ethernet model

Digi XBee Industrial Gateway

17

XBee Industrial Gateway hardware Ethernet model hardware specifications

Item Description More information

1 Power requirements

2 Ethernet features

3 XBee antenna

4 LED status indicators

See Power requirements.

See Ethernet specifications.

See XBee Industrial Gateway antennas.

See XBee Industrial Gateway LED descriptions.

Ethernet model hardware specifications

Specifications Value

Environmental Operating

temperature

Relative
humidity

Storage and
transport
temperature

Altitude 2000 meters (6560 feet)

Ethernet
isolation

-30° C to 70° C (-22° F to 158° F)

5% to 95% (non-condensing)

-40 to 85° C (-40 to 185° F)

500 VAC min per IEEE 802.3/ANSI X3.263

Power
requirements

DC power
input

n Voltage input: 5 VDC +/- 5%

n Power consumption: Typical: 1.2 W, Max: 2.5 W

n Connector: 2.5 mm x 5.7 mm, center pin positive

Dimensions Length 7.62 cm (3 in)

Width 10.16 cm (4 in)

Depth 2.54 cm (1 in)

Weight 0.5 kg (0.22 lb)

Ethernet Ethernet

1 RJ-45 port

Ports

Physical

10/100 Base-T (Auto-MDIX)

Layer

Data Rate 10/100 Mbps (auto-sensing)

Mode Full or half duplex (auto-sensing)

Digi XBee Industrial Gateway

18

XBee Industrial Gateway hardware Ethernet model hardware specifications

Specifications Value

XBee Module type

Transmit
power

Receiver
sensitivity
(1% PER)

Development Python

version

Memory

n XBee S2C ZigBee

n XBee-PRO S2C ZigBee

n The domestic product version uses the XBee-PRO RF

module, with a transmit power of 63 mW (+18 dBm).

n The international product version uses the regular XBee RF

module, with a transmit power of 6.3 mW (+8 dBm).

-102 dBm

See the XBee/XBee-PRO ZigBee RF Module User Guide (available from
the XBee/XBee-PRO ZigBee Modules (S2C) page) for complete
specifications and product information.

2.7.1

64 MB RAM, 128 MB Flash
20 MB RAM 20 MB Flash available for Python applications

Digi XBee Industrial Gateway

19

XBee Industrial Gateway hardware Cellular model

Cellular model

Item Description More information

1 Power requirements

2 Ethernet features

3 XBee antenna

4 Cellular features

5 SIM card installation

6 LED status indicators

See Power requirements.

See Ethernet specifications.

See XBee Industrial Gateway antennas.

See Cellular specifications.

See Set up and configure a cellular device.

See XBee Industrial Gateway LED descriptions.

Digi XBee Industrial Gateway

20

XBee Industrial Gateway hardware Cellular model hardware specifications

Cellular model hardware specifications

Specifications Value

Environmental Operating temperature -30° C to 70° C (-22° F to 158° F)

Relative humidity 5% to 95% (non-condensing)

Storage and transport

-40 to 85° C (-40 to 185° F)

temperature

Altitude 2000 meters (6560 feet)

Ethernet isolation 500 VAC min per IEEE 802.3/ANSI X3.263

Power
requirements

DC power input

n Voltage input: 5 VDC +/- 5%

n Power consumption: Typical: 3.5 W, Max: 11

W

n Connector: 2.5 mm x 5.7 mm, center pin

positive

Dimensions Length 10.16 cm (4 in)

Width 7.62 cm (3 in)

Depth 2.54 cm (1 in)

Weight 0.5 kg (0.22 lb)

Ethernet Ethernet Ports 1 RJ-45 port

Physical Layer 10/100 Base-T (Auto-MDIX)

Data Rate 10/100 Mbps (auto-sensing)

Mode Full or half duplex (auto-sensing)

Cellular GSM/GPRS/EDGE

Operating 3G bands:

n B5(850)

n B8(900)

n B2(1900)

n B1(2100)

n B4(AWS)

Operating 4G bands (North America):
(AT&T, T-Mobile)

n B12/B13(700),

n B5(850),

n B4(AWS1700),

n B2(1900)

Digi XBee Industrial Gateway

21

XBee Industrial Gateway hardware XBee Industrial Gateway antennas

Specifications Value

XBee

Module type

Transmit power

Receiver sensitivity (1%

-102 dBm

PER)

See the XBee/XBee-PRO ZigBee RF Module User Guide
(available from the XBee/XBee-PRO ZigBee

Modules (S2C) page) for complete specifications

and product information.

Development Python version 2.7.1

Memory

128 MB RAM, 256 MB Flash
20 MB RAM 20 MB Flash available for Python
applications

n XBee S2C ZigBee

n XBee–PRO S2C ZigBee

n The domestic product version uses the

XBee-PRO RF module, with a transmit

power of 63 mW (+18 dBm).

n The international product version uses the

regular XBee RF module, with a transmit

power of 6.3 mW (+8 dBm).

XBee Industrial Gateway antennas

The XBee Industrial Gateway device uses only external antennas. Connecting antenna(s) to the device
is required.

Note The XBee Industrial Gateway does not have internal antennas.

n Ethernet model:Requires one external XBee antenna.

l For information about purchasing an XBee antenna, see the Digi XBee antenna product

page.

n Cellular model: Requires one external XBee and, depending on the device variant, either one

or two external Cellular antennas.

l For information about purchasing an XBee antenna, see the Digi XBee antenna product

page.

l For information about purchasing a Cellular antenna, see the Digi Cellular antenna product

page.

XBee Industrial Gateway LED descriptions

XBee Industrial Gateway has several LEDs. See the sections below for a description of the LEDs and
their default behavior.

Digi XBee Industrial Gateway

22

XBee Industrial Gateway hardware XBee Industrial Gateway LED descriptions

n Signal strength LED (cellular models only)

n Network LED

n XBee LED

n Power LED

You can control some of the LEDs programmatically. See LED control for a description of how to
control the LEDs on XBee Industrial Gateway.

See Troubleshooting LEDs for troubleshooting information.

LEDs for the Cellular model LEDs for the Ethernet model

Signal strength LED (cellular models only)

Color and blink

LED

pattern Description

OFF (dark) No (or very poor) cellular signal. Moving device to a better

location is recommended.

Solid yellow Adequate cellular signal. This signal strength works for most

applications.

Solid green Good cellular signal.

Digi XBee Industrial Gateway

23

XBee Industrial Gateway hardware XBee Industrial Gateway LED descriptions

Network LED

Note The Network LED remains dark during the initial boot of the device. All diagnosis related to this

LED must be done after the device has been running for at least 60 seconds.

Color and blink

LED

pattern Description

OFF XBee Industrial Gateway operating system is not yet

running.

Blinking yellow,
slow

Solid yellow An IP address has been assigned to XBee Industrial

Blinking yellow ­fast (1 blink per
second)

Solid yellow to
blinking green

Operating system is running, but no network link is
established or IP address assigned.

Gateway.

A network issue has occurred. The two most common
Remote Manager connectivity-related reasons for this
state are:

1. XBee Industrial Gateway cannot connect to a DNS

server to resolve the Remote Manager server

address. See Cannot connect to DNS server to

resolve the Remote Manager server address.

2. XBee Industrial Gateway cannot connect to an NTP

time server to get the correct time. See Cannot

connect to NTP time server to get correct time.

XBee Industrial Gateway is attempting a connection to a
Remote Manager server.

XBee LED

The XBee LED indicates the network connection status of the XBee RF module in XBee Industrial
Gateway to a ZigBee wireless network. At startup, if you are not yet deploying your device in a ZigBee
network, you can ignore this LED and its states. Once XBee Industrial Gateway is deployed in a ZigBee
network, the XBee LED behavior varies depending on whether XBee Industrial Gateway acts as a

Digi XBee Industrial Gateway

Blinking green - fast

(1 blink per second)

Solid green XBee Industrial Gateway is connected to the Remote

Remote Manager server found and XBee Industrial
Gateway is undergoing authentication.

Manager server.

24

XBee Industrial Gateway hardware XBee Industrial Gateway LED descriptions

coordinator or a router. For information on changing XBee Industrial Gateway from a coordinator to a
router, see the topic Joining XBee Industrial Gateway to an existing ZigBee network.

Note The XBee LED remains dark during the initial boot of the device. All diagnosis related to this LED

must be done after the device has been running for at least 60 seconds.

Color and blink

LED

pattern Description

Solid green The XBee RF module has not started or joined a network.

Blinking green The XBee RF module has started or joined a network.

Power LED

Color and blink

LED

pattern Description

OFF (dark) No power.

Solid green Device is powered. This state does not indicate that the

device is fully operational. The Network LED and its states
convey such information.

Digi XBee Industrial Gateway

25

Set up XBee Industrial Gateway

Based on the XBee Industrial Gateway model that you have, choose one of the following options:

n Setting up the XBee Industrial Gateway Cellular hardware

n Setting up the XBee Industrial Gateway Ethernet hardware

Setting up the XBee Industrial Gateway Cellular hardware

This section walks you through the steps required to set up your XBee Industrial Gateway Cellular
hardware and provides additional reference information.

Verify your XBee Industrial Gateway Cellular components

XBee Industrial Gateway cellular model includes the following components:

Component Description

XBee Industrial Gateway Cellular model

Digi XBee Industrial Gateway

26

Set up XBee Industrial Gateway Setting up the XBee Industrial Gateway Cellular hardware

Component Description

Ethernet cable

Power supply

Required additional equipment

Component Description

A computer connected to the
Internet.

Digi XBee Industrial Gateway

27

Set up XBee Industrial Gateway Setting up the XBee Industrial Gateway Cellular hardware

Component Description

XBee antenna

Cellular antennas

An XBee antenna must be connected.
For information about purchasing an XBee antenna, see the

Digi XBee antenna product page.

Depending on the device variant, either one or two cellular
antennas must be connected to the device.
For information about purchasing a cellular antenna, see the

Digi Cellular antenna product page.

Connect the hardware

1. Install a SIM card. See Set up and configure a cellular device for instructions.

2. Optional: If using an Ethernet connection in addition to the cellular, connect one end of the

Ethernet cable to your gateway and the other to a live Ethernet jack.

3. Connect the XBee antenna to the device.

4. Connect the cellular antenna(s) to the device. If your device has two cellular antenna locations,

you must connect an antenna to each location.

5. Connect the power supply.

6. Startup Sequence - After power is applied:

a. The Power LEDturns solid green.

b. The XBee LEDturns blinking green when XBee Industrial

Gateway creates a ZigBee network.

c. The Network LEDgradually turns solid green when XBee

Industrial Gateway connects to Remote Manager.

d. For the Cellular model, the Signal Strength LEDturns

either yellow or green, depending on the cellular signal

strength.

Connect XBee Industrial Gateway to the cellular network

Register the modem in the XBee Industrial Gateway cellular device and set it up in your mobile service
provider's network. See Set up and configure a cellular device for information on configuring the XBee
Industrial Gateway cellular model. Disconnect the Ethernet cable when the configuration steps are
complete.

Digi XBee Industrial Gateway

28

Set up XBee Industrial Gateway Setting up the XBee Industrial Gateway Ethernet hardware

Setting up the XBee Industrial Gateway Ethernet hardware

This section walks you through the steps required to set up your XBee Industrial Gateway Ethernet
hardware and provides additional reference information.

Verify your XBee Industrial Gateway Ethernet components

XBee Industrial Gateway Ethernet model includes the following components:

Component Description

XBee Industrial Gateway Ethernet model

Ethernet cable

Power supply

Digi XBee Industrial Gateway

29

Set up XBee Industrial Gateway Setting up the XBee Industrial Gateway Ethernet hardware

Required additional equipment

Component Description

A computer connected to the
Internet.

XBee antenna

An XBee antenna must be connected.
For information about purchasing an XBee antenna, see the Digi

XBee antenna product page.

Connect the hardware

1. Optional: If using an Ethernet connection in addition to the cellular, connect one end of the

Ethernet cable to your gateway and the other to a live Ethernet jack.

2. Connect the XBee antenna to the device.

3. Connect the power supply.

4. Startup Sequence - After power is applied:

a. The Power LEDturns solid green.

b. The XBee LEDturns blinking green when XBee Industrial

Gateway creates a ZigBee network.

c. The Network LEDgradually turns solid green when XBee

Digi XBee Industrial Gateway

Industrial Gateway connects to Remote Manager.

30

Set up XBee Industrial Gateway Setting up the XBee Industrial Gateway Ethernet hardware

Connect XBee Industrial Gateway to the Ethernet network

Your XBee Industrial Gateway automatically connects to the Ethernet network when a DHCP server is
available to assign an IP address to it and no firewalls block outgoing traffic to ports 3197 and 3199. If
the Ethernet network does not come up, see see Cannot connect to DNS server to resolve the

Remote Manager server address.

Note XBee Industrial Gateway requires a DHCP server to assign its IP address. If you do not have a

DHCP server, see Ethernet IP network settings for information on configuring your IP parameters.

Digi XBee Industrial Gateway

31

Getting started with XBee Industrial Gateway

This section walks you through the steps required to set up your XBee Industrial Gateway and
provides additional reference information.

Set up XBee Industrial Gateway summary

These instructions give an overview of how to set up XBee Industrial Gateway.

1. Configure the network settings. These settings include IP networking parameters and Remote

Manager connectivity.For more information, see:

n Ethernet IP network settings

n Mobile Connectivity settings

2. Connect the XBee nodes to XBee Industrial Gateway. This step involves configuring the

parameters for forming XBee networks on both XBee Industrial Gateway and XBee nodes.

There are three substeps:

a. Configure XBee Industrial Gateway as a coordinator.

b. Join XBee nodes to the coordinator.

c. Verify that the XBee nodes are joined to the coordinator.

See Connect the XBee nodes to XBee Industrial Gateway for more information.

3. Configure XBee ZigBee network addressing settings. See Configure the ZigBee network

addressing parameters for XBee nodes for more information.

4. Explore configuring XBee nodes for input/output.

a. If using serial I/O, configure XBee nodes for serial I/O. See Explore serial I/O for

b. If using digital or analog I/O, configure the XBee nodes for digital or analog I/O. See

5. Look at your device data on Remote Manager. See View your device data for more information.

The following image shows the layout of a fully set up XBee Industrial Gateway.

Digi XBee Industrial Gateway

more information.

Explore digital and analog I/O for more information.

32

Getting started with XBee Industrial Gateway Joining ZigBee networks

Joining ZigBee networks

ZigBee networks are called Personal Area Networks or PANs. In the ZigBee protocol, the only node
that can start a new network is the coordinator. For that reason, each ZigBee network must have one
coordinator.

XBee Industrial Gateway includes a built-in XBee ZigBee node already configured as coordinator.
Therefore, as soon as you power on the XBee Industrial Gateway device, your ZigBee network is
initialized.

To start a network, the coordinator must automatically choose a PAN identifier (PAN ID) and the
operating channel for that network. Once those parameters are established and the network is

Digi XBee Industrial Gateway

33

Getting started with XBee Industrial Gateway Joining ZigBee networks

initialized, the coordinator and routers can allow other devices (other routers or end devices) to join
the network and route data.

Each network is defined with a unique PAN identifier (PAN ID). This identifier is common among all
devices of the same network. That is, devices on the same ZigBee network must share the same PAN
ID in order to communicate with each other. When you power on a coordinator, it automatically
establishes the PAN ID or uses a pre-configured one when it creates the new network.

n If the PANID of the coordinator is 0, it performs a PAN scan to identify nearby ZigBee networks

and uses a random unused PAN ID to start the new network. By default, an XBee Industrial

Gateway coordinator is configured to generate a random PAN ID.

n If the PANID for a router or end device is 0, it performs a PAN scan and tries to join any

available ZigBee network it finds.

You can connect to an XBee ZigBee module that is configured as a router node to the network
initialized by XBee Industrial Gateway. By default, the PAN ID of this ZigBee module is configured to 0.
Therefore, if you power on the XBee ZigBee module and there is no other ZigBee network around, the
module joins the ZigBee network initialized by XBee Industrial Gateway automatically. The joining
operation occurs when the Association LED of the board on which the XBee ZigBee module is mounted
starts blinking.

The 802.15.4 PHY (physical layer) protocol description defines 16 operating channels in the 2.4 GHz
frequency band. Before starting the network, the coordinator automatically performs a channel scan
to select a good channel to use for the network.

You can configure all the ZigBee nodes in a network with the channel or channels on which they
operate.

Joining XBee Industrial Gateway to an existing ZigBee network

Although this is not a common task, you can configure your XBee Industrial Gateway device to operate
as a router and join an existing ZigBee network.

To join XBee Industrial Gateway to an existing ZigBee network:

1. Open a web browser and type the URL of XBee Industrial Gateway: http://192.168.100.1. The

XBee Industrial Gateway web interface appears.

2. Click XBee Network in the left menu.

3. Select the XBee Industrial Gateway ZigBee local XBee device. The XBeeConfiguration page

appears.

4. From the XBee Configuration page, click Network Settings.

Digi XBee Industrial Gateway

34

Getting started with XBee Industrial Gateway Joining ZigBee networks

5. Configure the Extended PAN ID (ID) option with the PAN ID of the network to which XBee

Industrial Gateway should join.

6. Clear the Coordinator Enable(CE) check box. This allows XBee Industrial Gateway to behave

as a router node within the ZigBee network.

7. Click Apply to save the changes to the device. After you apply the changes, XBee Industrial

Gateway behaves as a router node and tries to connect to the ZigBee network with the PAN ID

that you configured.

To join your XBee ZigBee module from the kit to an existing network, follow the steps described in

Configuring XBee Industrial Gateway with a custom PAN ID.

Configuring XBee Industrial Gateway with a custom PAN ID

In some cases, you want control of the PAN ID used to create your ZigBee network. Use a custom
PANIDand configure the coordinator, routers, and end devices to use it when there are other
networks around and you do not want your router or end device nodes to join them.

To configure XBee Industrial Gateway with a custom PANID:

1. Open a web browser and type the URL of XBee Industrial Gateway: http://192.168.100.1. The

XBee Industrial Gateway web interface appears.

2. Under Configuration, click XBee Network.

3. Select the XBee Industrial Gateway local XBee device that you want to configure. The XBee

Configuration page appears.

4. From the XBee Configuration page, click Network Settings.

Digi XBee Industrial Gateway

35

Getting started with XBee Industrial Gateway XBee Industrial Gateway and non-XBee ZigBee Devices

5. Configure the Extended PAN ID (ID) option with your custom PAN ID value.

6. Click Apply to save the changes to the device. After applying the changes, the coordinator

initializes the ZigBee network with the new PAN ID. If you had any other ZigBee nodes

connected to the network, you must update their PAN IDs so they will join the new one.

XBee Industrial Gateway and non-XBee ZigBee Devices

You can refer to additional resources to learn about using XBee Industrial Gateway with non-XBee
ZigBee devices. Digi provides support and resources for your use of the product.

Resources include:

n Digi forum

n Digi Knowledge Base

n XBee/XBee-PRO ZB RF Modules User Guide for more information about features and operation of

the XBee RF module mounted inside the gateway

n XBee ZigBee information on the Digi XBee ZigBee product page

Digi XBee Industrial Gateway

36

Administration and maintenance tasks

There are several administrative and maintenance tasks that you need to perform periodically on
XBee Industrial Gateway. This topic covers common administrative tasks and how to perform them
through Remote Manager and the web interface.

File management

The XBee Industrial Gateway file management feature lets you manage custom applications, their
associated data files, and other files. The File Management page is available in Remote Manager and
in the web interface.

You can also push firmware update files to the device file system, and pull log files from the device file
system. See XBee Industrial Gateway file system for information about the file system.

File Management page in Remote Manager

You can use the File Management page in Remote Manager to load files, such as custom application
files, onto XBee Industrial Gateway and display current information about loaded files.

You can also use this page to download system log files from XBee Industrial Gateway to view for
troubleshooting or other purposes. These log files are in the /WEB/logging folder. For a description of
the XBee Industrial Gateway file system layout, see XBee Industrial Gateway file system.

Note Digi recommends using no more than 20 MB for custom applications, as XBee Industrial Gateway

requires a portion of the same space to be capable of managing persistent system logs and firmware
updates.

Access the File Management page

Follow this process to access the File Management page in Remote Manager:

1. Access Remote Manager and log in.

2. Click the Device Management tab.

3. From the list of devices, double-click on the device you want to review.

4. Click the File Management link in the left-hand pane. The File Management screen displays.

File Management toolbar

The File Management toolbar provides quick access to file management tasks.

Digi XBee Industrial Gateway

37

Administration and maintenance tasks File management

Button/Field

Name Description

Upload file Opens a dialog for uploading files to the current folder (directory).

Download file Downloads the selected file to a computer. You can choose to open

the downloaded file with a specified tool or save it.

Delete Deletes the selected items.

Refresh Refreshes the list of folders and files displayed.

Back Move to the previous folder in folder history.

Forward Move to the next folder in folder history.

Home Returns to the root folder.

Current or
destination
folder

Go Goes to the directory specified in

An editable field that displays the current folder. You can use this
field to type a different destination directory.

Current or destination folder

field.

File Management page in the XBee Industrial Gateway web interface

You can use the File Management page to load files onto XBee Industrial Gateway and display current
information about loaded files. For a description of the XBee Industrial Gateway file system layout, see

XBee Industrial Gateway file system.

Access the File Management page

Follow this process to access the File Management page in the web interface:

1. Access the XBee Industrial Gateway web interface.

2. Click File Management under Administration to launch the File Management page.

File Management page

The following fields and buttons appear on the File Management page:

Volume Information section: Displays the current directory for loading files and free space remaining.

Note Digi recommends using no more than 20 MB for custom applications, as XBee Industrial Gateway

requires a portion of the same space to be capable of managing persistent system logs and firmware
updates.

Upload to Current Directory section: Uploads files to the current directory.

n Choose File: To find a file on your computer, click Choose File and go to the file.

n Update file: Click Update file to begin the file upload process.

File List: A listing of the current directory (as noted in the Volume Information section) on the device.

Digi XBee Industrial Gateway

38

Administration and maintenance tasks Back up or restore the configuration

n Open: Opens a directory after it is selected in the file list. The current directory changes and

the list is updated.

n Make Directory: Creates a new, empty directory in the current directory.

n Save As: Downloads a regular file from the file system to your local computer.

n Remove: Deletes files or empty directories. If there are one or more files in a directory, the

directory cannot be deleted.

Refresh button: Reloads the information on the page.

Back up or restore the configuration

After you configure XBee Industrial Gateway device, back up the configuration settings. You can back
up the settings from the Remote Manager or the web interface.

Having a backup of the configuration settings is recommended if you run into one of the following
situations:

n You need to restore the configuration settings because a problem occurred.

n You upgraded or added the firmware and you need to restore your configuration settings.

n You added new devices that need to be configured and want to use the same configuration

settings as the original device. In this instance, you can load the backup configuration settings

from the original device onto other devices.

Back up and restore files from Remote Manager

1. Access Remote Manager and log in.

2. From the Devices page, click the devices in the Device list that you want to back up.

3. Click the More button within the toolbar and then select the Export Properties option from

under the Devices category.

4. Choose one of the following options from the Export Properties dialog and then click OK:

n Export all: Exports the device’s entire configuration. The option allows you to export

the entire configuration, including IP address information, and provides you with a

complete backup configuration for the device.

n Export all except unique network and device identity properties: Exports the

non-networking portion of the configuration. Choose this option if you want to use this

device's configuration as a template to apply to a group of devices in the future.

Back up and restore files from the XBee Industrial Gateway web interface

The Backup/Restore page allows you to back up and restore the following device configuration
settings to a file:

n XBee Industrial Gateway

n (Optional) XBee RF module

Digi XBee Industrial Gateway

39

Administration and maintenance tasks Back up or restore the configuration

Back up files

To back up files from the XBee Industrial Gateway web interface:

1. Access the XBee Industrial Gateway web interface.

2. Click Backup/Restore under Administration.

3. In the Volume Information section, review the amount of free space available.

4. If you want to save the configuration settings for the XBee RF module along with the device

configuration settings, select the Include XBee gateway radio settings in the backup file

option.

5. In the Backup field, enter the name of the back up file.

6. Click OK to start the process.

Restore files

To restore files from the XBee Industrial Gateway web interface:

1. Access the XBee Industrial Gateway web interface.

2. Click Backup/Restore under Administration.

3. Click Choose File in the Restore Configuration section.

4. Select the configuration file you want to restore.

5. Click OK.

6. Click Restore to restore the configuration from the selected file.

Backup/Restore page

The following fields and buttons appear on the Backup/Restore page:

Volume Information section: Displays information about the user file system, /userfs.

n Current Directory: The backup file is temporarily saved in this directory on the device. Note

that navigating to the file system is not possible on this page. To go to the file system, click File

Management under Administration and then go to the file system.

n Free Space: The amount of free space on the user file system. The typical size of a backup file

is about 8 KB.

Backup Configuration section: Downloads the gateway configuration file through the web browser
and allows you to save the file on your computer.

n Include XBee gateway radio settings in the backup file: If enabled, the configuration

settings for the XBee RF module are saved along with the device configuration settings.

n Backup: The name of the backup file. The default file name is backup.cfg. You can change the

file name from the save file dialog box. Any name is allowed.

Restore Configuration section: Restores configuration settings from a backup file on your computer
or a server.

n Choose File: Opens a browse dialog for locating and selecting the appropriate configuration

file.

n Restore: Click Restore to restore the configuration from the selected file.

Digi XBee Industrial Gateway

40

Administration and maintenance tasks Update firmware

Errors

Any errors that occur during the restore process appear in a red banner at the top of the
Backup/Restore page. Typically, the only reason an error occurs is if a user has modified the backup
file. The following list provides some of the possible error messages.

n Invalid file contents: The file contents are not a valid backup format. This may be caused by

invalid XML syntax.

n Element set_setting has extra content (name): The settings group name is not recognized.

n Element set_setting failed to validate content (name): Incorrect value for setting name.

n Other RCI errors are possible, but are less common.

Update firmware

There are several types of firmware updates for XBee Industrial Gateway:

n XBee Industrial Gateway operating system: You can download Gateway operating system

firmware updates for XBee Industrial Gateway from the Digi Support site. You can then load

the firmware through the web interface or Remote Manager.

You can only upgrade the gateway operating system, not downgrade it, through the web

interface or Remote Manager. The firmware image contains a certificate that is verified before

XBee Industrial Gateway accepts an upgrade.

n XBee RF module on the gateway: See Update the local XBee Industrial Gateway firmware.

n XBee RF modules on your local network to be delivered Over the Air (OTA): As XBee

networks can involve a large number of nodes, Digi provides a way to schedule automatic XBee

Industrial Gateway firmware updates and manage firmware files. In the XBee Industrial

Gateway web interface, OTA firmware updates are performed from a page linked from the

XBee Configuration page. These firmware updates are supported for XBee ZigBee modules

only. For information on these updates, see XBee network OTA firmware updates.

Update firmware from Remote Manager

You can update the firmware from Remote Manager:

n Update the XBee Industrial Gateway device operating system firmware

n Update the local XBee Industrial Gateway firmware

n Update the XBee network node firmware (OTA updates) from Remote Manager

You can also schedule firmware updates from Remote Manager.

Update the XBee Industrial Gateway device operating system firmware

To update the XBee Industrial Gateway device operating system firmware:

1. Download the appropriate firmware from XBee Gateway product support page. For more

details on firmware filename conventions, see About firmware files.

2. Log in to Remote Manager.

3. Click the Device Management tab.

Digi XBee Industrial Gateway

41

Administration and maintenance tasks Update firmware

4. Select one or more devices from the device list to which you want to apply firmware updates,

right-click, and select Update Firmware.

5. Type or browse to the .bin filename containing the firmware update.

6. Click Update Firmware.

Update the local XBee Industrial Gateway firmware

To update the local XBee Industrial Gateway firmware:

1. Download the appropriate firmware from the XBee Gateway product support page. For more

details on firmware file name conventions, see About firmware files.

2. Log in to Remote Manager.

3. Click the Device Management tab.

4. Go to the device list.

5. Select one or more devices to which you want to apply firmware updates, right-click, and then

select Update Gateway XBee Radio Firmware.

6. Type or browse to the .ebl filename containing the firmware update.

7. Click Update Firmware.

The XBee Industrial Gateway firmware is updated. If the gateway is enabled, most XBee

Industrial Gateway module settings will be preserved when the firmware update completes.

Some settings, such as encryption keys, may not be preserved and must be entered again.

8. If required, type your encryption keys.

Schedule firmware updates

You can schedule firmware updates from Remote Manager. See the Digi Remote Manager User Guide
for more information on scheduling firmware updates.

1. Log in to Remote Manager.

2. Click the Device Management tab.

3. From the list, select the device for which you want to schedule a firmware update.

4. Right-click on the device, and choose Firmware > Update Firmware. The Update Firmware

dialog appears.

5. In the File field, enter or browse for the file containing the firmware update.

6. From the Schedule Options drop-down in the upper right corner of the dialog, select the

appropriate scheduling option.

7. Click Update Firmware to schedule the update.

Update firmware from the XBee Industrial Gateway web interface

Firmware updates are available from the Administration > Firmware Update page in the XBee
Industrial Gateway web interface.

n Update the XBee Industrial Gateway device operating system firmware

n Update the local XBee Industrial Gateway firmware

Digi XBee Industrial Gateway

42

Administration and maintenance tasks Update firmware

Update the XBee Industrial Gateway device operating system firmware

To update the XBee Industrial Gateway device operating system firmware:

1. Download the appropriate firmware from the XBee Gateway product support page. For more

details on firmware filename conventions, see About firmware files.

2. In the XBee Industrial Gateway web interface, click Firmware Update under Administration.

The Firmware Update page appears.

3. Select the Upgrade device operating system check box.

4. Click Next.

Status information for the firmware update appears, including the following information:

n Target Firmware: The device operating system firmware to be loaded on XBee

Industrial Gateway.

n Status: The current status of the firmware update operation.

For the XBee Industrial Gateway device operating system, the firmware update

operation moves through several states:

a. The web browser uploads the firmware file.

b. The firmware update is applied to the XBee Industrial Gateway operating

system. If the firmware update is successful, the message Firmware

Upgrades Completed Successfully appears. If errors occur during the

update, the message Completed with errors appears. If you need help

understanding the errors and viewing the log file containing the errors,

contact Digi Support.

c. XBee Industrial Gateway automatically reboots.

d. XBee Industrial Gateway returns to an operating state (run). All these states

are shown on the Firmware Update page.

Update the local XBee Industrial Gateway firmware

To update the local XBee Industrial Gateway firmware:

1. Download the appropriate firmware from the XBee Gateway product support page. For more

details on firmware filename conventions, see About firmware files.

2. In the XBee Industrial Gateway web interface, click Firmware Update under Administration.

The Firmware Update page appears.

3. Select the Upgrade local (gateway) XBee’s firmware check box.

4. Click Next.

5. Type or browse to the filename containing the firmware update.

Digi XBee Industrial Gateway

43

Administration and maintenance tasks Mobile device status

6. Click Next.

Status information for the firmware update appears, including the following information:

n Target Firmware: The device operating system firmware to be loaded on XBee

Industrial Gateway.

n Status: The current status of the firmware update operation.

The XBee firmware is updated. If the gateway is enabled, most XBee module settings will be

preserved when the firmware update completes. Some settings, such as encryption keys, may

not be preserved and must be entered again.

7. If required, type your encryption keys.

About firmware files

Firmware files for the operating system and XBee module on XBee Industrial Gateway are available
through Digi Technical Support on the XBee Gateway Support page. Click the Firmware Updates link.

Gateway operating system firmware files

Gateway operating system firmware files have a .bin extension.

XBee RF module firmware files

XBee RF module firmware files have an .ebl extension. From the Digi Support site, click the Firmware
Updates option. You can select the product and then download the firmware.

There is only one firmware file for the XBee RF module in XBee Industrial Gateway products. It is
named XBP24-S2C_40XX.ebl, where XX is the firmware version.

There are other possible file types for OTA firmware updates. See XBee network OTA firmware

updates.

Mobile device status

The items on Mobile Status page are specific to a cellular modem or service provider account. These
items vary in the information reported from modem to modem and also differ between LTE and GSM
services. A value that appears here depends on the modem type and connection state; if there is no
value for a status field, it does not appear. Use this information when troubleshooting issues and
communicating with technical support.

Displaying the mobile device status

To display the status of mobile device, choose one of the following options:

From Remote Manager

1. Click the Device Management tab.

2. From the device list, double-click the device to display the device properties menu.

3. Select System Information >Mobile Information. The Mobile Information page appears.

From the XBee Industrial Gateway web interface

Click Mobile Status under Administration. The Mobile Status page appears.

Digi XBee Industrial Gateway

44

Administration and maintenance tasks Mobile device status

Mobile Status page

The following table describes the fields on the Mobile Status or Mobile Information page.

In general, all of the status fields in the page may display for either GMS or LTE cellular modems. The
status fields display depending on the modem type, service, or registration or connection state.

Status field

Device type The type of cellular modem. The possible values are

Description

LTE

and GSM.

Manufacturer The manufacturer of the cellular modem.

Model The manufacturer’s model number for the cellular modem.

Revision The manufacturer’s version number for the software running on the

cellular modem.

Serial number The manufacturer’s serial number for the cellular modem.

Phone number

The phone number stored on the SIM. The SIM may not have a number
stored, or it may not be correct.

SIM IMSI The International Mobile Subscriber Identity (IMSI) for the SIM card. This

value is the account number for the mobile subscriber.

SIM ICCID The Integrated Circuit Card Identifier (ICCID) for the SIM card. This value

is the serial number of the SIM card.

SIM PIN status

Indicates the lock status of the SIM. There area many possible status
values. The most common status values are:

n READY: SIM is ready. The PIN was entered or no PIN is required.

n SIM PIN: A PIN is required to unlock the SIM. You can enter the

PIN from the Mobile Configuration page.

SIM slot index

n SIM PUK, SIM PIN2, SIM PUK2, and similar codes: The SIM is

locked and cannot be unlocked by the XBee Industrial Gateway

cellular device. It must be placed in another device or phone to be

unlocked.

n Error: Either the SIM was not inserted or there was another SIM

problem.

This status only appears for products that support multiple SIMs.
Indicates which SIM slot is currently in use by the device.

n 1 means the first slot.

n 2 means the second slot.

Digi XBee Industrial Gateway

45

Administration and maintenance tasks Mobile device status

Status field

Signal strength

Signal level

Signal quality

Registration status

Description

Received cellular signal strength indicator (RSSI) for GSM.. A measure of
the signal level of the network.
Different RSSI levels are used by GSM to determine the number of bars.

n For GSM: -108 or more is 1 bar, -93 is 2, -77 is 3 bars.

Reference Signal Received Power (RSRP) for LTE. A measure of the
signal level of the network.

n For LTE: -118 or more is 1 bar, -106 is 2, -90 is 3 bars.

The number of bars indicates the strength of the received cellular signal.

n 0: No signal

n 1: Poor signal

n 2: Adequate signal

n 3: Good signal

An indicator of the quality of the received cellular signal, measured in dB.
This value is also known as Ec/Io.

The status of the cellular modem’s connection to a cellular network.

n Not registered

n Registered (Home network)

n Searching for Network

n Not Registered (Access Denied)

n Not Available (Reason not Known)

n Registered (Roaming)

Cell ID Identifier of the cellular base station with which the cellular modem is

registered.

Location area code Identifier of the location of a group of cellular base stations with which

the cellular modem is registered, in hexadecimal format.

Mobile country code

Identifies a mobile phone operator/carrier with which the cellular
modem is registered.

Mobile network code Identifies a mobile phone operator/carrier with which the cellular

modem is registered.

Operator name The name of the mobile operator with which the modem is registered.

This corresponds to the mobile country and network codes.

Digi XBee Industrial Gateway

46

Administration and maintenance tasks Mobile device status

Status field

Band

Description

The radio frequency band used by the modem.
LTEcan use one of the following bands:

n Band 2

n Band 4

n Band 5

n Band 13

Service

The type of data service provided by the cellular network. For LTE, the
data service is one of the following:

n None

n 1xRTT

n EVDO Rev 0

n EVDO Rev A

Future cellular modems may have other values.

Channel Radio channel being used by the cellular modem.

Profile

The current set of mobile configuration settings used to configure the
cellular modem. XBee Industrial Gateway cellular products always use
profile 0.

Connection state

The operating state of the cellular modem. The possible states are as
follows:

n Initializing: Resetting and configuring the modem.

n Registering: Searching for the modem's cellular network.

n Delay before connecting: The modem delays after an

unsuccessful connection (Verizon only).

n Connecting: Establishing a mobile data connection.

n Connected: Established an active mobile data connection .

n Disconnecting: Ending the mobile data connection.

n Disconnected: Ended the mobile data connection. See Disconnect

reason for the cause.

n Disabled: The mobile data connection is disabled in the

configuration settings.

n PRL update: Updating the preferred roaming list (LTE only).

n Operator scan: Searching the modem for available mobile

operators (GSM only).

n No device found: The modem is not available or is

malfunctioning.

Digi XBee Industrial Gateway

47

Administration and maintenance tasks Mobile device status

Status field

Description

Connection duration Amount of time the current mobile data connection has been active. The

format is N days HH:MM:SS.

Connection error

This status appears only after a connection error occurs. The possible
reasons the previous connection attempt failed are as follows:

n SIM PIN required: The SIM PIN must be entered on the Mobile

Configuration page.

n SIM PIN incorrect: The SIM PIN entered does not match the

actual one for the SIM.

n SIM not ready: No SIM inserted or other SIM problem.

n Not registered: The modem did not register with a cellular

network.

n Dial failed: Error starting data connection.

n Authentication failed: Incorrect login or password entered on

the Mobile Configuration page.

n Connection timeout: Connection did not complete.

n Device reset error: The modem could not be reset.

n Device open error: The modem is malfunctioning.

n Device config error: The modem could not be configured.

n PPP error: Internal system error.

Disconnect reason

This status appears after a previous connection ends. The possible
reasons the previous connection ended are as follows:

n User requested: Initiated by user action.

n Network disconnect: Initiated by cellular network or carrier.

n Carrier loss: Poor signal or disconnected by network.

n Connection timer: Connection did not complete.

n Receive idle timer: No data received for configured receive idle

time.

n Device monitoring error: Error while monitoring the modem

status. May indicate a malfunctioning modem.

IP address Internet protocol address of the mobile data interface. You can contact

the device at this IP address if permitted by the carrier.

Digi XBee Industrial Gateway

48

Administration and maintenance
tasks

Displaying the XBee Industrial Gateway End User License Agreement

(EULA)

Status field

DNS primary address

Receive idle time The amount of time since the cellular modem last received data.

Transmit idle time The amount of time since the cellular modem last transmitted data.

Connections The number of mobile data connection attempts since the XBee

Connection errors The number of unsuccessful mobile data connection attempts since the

Carrier loss The number of times the connection was lost because of poor signal or

LCP echo failed The number of failed Link Control Protocol (LCP) echo requests that

Idle timeout The number of connection resets that occurred because the idle timeout

Description

IP address of the primary Domain Name System (DNS) server assigned
by the mobile carrier. This server resolves domain names to IP
addresses.
See Default behavior regarding DNS for more information on how XBee
Industrial Gateway uses the DNS primary and secondary address.

Industrial Gateway cellular device was started.

XBee Industrial Gateway cellular device was started.

being disconnected by the network.

were sent after a “quiet” interval to test the cellular link and/or keep it
alive. Not used by XBee Industrial Gateway cellular products.

reached/exceeded the maximum allowed for transmitted and received
data.

User disconnect The number of disconnects of the cellular connection performed by

device users.

Monitoring errors Number of errors encountered while monitoring the cellular modem

status. May indicate a malfunctioning modem.

Device resets Number of cellular modem resets caused by errors, failed connection

attempts, or user requests.

Received bytes Number of bytes received by the cellular modem during the current data

session.

Transmitted bytes Number of bytes transmitted by the cellular modem during the current

data session.

Total received bytes Total number of bytes received by the modem since the XBee Industrial

Gateway cellular device was started.

Total transmitted bytes Total number of bytes transmitted by the modem since the XBee

Industrial Gateway cellular device was started.

Displaying the XBee Industrial Gateway End User License Agreement (EULA)

You can access the End User License Agreement (EULA) for XBee Industrial Gateway from the web
interface.

Note The XBee Industrial Gateway EULA is not available through Remote Manager.

Digi XBee Industrial Gateway

49

Administration and maintenance tasks Rebooting XBee Industrial Gateway

1. Access the web interface.

2. Click Legal Notices under Administration.The EULA for XBee Industrial Gateway appears.

Rebooting XBee Industrial Gateway

You can reboot XBee Industrial Gateway as needed. Note that XBee Industrial Gateway reboots itself
if you make changes to the configuration that require a reboot to activate those changes.

To reboot XBee Industrial Gateway, choose one of the following options:

n From Remote Manager, right-click the XBee Industrial Gateway device and select More >

Reboot.

n From the web interface, click Reboot under Administration.

Wait approximately one minute for the reboot to complete.

Displaying system information

To display system information, choose one of the following options:

From Remote Manager

1. Click the Device Management tab.

2. From the device list, double-click the device to display the device properties menu.

3. Click System Information. The System Information page appears.

From the XBee Industrial Gateway web interface

View general system information and system statistics from the Home page.

Disconnecting XBee Industrial Gateway from Remote Manager

You can disconnect XBee Industrial Gateway from Remote Manager.

1. Log in to Remote Manager.

2. Click the Device Management tab.

3. From the device list, select the XBee Industrial Gateway device that you want to disconnect.

4. Select More > Disconnect. A confirmation dialog displays.

5. Click Yes to complete the disconnect process.

If XBee Industrial Gateway is configured to automatically reconnect to Remote Manager, the
device re-establishes the connection to Remote Manager after its reconnection timeout period
has expired.

Digi XBee Industrial Gateway

50

About programming

XBee Industrial Gateway offers a variety of interfaces that produce and/or consume data. Developing
software programs for XBee Industrial Gateway products allows Digi customers to provide custom
logic to control the information to and from these interfaces.

This section introduces the Digi programming tools and resources available to you. You can also see

Program XBee Industrial Gateway using Python to learn about programming elements and operations

available for XBee Industrial Gateway using annotated example programs.

Python

XBee Industrial Gateway features a standard Python 2.7.1 distribution, allowing you to develop and
test applications that are not dependent on Digi-proprietary interface modules. Python is a dynamic,
object-oriented language for developing software applications, from simple programs to complex
embedded applications.

The standard Python 2.7.1 distribution has a more complete library set than the versions supported in
predecessor gateway products, and integrates well with standard Python. You can typically transfer
scripts developed in this manner to the device for final testing at the end of the development cycle,
with a computer serving as a device proxy during the bulk of development.

For detailed information about programming with Python, see Program XBee Industrial Gateway

using Python.

The sections below describe the basic Python applications that you may use:

n Python: XBee Industrial Gateway features a standard Python 2.7.1 distribution, allowing you to

develop and test applications that are not dependent on Digi-proprietary interface modules.

Python is a dynamic, object-oriented language for developing software applications, from

simple programs to complex embedded applications.

For more information, see Program XBee Industrial Gateway using Python.

n XBee Industrial Gateway Python application: The XBee Industrial Gateway Python

application resides on XBee Industrial Gateway. Its key functions include connecting your XBee

modules to Remote Manager, enabling uploads of data to Remote Manager, and receiving

remote text and commands. Python application is installed by default in your XBee Industrial

Gateway device and automatically starts when the gateway is initialized.

For more information on the XBee Industrial Gateway Python application, see XBee Industrial

Gateway Python application and Remote Manager.

n Digi ESP: Digi ESP is an IDE featuring device detection, debugging, compiling, and downloading

of Device Integration Application (DIA)/Python code to Digi gateways.

For more information, see Digi ESP for Python.

Digi XBee Industrial Gateway

51

About programming XBee ZigBee Cloud Kit web application source code

n DIA: Device Integration Application (DIA) is an application software platform for Digi gateways.

DIA makes it easy to connect remote devices and sensors to Digi gateway products.

For more information, see DIA software.

n Linux command shell: The Linux command shell interface that is available on XBee Industrial

Gateway is useful for some programming and device management tasks. With the Linux

command shell, you can experiment with the Python interpreter interactively, create scripts,

launch scripts, and control the script operation.

For more information, see Linux command shell (command-line interface).

XBee ZigBee Cloud Kit web application source code

You can use the XBee ZigBee Cloud Kit web application source code and other tools available on
Github to build your own custom applications.

The source code for the XBee ZigBee Cloud Kit web application is located at

https://github.com/digidotcom/XBeeZigBeeCloudKit.

For more information on the XBee ZigBee Cloud Kit, see the XBee ZigBee Cloud Kit support page.

Programming calls through Server Command Interface (SCI) and
Remote Command Interface (RCI)

You can use the Web Services Server Command Interface (SCI) and the Remote Command Interface
(RCI) as an alternative means of getting settings and state data from the device. For more
information, see:

n SCI (Server Command Interface) chapter of the Digi Remote Manager Programmer Guide

n Remote Command Interface (RCI) Specification document

XBee Industrial Gateway file system

XBee Industrial Gateway supports standard Linux shell file operations for managing directories and
files.

You can access the file system resident on XBee Industrial Gateway through the following interfaces:

n Web interface

n Command line interface

n Remote Manager

Important directories

/WEB/python

The /WEB/python/ directory contains user-specific files, such as custom Python applications. You can
create subdirectories in this area for the customer's applications. This area is read-write.

/WEB/logging

The /WEB/logging directory contains system log files, including eventlog.txt, python.log, digi.log,
xbee.log, and sef.log. These files are read-only. For more information on these files, see XBee

Digi XBee Industrial Gateway

52

About programming Load applications onto XBee Industrial Gateway

Industrial Gateway system log.

Load applications onto XBee Industrial Gateway

To load an application onto XBee Industrial Gateway, use the File Management function in Remote
Manager or the XBee Industrial Gateway web interface. For instructions, see File management.

Digi XBee Industrial Gateway

53

Program XBee Industrial Gateway using Python

XBee Industrial Gateway features a standard Python 2.7.1 distribution, allowing you to develop and
test applications that are not dependent on Digi-proprietary interface modules. Python is a dynamic,
object-oriented language for developing software applications, from simple programs to complex
embedded applications.

The standard Python 2.7.1 distribution has a more complete library set than the versions supported in
predecessor gateway products, and integrates well with standard Python. You can typically transfer
scripts developed in this manner to the device for final testing at the end of the development cycle,
with a computer serving as a device proxy during the bulk of development.

The following sections contain information about programming XBee Industrial Gateway with Python:

Find Python learning resources 55
Digi-specific Python modules for programming 55
Sample programs 55
XBee Industrial Gateway Python application and Remote Manager 58
Configuring a Python application in the web interface 83
Digi ESP for Python 83
DIA software 87
Linux command shell (command-line interface) 87

Digi XBee Industrial Gateway

54

Program XBee Industrial Gateway using Python Find Python learning resources

Find Python learning resources

You can learn more about programming with Python by referring to the following sections.

Digi Python Programmer's Guide

The Digi Python Programmer’s Guide on the Digi Wiki for Developers introduces the Python
programming language by showing how to create and run a simple Python program. It reviews Python
modules, particularly those with Digi-specific behavior, and describes how to load and run Python
programs onto Digi devices, and run sample Python programs.

Python support forum

You can find answers to common questions and exchange ideas and examples with other members of
the Digi Python development community at the Digi Forum.

Digi Wiki for Developers

The Digi Wiki for Developers provides references for developing solutions using the Digi
communications portfolio, software and services, including Python, Remote Manager, DIA, and more.
The Wiki includes how-to's, example code, and M2M information to speed application development.
Digi encourages an active developer community and welcomes your contributions.

Digi-specific Python modules for programming

Several Digi-provided built-in modules apply to functionality in XBee Industrial Gateway and are
documented on the ConnectPort X2e developer Wiki. From that page, you can go to the information
pages on these modules:

n digihw: Provides an interface to local hardware.

n idigimsg: This is an internal module with functions used by DIA and Smart Energy Framework.

n rci: Provides a mechanism for processing arbitrary RCI request strings, as well as a means to

set up callbacks to allow Python scripts to respond to remote requests made via specialized

RCI commands.

n uptime: Allows access to the Linux gettime function for various clocks.

n watchdog: A safeguard that an application can use for critical operations, in which, if the

application threads do not service their watchdog within the promised interval, the entire

system reboots.

n xbee: A collection of utility methods for programming the XBee RF module on XBee Industrial

Gateway. It also includes the Python XBee socket interface support.

Sample programs

These simple annotated samples introduce several programmable features for XBee Industrial
Gateway, including:

n LED control

n Watchdog

Digi XBee Industrial Gateway

55

Program XBee Industrial Gateway using Python Sample programs

n RCI callback

n XBee functions

LED control

Controlling the LEDs on XBee Industrial Gateway is handled through the user_led_set function. This
sample program controls the Network LED.

Note that if native features are still assigned to the LED, those behaviors will mix with the behaviors in
the sample program.

Note The highlighted numbers in the sample code correspond to the items in the Program Notes,

below.

import digihw (1)
import time

while True:
digihw.user_led_set(True,1) (2)
time.sleep(1.0)
digihw.user_led_set(False,1) (3)

digihw.user_led_set(True, 2) (4)
time.sleep(1.0)
digihw.user_led_set(False,2) (5)

Program notes

1. The digihw module includes the user_led_set function needed by the program. The user_led_

set has two are two parameters: value and led. The user controlled LED is made to match the

logic state of the “value” parameter. A value of “True” turns on the LED, and a value of “False”

turns it off. The “led” parameter indicates which user LED to blink, with LED 1 being the default.

2. Turn on the “yellow” Network LED.

3. Turn off the “yellow” Network LED.

4. Turn on the “green” Network LED.

5. Turn off the “green” Network LED.

Watchdog

The watchdog feature, provided through the watchdog module, exists as a safeguard. If there are
critical operations that “must” happen periodically, or else the system will be irretrievably broken, an
application can request that a “watchdog” be established. If the application threads do not service
their watchdog within the promised interval, the entire system reboots. You can change or, if
necessary, delete the intervals for these software watchdogs . Using a software watchdog exists as a
measure of last resort. Appropriate error detection and handling with Python scripts is certainly
recommended.

The following sample program demonstrates the watchdog feature.

Note The highlighted numbers in the sample code correspond to the items in the Program Notes,

below.

Digi XBee Industrial Gateway

56

Program XBee Industrial Gateway using Python Sample programs

import watchdog (1)
import time

w=watchdog.Watchdog('test',20) (2)
for x in xrange(1,6): (3)
print "Step ", x (4)
time.sleep(10.0) (5)
w.heartbeat() (6)
print "Step just before the end..." (7)
time.sleep(60.0) (8)
print "Step after the end." (9)

Program notes

1. The watchdog module includes the Watchdog class needed by the program.

2. Create a watchdog object named “test” that will expire in 20 seconds.

3. Loop five times (1-5).

4. Indicate our iteration...

5. ... sleeping less than the timeout on each iteration, but more time than the timeout in total.

6. Reset the watchdog timer to 20 seconds each iteration, allowing all of the loops to complete.

7. Indicate that small loops are complete.

8. Sleep for an interval much longer than the timeout.

9. This print statement never executes, because the system will reboot when the watchdog

timeout expires.

RCI callback

An RCI callback involves two types of actions, demonstrated in the following programs:

n Making RCI requests from Python applications.

n Extending RCI to allow Remote Manager to make requests of Python applications. This is

known as an RCI callback.

The following example shows an RCI request.

Note The highlighted numbers in the sample code correspond to the items in the Program Notes,

below.

import rci (1)

request_string=""" (2)
<rci_request version="1.1">
<query_state>
<interface_info name="eth0">
<ip/>
</interface_info>
</query_state>
</rci_request>
"""

print rci.process_request(request_string) (3)

Program notes

Digi XBee Industrial Gateway

57

Program XBee Industrial Gateway using
Python

1. The rci module includes the process_request function needed by the program.

2. A string representing the RCI request is needed. This sample uses the Python multi-line string

syntax to make it clear that the XML represents a request for the current IP address of the

Ethernet interface. Combining the lines into a single string on one line would work in the same

way.

3. The RCI XML is submitted for parsing, and the resulting string is returned. In this sample, the

result is simply printed.

Following example shows a simple RCI callback:

import rci (1)

def cb(req): (2)
print "Received request: " + req (3)

r=rci.RciCallback() (4)
r.register_callback('test', cb) (5)

rci.process_request('<rci_request version="1.1"><do_command
target="test"><customxml/></do_command></rci_request>')(6)

Program notes

1. The RCI module includes the RciCallback class needed by the program.

XBee Industrial Gateway Python application and Remote

Manager

2. Create a function to be called whenever a remote entity wants to communicate with this

script.

3. This simple function will simply demonstrate that it received a request that could be parsed

and handled however the application saw fit.

4. Create a callback object.

5. Assign the target “test” to the new callback object. If a remote entity issues a “do_command”

with the target “test”, the supplied callback function will be called.

6. This is simply an example that causes the callback to be called. This example could also have

been a remote SCI query through Remote Manager.

XBee functions

For a description of the XBee module and program samples, see the ZigBee module Wiki page.

XBee Industrial Gateway Python application and Remote Manager

The XBee Industrial Gateway Python application is an application that resides on XBee Industrial
Gateway. It allows you to connect your XBee modules to Remote Manager, enabling them to upload
data to Remote Manager and receive remote text and commands. The XBee Industrial Gateway
Python application is already installed in your XBee Industrial Gateway device and automatically starts
when the gateway is initialized.

For a complete explanation about Remote Manager, see the Remote Manager documentation. This
documentation is available from the Documentation link within the Remote Manager platform.

Digi XBee Industrial Gateway

58

Program XBee Industrial Gateway using
Python

How does the XBee Industrial Gateway Python application work?

XBee Industrial Gateway and XBee Industrial Gateway Python application software combination acts
as a bridge between your XBee network and Remote Manager. This means that using the capabilities
provided by Remote Manager, you can communicate with and manage not just XBee Industrial
Gateway, but also all the XBee modules of the network individually. Similarly, all the XBee modules can
report data to Remote Manager and store the data there to be retrieved later.

Consumer applications, such as web apps, mobile apps, and so on, can use Remote Manager web
services to retrieve data stored by the XBee modules and represent it in different ways, or talk
directly with any of the XBee modules to configure them, activate Digital Input/Output (DIO) lines, etc.
The following figure illustrates the role of XBee Industrial Gateway and XBee Industrial Gateway
Python application in such a scenario.

XBee Industrial Gateway Python application and Remote

Manager

Key features and operations of the XBee Industrial Gateway Python application

The XBee Industrial Gateway Python application provides the following features:

Digi XBee Industrial Gateway

59

Program XBee Industrial Gateway using
Python

n Automatically store status information for DIO and Analog-to-Digital Converter (ADC) lines

reported by the XBee nodes of the network in Remote Manager.

n Receive serial data from Remote Manager and send it to the corresponding XBee module of

the network.

n Receive serial data from an XBee node of the network and store it in Remote Manager

automatically.

n Set the value of the DIO lines of any XBee module in the network through Remote Manager.

XBee Industrial Gateway Python application requirements

You must complete the following requirements before you can use the XBee Industrial Gateway
Python application and Remote Manager capabilities:

1. A Remote Manager account. If you do not have a Remote Manager account, follow the

instructions in the Digi Remote Manager User Guide to create a Remote Manager account.

2. Your XBee Industrial Gateway device must be registered in your Remote Manager account.

Follow the instructions in the Digi Remote Manager User Guide to register a device in your

Remote Manager account.

XBee Industrial Gateway Python application and Remote

Manager

3. The XBee Industrial Gateway Python application must be running in your XBee Industrial

Gateway device. By default, the XBee Industrial Gateway Python application is already installed

and running on the XBee Industrial Gateway devices; that is, the application executes

automatically when the device is initialized. Therefore, you do not have to start the application.

If you uninstalled the application, use the File Management function in Remote Manager or the

XBee Industrial Gateway web interface to install the XBee Industrial Gateway Python

application again.

Store status data for XBee lines in Remote Manager

You can configure XBee nodes in a network to report information about the status of the DIO lines and
ADC values to the coordinator or other nodes in the network. This scenario is very common when the
XBee node is attached to one or more sensors to monitor a process or some environment values. In
such a case, you may want to report the data from the sensor(s) to the coordinator every time a line
changes its status or every period of time. Using the XBee Industrial Gateway Python application, you
can automatically upload those values to Remote Manager, store them there, and retrieve the values
later for use by other user applications.

Whenever an XBee module in the network reports the status of the DIO lines and ADC values to XBee
Industrial Gateway, the XBee Industrial Gateway Python application automatically handles the XBee
frame containing those values, processes it, and uploads the reported values to Remote Manager.
This process generates a data stream for each of the different measures reported by the XBee
module. For more information about data streams are, see the Digi Remote Manager Programmer

Guide. The following figure demonstrates the process of storing status data on Remote Manager.

Using the Remote Manager Web Services API, you can retrieve the data stream values from Remote
Manager to be used in end user applications with different purposes, for example, to display a
histogram or generate a database. To learn more about the Remote Manager Web Services API, see
the Digi Remote Manager Programmer Guide.

Digi XBee Industrial Gateway

60

Program XBee Industrial Gateway using
Python

XBee Industrial Gateway Python application and Remote

Manager

Example: Configuring the XBee node to report line and upload status

You can configure an XBee node from the network to report the status of the DIO1 each time it
changes and verify that the values are uploaded to Remote Manager.

To configure XBee node to report line and upload status:

1. Ensure the XBee device you are going to configure is attached to an XBee Interface Board

(XBIB). You will use the User Button 3 (SW3) of the XBIB to change the status of DIO1 as it is

directly connected to the DIO1 of the module.

2. From a web browser, go to the Home page of your XBee Industrial Gateway web interface.

3. Under Configuration, click XBee Network. The XBee Configuration page appears.

Digi XBee Industrial Gateway

61

Program XBee Industrial Gateway using
Python

4. Click the DiscoverXBee Devices button to locate the remote XBee devices that are in the

same network as XBee Industrial Gateway.

5. Click the XBee device that you want to configure.

6. From the XBee Configuration page, click Input/Output Settings.

7. Under I/O Pin Settings, configure I/O Pin 1 (AT setting D1) to Digital Input (3) and change

the value of the DIO Change Detect (IC) setting to 0x2. These settings configure DIO1 as

input. Each time the value of DIO1 changes, the XBee device sends an XBee packet to XBee

Industrial Gateway with the new value of the DIO. In addition, the XBee Industrial Gateway

Python application uploads the new value to Remote Manager.

XBee Industrial Gateway Python application and Remote

Manager

8. On the XBIB, press the User Button 3 (SW3) several times. This action causes the XBee

module report the status of DIO1.

9. From a web browser, log in to Remote Manager.

10. From Remote Manager, click Data Services. The Data Services page appears.

Digi XBee Industrial Gateway

62

Program XBee Industrial Gateway using
Python

11. Click Data Streams. The Data Streams view contains all the data streams, or data channels, of

the devices that you have registered in your account.

There you will find the streams generated by any XBee node from your network that reported

any data. The data streams follow this pattern:

[device_id]/[source]/[xbee_mac]{/[dio_number]}

Where:

n [device_id] Is the ID of your XBee Industrial Gateway.

n [source] Is the source of the data. Legal values are:

l xbee.digitalIn

l xbee.analog

l xbee.serialIn

n [xbee_mac] Is the MAC Address of the XBee node that reported the data in the

following format:

[XX:XX:XX:XX:XX:XX:XX:XX]!

n [dio_number] Is the name of the DIO that generated the data. This is only present if

the [SOURCE] is xbee.digitalIn or xbee.analog.

XBee Industrial Gateway Python application and Remote

Manager

One of those streams should correspond to the DIO1 of your XBee device. For example:

00000000-00000000-00409DFF-FF5C388D/xbee.digitalIn/

[00:13:A2:00:40:31:A8:E1]!/DIO1

12. Click the serial data stream that correspond to the DIO1 of your XBee device. Note how the

values stored have been changed between 0 and 1. For example:

Each stream contains a historical view of the values of the data channel it represents. To

display the historical values, switch from the Table to Chart view.

Digi XBee Industrial Gateway

63

Program XBee Industrial Gateway using
Python

Receive serial data from Remote Manager

In some scenarios, you can attach an XBee module to a microcontroller that can manage the radio
module, configure it, process data reported by the module, and execute actions. In those cases, the
combination of XBee module and microcontroller can use a custom communications protocol
transmitted wirelessly from an XBee network node to the target XBee node, and via serial from the
target XBee node to the microcontroller to which it is attached.

The XBee Industrial Gateway Python application allows sending a serial data packet through Remote
Manager, using the Web Services API, to a specific XBee module or all XBee modules in the network
that will be transmitted through its serial interface. That serial packet can contain any data, including
the custom protocol that your XBee module and microcontroller use to communicate between them.
The following figure demonstrates the process for receiving serial data from Remote Manager.

To send serial data to one of the XBee nodes on your network through Remote Manager, you need to
use the Remote Manager Web Services API. In this case, you need to send a POST command
containing a Server Command Interface (SCI) request to Remote Manager. The SCI request in turn
contains a Remote Command Interface (RCI) do_command element, with xbgw as target attribute
and the send_serial command as content. To learn more about SCI requests, the RCI protocol, and
the Web Services API, see the Digi Remote Manager Programmer Guide.

XBee Industrial Gateway Python application and Remote

Manager

Digi XBee Industrial Gateway

64

Program XBee Industrial Gateway using
Python

XBee Industrial Gateway Python application and Remote

Manager

send_serial command definition

The send_serial command sends serial data to a specific XBee node in your network. To use this
command, add it to an SCI request inside the RCI do_command element.

Command syntax

The send_serial command must follow this syntax:

<send_serial addr=”{address|broadcast}” encoding={“base64”|”utf­8”}”>value</send_serial>

Command attributes

Digi XBee Industrial Gateway

65

Program XBee Industrial Gateway using
Python

n addr

l Usage: Required.

l Description: This attribute indicates the destination address of the node to which the

content indicated by the command body should be transmitted.

l Value: Legal values for this attribute include:

The 64-bit IEEE address of the node following one of these patterns:

XX:XX:XX:XX:XX:XX:XX:XX

[XX:XX:XX:XX:XX:XX:XX:XX]!

XXXXXXXXXXXXXXXX

XX-XX-XX-XX-XX-XX-XX-XX

The string broadcast, which transmits the string to all nodes using a broadcast packet.

n encoding

l Usage: Optional.

XBee Industrial Gateway Python application and Remote

Manager

l Description: Specifies how the character data in the command elements is processed.

l Value: The following encoding types are allowed:

o

base64: Use Base64 encoding. Character data is decoded during command processing

prior to transmit on the RF Network.

o

utf-8: Use UTF-8 variable-width encoding. While you can specify this encoding type,

current limitations in RCI/SCI processing through Remote Manager mean that true UTF-

8 encoding is not passed cleanly through all systems and end-to-end. It is only safe to

use ASCII. Specifying 'utf-8' is primarily useful for evaluation only.

o

Default value: base64.

Command body (value)

The command body contains the data to be transmitted to the specified XBee node of the network.
The command body content depends on the value of the encoding attribute:

n base64: The command body value must be encoded in base64. The XBee Industrial Gateway

Python application will receive the encoded content but, prior to transmission to the

corresponding XBee node, the application will decode the command body to its original content

and that will be transmitted.

n utf-8: The command body value must be the serial data that you want to send to the XBee

node. The entire content of the command body as received by the gateway Python application

will be transmitted subject to whitespace handling rules of XML and the limitations of Remote

Manager to represent individual code points. For best results, base64 encoding is preferred for

production code and evaluation is best when limited to the ASCII subset.

Note Whitespace is not significant when the XBee Industrial Gateway Python application processes

base64. However, whitespace in UTF-8 is significant, because it is impossible to determine whether

Digi XBee Industrial Gateway

66

Program XBee Industrial Gateway using
Python

the whitespace should be considered as such and thus take the conservative approach of keeping it
significant and passing it on.

Request and reply examples

n Request

This SCI request sends a serial data command with the text Hello, World! encoded in base64

to the XBee node of our network corresponding to the MAC address 00:11:22:33:44:55:65:77.

Note The request is using a dummy device ID and XBee MAC address. You will need to use your

own XBee Industrial Gateway device ID and XBee MAC address if you want to test this example.

<sci_request version="1.0">

<send_message>

<targets>

<device id="00000000-00000000-001122FF-FF334455"/>

</targets>

<rci_request version="1.1">

<do_command target="xbgw">

<send_serial addr="00:11:22:33:44:55:66:77"

encoding="base64"> SGVsbG8sIFdvcmxkIQ==

</send_serial>

</do_command>

</rci_request>

</send_message>

</sci_request>

XBee Industrial Gateway Python application and Remote

Manager

Digi XBee Industrial Gateway

67

Program XBee Industrial Gateway using
Python

n Reply

If the SCI request succeeds, you will receive a SCI reply containing the send_serial command

response element. As it was successful, the response will be empty.

<sci_reply version="1.0">

<send_message>

<device id="00000000-00000000-001122FF-FF334455">

<rci_reply version="1.1">

<do_command target="xbgw">

<responses command="send_serial">

</responses>

</do_command>

</rci_reply>

</device>

</send_message>

</sci_reply>

XBee Industrial Gateway Python application and Remote

Manager

<response/>

If the SCI request fails, you will receive an SCI reply containing the send_serial command

response element that includes an error element indicating the cause of the error. For

example:

<sci_reply version="1.0">

<send_message>

<device id="00000000-00000000-001122FF-FF334455">

<rci_reply version="1.1">

<do_command target="xbgw">

<responses command="send_serial">

<response>

<error id="encoding">

<desc>Unrecognized encoding</desc>

<hint>basd64</hint>

</error>

</response>

</responses>

</do_command>

</rci_reply>

</device>

</send_message>

</sci_reply>

The error element contains an id attribute indicating the error identifier. For more information
regarding the possible XBee Industrial Gateway Python application error identifiers, see XBee

Industrial Gateway Python application command errors.

Digi XBee Industrial Gateway

68

Program XBee Industrial Gateway using
Python

The desc element displays the meaning of the error identifier, and the hint element provides an
explanation of what caused the received error.

Example: Sending text to an XBee node through Remote Manager

The following example assumes the microcontroller attached to the XBee device is a computer.

You must install XCTU on your computer. If you do not have XCTU installed, go to www.digi.com/xctu
to download and install XCTU.

To send a Hello, World! text to an XBee node on your network through Remote Manager:

1. Attach the XBee node from your network to an XBIB device and connect it to your computer

using a serial or USB cable. This is the node that will receive the serial data.

2. Open XCTU and add the XBee node that is connected to your computer to the list of radio

modules.

3. Once XCTU has started and your XBee node is added to the list, select the node and click the

Consoles working mode tab. The Console log window appears and displays the XBee

node’s serial console.

4. Connect the console.

5. From a web browser, log in to Remote Manager.

XBee Industrial Gateway Python application and Remote

Manager

6. Click Documentation and then click API Explorer. The APIconsole appears.

Digi XBee Industrial Gateway

69

Program XBee Industrial Gateway using
Python

7. From the API console, select POSTHTTPMethod and write the following SCI request that

includes the send_serial command.The send_serial command will be sent to the remote

XBee node within the RCI do_command element, as follows:

<sci_request version="1.0">

<send_message>

<targets>

<device id="{device_id}"/>

</targets>

<rci_request version="1.1">

<do_command target="xbgw">

<send_serial addr="{xbee_mac}"

encoding="base64">SGVsbG8sIFdvcmxkIQ==

</send_serial>

</do_command>

</rci_request>

</send_message>

</sci_request>

XBee Industrial Gateway Python application and Remote

Manager

Where:

n {device_id} is the ID of your XBee Industrial Gateway device.

{xbee_mac} is the MAC address of the XBee node that you attached to your computer.

For example:

<sci_request version="1.0">

<send_message>

<targets>

<device id="00000000-00000000-00409dff-ff5c3BBd"/>

</targets>

<rci_request version="1.1">

<do_command target="xbgw">

<send_serial addr="0013A2004031A8E1"

encoding="base64">SGVsbG8sIFdvcmxkIQ==

</send_serial>

</do_command>

</rci_request>

</send_message>

</sci_request>

The content of the send_serial command is the text Hello, World! encoded in base64 as it is

specified in the encoding attribute.

8. Click Send.

Digi XBee Industrial Gateway

70

Program XBee Industrial Gateway using
Python

9. Verify in XCTU that the serial console for the XBee node that you added received the data.

Depending on the operating mode (API or AT) of the XBee device, you will receive the data in

one of the following modes:

n AT mode: You will see the text Hello, World! in the console.

n API mode: You will receive a Receive Packet API frame with the Hello World! text (HEX

values of the ASCII characters) in the Received data field of the frame.

Store serial data in Remote Manager

As explained in Receive serial data from Remote Manager, when your XBee device is connected to a
microcontroller and you want to send serial data to it, you can do so through Remote Manager by
using the Web Services API and the send_serial command. The XBee Industrial Gateway Python
application stores serial data sent from the microcontroller to the XBee Industrial Gateway device and
from the XBee Industrial Gateway device to XBee Industrial Gateway running the XBee Industrial
Gateway Python application.

Store serial data in Remote Manager when you want to:

n Track an event that happened in the microcontroller.

n Track the measurements that are managed by the microcontroller.

XBee Industrial Gateway Python application and Remote

Manager

n Store commands or serial data generated by the microcontroller in Remote Manager.

End-user applications can retrieve the serial data from Remote Manager later to perform some tasks.

Whenever an XBee module on the network sends any kind of serial data to XBee Industrial Gateway,
the XBee Industrial Gateway Python application automatically processes the frame containing the
serial data and uploads it to Remote Manager, thereby generating a data stream. To learn more
about data streams, see the Digi Remote Manager User Guide and Digi Remote Manager Programmer

Guide.

Digi XBee Industrial Gateway

71

Program XBee Industrial Gateway using
Python

XBee Industrial Gateway Python application and Remote

Manager

Using the Remote Manager Web Services API, you can retrieve the serial data values from Remote
Manager. End user applications can use the serial data for different purposes. For example:

n Display a list of events

n Perform a specific task

To learn more about the Remote Manager Web Services API, see the Digi Remote Manager

Programmer Guide.

By default, the serial data is stored in Remote Manager and encoded in base64 format. The reason
behind this is that white spaces are not correctly handled by Remote Manager at the moment. The
XBee Industrial Gateway Python application has a configuration file containing the settings of the
application. One of those settings is the encoding of the serial data prior to store it in Remote
Manager.

To change the setting to store the data in UTF-8 format:

1. Open /WEB/python/xbgw_settings.json in an editor.

2. Change "encode serial": true to "encode serial": false.

See XBee Industrial Gateway Python application configuration file for more information on the
configuration file.

Digi XBee Industrial Gateway

72

Program XBee Industrial Gateway using
Python

Example: Send serial data from an XBee node to XBee Industrial Gateway

The following example assumes the microcontroller attached to the XBee device is a computer.

To send a serial data package from an XBee node on your network to XBee Industrial Gateway and
verify that it has been automatically uploaded to Remote Manager:

1. Attach one XBee node from your network to an XBIB device and connect it to your computer

using a serial or USB cable. This is the node that will send the serial data to XBee Industrial

Gateway.

2. Open XCTU. Add the XBee node that is connected to your computer to the list of radio modules.

3. Once XCTU has started and your XBee node is added to the list, select the node and click the

Consoles working mode tab. The Console log window appears and displays the XBee

node’s serial console.

4. Connect the console.

5. Depending on the working mode (API or AT) of the XBee device, choose one of the following

options.

n AT mode:

a. Click the Add new packet button and paste the following text in the dialog:

XBee Industrial Gateway Python application and Remote

Manager

Hello, World!

b. Once the packet is added to the list of packets, select it and click the Send

selected packet button.

n API mode:

Click the Add new frame button.

a.

b. Paste the following text in the dialog:

7E 00 1B 10 01 00 00 00 00 00 00 00 00 FF FE 00 00 48 65 6C

6C 6F 2C 20 57 6F 72 6C 64 21 88

The previous text is a Transmit Request frame. You can also generate it by

yourself by clicking the Edit frame using the Frames Generator tool button:

c. After adding the frame to the list of frames, select the frame and click the

Send selected frame button.

6. From a web browser, log in to Remote Manager.

Digi XBee Industrial Gateway

73

Program XBee Industrial Gateway using
Python

7. Click Data Services and then click Data Streams. The Data Streams page appears and displays

all the data streams (data channels) by the XBee nodes that are registered to your account on

your network that reported data. The streams follow this pattern:

[device_id]/[source]/[xbee_mac]{/[dio_number]}

Where:

n [device_id] Is the ID of your XBee Industrial Gateway.

n [source] Is the source of the data. Legal values are:

l xbee.digitalIn

l xbee.analog

l xbee.serialIn

n [xbee_mac] Is the MAC Address of the XBee node that reported the data in the

following format:

[XX:XX:XX:XX:XX:XX:XX:XX]!

XBee Industrial Gateway Python application and Remote

Manager

n [dio_number] Is the name of the DIO that generated the data. This is only present if

the [SOURCE] is xbee.digitalIn or xbee.analog.

One of the streams displayed should correspond to the serial data of your XBee device.

For example:

00000000-00000000-00409DFF-FF5C388D/xbee.serialIn/

[00:13:A2:00:40:31:A8:E1]!

Click that serial data stream. Observe how the latest serial data value corresponds to

the following text:

SGVsbG8sIFdvcmxkIQ==

This serial data value is Hello, World! encoded in base64.

Manage XBee DIO lines though Remote Manager

The XBee Industrial Gateway Python application allows you to remotely manage the DIO lines of any
of the XBee nodes on your network through Remote Manager. Use this application feature to turn
on/off different actuators.

The XBee Industrial Gateway Python application can receive digital output commands sent through
Remote Manager (using the Web Services API) and dispatch them to a specific XBee module in the
network to set its corresponding pin high or low.

The following figure demonstrates how this remote management mechanism works.

Digi XBee Industrial Gateway

74

Program XBee Industrial Gateway using
Python

XBee Industrial Gateway Python application and Remote

Manager

To set the value of a DIO pin of one XBee node on your network through Remote Manager, you need to
use the Remote Manager Web Services API.

In this case, you will need to send a POST command, containing a Server Command Interface (SCI)
request to Remote Manager. The SCI command in turn contains a Remote Command Interface (RCI)
do_command element with xbgw as target attribute and the set_digital_output command as
content.

If you never worked with Remote Manager Web Services API before, see the Digi Remote Manager

Programmer Guide to learn more about SCI requests and RCI protocol.

set_digital_output command definition

The set_digital_output command configures the value of a DIO of a specific XBee node in your
network. Add this command to the SCI request inside the RCI do_command element.

Command syntax

Digi XBee Industrial Gateway

75

Program XBee Industrial Gateway using
Python

The set_digital_output command must follow this syntax:

<set_digital_output addr=”address” index=”index”>value</set_digital_output>

Command attributes

n addr

l Usage: Required.

l Description: This attribute indicates the destination address of the node to which the

content indicated by the command body should be transmitted. This address is expressed

as the 64-bit IEEE address of the node.

l Value: The 64-bit IEEE address of the node following one of these patterns:

XX:XX:XX:XX:XX:XX:XX:XX

[XX:XX:XX:XX:XX:XX:XX:XX]!

XXXXXXXXXXXXXXXX

XX-XX-XX-XX-XX-XX-XX-XX

n index

XBee Industrial Gateway Python application and Remote

Manager

l Usage: Required if the name attribute is not specified.

l Description: This is the pin index for which settings are being changed.

l Value: The value for this attribute must represent a valid integer between 0 and 12.

Indices 0-9 map to DIO values. That is, they set the Dx AT parameter, where x is the index.

For example, index 8 is equivalent to setting D8; index 12 is equivalent to setting P2.

Indices 10-12 map to PWM values. That is, they set the Px AT parameter, where x is index-

10.

n name

l Usage: Required if index attribute is not specified.

l Description: The name of the pin for which settings are being changed.

l Value: Specify either the AT parameter corresponding to that pin (from D0 to D9) or the

functional name of the pin (from DIO0 to DIO12) as the value for this attribute.

Note Currently, set_digital_output supports setting pins on remote ZigBee nodes only. This means

that pin index 9 is invalid, because DIO9 is not user-configurable on such nodes. Future updates to this
command may open up the possibility to change this behavior; for example, for 802.15.4 nodes.

Command body (value)

The body of the set_digital_output command indicates whether to set the digital output pin low or
high. Legal values for the body to configure the pin are:

n high or true: Sets the pin high (ON). Other legal values include:

1, yes, y, on

Digi XBee Industrial Gateway

76

Program XBee Industrial Gateway using
Python

n low or false: Sets the pin low (OFF). Other legal values include:

0, no, n, off

Request and reply examples

n Request

This SCI request example configures DIO4 of the XBee node corresponding to the MAC address

00:13:a2:00:40:9f:6f:cb to high. The command uses the attribute index to indicate the pin to

be configured instead of the name one:

<sci_request version="1.0">

<send_message>

<targets>

<device id="00000000-00000000-00409DFF-FF5C4C66"/>

</targets>

<rci_request version="1.1">

<do_command target="xbgw">

<set_digital_output addr="00:13:a2:00:40:9f:6f:cb"

index="4">1</set_digital_output>

</do_command>

</rci_request>

</send_message>

</sci_request>

XBee Industrial Gateway Python application and Remote

Manager

Note This example request uses a dummy device ID and XBee MAC address. You must use your

own XBee Industrial Gateway device ID and XBee MAC address to test this example.

Digi XBee Industrial Gateway

77

Program XBee Industrial Gateway using
Python

n Reply

<sci_request version="1.0">

<send_message>

<device id="00000000-00000000-00409DFF-FF5C4C66"/>

<rci_reply version="1.1">

<do_command target="xbgw">

<responses command="set_digital_output">

</responses>

</do_command>>

</rci_reply>

</device>

</send_message>

</sci_reply>

If the SCI request fails, you will receive an SCI reply containing the set_digital_output

command response element that includes an error element indicating the cause of the error.

For example:

XBee Industrial Gateway Python application and Remote

Manager

<response/>

<sci_reply version="1.0">

<send_message>

<device id="00000000-00000000-00409DFF-FF5C4C66">

<rci_reply version="1.1">

<do_command target="xbgw">

<responses command="set_digital_output">

<response>

<error id="invalidattr">

<desc>Attribute value is incorrect</desc>

<hint>DIO9 cannot be configured for

digital.</hint>

</error>

</response>

</responses>

</do_command>

</rci_reply>

</device>

</send_message>

</sci_reply>

The error element contains an id attribute indicating the error identifier. For more information
regarding the possible XBee Industrial Gateway Python application error identifiers, see XBee

Industrial Gateway Python application command errors.

Digi XBee Industrial Gateway

78

Program XBee Industrial Gateway using
Python

The desc element displays the meaning of the error identifier. The hint element provides an
explanation with the cause of the received error.

Example: Turn on an LED on the XBee interface board

To turn on the User LED 4 (DS4) of the XBee Interface Board (XBIB):

1. Ensure the XBee node you are going to configure is attached to an XBIB device. You will change

the status of the User LED 4 (DS4) of the board by modifying the value of the DIO4 of the XBee

node because they are connected each other.

2. From a web browser, go to the Home page of your XBee Industrial Gateway web interface.

3. Under Configuration, click XBee Network. The XBee Configuration page appears.

4. Click the DiscoverXBee Devices button to locate the remote XBee devices that are in the

same network as XBee Industrial Gateway.

5. Click the XBee device that you want to configure.

6. From the XBee Configuration page, click Input/Output Settings.

7. Under I/O Pin Settings, configure I/O Pin 4 (AT setting D1) to Digital Output High (5). This

way, the DIO4 is configured as output and its value is set to high turning the User LED 4 (DS4)

OFF because the LED in the board is using an inverted logic.

XBee Industrial Gateway Python application and Remote

Manager

Digi XBee Industrial Gateway

79

Program XBee Industrial Gateway using
Python

8. From a web browser, log in to Remote Manager.

9. Click Documentation and then click API Explorer. APIconsole appears.

10. From the API console, select POSTHTTPMethod and write the following SCI request that

includes the set_digital_output command.The set_digital_output command will be sent to

the remote XBee node within the RCI do_command element, as follows:

<sci_request version="1.0">

<send_message>

<targets>

<device id="{device_id}"/>

</targets>

<rci_request version="1.1">

<do_command target="xbgw">

<set_digital_output addr="{xbee_mac}" name="DIO4">low</set_

digital_output>

</do_command>

</rci_request>

</send_message>

</sci_request>

XBee Industrial Gateway Python application and Remote

Manager

Where:

n {device_id} is the ID of your XBee Industrial Gateway device.

n {xbee_mac} is the MAC address of the XBee node that you attached to your computer.

For example:

<sci_request version="1.0">

<send_message>

<targets>

<device id="00000000-00000000-00409dff-ff5c3BBd"/>

</targets>

<rci_request version="1.1">

<do_command target="xbgw">

<set_digital_output addr="0013A2004031A8E1"

name="DIO4">low</set_digital_output>

</do_command>

</rci_request>

</send_message>

</sci_request>

The set_digital_output command sets the value of the DIO4 to low, which will turn ON the

User LED 4 (DS4) of the board.

11. Click Send.

Digi XBee Industrial Gateway

80

Program XBee Industrial Gateway using
Python

12. Verify that the User LED4 (DS4) on the XBIB board is now ON.

13. Now try to turn the LED off by sending the same request, but changing the value of the set_

digital_output command to high.

XBee Industrial Gateway Python application configuration file

You can configure some of the XBee Industrial Gateway Python application features using a
configuration file. This configuration file is placed at the same level as the application itself within the
file system and its content is written in JSON format. The file has the following structure:

{
category 1: {
setting 1: value 1
setting 2: value 2
...
setting n: value n
}
category 2: {
setting 1: value 1
setting 2: value 2
...
setting n: value n

XBee Industrial Gateway Python application and Remote

Manager

...
category n: {
setting 1: value 1
setting 2: value 2
...
setting n: value n
}
}

The first level of the settings structure in this configuration file is the name of the category to which
the settings contained inside belongs. The second level of the structure is the list of settings
contained in the category.

The contents of this configuration file are:

{
"devicecloud": {
"encode serial": true
}
}

The XBee Industrial Gateway Python application provides the following category, with one
configurable setting:

n devicecloud

l encode serial:

o

Type: Boolean

o

Description: Indicates whether or not the serial data that is sent and stored in Remote

Manager is encoded in base64.

o

Default value: true

Digi XBee Industrial Gateway

81

Program XBee Industrial Gateway using
Python

Changing XBee Industrial Gateway Python application settings

To change any XBee Industrial Gateway Python application setting:

1. Open a web browser and access the Home page of your XBee Industrial Gateway web

interface.

2. Click File Management under Administration.

3. Download the file xbgw_settings.json.

4. Using a text editor, open the xbgw_settings.json file and modify the settings that you want to

change.

5. Return to the File Management page for XBee Industrial Gateway and upload the xbgw_

settings.json file to XBee Industrial Gateway.

6. Reboot your XBee Industrial Gateway device. Your changes to the XBee Industrial Gateway

Python application settings go into effect when the XBee Industrial Gateway device is

initialized.

XBee Industrial Gateway Python application command errors

When you use the Web Service API from Remote Manager to send the commands provided by the
XBee Industrial Gateway Python application, you may receive an error with an identifier. The following
list displays all possible errors that may appear when sending commands to XBee Industrial Gateway
Python application.

These errors do not generally appear during in normal operation. When setfailed, txfailed, or txfull
appears, the most likely cause is network issues. These errors typically appear when you issue a
command incorrectly.

XBee Industrial Gateway Python application and Remote

Manager

ID Description

address Invalid address

encoding Unrecognized encoding

badoutput Invalid digital output value

base64 Unable to decode as base64

invalidattr Attribute value is incorrect

missingattr Missing required command attribute

toomanyattrs Too many attributes were given

setfailed Remote node rejected set command

txfailed Transmit operation failed

txfull Too many outstanding transmits

txstatus TX Status delivery failure

unexpected Unexpected/unclassified error

Digi XBee Industrial Gateway

82

Program XBee Industrial Gateway using Python Configuring a Python application in the web interface

Configuring a Python application in the web interface

The web interface of the XBee Industrial Gateway device includes a section that allows you to
configure and manage the Python processes or applications running in the device.

Before you configure a Python application, the Python application must be loaded on the XBee
Industrial Gateway device. See File management for more information on loading files on an XBee
Industrial Gateway device.

To configure a Python application for an XBee Industrial Gateway device:

1. Log in to the web interface for the XBee Industrial Gateway device.

2. Under Configuration, click Python.The Python Configuration page appears and displays the

list of Python processes or applications that are currently configured in XBee Industrial

Gateway as well as their status and the action that will be executed when the applications exit.

Note that the first time you load this page, the list will be empty.

3. Select the Enable check box associated with the Python application. When enabled, the Python

application starts immediately after your changes are saved. By selecting the Enable check

box, the Python application also automatically starts after a system starts up.

A green icon will appear in the Active column when a Python application is running. Note

that you can stop a configured Python application immediately by clearing the Enable check

box and clicking Apply.

4. Click Apply to save your changes.

Digi ESP for Python

Digi ESP for Python supports XBee Industrial Gateway. Digi ESP is an IDE featuring device detection,
debugging, compiling, and downloading of Device Integration Application (DIA)/Python code to Digi
gateways. Digi ESP includes example applications that can demonstrate the use of some of Digi’s
proprietary Python extensions, serving as templates for applications seeking to incorporate common
functionality.

n For examples of how to use Digi ESP for Python with XBee Industrial Gateway, see Access the

program samples in Digi ESP.

n For Digi ESP for Python installation instructions, see Install the Digi ESP for Python

Development Environment.

Access the program samples in Digi ESP

Digi ESP for Python provides samples to use as a base for programming XBee Industrial Gateway,
including specific examples for exercising specific interfaces available on XBee Industrial Gateway. You
can access these program samples from the Python or DIA samples wizard.

To access the program samples in Digi ESP:

1. From Digi ESP, go to File > New > Digi Python Application Sample Project or File > New >

DIA Sample Project. The sample wizard for Python or DIA appears.

2. Select the Show only samples compatible with platform check box and then select XBee

Gateway from the combo box. The compatible samples appear in the Sample projects list.

3. Select the samples you want to display or click Select All to select all of the samples.

Digi XBee Industrial Gateway

83

Program XBee Industrial Gateway using Python Digi ESP for Python

4. Click Next. The Remote device selection page appears.

5. Specify the XBee Industrial Gateway device you want to use.

n Select Use Current Remote Device to use the device that is currently active in Remote

Manager.

n Select Select Specific Remote Device to display a list of devices and select a device

from the list.

6. Click Next to complete the process.

Install the Digi ESP for Python Development Environment

The Digi ESP™ for Python Development Environment is an Eclipse-based Integrated Development
Environment (IDE) that simplifies the process of creating Python applications for ConnectPort X2e ZB.
It also provides many example projects.

To download and install the Digi ESP for Python Development Environment:

1. Navigate to the Digi XBee Gateway product support page.

2. Click the Product Support > Drivers link or scroll down the page to the Drivers section.

3. Click the Digi ESP for Python - Windows XP/Vista/Windows 7 installer link to download the

Digi ESPfor Python Development Environment.

Note While MACoperating systems are supported, this procedure shows how to install Digi

ESPfor Python on a Windows operating system. If you are using a MACoperator system, click
the Digi ESP for Python - MAC OS X (10.6) installer link.

4. Once the Digi ESP for Python framework has been downloaded, run the Digi ESP for Python

framework installation wizard.

a. Follow the steps in the wizard to complete the installation process.

b. In the Choose Components dialog, select Digi ESP for Python.

c. On the last page of the wizard, several prompts are displayed. Select Show Release

Notes to open and view the Release Notes for the Digi ESP for Python framework.

d. Click Finish to close the installation wizard. The installation process installs Digi

ESP in this program group:

Digi > Python > Dev Tools > Digi ESP for Python

5. The Digi ESP for Python framework will launch automatically. A prompt to select a workspace

directory is displayed. This 'workspace' is the directory where projects and configurations will

be stored. The default location is a sub-folder called workspace on the user home directory, for

example:

c:/Documents and Settings/[username]/workspace

Use the default workspace directory, or click Browse and navigate to your desired alternate
workspace location, select Use this as the default and do not ask again, and click OK.

Digi XBee Industrial Gateway

84

Program XBee Industrial Gateway using Python Digi ESP for Python

6. The first time you run Digi ESPfor Python, the Workbench displays.

Before the Workbench displays, the Welcome page displays for just a moment, and then
displays along the right side of the Workbench screen. Most of the time, the Welcome page is
minimized. When minimized, select Help > Welcome from the main menu to maximize the
Welcome page.

In the Welcome page, click the Workbench icon to display the Workbench screen.

Digi XBee Industrial Gateway

85

Program XBee Industrial Gateway using Python Digi ESP for Python

7. You can display an overview for Digi ESPfor Python.

a. Select Help > Welcome from the main menu. The Welcome page appears.

b. In the Welcome tab, click the Overview icon. The Overview page appears.

c. On the overview page, click Getting Started. The Digi ESP for Python Getting Started

Guide is displayed in the Help - Digi ESPfor Python window.

8. Scroll to and click the XBee Gateway/ConnectPort X2e link.

9. Follow the XBee Gateway/ConnectPort X2e getting started instructions to build your first

application using Digi ESP for Python.

Digi XBee Industrial Gateway

86

Program XBee Industrial Gateway using Python DIA software

DIA software

The Digi ESP development environment includes Device Integration Application (DIA) software. DIA
software is another advanced programming tool for developing custom programs for XBee Industrial
Gateway. DIA software simplifies connecting remote devices and sensors to Digi gateway products by
providing ready-to-use software. DIA is targeted for applications that need to gather samples of data
from a set of devices, such as ZigBee® sensors and wired industrial equipment. The Digi gateways can
use the DIA framework to gather data from XBee sensor networks, transform the data into a useful
form, and push the data to Remote Manager for consumption by a user.

DIA allows developers to focus efforts on proprietary logic, and includes a comprehensive library of
ready-to-use modules for common operations and abstractions for components like:

n Interface handling (drivers)

n Data management (channels)

n Data delivery (presentations)

Written in the Python programming language for use on Digi devices, you can extend it to meet unique
device connectivity requirements. When used with the Digi ESP for Python, DIA can shrink the
development cycle for complex data gathering and transformation applications.

For more information on DIA software, see the DIA page on the Device Cloud Wiki.

Linux command shell (command-line interface)

XBee Industrial Gateway has a Linux shell command-line interface, which allows you to experiment
with the Python interpreter interactively, create scripts, launch scripts, and control the script
operation. While Digi ESP for Python is intended as the main programming interface, you may find this
interface useful for some programming and device management tasks.

A shell is a program that takes commands from the keyboard and gives them to the operating system
to perform. On XBee Industrial Gateway, a program called ash acts as the shell program. You can use
this shell in several useful instances, particularly in managing files, executing Python programs, and
programming and executing commands to the XBee RF module in the gateway.

User name and password for the Linux command shell

The command-line interface is accessed using SSH and is described in the Linux command shell
(command-line interface). Access to XBee Industrial Gateway is at the user level.

n User name: python

n Password: dbps

XBee Industrial Gateway ash shell reference documentation

For more information on the ash shell, go to the following website: http://linux.die.net/man/1/ash.
Note that the ash shell supported in XBee Industrial Gateway is similar, but not identical, to the ash
shell described in this website.

Connect and log in to the XBee Industrial Gateway device

To connect and log in to the XBee Industrial Gateway device through the command-line interface:

1. Open a command prompt or terminal window, such as one provided by PuTTY. You can

download PuTTY from http://www.putty.org/.

Digi XBee Industrial Gateway

87

Program XBee Industrial Gateway using Python Linux command shell (command-line interface)

2. Choose one of the following option:

n From Windows, type:

putty python@

n From Linux, type:

$ ssh python@

Where my_ip_address is the IP address of XBee Industrial Gateway.

3. Type dbps when prompted for the password.

my_ip_address

my_ip_address

Log in to XBee Industrial Gateway through the Digi ESP for Python
command-line interface

Within Digi ESP for Python, there is a separate login on the Device Manager LAN Connection tab in
Digi ESP for Python.

1. Access Digi ESP for Python.

2. Click the Device Manager icon in the toolbar.

3. Select Digi Device > New_configuration from the left pane.

4. Click the LAN Connection tab.

5. Perform authentication.

a. Select the User login information if required option.

b. In the Login field, type: python

c. In the Password field, type: dbps

6. Click Apply to start the validation process.

Digi XBee Industrial Gateway

88

Program XBee Industrial Gateway using Python Linux command shell (command-line interface)

Digi XBee Industrial Gateway

89

Configure XBee Industrial Gateway

XBee Industrial Gateway is designed to allow network communication with minimal configuration.
However, there are several configuration settings that you can adjust. This section covers the
configuration of these settings from Remote Manager and the XBee Industrial Gateway web interface.

After you configure XBee Industrial Gateway device, back up the configuration settings. See Back up

or restore the configuration for more information.

XBee Industrial Gateway uses the following configurable settings to start up the XBee Industrial
Gateway device and initiate communication.

Configure settings from Remote Manager 91
Configure settings from the XBee Industrial Gateway web interface 92
Ethernet IP network settings 93
Mobile Connectivity settings 97
Digi Mobile SureLink™ settings 101
DNS settings 104
Mobile firewall settings 105
Autostart settings for the Python Program 105
Configure Remote Manager connectivity settings 106
Ethernet SureLink™ settings 113
GPS static position settings 115
Network Failover settings 116
Time settings 118

Digi XBee Industrial Gateway

90

Configure XBee Industrial Gateway Configure settings from Remote Manager

In addition to the methods described in this section, you can perform configuration programmatically,
through Web Services, and natively using Python modules. See the About programming for more
information.

Configure settings from Remote Manager

In Remote Manager, you can configure XBee Industrial Gateway device settings, such as network
connection, failover, and time settings. You can also monitor and manage XBee Industrial Gateway
device data.

Before you can configure settings in Remote Manager, you must perform these prerequisites:

1. Set up a Remote Manager account. See Create a new account in the Digi Remote Manager User

Guide for instructions.

2. Log in to the Remote Manager account. See Log in to your Remote Manager account in the Digi

Remote Manager User Guide for instructions.

3. Add XBee Industrial Gateway devices to the Remote Manager device list. See Add devices to

your inventory in the Digi Remote Manager User Guide for instructions.

See Remote Manager interface for more basic information about Remote Manager.

Basic configuration settings

In Remote Manager, you can access basic configuration settings for XBee Industrial Gateway by
double-clicking on a device in the device list to display the Properties page. As an alternative, you can
right-click on a device and select the Properties option.

Some of the basic configuration settings located in this menu are:

n Ethernet IP network settings

n Mobile Connectivity settings (for Cellular models only)

n Digi Mobile SureLink™ settings (for Cellular models only)

n DNS settings

n Autostart settings for the Python Program

n File Management page in Remote Manager

Advanced configuration settings

You can access advanced configuration settings for XBee Industrial Gateway by double-clicking on a
device in the device list to display the Properties page, and then selecting Advanced Configuration.

The settings available in this menu vary by model. Some of the settings are:

n Time settings

n Mobile firewall settings (for Cellular models only)

n Configure Remote Manager connectivity settings

n Ethernet SureLink™ settings

n GPS static position settings

n Network Failover settings

n Configure XBee network settings

Digi XBee Industrial Gateway

91

Configure XBee Industrial Gateway Configure settings from the XBee Industrial Gateway web interface

Configure settings from the XBee Industrial Gateway web interface

The XBee Industrial Gateway web interface allows you to configure critical network configuration
settings and other features. If you already know the IP address for the XBee Industrial Gateway
device, you can open a web browser and type the IP address in the address bar to open the XBee
Industrial Gateway web interface. If you do not know the IP address for the XBee Industrial Gateway
device, you can use the Digi DeviceDiscovery utility to locate XBee Industrial Gateway on your
network.

The XBee Industrial Gateway web interface does not display every device setting. For more extensive
access to settings, use Remote Manager or a programmatic interface.

Access the XBee Industrial Gateway web interface

To access the XBee Industrial Gateway web interface, choose one of the following options:

If you know the XBee Industrial Gateway device's IP address

Open a web browser, type the IP address in the address bar, and press the Enter key. For example:
http://10.101.1.178. The XBee Industrial Gateway web interface appears.

If you do not know the XBee Industrial Gateway device's IP address

If you already ran the Wireless Access Point wizard, you need the Digi Device Discovery Utility to
rediscover the device and open its web interface.

1. From a web browser, go to the Product Support Download page and click the Diagnostics,

Utilities & MIBs link from the Support Downloads section.

2. Select your product from the list, or a enter keywords to locate it.

3. Select your operating system from the drop-down list, then select the Device Discovery

Utility.

4. Follow the prompts to complete the installation of the Digi Device Discovery Utility.

5. To open the Digi Device Discovery on your computer, select Start >Digi >Digi Device

Discovery >Digi Device Discovery. The Digi Device Discovery window appears.

6. Locate your XBee Industrial Gateway in the list of devices by matching the Serial Number on

the XBee Industrial Gateway's label to the corresponding value in the MAC address column in

the Digi Device Discovery window.

7. Double-click the device to open the XBee Industrial Gateway web interface, or select the device

and click Open web interface under Device tasks in the Digi Device Discovery window.

8. To change a subset of configuration settings through Digi Device Discovery, click the Configure

Network Settings button. When you change configuration settings, you are prompted for a

password. Leave the Password field blank and click OK.

Home page

The Home page appears by default when you access the web interface for a Digi device. The
information listed on this page may vary based on product and supported features.

Digi XBee Industrial Gateway

92

Configure XBee Industrial Gateway Ethernet IP network settings

Home page section Description

Device Information The Device Information section of the Home page

summarizes current system parameters and
network connectivity status.

Network Connectivity Status LED The Network Connectivity Status LED and

displayed information indicates the readiness of
XBee Industrial Gateway to communicate in a
network and with the Remote Manager server. See

XBee Industrial Gateway LED descriptions for

descriptions of the status LEDs and the various
network connectivity status conditions listed.

Refresh button Clicking Refresh to update the Home page. This

refresh operation is necessary because items like
system time and network connectivity status are not
dynamically updated when the state changes on the
device. This refresh operation also updates device
status information.

Left pane The left side of the Home page displays a menu

consisting of configuration and administration tasks.

Configuration menu The options under Configuration in the menu allow

Administration menu The options under Administration in the menu allow

Apply button The web interface runs locally on the device, which

Cancel changes to configuration settings

Ethernet IP network settings

The Ethernet Network settings display the current IP address and DHCP settings for Ethernet
network communications. You can change the IP address from the default either by obtaining a new
one through DHCP or by entering a static IP address, subnet mask, and default gateway, and Domain
Name System (DNS) servers.

you to configure settings for various features. Some
of the configuration settings are organized on sets of
linked screens. The options in this menu may vary
based on product and supported features.

you to complete common device administration
tasks. See Administration and maintenance tasks for
more information.

means that the interface always maintains and
displays the latest settings in the Digi device. If you
make changes, click Apply to apply the changes to
the configuration settings to the Digi device.

To cancel changes to configuration settings, click
Refresh or Reload on the web browser. This causes
the web browser to reload the page. Any changes
made since the last time the you clicked Apply are
reset to their original values.

Digi XBee Industrial Gateway

93

Configure XBee Industrial Gateway Ethernet IP network settings

Default Ethernet settings

For Ethernet networks, the default configuration for the Ethernet model of the XBee Industrial
Gateway allows you to power up the XBee device and join an Ethernet network without any additional
configuration. In this default configuration:

n XBee Industrial Gateway uses a DHCP server to obtain its IP address information. A DHCP

server needs to provide an IP address, subnet mask, default gateway, and Domain Name

System (DNS) server for the device. If you disable DHCP, you must set all of these IP address

settings yourself. In the absence of a DHCP server, you need to assign a static IP address using

the Digi Device Discovery Utility and changing the network settings through the web interface.

n The default behavior regarding NTP time server access, Configure Remote Manager

connectivity settings, and DNS server all proceed as described.

If your Ethernet network configuration does not match these default behaviors, you need to adjust
the Ethernet network configuration settings. See Configuring Ethernet Settings for more information.

Configuring Ethernet Settings

To configure Ethernet settings, choose one of the following options:

From Remote Manager

1. Click the Device Management tab.

2. From the device list, double-click the device to display the device properties menu.

3. Click the Ethernet (eth)0 properties. The Ethernet (etho) page appears.

4. Complete the fields and click Save to save your changes.

From the XBee Industrial Gateway web interface

1. Select Configuration > Ethernet Network to access the Ethernet IP network settings.

2. Complete the fields and click Apply to save your changes.

Ethernet Configuration page

The following list describes the Ethernet network settings in the Ethernet (eth0) page:

IP Settings

You can set the IP address for XBee Industrial Gateway either automatically, using DHCP, or by
assigning a static IP address. You must enable either the Obtain an IP address automatically using
DHCP or the Use the following IP addressoption.

n Obtain an IPaddress automatically using DHCP: Select this option to enable DHCP to

assign an IP address to the gateway. XBee Industrial Gateway uses a DHCP server to obtain its

IP address information, by default. A DHCP server needs to provide an IP address, subnet

mask, default gateway, and Domain Name System (DNS) server for the device. If you disable

DHCP, you must select the Use the following IP address option and configure these settings

manually.

Digi XBee Industrial Gateway

94

Configure XBee Industrial Gateway Ethernet IP network settings

n Use the following IP address: Specify a static IP address for XBee Industrial Gateway,

consisting of the following:

l IP Address: The IP address assigned to network devices.

l Subnet Mask: The subnet mask assigned to the device. The subnet mask is combined with

the IP address to determine which network this Digi device is part of.

l Default Gateway: The IP address of the computer that enables this Digi device to access

other networks, such as the Internet.

Advanced Settings

n Interface enable: Enables or disables the Ethernet network interface.

n Auto IP enable: Enables or disables use of AutoIP address assignment. When AutoIP is

enabled, XBee Industrial Gateway automatically self-configures an IP address when an address

is not available from other methods. For example, when the Digi device is configured for DHCP

and a DHCP server is not currently available. For more information on AutoIP, see RFC 3927,

Dynamic Configuration of IPv4 Link-Local Addresses.

n Source route enable: Enables or disables source routing to specify a route through the

network.

Ethernet Network Configuration page

The following list describes the Ethernet network settings the Ethernet Network page by section.

Note The Ethernet Network page is only available for Wi-Fi models.

Current IP Parameters

This section displays the active Ethernet IP parameters for XBee Industrial Gateway.

n IP Address: The IP address assigned to network devices.

n Subnet Mask: The subnet mask assigned to the device. The subnet mask is combined with the

IP address to determine which network this Digi device is part of.

n Default Gateway: The IP address of the computer that enables this Digi device to access other

networks, such as the Internet.

Digi XBee Industrial Gateway

95

Configure XBee Industrial Gateway Ethernet IP network settings

Interface Configuration

n Enable this network interface: Enables or disables the Ethernet network interface.

n Speed: The Ethernet speed that XBee Industrial Gateway uses on the Ethernet network.

l Automatic: The device senses the Ethernet speed of the network and adjusts

automatically. The default is Automatic. If one side of the Ethernet connection is using

auto (negotiating), the other side can set the Ethernet speed to whatever value is desired.

Or, if the other side is set for 100 Mbps, this side must use 100 Mbps.

10: The device operates at 10 megabits per second (Mbps) only.

l 100: The device operates at 100 Mbps only.

n Duplex Mode: The mode that XBee Industrial Gateway uses to communicate on the Ethernet

network. Specify one of the following options:

l Automatic: The device senses the mode used on the network and adjusts automatically.

The default is auto. If one side of the Ethernet connection is using auto, the other side can

set the duplex value to whatever is desired. If one side uses a fixed value (for example,

half-duplex), the other side has to use the same duplex mode.

Full Duplex: The device communicates in full-duplex mode.

Half Duplex: The device communicates in half-duplex mode.

Stored IP Configuration

You can set the IP address for XBee Industrial Gateway either automatically, using DHCP, or by
assigning a static IP address. You must enable either the DCHP or the Static IPoption.

n DHCP: Select On to enable DHCP to assign an IP address to the gateway. XBee Industrial

Gateway uses a DHCP server to obtain its IP address information, by default. A DHCP server

needs to provide an IP address, subnet mask, default gateway, and Domain Name System

(DNS) server for the device. If you disable DHCP, you must enable the Static IP option and

configure these settings manually.

In the absence of a DHCP server, you must assign a static IP address by accessing the Digi
Device Discovery tool and changing the network settings through that interface.

n AutoIP: Enables or disables use of AutoIP address assignment. When AutoIP is enabled, XBee

Industrial Gateway automatically self-configures an IP address when an address is not

available from other methods. For example, when the Digi device is configured for DHCP and a

DHCP server is not currently available. For more information on AutoIP, see RFC 3927, Dynamic

Configuration of IPv4 Link-Local Addresses.

n Static IP: Select ON to enable you to specify a static IP address for XBee Industrial Gateway.

You must specify the following:

l IP Address: The IP address assigned to network devices.

l Subnet Mask: The subnet mask assigned to the device. The subnet mask is combined with

the IP address to determine which network this Digi device is part of.

Digi XBee Industrial Gateway

96

Configure XBee Industrial Gateway Mobile Connectivity settings

l Default Gateway: The IP address of the computer that enables this Digi device to access

other networks, such as the Internet.

Mobile Connectivity settings

The mobile settings allow you to configure how to connect to mobile (cellular) networks using the
mobile connection, including the service provider, service plan, and settings used in connecting to the
mobile network. Additional settings configure the Digi SureLink™ feature.

The process for configuring your device and the settings displayed on the Mobile Configuration page
vary according to whether the mobile service provider network used with your Digi Cellular Family
product is based on GSM (Global System for Mobile communication) or LTE (Long-Term Evolution).

To configure the cellular interface for XBee Industrial Gateway, select the link below.

n Set up and configure a cellular device

There are several other related settings for cellular devices, including:

n Mobile Configuration page

n Digi Mobile SureLink™ settings

n Mobile firewall settings

Once the mobile settings have been configured, you can monitor the status of mobile connections by
going to Administration > Mobile Status. See Mobile device status for more information.

Default behavior with the cellular network

For cellular networks, thedefault behavior for XBee Industrial Gateway is as follows:

n The default behavior regarding NTP time server access, Configure Remote Manager

connectivity settings, and DNS server all proceed as described.

n You must connect XBee Industrial Gateway to the cellular network. How you connect XBee

Industrial Gateway to the cellular network depends on the type of cellular modem in the

device.

n Signal strength, account registration, and other issues can impact activation. For common

issues and resolutions, see Cellular connection issues.

Set up and configure a cellular device

This task requires a small screwdriver and a SIM card for your device.

Note This process should be completed for both GSM and LTE devices.

1. Obtain an account with your carrier of choice. The carrier will provide a SIM card and account

information, such as the APN and possibly a user name and password for the account.

Digi XBee Industrial Gateway

97

Configure XBee Industrial Gateway Mobile Connectivity settings

2. Install the SIM card in the device.

a. Using a small screwdriver, open the SIMdoor on the top of the device.

Note The device has two SIMcard slots. Only the slot numbered "1" is supported.

The slot numbered "2" is not supported.

b. Insert the SIM card in slot numbered "1". Make sure card is firmly inserted into the

card cage.

c. Close the SIM door.

d. Using a small screwdriver, screw the SIM door shut.

3. Power on the device.

4. Go to the mobile connectivity page.

n For Remote Manager, access Remote Manager and log in. Click the Mobile link.

See Configure settings from Remote Manager for information about adding a device to

Remote Manager

n For the web interface, open a browser and go to the XBee Industrial Gateway web

interface. Click Configuration > Mobile Connectivity.

See Configure settings from the XBee Industrial Gateway web interface for information

about accessing the web interface

5. Enter the connection settings for the cellular modem in the device. You can get this information

from your service provider and the information varies by service provider. In some cases, a user

name, password, or PIN are not necessary. See Mobile Configuration page for more

information about the fields in this screen.

a. In the Username and Password fields, enter the user name and the password, if

provided.

b. In the Access Point Name (APN) field, enter the APN. Note that an APN may not be

required for Verizon.

c. In the SIMPINfield, enter the SIM PIN, if provided.

d. Click Apply to save the mobile connectivity information to XBee Industrial Gateway.

Digi XBee Industrial Gateway

98

Configure XBee Industrial Gateway Mobile Connectivity settings

6. For the web interface only: Go to the Administration > Mobile Status page to view the

mobile status information. You can refresh the page to see the latest status information.

The device should now be able to connect to the mobile network. The status fields on the

Administration > Mobile Status fields will change to reflect the connectivity status.

n If the device successfully connects to the networks, two key connectivity status fields

appear as follows: SIM Pin State: READY and Connection state: Connected.

n If the device does not connect to the network, you do not see SIM Pin State on the

Mobile Status page, and/or the Connection state field has a value other than

Connected, additional setup and troubleshooting is necessary. See Troubleshooting

XBee Industrial Gateway GSM and LTE devices.

Configure mobile settings

To configure mobile settings, choose one of the following options:

From Remote Manager

1. Click the Device Management tab.

2. From the device list, double-click the device to display the device properties menu.

3. Click Mobile. The mobile connectivity settings identify the service provider to use when

connecting to the mobile network. Some values may be hidden, depending on your model.

4. Complete the fields and click Save to save your changes.

From the XBee Industrial Gateway web interface

1. From the XBee Industrial Gateway web interface, click the Mobile Connectivity under

Configuration. The Mobile Connectivity settings identify the service provider to use when

connecting to the mobile network. Some values may be hidden, depending on your model.

2. Complete the fields and click Apply to save your changes.

Mobile Configuration page

The Mobile settings on the Mobile page identify the service provider to use when connecting to the
mobile network.

n DNS server set by network: Select this option when you want to use the DNS server set by

the network.

n Username: The user name of the mobile connection needed to access the mobile network.

Depending on mobile service provider, this value may not be necessary.

n Password: The password of the mobile connection needed to access the mobile network.

Depending on mobile service provider, this value may not be necessary.

n Access Point Name (APN): The service plan or access point name (APN).

n SIM PIN: A password that allows an administrator of the device to access information on the

SIM card. The password is usually between four and eight digits. SIM PINs act like ATM PINs in

that they require users to authenticate themselves as the true owner of the card before

information is released. Depending on mobile service provider, this value may not be necessary.

Digi XBee Industrial Gateway

99

Configure XBee Industrial Gateway Mobile Connectivity settings

Mobile Connectivity Configuration page

The Mobile Connectivity settings identify the service provider to use when connecting to the mobile
network. The information that appears varies by product and whether the device is GSM- or CDMA­based. In addition, you can enable and configure the Short Message Service (SMS) from this page. For
GSM-based devices, enter the information for your account after you receive it from the mobile service
provider.

The fields on the Mobile Connectivity Configuration page are described as follows:

Current Status

This field displays the current status of the cellular modem and mobile connection, including serial
number information, signal strength and quality, and connection state.

Current Settings

n Mobile APN: The service plan or access point name (APN).

n Username: The user name of the mobile connection needed to access the mobile network.

Depending on mobile service provider, this value may not be necessary.

n Password: The password of the mobile connection needed to access the mobile network.

Depending on mobile service provider, this value may not be necessary.

n SIM PIN: A password that allows an administrator of the device to access information on the

SIM card. The password is usually between four and eight digits. SIM PINs act like ATM PINs in

that they require users to authenticate themselves as the true owner of the card before

information is released. Depending on mobile service provider, this value may not be necessary.

Short Message Service (SMS)settings

The SMS settings options configure the cellular Short Message Service (SMS) capabilities of the
cellular modem.

n Enable cellular Short Message Service (SMS) services: Enables or disables SMS features on

this Digi device. When this option is enabled, the you can configure the remaining SMS options.

This option is enabled (on) by default. When you disable SMS services, all SMS-related menu

items in the web interface and Remote Manager are disabled.

Device Cloud SMSsettings

These settings configure the Remote Manager-registered device to be managed by Remote Manager
via Short Message Service (SMS) messages.

n Enable Device Cloud SMS: Enables or disables Remote Manager SMS support.

n Phone Number: The phone number or short code of the Remote Manager server. This is a

setting in the device that allows the device to send to Remote Manager, and possibly restrict

messages to those coming from Remote Manager. The default value phone number is 32075.

n Service Identifier: The Service Identifier (prefix) of Remote Manager. This field is an optional

setting. You can use it when there is a shared short code in use, and an identifier (prefix) is

required to redirect a message to a specific service under that short code. The default value is

idgp. Use of the Service Identifier idgp is mandatory when the Phone Number is 32075.

Digi XBee Industrial Gateway

100