Page 1
XLR PRO™
Radio Frequency (RF) Modem
User Guide
Page 2
Revision history—90002202
Revision Date Description
B March
2014
C May 2015
D December
2015
E February
2016
F January
2017
Removed the data sample RX indicator frame type.
Updated descriptions for the DN, ND, and FN commands; added clarification
note to the WR command documentation.
Updated web configuration and Device Cloud options available with XLR PRO
firmware version 1006.
Updated Device Cloud brand name and login URLs.
Added certifications for Mexico and Australia.
Added USB support available with XLR PRO firmware version 1007.
Noted that user guide applies to all XLR PROmodels (XLR PRO and XLR PRO
INTL).
Moved source content and made miscellaneous editorial corrections.
Added a serial cable warning. Added Brazil and Peru certification
information. Updated ATcommands and API frames.
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
techcomm@digi.com.
XLR PRO Radio Frequency (RF) Modem User Guide
2
Page 3
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.
XLR PRO Radio Frequency (RF) Modem User Guide
3
Page 4
Contents
XLR PRO Radio Frequency (RF) Modem User Guide
Operational modes 10
For more information 11
Hardware
XLR PRO front panel 13
RJ45 serial port pinout 13
Hardware interfaces 14
Power supply 14
LEDs 14
Startup 15
Data transmission 15
Reset button 15
Antenna port 16
Set up the hardware
XLR PRO kit contents 18
Connect the hardware 19
Mount the XLR PRO 20
Right-angle mount DIN rail (not to scale) 20
Flush-mount bracket (not to scale) 21
Mounting guidelines 21
Antenna placement 22
Technical specifications
General 24
RF specifications 24
Rural range line-of-sight 24
Receiver sensitivity by RF data rate 24
UART interface data rates (software selectable) 25
Networking and security 25
Power requirements 25
Power supply 26
Environmental 26
Regulatory approvals 26
Connectors 26
XLR PRO Radio Frequency (RF) Modem User Guide
4
Page 5
Operations
XLR PRO operational design 28
Ethernet RF bridging 28
Serial mode selection 29
USB mode 30
Serial mode 30
RS-232 30
RS-485/422 30
IP socket mode 31
Controlling parameters 31
Operational description 32
Serial communications 32
Serial buffers 32
Networking methods
MAC/PHY layers 34
Ethernet bridging 34
Ethernet packet handling 34
Bridging precautions 35
Enable bridging 35
64-bit addresses 35
Unicast 35
Broadcast 35
Serial addressing basics 36
64-bit addresses 36
Unicast 36
Broadcast 36
Delivery method 36
AT commands
Special commands 39
AC (Apply Changes) 39
FR (Software Reset) 39
RE (Restore Defaults) 39
WR (Write) 39
MAC/PHY commands 40
ID (Network ID) 40
BR (RF Data Rate) 40
PL (Power Level) 40
RR (Unicast Retries) 41
MT(Broadcast Multi-Transmits) 41
Diagnostic commands 41
DB (Received Signal Strength) 41
EA (MAC ACK Timeouts) 42
ER (Received Error Count) 42
GD (Good Packets Received) 42
TR (Transmission Failure Count) 43
UA (Unicasts Attempted) 43
%H (MAC Unicast One Hop Time) 43
%8 (MAC Broadcast One Hop Time) 43
N? (Network Discovery Timeout) 44
XLR PRO Radio Frequency (RF) Modem User Guide
5
Page 6
Network commands 44
CE (Node Messaging Options) 44
BH (Broadcast Hops) 44
NH (Network Hops) 44
NN (Network Delay Slots) 45
RF Addressing commands 45
SH (Serial Number High) 45
SL (Serial Number Low) 45
DH (Destination Address High) 45
DL (Destination Address Low) 46
TO (Transmit Options) 46
NI (Node Identifier) 46
NT (Node Discovery Timeout) 47
NO (Node Discovery Options) 47
CI (Cluster ID) 47
DE (Destination Endpoint) 48
SE (Source Endpoint) 48
Addressing discovery and configuration commands 49
DN (Discover Node) 49
ND (Network Discover) 49
FN (Find Neighbors) 50
Security commands 50
KY (AES Encryption Key) 51
Serial interfacing commands 51
BD (Baud Rate) 51
NB (Parity) 51
SB (Stop Bits) 52
RO (Packetization Timeout) 52
FT (Flow Control Threshold) 52
AP (API Mode) 52
AO (API Options) 53
4E (Serial Protocol) 53
4D (RS-485 Duplex) 53
4T (RS-485 Termination) 54
D6 (RTS Flow Control) 54
D7 (CTS Flow Control) 54
Hardware diagnostics commands 55
TP (Temperature) 55
RP(RSSI PWM Timer) 55
Ethernet and IP socket mode commands 55
ES (IP Socket Mode Enable) 55
IB (IP Socket Baud Rate) 56
IP (IP Protocol) 56
DX (Destination IP Address) 57
C0 (Source Port) 57
DY (Destination Port) 57
TM (TCP Client Connection Timeout) 57
TS (TCP Server Connection Timeout) 58
MA (IP Addressing Mode) 58
MY (XLR IP Address) 58
MK (Subnet Mask) 59
GW (Default Gateway Address) 59
NS (DNS Address) 59
%M (Ethernet MAC address) 60
Device Cloud commands 60
XLR PRO Radio Frequency (RF) Modem User Guide
6
Page 7
DO (Device Cloud Enable) 60
KP (Device Description) 60
KC (Device Contact) 60
KL (Device Location) 61
LX (Latitude) 61
LY (Longitude) 61
EQ (Device Cloud FQDN) 61
DI (Device Cloud Indicator) 61
Web configuration commands 62
HE (Web Configuration Enable) 62
HU (Web Configuration User Name) 62
HW (Web Configuration Password) 62
Ethernet bridging commands 63
BE (Ethernet RF Bridging Enable) 63
BA (Bridge Destination MAC) 63
Command mode options 63
CC (Command Sequence Character) 63
CN (Exit Command mode) 64
CT (Command Mode Timeout) 64
GT (Guard Times) 64
Firmware commands 64
VB (Firmware Version) 64
VR (XLR PRO Firmware Version) 65
HV (Hardware Version) 65
VH (XLR PRO Baseboard Hardware Version) 65
*C (compatibility) 65
DD (Device Type Identifier) 65
PN (Part Number) 66
NP (Maximum Packet Payload Bytes) 66
CK (Configuration CRC) 66
Operate in API mode
API mode overview 68
Use the AP command to set the operation mode 68
API frame format 68
API operation (AP parameter = 1) 68
API operation-with escaped characters (AP parameter = 2) 69
API serial exchanges 70
AT command frames 70
Transmit and receive RF data 71
Remote AT commands 71
Code to support future API frames 71
API frame types 72
AT Command Frame - 0x08 72
AT Command - Queue Parameter Value frame - 0x09 74
Transmit Request frame - 0x10 75
Explicit Addressing Command frame - 0x11 77
Remote AT Command Request frame - 0x17 80
AT Command Response frame - 0x88 82
Modem Status frame - 0x8A 84
Transmit Status frame - 0x8B 85
Receive Packet frame - 0x90 87
Explicit Rx Indicator frame - 0x91 89
Remote Command Response frame - 0x97 91
XLR PRO Radio Frequency (RF) Modem User Guide
7
Page 8
Advanced application features
Network commissioning and diagnostics 94
Local configuration 94
Remote configuration 94
Send a remote command 94
Apply changes on remote devices 94
Remote command response 94
Test links in a network 95
Test links between adjacent devices 96
Example 97
RSSI indicators 97
Discover devices 98
General Purpose Flash Memory 98
Access General Purpose Flash Memory 99
Work with flash memory 110
Over-the-air (OTA) firmware updates 110
Distribute the new application 111
Verify the new application 111
Install the application 112
Keep in mind 112
Configure the XLR PRO using the web configuration interface
Access the XLR PRO web configuration interface 114
Set general options 114
Set Ethernet network options 114
Set Ethernet RF bridging options 115
Set Device Cloud connectivity options 116
Set XLR radio options 116
Set XLR radio serial options 117
Set XLR radio IP socket (Ethernet) options 118
Update firmware 119
Set web configuration options 119
Configure the XLR PRO using XCTU
Download and install XCTU 122
Download and install the USB driver 122
Connect XLR PRO to your PC 122
Launch XCTU and add the XLR PRO 122
Configure parameters using XCTU 122
Determine or assign an IP address 123
Determine the assigned DHCP address 123
Assign a static IP address 123
Update firmware with XCTU 123
Configure the XLR PRO using Digi Remote Manager
Create a Remote Manager account 126
Get the XLR PRO MAC address 126
Add a Digi XLR PRO to Remote Manager 126
Update firmware with Device Cloud 127
XLR PRO Radio Frequency (RF) Modem User Guide
8
Page 9
Configure Device Cloud connectivity options 127
Configure Ethernet network options 128
Configure Ethernet RF bridging options 128
Configure IP socket mode options 129
Configure serial mode options 130
Configure system options 131
Configure web configuration options 132
Configure XLR radio configuration options 132
Schedule Device Cloud configuration changes 134
Troubleshooting
Serial interface issues 136
Condition 136
Solution 136
Condition 136
Solution 136
Ethernet issues 136
Condition 136
Solution 136
General issues 136
Condition 136
Solution 136
Safety notices and certifications
RF exposure statement 138
Class 1, Division 2 (C1D2) certification—USA and Canada 138
FCC (United States) certification 139
Industry Canada (IC) certification 139
Australia certification 140
Mexico IFETEL 140
Brazil (ANATEL) 140
XLR PRO antennas
Omni-directional antennas 143
Yagi antennas 144
XLR PRO Radio Frequency (RF) Modem User Guide
9
Page 10
XLR PRO Radio Frequency (RF) Modem User Guide
The XLR PRO is a high performance, industrial grade long-range radio solution that offers serial,
Ethernet socket, and Ethernet bridging connectivity to ensure reliable wireless data communications
over long distances. There are two models:
n The XLR PRO RF Modem for North American distribution
n The XLR PRO INTL RF Modem for international distribution
In this documentation, the term XLR PRO refers to both models.
Packaged in a sturdy, rugged enclosure and using patent-pending Punch2™ Technology to maximize
range and significantly increase immunity to interference, the XLR PRO 900 MHz radio can connect a
variety of devices across many industrial applications.
Punch2 Technology leverages chirp spread spectrum (CSS) modulation to provide better receiver
sensitivity, multipath performance, and interference rejection than is available through commonly
used frequency hopping spread spectrum (FHSS) or direct sequence spread spectrum (DSSS) systems.
The advantages of Punch2 Technology arise from the characteristics of the chirp signal as well as
several digital-signal-processing techniques that enhance performance and reliability. With Punch2
Technology, data is spread to a higher bandwidth by multiplying each transmit modulation symbol
with a chirp signal. Operating at an expanded bandwidth provides several benefits:
n Greater receiver sensitivity
n Interference immunity
n Improved multipath performance
n Adjustable data rates
Flexible configuration and management options allow you to quickly set up and deploy one or more
XLR PRO modems, as well as apply firmware updates, get device status information, and more.
Operational modes
The XLR PRO offers the following operational modes:
XLR PRO Radio Frequency (RF) Modem User Guide
10
Page 11
XLR PRO Radio Frequency (RF) Modem User Guide For more information
n Serial (RS-232/RS-485/USB): In serial mode, the front panel serial port provides connectivity
to the XLR PRO via RS-232 or RS-485/422 as well as a USB serial virtual COM port.
n Ethernet (IP socket): In IP socket mode, an XLR PRO can transmit and receive serial data via a
TCP or UDP connection from either of the front panel Ethernet ports.
n Ethernet RF Bridging: In Ethernet RF bridging mode, an XLR PRO functions as an Ethernet
cable replacement, supporting point-to-multi-point transmission for a maximum of 16 XLR PRO
RF modems. By default, bridging mode is disabled. Serial data from serial or IP socket mode
operates concurrently with Ethernet RF Bridging. If serial and Ethernet traffic are sent at the
same time, there will be some latency.
For more information
The XLR PRO Radio Frequency (RF) family of products includes the following publications:
Part
Title
number Description
XLR
PRORadioFrequency
(RF) Module User
Guide
XLR PRO Radio
Frequency (RF)
Modem Quick Start
Guide
XLR PRO Radio
Frequency (RF)
Modem Getting
Started Guide
90001407 Provides complete information on all XLR PRO Radio Frequency
(RF) Module features; describes how to configure XLR PROs
using XCTU; provides reference information on all supported AT
commands and API frames.
90002204 Provides a brief summary of the XLR PRO and XLR PRO INTL
Radio Frequency (RF) Modem kit.
90002203 Provides step-by-step instructions for setting up a pair of XLR
PRO (or XLR PRO INTL) modems to test over-the-air
communications between the radios.
XLR PRO Radio Frequency (RF) Modem User Guide
11
Page 12
Hardware
XLR PRO front panel 13
RJ45 serial port pinout 13
Hardware interfaces 14
Power supply 14
LEDs 14
Reset button 15
Antenna port 16
XLR PRO Radio Frequency (RF) Modem User Guide
12
Page 13
Hardware XLR PRO front panel
XLR PRO front panel
The following figure shows XLR PRO front panel connectors and LEDs.
Item Description
1 Ethernet port 1
2 Ethernet port 2
3 Mini USB port
4 Serial data out LED
5 Serial data in LED
6 Power LED
7 Serial port
8 Link margin indicator LEDs (RSSI)
9 Reset button
10 DC power jack
WARNING! Use the serial port for serial connections only. Do not connect the serial RJ45
port to any PoE (power over Ethernet) device. Doing so could permanently damage the
XLR PRO or PoE device and void your XLR PRO warranty.
RJ45 serial port pinout
XLR PRO Radio Frequency (RF) Modem User Guide
13
Page 14
Hardware Hardware interfaces
Pin RS-232 RS-485 (4-wire) RS-485 (2-wire)
1 RXD TX+ TX/RX+
2 CTS TX- TX/RX-
3 TXD RX+ Unused
4 GND GND GND
5 GND GND GND
6 RTS RX- Unused
7 DRS/DCD Unused Unused
8 DTR Unused Unused
Hardware interfaces
The XLR PRO front panel offers the following interfaces:
n Serial (RJ45) port: The serial port (RJ45) supports RS-232 or RS-485/422 protocols.
n USB (mini USB): The mini USB port is used for configuration and basic serial communication
with a host PC. XLR PRO can act as a USB client only and requires drivers (Windows only) to
operate. The XLR PRO USB driver is available here:
www.digi.com/support/productdetail?pid=5603&type=drivers
n Ethernet: The Ethernet interface is 10/100 Base-T with a two-port Ethernet switch. The XLR
PRO does not support Power over Ethernet (PoE) and must be externally powered through the
DC power jack.
Power supply
The XLR PRO must be powered by a UL-listed power supply rated between 9 and 26 V DC. Refer to the
following table for the required input current settings.
Input voltage Minimum current rating
9 to 15 3 A
15 to 20 2 A
21 to 26 1.5 A
LEDs
The following tables describe XLR PRO LED behavior during startup and data transmissions. For a
diagram of the XLR PRO LEDS, see XLR PRO front panel.
XLR PRO Radio Frequency (RF) Modem User Guide
14
Page 15
Hardware Reset button
Startup
LED Status Description
Power Solid Power LED glows solid red.
Link margin
indicators (RSSI)
Serial Data In
(green)
Serial Data Out
(yellow)
Solid All of the link margin indicator LEDs show green for one second.
Solid On initial power on, if the green serial data in LED shows solid for three
seconds, the XLR PRO is in serial mode.
Solid On initial power on, if the yellow serial data out LED shows solid for
three seconds, the XLR PRO is in IP socket mode.
Data transmission
LED Status Description
Power Solid While power is on, the power LED shows solid red.
Link margin
indicators (RSSI)
Serial Data In
(green)
Solid
Solid Serial data in LED shows flashing when serial data is being transmitted.
The link margin indicator LEDs illuminate for four seconds to show the
signal strength of the last valid RF packet received.
n 3 LEDs = Very strong signal (> 30 dB fade margin)
n 2 LEDs = Strong signal (>20 dB fade margin)
n 1 LED = Moderate signal (>10 dB fade margin)
n 0 LED = Weak signal (<10 dB fade margin)
Serial Data Out
(yellow)
Reset button
You can use the Reset button to reset the XLR PRO and to restore factory default settings.
To reset the XLR PRO:
1. Hold down the Reset button for up to five seconds. The serial data in and serial data out LEDs
flash three times to indicate that five seconds have passed.
2. Release the Reset button. The XLR PRO resets.
To restore factory default settings:
1. Hold down the Reset button for about eight seconds. While you are holding down the reset
button, the serial data in and serial data out LEDs flash three times to indicate that five
seconds have passed. Continue to hold down the Reset button until the serial data in and serial
data out LEDs flash six times.
2. Release the Reset button. The XLR PRO is restored to factory default settings.
Solid Serial data out LED shows flashing when serial data is being received.
XLR PRO Radio Frequency (RF) Modem User Guide
15
Page 16
Hardware Antenna port
Antenna port
The antenna port is a 50 ohm RF signal connector for connecting to an external antenna. The
connector type is Reverse Polarity TNC (RPTNC) female. The connector has threads on the outside of
a barrel and a male center conductor.
XLR PRO Radio Frequency (RF) Modem User Guide
16
Page 17
Set up the hardware
XLR PRO kit contents 18
Connect the hardware 19
Mount the XLR PRO 20
Mounting guidelines 21
Antenna placement 22
XLR PRO Radio Frequency (RF) Modem User Guide
17
Page 18
Set up the hardware XLR PRO kit contents
XLR PRO kit contents
The following table shows the XLR PRO accessories kit.
Item Description
XLR PRO modem
Power supply
Network cable
Note If you replace the Network cable, the
replacement cable must be shielded.
Mini USB cable
RJ45/DB9F adapter
XLR PRO Radio Frequency (RF) Modem User Guide
18
Page 19
Set up the hardware Connect the hardware
Item Description
Antenna
Note Australian kit only: Power plug adapter kit
(UK, EU, AS)
Connect the hardware
The following figure shows how to connect the XLR PRO cables and antenna.
XLR PRO Radio Frequency (RF) Modem User Guide
19
Page 20
Set up the hardware Mount the XLR PRO
Mount the XLR PRO
CAUTION! You must install the XLR PRO in a Restricted Access Location. In addition, you
must restrict access to personnel who have been instructed on potential hazards, as
well as physically restrict access using a tool, or lock and key, or other means controlled
by a responsible authority.
The XLR PRO provides mounting holes in the bottom of the unit by which you can mount the unit
directly on a wall or attach mounting brackets. There are two mounting brackets for the XLR PRO:
n Right-angle mount
n Flush mount
The following illustrations show the dimensions of each option.
Right-angle mount DIN rail (not to scale)
XLR PRO Radio Frequency (RF) Modem User Guide
20
Page 21
Set up the hardware Mounting guidelines
Flush-mount bracket (not to scale)
Mounting guidelines
Follow these general guidelines when mounting the XLR PRO:
n Use the pre-drilled mounting holes located on the bottom of the XLR PRO unit to attach the
XLR PRO to the wall of an enclosure or DIN Rail bracket. Do not alter or move the mounting
holes.
n To attach brackets to the XLR PRO, use four (4) 6-32x3/8” screws. Do not use screws that are
longer than 3/8”.
XLR PRO Radio Frequency (RF) Modem User Guide
21
Page 22
Set up the hardware Antenna placement
Antenna placement
n Mount the XLR PRO antenna vertically—that is, pointed directly up or down.
n If the XLR PRO is mounted within a metal enclosure, use an antenna external to the enclosure
connected to the XLR PRO using a a 50 Ω coaxial cable, suitable for 900 MHz UHF radio
transmission.
XLR PRO Radio Frequency (RF) Modem User Guide
22
Page 23
Technical specifications
The following tables provide the device's technical specifications.
General 24
RF specifications 24
Rural range line-of-sight 24
Receiver sensitivity by RF data rate 24
UART interface data rates (software selectable) 25
Networking and security 25
Power requirements 25
Power supply 26
Environmental 26
Regulatory approvals 26
Connectors 26
XLR PRO Radio Frequency (RF) Modem User Guide
23
Page 24
Technical specifications General
General
Specification Value
Dimensions 18 x 13 x 3.8 cm (7.1 x 5 x 1.5 inches)
Weight 0.68kg (1.5 lbs)
Ethernet protocols UDP/TCP, DHCP client
Ethernet physical layer 10/100BASET-T/TX
RoHS Compliant
RF specifications
Specification Value
Frequency range:USA, Canada and Mexico ISM 902 to 928 MHz
Frequency range: Australia and Brazil ISM 915 to 928 MHz
RF data rate 9.4 kb/s to 3.2 Mb/s
Receiver selectivity at 141 kb/s RF data rate
Maximum transmit power (software selectable) +30 dBm (1 W)
Modulation Chirp Spread Spectrum
Rural range line-of-sight
Speed Range
1.2 Mb/s up to 100+ miles
Receiver sensitivity by RF data rate
The following table lists the available data rates along with the corresponding receiver sensitivity.
RF data rate setting (BR command) Data rate Receiver sensitivity (dBm, 25 °C)
0 9.4 kb/s -120
1 28 kb/s -118
70 dB (below 908 MHz, above 922 MHz)
40 dB (908 MHz to 922 MHz)
1
1
Based on 100-mile range results. Other data rates scale based on sensitivity levels. Results will vary based on
noise levels and line of sight quality.
XLR PRO Radio Frequency (RF) Modem User Guide
24
Page 25
Technical specifications UART interface data rates (software selectable)
RF data rate setting (BR command) Data rate Receiver sensitivity (dBm, 25 °C)
2 66 kb/s -116
3 141 kb/s -112
4 291 kb/s -109
5 591 kb/s -106
6 1.2 Mb/s -103
7 2.4 Mb/s -100
8 3.2 Mb/s -98
UART interface data rates (software selectable)
UART interface Data rate
TCP/UDP socket
Serial RS-485 921.6 kb/s
Serial RS-232 460.8 kb/s
UART Up to 921.6 kb/s
Networking and security
Item Specification
Supported network topologies Point-to-point/point-to-multipoint
Encryption 128-bit AES
Power requirements
Item Value
Supply voltage 9 VDC to 26 VDC
Receive current (typical) @ 9 VDC 300 mA typical
460.8 kb/s
Transmit current (typical) @ 9 VDC 950 mA typical
XLR PRO Radio Frequency (RF) Modem User Guide
@ 12 VDC 230 mA typical
@ 26 VDC 120 mA typical
@ 12 VDC 840 mA typical
@ 26 VDC 400 mA typical
25
Page 26
Technical specifications Power supply
Power supply
The XLR PRO must be powered by a UL-listed power supply rated between 9 and 26 V DC. Refer to the
following table for the required input current settings.
Input voltage Minimum current rating
9 to 15 3 A
15 to 20 2 A
21 to 26 1.5 A
Environmental
Specification Description
Operating temperature -40° C to 70° C
Regulatory approvals
Regulation Approval
Emissions/immunity FCC Part 15B
Hazardous locations Class I, Division 2, Groups A, B, C, and D
Mexico safety
Mexico radio
Australia RCM
Brazil ANATEL: 0621-16-1209
Peru Yes
Connectors
Connector Description
Antenna RPTNC
Power supply Phoenix
Ethernet (2) RJ45
Serial (1) RJ45
NOM NYCE safety
NOM-121
Configuration/Communication port Mini USB
XLR PRO Radio Frequency (RF) Modem User Guide
26
Page 27
Operations
XLR PRO operational design 28
Ethernet RF bridging 28
Serial mode selection 29
USB mode 30
Serial mode 30
IP socket mode 31
Serial communications 32
XLR PRO Radio Frequency (RF) Modem User Guide
27
Page 28
XLR PRO operational design
The XLR PRO uses a multi-layered firmware base for data flow. The flow of data depends on the
hardware and software configuration you choose. The configuration block diagram below shows the
host serial interface as the physical starting point and the antenna as the physical endpoint for
transferred data. As long as an interface block is able to touch another block above or below, the two
interfaces can interact. For example, if the XLR PRO is using API mode, Transparent mode is not
available.
Ethernet RF bridging
In Ethernet RF bridging mode, the XLR PRO functions as an Ethernet cable replacement, supporting
point-to-multipoint transmissions for up to 16 XLR PROs. It is configured by these parameters:
n BE (Bridge Enable): This parameter must be set to 1 to enable bridging, but it is disabled by
default.
XLR PRO Radio Frequency (RF) Modem User Guide
28
Page 29
Operations Serial mode selection
n BA (Destination RF MAC address for Ethernet bridging): Default value is 0xFFFF which is the
broadcast address. If pairing XLR PRO devices is desired, then this should be set to the RF MAC
address of the opposing XLR PRO. This can be identified by querying the SH (serial number
high) and SL (serial number low) parameters on the opposite XLR PRO (example:
BA=0x0013A20012345678).
With bridging enabled, the XLR PRO radios on the RF network should be treated as if they were a
single Ethernet cable. Consult a qualified network administrator to evaluate the radio deployment if
multiple XLR PRO radios will be used on the same LAN or if bridging multiple large networks together.
Serial mode selection
At any given time, only one serial mode can be selected. The XLR PRO selects the serial mode based
on cable connections detection and configuration options.
n USB
XLR PRO detects DTR on the USB virtual COM port.
n RS-232
XLR PRO detects DTR on the RS-232 serial port.
n RS-485/422
RS-485 configuration option is enabled or disabled via the 4E (Enable RS-485 Mode) parameter.
n IP socket
IP Socket configuration option is enabled or disabled via the ES (Enable IP Socket Mode)
parameter.
The following flow chart depicts how the XLR PRO selects serial mode:
There must be an active DTR signal to automatically detect an RS-232 serial connection. If the serial
cable or end device does not include an active DTR signal, disable IP socket mode (ES = 0) using XCTU,
the web configuration, or Device Cloud.
XLR PRO Radio Frequency (RF) Modem User Guide
29
Page 30
Operations USB mode
By default, RS-485 mode is disabled (4E = 0) and IP socket mode is enabled (ES = 1). So, by default, RS232 mode is selected if DTR is present. Otherwise, IP socket mode is selected. Use the 4E and ES
configuration parameters to select other modes, independent of DTR, which may not be present on a
serial port connection.
USB mode
The mini USB port is used for configuration and basic serial communication. To use the mini USB port,
install the XLR PRO USB driver (Windows only) on the host PC. (The driver is available at
www.digi.com/support/productdetail?pid=5603&type=drivers.) When connected via the mini USB port,
the XLR PRO appears as a virtual COM port on the host. The XLR PRO detects an active virtual DTR
signal to determine if a USB connection is active.
When communicating to the XLR PRO using the USB mode, serial settings and flow control are not
used. Serial settings (baud rate, parity, and stop bits) can be set to any value on the host PC and do
not affect the XLR PRO connection. If a host application requires flow control, use RS-232 serial mode.
Serial mode
When serial mode is the primary interface, the Serial Data In (green) LED lights for about three
seconds. Serial mode can be either RS-232 or RS-485/422, depending on serial mode selection. The
following parameters must be configured to match the host device, regardless of whether RS-232 or
RS-485 is selected:
n BD: Baud rate (See the AT command table for limits)
n NB: Parity (None, Even, or Odd)
n SB: Stop bits (1 or 2)
RS-232
RS-232 connections support hardware flow control using CTS and RTS and require matching
parameters on the XLR PRO and the host device. This includes the following:
n D6: RTS flow control. If enabled, then the XLR PRO will not output data unless RTS is asserted.
The host device should not de-assert RTS for long periods of time to avoid filling the serial
transmit buffer. If an RF data packet is received, and the serial transmit buffer does not have
enough space for all of the data bytes, the entire RF data packet will be discarded.
n D7: CTS flow control. If enabled, then the XLR PRO will not assert CTS low unless it can handle
more data from the host.
n FT: Flow control threshold. If CTS flow control is enabled (with the D7 parameter), the XLR PRO
de-asserts CTS when the serial receive buffer reaches the threshold defined by the FT
parameter. Once CTS is de-asserted, it will not be asserted again until the receive buffer has
17 bytes less than the threshold defined by FT. By default, FT is 65 bytes less than the
maximum space available for receive data.
RS-485/422
An RS-485 connection requires that 4E=1 and it also requires matching parameters on the XLR PRO
and the host device. This includes the following:
XLR PRO Radio Frequency (RF) Modem User Guide
30
Page 31
Operations IP socket mode
n 4E: Enable RS-485/422. If 4E is set to 0, then the XLR PRO will use RS-232. This parameter
needs to be set to 1 in order to use RS-485/422 on the serial port.
n 4D: Full duplex (4-wire) or half duplex (2-wire) operation. A default value of 0 selects half duplex
operation and 1 selects full duplex.
n 4T: RS-485/422 termination. Enable or disable line termination on the RS-485/422 interface.
The default value of 0 indicates that there is no line termination on the XLR PRO. If 4T is set to
1, then a 120 W termination resistor will be present on the RS-485/422 connection. This
parameter will have no effect on the XLR PRO if it is configured for RS-232.
IP socket mode
IP socket mode provides serial communication for a single TCP or UDP port on the XLR PRO (multiple
simultaneous connections are not supported). This would normally happen over the Ethernet
connection, but it may also occur over the bridge if Ethernet RF bridging is enabled and another XLR
PRO (which also has Ethernet RF bridging enabled) provides the Ethernet connection to an IP host.
With the factory default settings, the XLR PRO listens on port 9750 for incoming TCP traffic. A telnet
session can be initiated to the XLR PRO IP address as a simple IP socket connection.
The same operations that can occur in serial mode can also occur in IP socket mode. Those operations
are based on the payload of the IP frames. In other words, serial data coming to and from the XLR
PRO is equivalent to the payload of the IP socket mode data.
Controlling parameters
IP socket mode is configured by these parameters:
n IB: IP socket mode baud rate. This is set to the maximum rate of 460800 b/s by default, but it
may be set to a lower rate for throttling, if desired.
n IP: IP protocol. Default value of 1 selects TCP and 0 selects UDP. This parameter must match
the protocol used by the IP host.
n C0: TCP or UDP port on which the XLR PRO listens. The IP host must send data to this port for
the XLR PRO to accept the incoming data. If configuring the XLR PRO using XCTU, the port
number is displayed in hexadecimal.
n DY: Destination IP port. (See DX.)
n DX: Destination IP address. Tells the XLR PRO where to send data if it initiates the
conversation. If operating in TCP mode and a TCP connection does not currently exist, then the
XLR PRO attempts to make a connection to this IP address (and the IP port given by DY) to
send the data to the selected IP host and port. However, if a TCP connection already exists,
then the data is sent to that connection, ignoring the DX and DY parameters. If operating in
UDP mode, this rule changes slightly because it is a connectionless protocol. If the first IP
socket mode data comes from the XLR PRO, then DX/DY is used. If not, then all UDP data is
sent to the IP address and port from which the original data arrived.
XLR PRO Radio Frequency (RF) Modem User Guide
31
Page 32
Operations Serial communications
n TM: TCP client connection timeout. A client connection is one which was initiated by the XLR
PRO. This parameter tells how many seconds a TCP client connection remains connected when
no data is being sent or received on the connection.
n TS: TCP server connection timeout. A server connection is one which was initiated by an
external IP host. This parameter tells how many seconds a TCP server connection remains
connected when no data is being sent or received on the connection.
In addition to the above IP socket mode parameters, the MY parameter is also used in IP socket
mode:
n MY: IP address of the XLR PRO. By default, this address is learned from a DHCP server, but it
may be set to any value if static mode is used (MA=1).
Operational description
IP socket mode may start up in the following cases:
n Reset: Based on the mode selection rules previously described.
n Configuration parameters: Parameters that affect the mode are changed and applied.
n Unplugged cable: An RS-232 cable is unplugged.
When IP socket mode is the primary interface, the Serial Data Out (yellow) LED lights for about three
seconds.
Upon starting or restarting the XLR PRO, either a TCP or a UDP listener is set up depending on the IP
parameter. If UDP data is received or if a TCP connection gets established before the XLR PRO
attempts to send data, then the DX and DY parameters are unused. In this case, the XLR PRO takes
the role of a TCP or UDP server. But if the XLR PRO has data to send before an IP host sends data to
the XLR PRO, then DX and DY determine the destination of that data until the TCP connection times
out or until IP socket mode is restarted, whichever comes first.
Serial communications
Whether the XLR PRO is configured for USB, RS-232, RS-485/422, or IP socket mode, the XLR PRO
handles the traffic as serial data, and the XLR PRO handles all serial traffic the same, regardless of the
interface in use.
Serial buffers
n Serial receive buffer
When serial data enters the XLR PRO, the data is stored in the serial receive buffer until it can
be processed. Under certain conditions, the XLR PRO may not be able to process data in the
serial receive buffer immediately. If large amounts of serial data are sent to the XLR PRO such
that the serial receive buffer would overflow, then new data is discarded. If using RS-232, this
can be avoided by using hardware flow control. Software flow control can be used regardless of
which serial interface is used.
n Serial transmit buffer
When serial RF data is received, the data is moved into the serial transmit buffer and sent out
of the active serial interface of the XLR PRO. If the serial transmit buffer becomes full and
system buffers are also full, then the entire RF data packet is dropped. Whenever data is
received faster than it can be processed and transmitted out the serial port, there is a
potential of dropping data.
XLR PRO Radio Frequency (RF) Modem User Guide
32
Page 33
Networking methods
MAC/PHY layers 34
Ethernet bridging 34
Serial addressing basics 36
XLR PRO Radio Frequency (RF) Modem User Guide
33
Page 34
Networking methods MAC/PHY layers
MAC/PHY layers
PHY stands for “physical layer.” The PHY layer manages the hardware that modulates and
demodulates the RF bits.
MAC stands for “media access control.” The MAC layer sends and receives RF frames. Each packet
includes a MAC layer data header that contains addressing information, as well as packet options. This
layer implements packet acknowledgments (ACKs), packet tracking to eliminate duplicates, and so
on.
When a radio is transmitting, it cannot receive packets. There are no beacons or master/slave
requirements in the design of the MAC/PHY.
The following table shows the AT commands related to the MAC/PHY layers.
AT
command Description
ID
PL
RR
MT
The ID (network identifier) command sets the network identifier. For XLR PRO radios to
communicate, you must configure them with the same network identifier.
The PL (power level) command sets the transmit (TX) power level. You can reduce the
power level from the maximum to reduce current power consumption or to test at
short distances. This comes at the expense of reduced radio range.
The RR (unicast retries) command specifies the number of times a sending radio
attempts to get an ACK from a destination radio when sending a unicast packet.
The MT (broadcast multi-transmit) command specifies the number of times a broadcast
packet is repeatedly transmitted. This adds redundancy to improve reliability.
Ethernet bridging
The purpose of Ethernet RF bridging is to act as an Ethernet cable replacement. The MAC/PHY layer of
the Ethernet standard handles all Ethernet traffic. As a result, the XLR PRO does not have to have a
valid IP address on the network for bridging to work.
Ethernet packet handling
If the XLR PRO receives an Ethernet packet with a MAC address that does not match its own MAC
address, and if you enable Ethernet bridging, then the entire Ethernet packet is encapsulated inside of
a radio frame and sent over the air (OTA) to another XLR PRO.
The XLR PRO does not support fragmentation, so the unit sends the entire Ethernet packet in one OTA
frame. This can cause an issue at lower data rates. If BR (RF data rate) is less than 3 (141kb/s), then
full size Ethernet frames cannot be transmitted. However, smaller frames can be transmitted at
lower data rates. We do not recommend this for typical Ethernet applications, but you could use it in
some scenarios.
When the XLR PRO receives an RF bridging packet, it inspects the Ethernet MAC address of the
packet. If the address matches the Ethernet MAC address of the XLR PRO, then the XLR PRO handles
the packet on board. Otherwise, it forwards the frame over the Ethernet interface.
The MT (broadcast multi-transmit) and RR (unicast retries) parameters do not apply to Ethernet
bridging packets, but they do apply for all non-bridging traffic (serial or IP socket mode). Serial data
from serial or IP socket mode operates concurrently with Ethernet bridging. If the XLR PRO sends
serial and Ethernet traffic at the same time, the traffic encounters latency.
XLR PRO Radio Frequency (RF) Modem User Guide
34
Page 35
Networking methods Ethernet bridging
Bridging precautions
The practical application of an Ethernet bridge is to span two Ethernet networks that are not
otherwise connected. If they are connected by another path, then a bridge loop allows multiple paths
to the same node. When multiple paths to the same node occur, then a broadcast storm can result in
a saturated network, resulting in denial of service for legitimate traffic. Typically, this is alleviated by a
network switch that support the Spanning Tree Protocol (STP) to detect and prevent such a network
loop. The XLR PRO does not implement STP.
As a precaution, when using bridging, only connect one of the XLR PRO devices to the same Ethernet
network to avoid bridging loops. If you create multiple paths and you connect enterprise level
switches with STP to the XLR PRO devices, then the connected switch ports are shutdown.
When bridging two networks, if each has its own DHCP server, it can create many problems.
Enable bridging
To enable bridging, set the BE (bridging enable) parameter to 1. This parameter is disabled by default
due to the risk of encountering a bridging loop during initial configuration.
64-bit addresses
Each radio has a unique factory-assigned IEEE 64-bit address. You can read the factory-assigned
address with the SH (serial number high) and SL (serial number low) commands. Addresses use the
following form:
0x0013A2XXXXXXXXXX
The first six digits are the Digi Organizationally Unique Identifier (OUI). The broadcast address is
0x000000000000FFFF.
Unicast
To transmit to a specific device:
n For Ethernet RF bridging, set BA (bridge destination MAC) to the SH:SL of the destination radio.
BA is the entire 64-bit address and is not broken into two 32-bit values. For example:
BA=0x0013A20012345678
n If you have configured Ethernet bridging for unicasts, up to three retries occur while waiting for
an ACK. As a result, unicasts are slower, but more reliable than broadcasts.
Broadcast
To transmit to all devices:
n When using Transparent mode, set DH to all 0's and DL to 0xFFFF.
n For API mode set 0x000000000000FFFF in the 64-bit destination address field of the API frame.
By default, Ethernet bridging uses broadcasts and no retransmissions occur. If you send packets via
TCP, then the TCP protocol provides the retransmissions as needed to provide for reliability. UDP
packets may be lost when BA is set to a broadcast address.
XLR PRO Radio Frequency (RF) Modem User Guide
35
Page 36
Networking methods Serial addressing basics
Serial addressing basics
64-bit addresses
Each radio has a unique factory-assigned IEEE 64-bit address. You can read the factory-assigned
address with the SH (serial number high) and SL (serial number low) commands. Addresses use the
following form:
0x0013A2XXXXXXXXXX
The first six digits are the Digi Organizationally Unique Identifier (OUI). The broadcast address is
0x000000000000FFFF.
Unicast
To transmit to a specific radio:
n When using transparent mode, set DH and DL (destination address high and destination
address low) to match the SH and SL (serial number high and serial number low) of the
destination radio.
n For API mode, set SH and SL address in the 64-bit destination address field of the API frame.
Broadcast
To transmit to all devices:
n When using Transparent mode, set DH to all 0's and DL to 0xFFFF.
n For API mode set 0x000000000000FFFF in the 64-bit destination address field of the API frame.
By default, Ethernet bridging uses broadcasts and no retransmissions occur. If you send packets via
TCP, then the TCP protocol provides the retransmissions as needed to provide for reliability. UDP
packets may be lost when BA is set to a broadcast address.
Delivery method
The XLR PRO supports two delivery methods:
n Point-to-multipoint (0x40)
n Repeater (directed broadcast) (0x80)
Transparent mode uses the TO (transmit options) parameter as the default delivery method. For API
transmissions, the TxOptions API field specifies the delivery method. When the TxOptions API field is
set to 0, the value in the TO parameter will also be used by API transmissions.
Point to Point / Point to Multipoint (P2MP)
This delivery method does not use a network header, only the MAC header.
In P2MP, the sending devices always send all messages directly to the destination. Other nodes do not
repeat the packet. The sending device only delivers a P2MP unicast directly to the destination device,
which must be in range of the sending device.
The XLR PRO uses patented technology that allows the destination device to receive unicast
transmissions directed to it, even when there is a large amount of traffic. This works best if you keep
broadcast transmissions to a minimum.
XLR PRO Radio Frequency (RF) Modem User Guide
36
Page 37
Networking methods Serial addressing basics
A sending node repeats a P2MP broadcast transmission MT+1 times, but the receiving nodes do not
repeat it, so like a unicast transmission, the receiving device must be in range.
All devices that receive a P2MP broadcast transmission will output the data through the active serial
interface.
Repeater/directed broadcast
Ethernet RF bridging does not support repeater/directed broadcast. All Ethernet frames are
transmitted as point-to-point or point-to-multipoint regardless of what the TO (transmit option)
parameter.
Directed broadcast transmissions are received and repeated by all routers in the network. Because
ACKs are not used, the originating node sends the broadcast multiple times. By default a broadcast
transmission is sent four times—the extra transmissions become automatic retries without
acknowledgments. This results in all nodes repeating the transmission four times as well. Sending
frequent broadcast transmissions can quickly reduce the available network bandwidth and should be
used sparingly.
The MAC layer is the building block that is used to build repeater capability. Repeater mode is
implemented with a network layer header that comes after the MAC layer header in each packet. In
this network layer, there is additional packet tracking to eliminate duplicate broadcasts. In this
delivery method, unicasts and broadcast packets are both sent out as broadcasts that are always
repeated. All repeated packets are sent to every radio. Broadcast data is sent out the active serial
interface of all radios that receive it.
When a unicast is sent, it specifies a destination address in the network header. Only the radio that
has the matching destination address sends it out the serial port. This is called a directed broadcast.
Any node that has a CE (node messaging option) set to route will rebroadcast the packet if its BH
(broadcast hops) or broadcast radius values have not been depleted. If a repeated broadcast has
already been seen, the node will ignore it. The NH (network hops) parameter sets the maximum
number of hops that a broadcast will be repeated. This value is always used, unless a smaller BH value
is specified.
By default, the CE (node messaging option) parameter is set to not route broadcasts. Due to the longrange of the XLR PRO, Digi advises you to evaluate on a per-radio basis which nodes should be
configured as repeaters. Limiting the amount of congestion and generated RF traffic provides a more
reliable network.
Transmission timeouts
When a node receives an API Tx Request while in API mode or an RO (packetization timeout) while in
transparent mode, the time required to route the data to its destination depends on a number of
configured parameters and whether the transmission is a unicast or a broadcast.
Note The timeouts in this section are theoretical timeouts. An application should pad the calculated
maximum timeouts by a few hundred milliseconds. When using API mode, Tx Status API packets
should be the primary method of determining if a transmission has completed.
Transmit a broadcast
All of the routers in a network must relay a broadcast transmission.
The maximum delay occurs when the sender and receiver are on the opposite ends of the network.
The NH and %H parameters define the maximum broadcast delay as follows:
BroadcastTxTime = NH * NN * %8
Unless BH < NH, in which case the formula is:
BroadcastTxTime = BH * NN * %8
XLR PRO Radio Frequency (RF) Modem User Guide
37
Page 38
AT commands
Special commands 39
MAC/PHY commands 40
Diagnostic commands 41
Network commands 44
RF Addressing commands 45
Addressing discovery and configuration commands 49
Security commands 50
Serial interfacing commands 51
Hardware diagnostics commands 55
Ethernet and IP socket mode commands 55
Device Cloud commands 60
Web configuration commands 62
Ethernet bridging commands 63
Command mode options 63
Firmware commands 64
XLR PRO Radio Frequency (RF) Modem User Guide
38
Page 39
AT commands Special commands
Special commands
The following commands are special commands.
AC (Apply Changes)
Immediately applies new settings without exiting Command mode.
Parameter range
N/A
Default
N/A
FR (Software Reset)
Resets the device. The device responds immediately with an OK and performs a reset 100 ms later.
Parameter range
N/A
Default
N/A
RE (Restore Defaults)
Restore device parameters to factory defaults.
In order for the default parameters to persist through subsequent resets, send a separate WR
command after RE.
Parameter range
N/A
Default
N/A
WR (Write)
Writes parameter values to non-volatile memory so that parameter modifications persist through
subsequent resets.
When you issue a WR command add a 100 millisecond delay or wait for an OK response before issuing
any subsequent AT commands.
Note Once you issue a WR command, do not send any additional characters to the device until after
you receive the OK response.
Parameter range
N/A
Default
N/A
XLR PRO Radio Frequency (RF) Modem User Guide
39
Page 40
AT commands MAC/PHY commands
MAC/PHY commands
The following AT commands are MAC/PHY commands.
ID (Network ID)
Sets or displays the network identifier for the module. To communicate with other modules in a
network, the modules must have matching network identifiers. If you are using OEM network
identifiers, set ID to FFFF to use the factory value.
During join via commissioner, ID determines the extended pan ID of the network to join.
Parameter range
0 - 0x7FFF
Default
0x7FFF
BR (RF Data Rate)
Sets or displays the rate at which RF data is transmitted for all operational modes. Devices within a
network do not need to have matching data transmission rates. The BR setting does not control the
rate at which RF modules receive data.
Range
An integer from 0 through 8:
Value Description
0
1
2
3
4
5
6
7
8
Default
Default is 4 which indicates a data transmission rate of 290.8 kb per second.
9.38 kb/s
28.14 kb/s
65.66 kb/s
140.7 kb/s
290.8 kb/s
590.9 kb/s
1.191 Mb/s
2.392 Mb/s
3.189 Mb/s
PL (Power Level)
Sets or reads the power level at which the device transmits conducted power. Power levels are
approximate.
XLR PRO Radio Frequency (RF) Modem User Guide
40
Page 41
AT commands Diagnostic commands
Parameter range
An integer from 0 through 4:
Value Description
0
1
2
3
4
Default
4
0 dBm, (1 mW)
+10 dBm, (10 mW)
+20 dBm, (100 mW)
+27 dBm, (500 mW)
+30 dBm, (1 Watt)
RR (Unicast Retries)
Set or read the maximum number of MAC level packet delivery attempts for unicasts. If RR is nonzero, the sent unicast packets request an acknowledgment from the recipient. Unicast packets can
be retransmitted up to RR times if the transmitting device does not receive a successful
acknowledgment.
Parameter range
0 - 0xF
Default
0xA (10 retries)
MT(Broadcast Multi-Transmits)
Set or read the number of additional MAC-level broadcast transmissions. All broadcast packets are
transmitted MT+1 times to ensure they are received.
Parameter range
0x0 - 0x8
Default
3
Diagnostic commands
The following commands are diagnostic commands.
DB (Received Signal Strength)
Reports the received signal strength of the last received RF data packet. Because DB reports the
signal strength of the last hop only, DB does not provide an accurate quality measurement for a
multihop link.
XLR PRO Radio Frequency (RF) Modem User Guide
41
Page 42
AT commands Diagnostic commands
DB returns a hexadecimal value for the -dBm measurement. For example, if DB returns 0x60, then the
RSSI of the last packet received is -96 dBm.
Parameter range
0 - 0xFF [read-only]
Default
N/A
EA (MAC ACK Timeouts)
Reports or resets the total number of MAC-level unicast transmissions that timed out waiting for a
MAC ACK. The total can be up to RR (unicast retries) + 1 timeouts per unicast, up to a maximum of
0xFFFF. After 0xFFFF, additional retries are not counted. You can reset the counter to any 16-bit value
within the valid range by appending a hexadecimal value to the EA command.
EA is a volatile value—that is, the value does not persist across module resets.
Parameter range
0 - 0xFFFF
Default
N/A
ER (Received Error Count)
Reports or resets the total number of received packets that were rejected because of bit errors in the
packet, up to a maximum of 0xFFFF errors. After 0xFFFF, additional errors are not counted.
(Occasionally, random noise can cause a packet to be rejected.) You can reset the counter to any 16bit value within the valid range by appending a hexadecimal value to the ER command.
ER is a volatile value—that is, the value does not persist across device resets.
Parameter range
0 - 0xFFFF
Default
0
GD (Good Packets Received)
Reports or resets the total number of successfully received packets that contain a valid MAC header,
up to a maximum of 0xFFFF packets. After 0xFFFF, additional successfully received packets are not
counted. You can reset the counter to any 16-bit value within the valid range by appending a
hexadecimal value to the GD command.
GD is a volatile value—that is, the value does not persist across device resets.
Parameter range
0 - 0xFFFF
Default
N/A (0 after reset)
XLR PRO Radio Frequency (RF) Modem User Guide
42
Page 43
AT commands Diagnostic commands
TR (Transmission Failure Count)
Reports or resets the total number of unicast transmissions for which all retries failed with no MAC
ACK from the destination node, up to a maximum of 0xFFFF transmission failures. After 0xFFFF,
failures are no longer counted. You can reset the counter to any 16-bit value within the valid range by
appending a hexadecimal value to the TR command.
TR is a volatile value—that is, the value does not persist across module resets.
Parameter range
0 - 0xFFFF
Default
N/A
UA (Unicasts Attempted)
Reports or resets the total number of MAC unicast transmissions for which an ACK is requested, up to
a maximum of 0xFFFF transmissions. After 0xFFFF, additional transmissions are not counted. You can
reset the counter to any 16-bit value within the valid range by appending a hexadecimal value to the
UA command.
UA is a volatile value—that is, the value does not persist across device resets.
Parameter range
0 - 0xFFFF
Default
0
%H (MAC Unicast One Hop Time)
The MAC unicast one hop time timeout in milliseconds. If you change the MAC parameters it can
change this value.
Parameter range
[read-only]
Default
0x267
%8 (MAC Broadcast One Hop Time)
The MAC broadcast one hop time timeout in milliseconds. If you change MAC parameters, it can
change this value.
Parameter range
[read-only]
Default
0x23D
XLR PRO Radio Frequency (RF) Modem User Guide
43
Page 44
AT commands Network commands
N? (Network Discovery Timeout)
Reports the maximum response time in milliseconds for ND (Network Discover) and DN (Discover
Node) responses. The timeout is based on NT (Node Discovery Timeout) and the network propagation
time.
Parameter range
[read-only]
Default
0x3C41
Network commands
The following commands are network commands.
CE (Node Messaging Options)
Sets the routing and messaging mode for the device. A device can be configured to route or not route
and configured to multi-hop packets when TO (Transmit Options) is configured for Directed Broadcast
(0x80).
Parameter range
An integer from 0 through 2:
Value Description
0
1
2
Default
2
Standard router node. A standard router repeats directed broadcasts.
Not applicable.
Non-routing node.
BH (Broadcast Hops)
Sets or displays the maximum number of transmission hops for directed broadcast data transmissions
when TO (Transmit Options) is configured for Directed Broadcast (0x80). For maximum hops, set the
value to 0. If BH is set to a value greater than the value for NH (Network Hops), then the NH value is
used.
Parameter range
An integer from 0 through 4.
Default
0
NH (Network Hops)
Sets or displays the maximum number of hops expected for a Directed Broadcast network.
XLR PRO Radio Frequency (RF) Modem User Guide
44
Page 45
AT commands RF Addressing commands
Parameter range
An integer from 0 through 4.
Default
4
NN (Network Delay Slots)
Sets or displays the maximum delay slots before rebroadcasting a Directed Broadcast packet.
Parameter range
An integer from 0 through 8.
Default
3
RF Addressing commands
The following AT commands are RF addressing commands.
SH (Serial Number High)
Displays the upper 32 bits of the unique IEEE 64-bit extended address assigned to the XLR PRO in the
factory.
Parameter range
0 - 0xFFFFFFFF [read-only]
Default
Set in the factory
SL (Serial Number Low)
Displays the lower 32 bits of the unique IEEE 64-bit RF extended address assigned to the XLR PRO in
the factory.
Parameter range
0 - 0xFFFFFFFF [read-only]
Default
Set in the factory
DH (Destination Address High)
Displays the upper 32 bits of the unique IEEE 64-bit RF extended address for the destination module.
DH and DL (Destination Address Low) together define the destination address used for transmission of
transparent data. For broadcast, use the destination address 0x000000000000FFFF.
Parameter range
0 - 0xFFFFFFFF
XLR PRO Radio Frequency (RF) Modem User Guide
45
Page 46
AT commands RF Addressing commands
Default
0
DL (Destination Address Low)
Displays the lower 32 bits of the unique IEEE 64-bit RF extended address for the destination module.
and DL together define the destination address used for transmission of transparent data in either
serial or IP socket modes. For broadcast, use the destination address 0x000000000000FFFF.
Parameter range
0 - 0xFFFFFFFF
Default
0xFFFF
TO (Transmit Options)
The bitfield that configures the transmit options for transparent mode.
Note The TO setting only applies to CoAP transmissions if IP is set to 3).
Sets or displays transmit options for all serial transmissions. TO options can be overridden packet-bypacket using the TxOptions field of an API TxRequest frame.
Parameter range
One of the following hexadecimal values:
Value Description
0x40 Point-to-point/multipoint, ACK enabled
0x41 Point-to-point/mulitpoint, ACK disabled
0x80 Repeater/Directed broadcast, ACK enabled
0x81 Repeater/Directed broadcast, ACK disabled
Default
0x40
NI (Node Identifier)
Sets or displays a string identifier for the XLR PRO. The NI string identifier is returned by the ND
(Network Discover) command. The NI string identifier can also be used by the DN (Discover Node)
command to set the destination address—DL (Destination Address Low) and —to the extended 64-bit
address of the XLR PRO with the matching NI string identifier.
Parameter range
A string of case-sensitive ASCII printable characters from 0 to 20 bytes in length. The string cannot
start with the space character. A carriage return or a comma automatically ends the command.
XLR PRO Radio Frequency (RF) Modem User Guide
46
Page 47
AT commands RF Addressing commands
Default
One ASCII space character (0x20)
NT (Node Discovery Timeout)
Sets or displays the maximum randomized delay time used for sending network discovery responses—
ND (Network Discover), DN (Discover Node), and FN (Find Neighbors) command responses. The
random delay time is used to stagger the discovery command responses to alleviate network
congestion.
Use N? (Network Discovery Timeout) to determine the maximum response time a ND (Network
Discover) response requires based on NT and network propagation time.
Parameter range
0x20 - 0x2EE0 (x 100 ms)
Default
0x82 (13 seconds)
NO (Node Discovery Options)
Sets or displays network discovery options. Depending on the selected options, NO changes the
behavior of the ND (Network Discover) command and determines the values returned for received ND
responses and API node identification frames.
Parameter range
0x0 - 0x7 (bit field)
Hex
value Bitfield Description
0x01 00000001
0x02
0x03 00000011 Selects both 01 and 02 options
0x04 00000100
0x05 00000101 Selects both 01 and 04 options.
0x06 00000110 Both 02 and 04 options.
0x07 00000111 Select all options: 01, 02, and 04.
Default
00000010
0x0
Appends DD (Device Type Identifier) value to ND (Network Discover) responses
and API node identification frames.
Sends ND or FN (Find Neighbors) response frame when ND is issued.
Appends RSSI of the last hop for the repeater networks to ND or FN responses
and API node identification frames.
CI (Cluster ID)
XLR PRO
Sets or displays the default application layer cluster identifier used for all data transmissions.
XLR PRO Radio Frequency (RF) Modem User Guide
47
Page 48
AT commands RF Addressing commands
Parameter range
0 - 0xFFFF
Value Description
0x11 Transparent data
0x12
0x14 Link test
0x23 Memory Access (GPM)
Default
Loopback (the destination node echoes transmitted packets back to the originator)
0x11
DE (Destination Endpoint)
Sets or displays the application layer destination ID value. The value is used as the destination
endpoint for all data transmissions. The default value (0xE8) is the Digi data endpoint.
Parameter range
Value Description
0xE6 Digi device endpoint
0xE8 Digi data endpoint
Default
0xE8
SE (Source Endpoint)
Sets or displays the application layer source endpoint value. The value is used as the source endpoint
for all data transmissions. The default value (0xE8) is the Digi data endpoint.
Parameter range
Value Description
0xE6 Digi device endpoint
0xE8 Digi data endpoint
Default
0xE8
XLR PRO Radio Frequency (RF) Modem User Guide
48
Page 49
AT commands Addressing discovery and configuration commands
Addressing discovery and configuration commands
DN (Discover Node)
Resolves an NI (Node identifier) string to a physical address (case sensitive).
DN behavior in Command mode
When a destination address is discovered, the device:
1. Sets DL (Destination Address Low) and to the extended 64-bit address of the device with the
matching string.
2. Returns OK<CR>.
3. Exits command mode to allow immediate communications.
For API mode (AP = 1 or 2):
When a destination address is discovered:
n Receiving device returns 0xFFFE and 64-bit extended addresses in an API command response
frame.
Errors
If there is no response after the number of milliseconds set by the N? (Network Discovery Timeout)
parameter or a parameter is not specified (left blank), the command is terminated and an ERROR
message is returned. When an ERROR is returned, command mode is not exited.
Parameter range
A string of case-sensitive ASCII printable characters from 1 to 20 bytes in length. The string cannot
start with the space character. A carriage return or a comma automatically ends the command.
Default
N/A
ND (Network Discover)
Discovers and reports all devices found in the network.
For each discovered device, the following information is returned:
RESERVED<CR> (always 0xFFFE)
SH<CR> (4 bytes)
SL<CR> (4 bytes)
NI<CR> (Variable length, up to 20 bytes)
PARENT_NETWORK ADDRESS<CR> (always 0xFFFE)
DEVICE_TYPE<CR> (1 Byte: 0=Coord, 1=Router, 2=End Device)
STATUS<CR> (1 Byte: Reserved)
PROFILE_ID<CR> (2 Bytes)
MANUFACTURER_ID<CR> (2 Bytes)
DIGI DEVICE TYPE<CR> (4 Bytes. Optionally included based on settings.)
RSSI OF LAST HOP<CR> (1 Byte. Optionally included based on settings.)
<CR>
XLR PRO Radio Frequency (RF) Modem User Guide
49
Page 50
AT commands Security commands
After the number of milliseconds set by the N? (Network Discovery Timeout) parameter, the command
ends by returning a carriage return (CR). Optionally, ND also accepts a as a parameter and only a
device that matches the identifier is returned.
If the ND command is sent through a local API frame, each response is returned as a separate Local or
Remote AT Command Response API packet, respectively. The data returned is the same without
carriage return delimiters. The string ends with a 0x00 (null) character.
Parameter range
N/A
Default
N/A
FN (Find Neighbors)
Discovers and reports all devices found within immediate RF range.
For each discovered device, the following information is reported:
RESERVED<CR> (always 0xFFFE)
SH<CR> (4 bytes)
SL<CR> (4 bytes)
NI<CR> (Variable length, up to 20 bytes)
PARENT_NETWORK ADDRESS<CR> (always 0xFFFE)
DEVICE_TYPE<CR> (1 Byte: 0=Coord, 1=Router, 2=End Device)
STATUS<CR> (1 Byte: Reserved)
PROFILE_ID<CR> (2 Bytes)
MANUFACTURER_ID<CR> (2 Bytes)
DIGI DEVICE TYPE<CR> (4 Bytes. Optionally included based on settings.)
RSSI OF LAST HOP<CR> (1 Byte. Optionally included based on settings.)
<CR>
If the FN command is issued in command mode, after the number of milliseconds set by the N?
(Network Discovery Timeout) parameter + overhead time, the command ends by returning a carriage
return (CR).
If the FN command is sent through a local API frame, each response is returned as a separate Local or
Remote AT Command Response API packet, respectively. The data returned is the same without
carriage return delimiters. The string ends with a 0x00 (null) character.
Parameter range
N/A
Default
N/A
Security commands
The following AT commands are security commands.
XLR PRO Radio Frequency (RF) Modem User Guide
50
Page 51
AT commands Serial interfacing commands
KY (AES Encryption Key)
Sets the 16-byte network security key used for encryption and decryption of transmitted data. This
command is write-only. If you attempt to read KY, an OK status is returned. You must set the
encryption key to the same value for all devices for successful communication.
Parameter range
128-bit value
Default
N/A
Serial interfacing commands
The following commands are serial interfacing commands.
BD (Baud Rate)
Sets or displays the serial baud rate for the XLR PRO. BD affects only the interface data rate for RS232 and RS-485/422 data through the serial port.
Parameter range
A BD value of 1 through 0xA selects a standard baud rate preset.
A hexadecimal value from 0x5B9 through 0x5B8D80 specifies a specific baud rate.
Preset values include:
To set a non-standard baud rate, enter a value above 0x5B9. BD adjusts the value to the closest
supported baud rate. After entering a specific baud rate, query BD to read the actual baud rate. Baud
rates can be set as high as 6 Mb/s, but the host and serial switching circuitry may not support it.
Default
0x03 (9600 b/s)
NB (Parity)
Set or display the parity settings for serial communications.
Parameter range
0x00 - 0x02
Parameter Description
0x00 No parity
0x01 Even parity
0x02 Odd parity
Default
0x00
XLR PRO Radio Frequency (RF) Modem User Guide
51
Page 52
AT commands Serial interfacing commands
SB (Stop Bits)
Sets or displays the number of stop bits for the UART.
Parameter range
One of the following values:
Value Description
0x0 One (1) stop bit.
0x1 Two (2) stop bits.
Default
0
RO (Packetization Timeout)
Set or read the number of character times of inter-character silence required before transmission
begins when operating in Transparent mode.
Set or read the number of character times of inter-character silence required before transmission
begins when operating in Transparent mode.
Set RO to 0 to transmit characters as they arrive instead of buffering them into one RF packet.
Parameter range
0 - 0xFF (x character times)
Default
3
FT (Flow Control Threshold)
Set or display the flow control threshold.
De-assert CTS and/or send XOFF when FT bytes are in the UART receive buffer. Re-assert CTS when
less than FT-16 bytes are in the UART receive buffer.
Parameter range
0x11 - 0x94F
Default
0x91F
AP (API Mode)
When you enable API, you must format the serial data as API frames because Transparent operating
mode is disabled.
The device ignores this command when using SPI, where API mode is always enabled.
Parameter range
0 - 2
XLR PRO Radio Frequency (RF) Modem User Guide
52
Page 53
AT commands Serial interfacing commands
Value Description
0
1 API mode without escapes. The device packetizes all UART input and output data in API
2 API mode with escapes. The device is in API mode and inserts escaped sequences to allow
Default
Transparent mode. API mode is off. All serial input and output is raw data and packets are
delineated using the RO and RB parameters.
format, without escape sequences.
for control characters.
0
AO (API Options)
AO (API Options)
Sets or displays the API data frame output format for received frames. Applies to both UART and SPI
interfaces.
Parameter range
0, 1
Value Description
0
API RX indicator (0x90)
1
Default
0
API Explicit RX indicator (0x91)
4E (Serial Protocol)
Sets or displays the serial protocol used for serial mode operation.
Range
Value Description
0 RS-232
1 RS-485/422
Default
0 (RS-232).
4D (RS-485 Duplex)
Sets or displays duplex option for RS-485. This settings has no impact on RS-232 communications.
XLR PRO Radio Frequency (RF) Modem User Guide
53
Page 54
AT commands Serial interfacing commands
Range
Value Description
0 Two-wire (half-duplex)
1 Four-wire (full-duplex)
Default
0 (half-duplex).
4T (RS-485 Termination)
Sets or displays whether line termination is enabled or disabled for RS-485/422. Line termination
enables a 120 Ohm termination resistor on the RS-485/422 data lines. This setting has no impact on
RS-232 communication.
Range
Value Description
0 Line termination is disabled.
1 Line termination is enabled.
Default
0 (line termination is disabled).
D6 (RTS Flow Control)
Sets or displays whether RTS flow control is enabled or disabled for the serial port.
Parameter range
0 - 1
Value Description
0 RTS flow control is disabled
1 RTS flow control is enabled
Default
0
D7 (CTS Flow Control)
Sets or displays whether CTS flow control is enabled or disabled for the serial port.
XLR PRO Radio Frequency (RF) Modem User Guide
54
Page 55
AT commands Hardware diagnostics commands
Parameter range
Parameter Description
0
1
Default
0
0x1
CTS flow control is disabled
CTS flow control is enabled
Hardware diagnostics commands
TP (Temperature)
Displays the temperature of the XLR PRO in degrees Celsius. The temperature value is displayed in 8bit two’s compliment format. For example, 0x1A = 26°C, and 0xF6 = -10°C.
Because the XLR PRO produces heat, this temperature reading is usually above the ambient
temperature.
Parameter range
0 - 0xFF which indicates degrees Celsius displayed in 8-bit two's compliment format.
Default
N/A
RP(RSSI PWM Timer)
Sets or displays the amount of time (in deciseconds) the RSSI LEDs are active after a valid RF packet is
received. When RP is FF, output is always on.
Parameter range
0 - 0xFF (x 100 ms)
Default
0x28 (four seconds)
Ethernet and IP socket mode commands
ES (IP Socket Mode Enable)
Sets or displays whether IPsocket mode is enabled. Enabling socket mode allows serial traffic to be
sent to a TCP or UDP port based on the parameter. The XLR PRO remains in listen-only state unless
DX (Destination IP Address) is set to a valid IP address.
XLR PRO Radio Frequency (RF) Modem User Guide
55
Page 56
AT commands Ethernet and IP socket mode commands
Range
Value Description
0 IPsocket mode is disabled.
1 IP socket mode is enabled.
Default
Default is 1 (IP socket mode is enabled).
IB (IP Socket Baud Rate)
Sets or displays the IP socket baud rate for the XLR PRO. This value only affects the interface data
rate for serial TCP/UDP data through the Ethernet port.
Range
An integer from 1 through 9 to select a preset baud rate; or a hexadecimal value from 0x5B9
through 0x5B8D80 to specify a specific baud rate.
Preset values include:
Value Description
1 2,400 b/s
2 4,800 b/s
3 9,600 b/s
4 19,200 b/s
5 38,400 b/s
6 57,600 b/s
7 115,200 b/s
8 230,400 b/s
9 460,800 b/s
To set a non-standard baud rate, enter a value above 0x5B9. IB adjusts the value to the closest
supported baud rate. After entering a specific baud rate, query IB to read the actual baud rate.
Default
Default is 9 (460,800 b/s).
IP (IP Protocol)
Sets or displays the protocol used for the listening port (C0 (Source Port)) while the device is in
Transparent mode (AP = 0).
XLR PRO Radio Frequency (RF) Modem User Guide
56
Page 57
AT commands Ethernet and IP socket mode commands
Parameter range
Value Description
0x00 UDP
0x01 TCP
Default
0x0
0x01
DX (Destination IP Address)
Sets or displays the destination IPaddress in IPv4 format for outgoing IPsocket mode data. For
broadcast, set DX to 255.255.255.255.
Range
A valid address in IPv4 format from 0.0.0.0 to 255.255.255.255.
Default
Default is 0.0.0.0.
C0 (Source Port)
Sets or displays the listening IP port number for TCP and UDP traffic. An incoming socket is
established only if the protocol (TCP or UDP) matches the protocol set by the IP (IP Protocol)
parameter.
Range
A hexadecimal value from 0x0 through 0xFFFF
Default
0x2616 (port 9750)
DY (Destination Port)
Sets or displays the outgoing IP port number for TCP and UDP socket connections. A socket to this IP
port is made to the destination IPv4 address defined by the DX (Destination IP Address) parameter
using the protocol defined by the IP (IP Protocol) parameter.
Range
A hexadecimal value from 0x0 through 0xFFFF.
Default
Default is hexadecimal 0x2616 (port 9750).
TM (TCP Client Connection Timeout)
Sets or displays the timeout in seconds for outgoing TCP socket connections when the XLR PRO is
acting as a TCP client. The connection is closed if no activity is detected during this timeout period.
XLR PRO Radio Frequency (RF) Modem User Guide
57
Page 58
AT commands Ethernet and IP socket mode commands
When set to 0x0, the connection is closed immediately after data is sent. The maximum timeout is 1
day.
Range
A hexadecimal value from 0x0 through 0x15180 (86400 seconds or 24 hours).
Default
0x3C (60 seconds).
TS (TCP Server Connection Timeout)
Sets or displays the timeout in seconds for incoming TCP socket connections when the XLR PRO is
acting as a TCP server. The connection is closed if no activity is detected during this timeout period.
When set to 0, the connection is closed immediately after data is sent. The maximum timeout is 1 day.
Range
A hexadecimal value from 0x0 through 0x15180 (86400 seconds or 24 hours).
Default
0x3C (60 seconds).
MA (IP Addressing Mode)
Sets or displays the IP addressing mode: DHCP or static. If you configure DHCP and no DHCP server is
detected, Auto-IP is used. See MY (XLR IP Address) for details.
Range
Value Description
0
1
Default
Default is 0 (DHCP addressing mode).
DHCP addressing mode.
Static addressing mode.
MY (XLR IP Address)
Sets or displays the IP address of the XLR PRO. If MA (IP Addressing Mode) is DHCP, this parameter is
read-only and an IP address is requested from an available DHCP server on the network.
If no DHCP server is detected on the network after 1 minute, then an Auto-IP address is assigned.
After an Auto-IP address is assigned, the XLR PRO requests a DHCP address assignment every 5
minutes.
The format of the Auto-IP address is as follows:
169.254.xxx.yyy
XLR PRO Radio Frequency (RF) Modem User Guide
58
Page 59
AT commands Ethernet and IP socket mode commands
xxx Second to last byte of the Ethernet MAC address.
yyy Last byte of the Ethernet MAC address.
If the Auto-IP address of the XLR PRO conflicts with another address on the network, then the Auto-IP
address is incremented by one until the conflict is resolved.
Auto-IP Example: Ethernet MAC = 0x409D5A329. The last two bytes are 0xA3 and 0x29. When
converted from hexadecimal to decimal, these bytes become 163 and 41. The Auto-IP address
assigned to this radio is 169.254.163.41.
Range
A valid address in IPv4 format from 0.0.0.0 to 255.255.255.255.
Default
N/A
MK (Subnet Mask)
Sets or displays the network subnet mask of the XLR PRO. If MA (IP Addressing Mode) is DHCP, this
parameter is read-only and the subnet mask is assigned by a DHCP server on the network. The subnet
mask that is assigned in Auto-IP is 255.255.0.0.
Range
A valid address in IPv4 format from 0.0.0.0 to 255.255.255.255.
Default
N/A
GW (Default Gateway Address)
Sets or displays the gateway address of the XLR PRO. If MA (IP Addressing Mode) is DHCP, this
parameter is read-only and the gateway address is assigned by a DHCP server on the network. The
gateway address that is assigned in Auto-IP is 0.0.0.0.
Range
A valid address in IPv4 format from 0.0.0.0 to 255.255.255.255.
Default
N/A
NS (DNS Address)
Sets or displays the IPv4 address of the domain name server for the XLR PRO.
Range
A valid address in IPv4 format from 0.0.0.0 to 255.255.255.255
Default
N/A
XLR PRO Radio Frequency (RF) Modem User Guide
59
Page 60
AT commands Device Cloud commands
%M (Ethernet MAC address)
Displays the Ethernet MAC Address assigned to the XLR PRO. This is a read-only parameter.
Range
A hexadecimal value from 0x0 through 0xFFFFFFFFFF.
Default
Default is a factory set value.
Device Cloud commands
DO (Device Cloud Enable)
Sets or displays whether Device Cloud support is enabled.
Range
Value Description
0x00 Disable Device Cloud support.
0x01 Enable Device Cloud support.
Default
0x01
KP (Device Description)
Sets or displays a user-defined description for the XLR PRO displayed in Device Cloud and web
configuration interfaces.
Range
From 0 through 31 ASCII characters
Default
One ASCII space character (0x20)
KC (Device Contact)
Sets or displays a user-defined contact for the XLR PRO displayed in Device Cloud and web
configuration interfaces.
Range
From 0 through 31 ASCII characters.
Default
One ASCII space character (0x20).
XLR PRO Radio Frequency (RF) Modem User Guide
60
Page 61
AT commands Device Cloud commands
KL (Device Location)
Sets or displays a user-defined physical location for the XLR PRO displayed in Device Cloud and web
configuration interfaces.
Range
From 0 through 31 ASCII characters.
Default
One ASCII space character (0x20).
LX (Latitude)
Sets or displays a user-defined GPS latitude coordinate for the XLR PRO displayed in Device Cloud and
web configuration interfaces. The latitude is a user-defined field—the XLR PRO does not have GPS
functionality.
Range
From 0 through 15 ASCII characters.
Default
Default is 0.000.
LY (Longitude)
Sets or displays a user-defined GPS longitude coordinate for the XLR PRO displayed in Device Cloud
and web configuration interfaces. The longitude is a user-defined field—the XLR PRO does not have
GPS functionality.
Range
From 0 through 31 ASCII characters.
Default
Default is -0.000.
EQ (Device Cloud FQDN)
Sets or display the fully qualified domain name of the Device Cloud server.
If NS (DNS Address) does not define a valid DNS server, enter an IP address for EQ.
Range
From 0 through 63 ASCII characters.
Default
devicecloud.digi.com
DI (Device Cloud Indicator)
Displays the current Device Cloud status for the XLR PRO.
XLR PRO Radio Frequency (RF) Modem User Guide
61
Page 62
AT commands Web configuration commands
Parameter range
Value Description
0
1
2
3
4
5
Default
N/A
Connected
Device Cloud not accessible
Device Cloud connection in progress
Disconnecting from Device Cloud
Not configured for Device Cloud support
DHCP is enabled and no DHCP server was found
Web configuration commands
HE (Web Configuration Enable)
Sets or displays whether XLR PRO web configuration (HTTP) is enabled.
Range
Value Description
0
1
Default
Default is 1 (web configuration is enabled).
Web configuration is disabled.
Web configuration is enabled.
HU (Web Configuration User Name)
Sets or displays the user name for web configuration (HTTP)access.
Range
From 0 to 63 ASCII characters.
Default
Default is admin.
HW (Web Configuration Password)
Sets the password for the web configuration (HTTP)access user name. This is a write-only parameter.
If you attempt to display/read the password, OK is returned.
XLR PRO Radio Frequency (RF) Modem User Guide
62
Page 63
AT commands Ethernet bridging commands
Range
From 0 to 63 ASCII characters.
Default
Default is password.
Ethernet bridging commands
BE (Ethernet RF Bridging Enable)
Sets or displays whether Ethernet RF bridging is enabled.
Range
Value Description
0 Ethernet RF bridging is disabled.
1 Ethernet RF bridging is enabled.
Default
0x0 (disabled).
BA (Bridge Destination MAC)
Sets or displays the destination RF MAC address to use for Ethernet RF Bridging. Set BA to 0xFFFF as
the broadcast address.
Range
A hexadecimal value from 0x0 to 0013A200FFFFFFFF.
Default
0xFFFF (broadcast address).
Command mode options
The following commands are Command mode option commands.
CC (Command Sequence Character)
Sets or displays the ASCIIsequence character to use for entering AT command mode. Repeating the
CC character three times causes the XLR PRO to enter AT command mode. The device responds with
OK\r when Command mode is successfully entered. The following commands are related to CC:
n Use GT (Guard Times) to define a guard time—the amount of time before and after entering a
command sequence—to guard against inadvertently entering Command mode.
n Use CT (Command Mode Timeout) to define the timeout for Command mode.
n Use CN (Exit Command mode) to immediately exit Command mode and return to idle mode.
XLR PRO Radio Frequency (RF) Modem User Guide
63
Page 64
AT commands Firmware commands
Parameter range
0 - 0xFF
Default
0x2B (ASCII + character)
CN (Exit Command mode)
Exits Command mode and returns the XLR PRO to Idle mode.
Parameter range
N/A
Default
N/A
CT (Command Mode Timeout)
Sets or reads the Command mode timeout parameter. If a device does not receive any valid
commands within this time period, it returns to Idle mode from Command mode.
Parameter range
2 - 0x1770 (x 100 ms)
Default
0x64 (10 seconds)
GT (Guard Times)
Set the required period of silence before and after the command sequence characters of the
Command mode sequence (GT + CC + GT). The period of silence prevents inadvertently entering
Command mode.
Parameter range
0 - 0xFFFF
Default
0x3E8 (one second)
Firmware commands
The following AT commands are firmware commands.
VB (Firmware Version)
Displays the XLR PRO firmware version.
Range
N/A
XLR PRO Radio Frequency (RF) Modem User Guide
64
Page 65
AT commands Firmware commands
Default
N/A
VR (XLR PRO Firmware Version)
Displays the XLR PROmodule firmware.
Range
N/A
Default
N/A
HV (Hardware Version)
Display the device's hardware version number.
Parameter range
N/A
Default
N/A
VH (XLR PRO Baseboard Hardware Version)
Displays the XLR PRO RF modem baseboard hardware version.
Range
N/A
Default
N/A
*C (compatibility)
Displays the compatibility setting for the XLR PRO.
Range
N/A
Default
N/A
DD (Device Type Identifier)
The Digi device type identifier value. Use this value to differentiate between multiple devices.
The XLR PRO product code upper word is 0x000E.
Parameter range
0 - 0xFFFFFFFF [read-only]
XLR PRO Radio Frequency (RF) Modem User Guide
65
Page 66
AT commands Firmware commands
Default
0xE001C
PN (Part Number)
Displays the manufacturing part number for the XLR PRO.
Range
N/A
Default
N/A
NP (Maximum Packet Payload Bytes)
Reads the maximum number of RF payload bytes that you can send in a transmission.
Parameter range
0 - 0xFFFF (bytes) [read-only]
Default
N/A
CK (Configuration CRC)
Displays the cyclic redundancy check (CRC) of the current AT command configuration settings.
This command allows you to detect an unexpected configuration change on a device.
After a firmware update this command may return a different value.
Parameter range
0 - 0xFFFF
Default
N/A
XLR PRO Radio Frequency (RF) Modem User Guide
66
Page 67
Operate in API mode
API mode overview 68
Use the AP command to set the operation mode 68
API frame format 68
API serial exchanges 70
Code to support future API frames 71
API frame types 72
XLR PRO Radio Frequency (RF) Modem User Guide
67
Page 68
Operate in API mode API mode overview
API mode overview
By default, the XLR PRO acts as a serial line replacement (Transparent operation), it queues all UART
data that it receive through the DI pin for RF transmission. When the device receives an RF packet, it
sends the data out the DO pin with no additional information.
The following behaviors are inherent to Transparent operation:
n If device parameter registers are to be set or queried, a special operation is required for
transitioning the device into Command Mode.
API operating mode is an alternative to transparent mode. API mode is a frame-based protocol that
allows you to direct data on a packet basis. It can be particularly useful in large networks where you
need to control the destination of individual data packets or when you need to know which node a
data packet was sent from. The device communicates UART data in packets, also known as API
frames. This mode allows for structured communications with serial devices. It is helpful in managing
larger networks and is more appropriate for performing tasks such as collecting data from multiple
locations or controlling multiple devices remotely.
Use the AP command to set the operation mode
Use AP (API Mode) to specify the operation mode:
AP=0: Transparent operating mode, UART serial line replacement with API modes
disabled. This is the default option.
AP=1: Enables API operation.
AP=2: Enables API operation with escaped characters.
The API data frame structure differs depending on what mode you choose.
API frame format
An API frame consists of the following:
n Start delimeter
n Length
n Frame data
n Checksum
API operation (AP parameter = 1)
This is the recommended API mode for most applications. The following table shows the data frame
structure when you enable this mode:
Frame fields Byte Description
Start delimiter 1 0x7E
Length 2 - 3 Most Significant Byte, Least Significant Byte
Frame data 4 - n API-specific structure
Checksum n + 1 1 byte
XLR PRO Radio Frequency (RF) Modem User Guide
68
Page 69
Operate in API mode API frame format
Any data received prior to the start delimiter is silently discarded. If the frame is not received correctly
or if the checksum fails, the XLR PRO replies with a radio status frame indicating the nature of the
failure.
API operation-with escaped characters (AP parameter = 2)
Setting API to 2 allows escaped control characters in the API frame. Due to its increased complexity,
we only recommend this API mode in specific circumstances. API 2 may help improve reliability if the
serial interface to the device is unstable or malformed frames are frequently being generated.
When operating in API 2, if an unescaped 0x7E byte is observed, it is treated as the start of a new API
frame and all data received prior to this delimiter is silently discarded. For more information on using
this API mode, refer to the following knowledge base article:
http://knowledge.digi.com/articles/Knowledge_Base_Article/Escaped-Characters-and-API-Mode-2
API escaped operating mode works similarly to API mode. The only difference is that when working in
API escaped mode, the software must escape any payload bytes that match API frame specific data,
such as the start-of-frame byte (0x7E). The following table shows the structure of an API frame with
escaped characters:
Frame fields Byte Description
Start delimiter 1 0x7E
Length 2 - 3 Most Significant Byte, Least Significant Byte Characters escaped if needed
Frame data 4 - n API-specific structure
Checksum n + 1 1 byte
Start delimiter field
This field indicates the beginning of a frame. It is always 0x7E. This allows the device to easily detect a
new incoming frame.
Escape characters
When sending or receiving a serial data frame, specific data values must be escaped (flagged) so they
do not interfere with the data frame sequencing. To escape an interfering data byte, insert 0x7D and
follow it with the byte to be escaped (XORed with 0x20).
The following data bytes need to be escaped:
0x7E (start delimiter)
0x7D (escape)
0x11 (XON)
0x13 (XOFF)
To escape a character:
1. Insert 0x7D (escape character).
2. Append it with the byte you want to escape, XORed with 0x20.
In API operating mode with escaped characters, the length field does not include any escape
characters in the frame and the firmware calculates the checksum with non-escaped data.
Example: Raw serial data frame (before escaping interfering bytes):
XLR PRO Radio Frequency (RF) Modem User Guide
69
Page 70
Operate in API mode API serial exchanges
0x7E 0x00 0x02 0x23 0x11 0xCB
0x11 must be escaped which results in the following frame:
0x7E 0x00 0x02 0x23 0x7D 0x31 0xCB
Note Note In the above example, the length of the raw data (excluding the checksum) is 0x0002 and
the checksum of the non-escaped data (excluding frame delimiter and length) is calculated as:
0xFF - (0x23 + 0x11) = (0xFF - 0x34) = 0xCB
Length field
The length field is a two-byte value that specifies the number of bytes contained in the frame data
field. It does not include the checksum field.
Frame data
This field contains the information that a device receives or will transmit. The structure of frame data
depends on the purpose of the API frame:
Frame data
Data
1 2 3 4 5 6 7 8 9 ... n n+1
0x7E MSB LSB Data
n Frame type is the API frame type identifier. It determines the type of API frame and indicates
how the Data field organizes the information.
n Data contains the data itself. This information and its order depend on the what type of frame
that the Frame type field defines.
Multi-byte values are sent big-endian.
Checksum field
To test data integrity, a checksum is calculated and verified on non-escaped data.
To calculate: Not including frame delimiters and length, add all bytes keeping only the lowest 8 bits of
the result and subtract the result from 0xFF.
To verify: Add all bytes (include checksum, but exclude the delimiter and length). If the checksum is
correct, the sum will equal 0xFF.
API serial exchanges
You can use the Frame ID field to assign an identifier to each outgoing API frame. This Frame ID, if
non-zero, can correlate between the outgoing frames and the associated responses.
AT command frames
The following image shows the API frame exchange that takes place at the serial interface when
sending an AT command request to read or set an XLR PRO parameter. To disable the response, set
the frame ID to 0 in the request.
XLR PRO Radio Frequency (RF) Modem User Guide
70
Page 71
Operate in API mode Code to support future API frames
Transmit and receive RF data
The following image shows the API exchanges that take place at the serial interface when sending RF
data to another device. The transmit status frame is always sent at the end of a data transmission
unless the frame ID is set to 0 in the TX request. If the packet cannot be delivered to the destination,
the transmit status frame indicates the cause of failure. The received data frame type (standard 0x90,
or explicit 0x91) is set by the AP command.
Remote AT commands
The following image shows the API frame exchanges that take place at the serial interface when
sending a remote AT command. A remote command response frame is not sent out the serial
interface if the remote device does not receive the remote command.
Code to support future API frames
If your software application supports the API, you should make provisions that allow for new API
frames in future firmware releases. For example, you can include the following section of code on a
host microprocessor that handles serial API frames that are sent out the device's DOUT pin:
void XBee_HandleRxAPIFrame(_apiFrameUnion *papiFrame){
switch(papiFrame->api_id){
case RX_RF_DATA_FRAME:
//process received RF data frame
break;
case RX_IO_SAMPLE_FRAME:
//process IO sample frame
break;
case NODE_IDENTIFICATION_FRAME:
//process node identification frame
break;
default:
XLR PRO Radio Frequency (RF) Modem User Guide
71
Page 72
Operate in API mode API frame types
//Discard any other API frame types that are not being used
break;
}
}
API frame types
The following sections document API frame types.
AT Command Frame - 0x08
Description
Use this frame to query or set device parameters on the local device. This API command applies
changes after running the command. You can query parameter values by sending the 0x08 AT
Command frame with no parameter value field (the two-byte AT command is immediately followed by
the frame checksum).
A 0x88 response frame is populated with the parameter value that is currently set on the device.
Format
The following table provides the contents of the frame. For details on frame structure, see API frame
format.
Frame
data
fields Offset Description
Frame
type
Frame ID 4
AT
command
Parameter
value
3 0x08
5-6 Command name: two ASCII characters that identify the AT command.
7-n
If present, indicates the requested parameter value to set the given register.
If no characters are present, it queries the register.
Example
The following example illustrates an AT Command frame when you modify the device's NH parameter
value.
Frame data fields Offset Example
Start delimiter 0 0x7E
Length MSB 1 0x00
LSB 2 0x04
XLR PRO Radio Frequency (RF) Modem User Guide
72
Page 73
Operate in API mode API frame types
Frame data fields Offset Example
Frame type 3 0x08
Frame ID 4 0x52
AT command 5 0x4E (N)
6 0x48 (H)
Parameter value (NH2 = two network hops) 7 0x02
Checksum 8 0x0D
XLR PRO Radio Frequency (RF) Modem User Guide
73
Page 74
Operate in API mode API frame types
AT Command - Queue Parameter Value frame - 0x09
Description
This frame allows you to query or set device parameters. In contrast to the AT Command (0x08)
frame, this frame queues new parameter values and does not apply them until you issue either:
n The AT Command (0x08) frame (for API type)
n The AC command
When querying parameter values, the 0x09 frame behaves identically to the 0x08 frame. The device
returns register queries immediately and not does not queue them. The response for this command is
also an AT Command Response frame (0x88).
Format
The following table provides the contents of the frame. For details on frame structure, see API frame
format.
Frame data
fields Offset Description
Frame type 3 0x09
Frame ID 4
AT command
Parametervalue
Identifies the data frame for the host to correlate with a subsequent
ACK. If set to 0, the device does not send a response.
5-6 Command name: two ASCII characters that identify the AT command.
7-n If present, indicates the requested parameter value to set the given
register. If no characters are present, queries the register.
XLR PRO Radio Frequency (RF) Modem User Guide
74
Page 75
Operate in API mode API frame types
Transmit Request frame - 0x10
Description
This frame causes the device to send payload data as an RF packet to a specific destination.
n For broadcast transmissions, set the 64-bit destination address to 0x000000000000FFFF .
n For unicast transmissions, set the 64 bit address field to the address of the desired destination
node.
n Set the reserved field to 0xFFFE.
n Query the NP command to read the maximum number of payload bytes.
You can set the broadcast radius from 0 up to NH. If set to 0, the value of NH specifies the broadcast
radius (recommended). This parameter is only used for broadcast transmissions.
You can read the maximum number of payload bytes with the NP command.
Note Using source routing reduces the RF payload by two bytes per intermediate hop in the source
route.
Format
The following table provides the contents of the frame. For details on frame structure, see API frame
format.
Frame data
fields Offset Description
Frame type 3 0x10
Frame ID 4
64-bit
destination
address
Reserved 13-14
Broadcast
radius
Transmit
options
RF data
5-12
15
16
17-n
Identifies the data frame for the host to correlate with a subsequent ACK.
If set to 0, the device does not send a response.
MSB first, LSB last. Set to the 64-bit address of the destination device.
Broadcast = 0x000000000000FFFF
Set to 0xFFFE.
Sets the maximum number of hops a broadcast transmission can occur. If
set to 0, the broadcast radius is set to the maximum hops value.
Up to NP bytes per packet. Sent to the destination device.
Example
The example shows how to send a transmission to a device if you disable escaping (AP = 1), with
destination address 0x0013A200 400A0127, and payload “TxData0A”.
XLR PRO Radio Frequency (RF) Modem User Guide
75
Page 76
Operate in API mode API frame types
Frame data fields Offset Example
Start delimiter 0 0x7E
Length MSB 1 0x00
LSB 2 0x16
Frame type 3 0x10
Frame ID 4 0x01
64-bit destination
address
Broadcast radius 15 0x00
Options 16 0x00
RF data 17 0x54
MSB 5 0x00
6 0x13
7 0xA2
8 0x00
9 0x40
10 0x0A
11 0x01
LSB 12 0x27
18 0x78
19 0x44
20 0x61
21 0x74
Checksum 25 0x13
If you enable escaping (AP = 2), the frame should look like:
0x7E 0x00 0x16 0x10 0x01 0x00 0x7D 0x33 0xA2 0x00 0x40 0x0A 0x01 0x27 0xFF 0xFE 0x00
0x00 0x54 0x78 0x44 0x61 0x74 0x61 0x30 0x41 0x7D 0x33
The device calculates the checksum (on all non-escaped bytes) as [0xFF - (sum of all bytes from API
frame type through data payload)].
XLR PRO Radio Frequency (RF) Modem User Guide
22 0x61
23 0x30
24 0x41
76
Page 77
Operate in API mode API frame types
Explicit Addressing Command frame - 0x11
Description
This frame is similar to Transmit Request (0x10), but it also requires you to specify the applicationlayer addressing fields: endpoints, cluster ID, and profile ID.
This frame causes the device to send payload data as an RF packet to a specific destination, using
specific source and destination endpoints, cluster ID, and profile ID.
n For broadcast transmissions, set the 64-bit destination address to 0x000000000000FFFF .
n For unicast transmissions, set the 64 bit address field to the address of the desired destination
node.
n Set the reserved field to 0xFFFE.
Query the NP command to read the maximum number of payload bytes. For more information, see
Firmware commands.
You can set the broadcast radius from 0 up to NH to 0xFF. If set to 0, the value of NH specifies the
broadcast radius (recommended). This parameter is only used for directed broadcast transmissions
(transmit options = 0x80).
Format
The following table provides the contents of the frame. For details on frame structure, see API frame
format.
Frame data
fields Offset Description
Frame type 3 0x11
Frame ID 4
64-bit
destination
address
Reserved 13-14 Set to 0xFFFE.
Source
endpoint
Destination
endpoint
Cluster ID
Profile ID 19-20 The Profile ID that the host uses in the transmission.
Broadcast
radius
5-12 MSB first, LSB last. Set to the 64-bit address of the destination device.
15 Source endpoint for the transmission.
16
17-18 The Cluster ID that the host uses in the transmission.
21
Identifies the data frame for the host to correlate with a subsequent ACK
(0x8B). If set to 0, the device does not send a response.
Broadcast = 0x000000000000FFFF
Destination endpoint for the transmission.
Sets the maximum number of hops a broadcast transmission can traverse.
If set to 0, the transmission radius set to the network maximum hops value.
XLR PRO Radio Frequency (RF) Modem User Guide
77
Page 78
Operate in API mode API frame types
Frame data
fields Offset Description
Transmission
22
options
Data payload 23-n
Up to NP bytes per packet. Sent to the destination device.
Transmit Options bit field
Bit Meaning Description
0 Disable ACK Disable acknowledgments on all unicasts
1 Disable RD Disable Route Discovery on all DigiMesh unicasts
2 NACK Enable NACK messages on all DigiMesh API packets
3 Trace Route Enable a Trace Route on all DigiMesh API packets
4 Reserved <set this bit to 0>
5 Reserved <set this bit to 0>
6, 7 Delivery method
Set all other bits to 0.
b’00 = <invalid option>
b’01 - Point-multipoint (0x40)
b'10 = Directed Broadcast (0x80)
Example
The following example sends a data transmission to a device with:
n 64-bit address: 0x0013A200 01238400
n Source endpoint: 0xE8
n Destination endpoint: 0xE8
n Cluster ID: 0x11
n Profile ID: 0xC105
n Payload: TxData
Frame data fields Offset Example
Start delimiter 0 0x7E
Length MSB 1 0x00
LSB 2 0x1A
Frame type 3 0x11
Frame ID 4 0x01
XLR PRO Radio Frequency (RF) Modem User Guide
78
Page 79
Operate in API mode API frame types
Frame data fields Offset Example
64-bit destination address MSB 5 0x00
6 0x13
7 0xA2
8 0x00
9 0x01
10 0x23
11 0x84
LSB12 0x00
Reserved
Source endpoint 15 0xE8
Destination endpoint 16 0xE8
Cluster ID 17 0x00
Profile ID 19 0xC1
Broadcast radius 21 0x00
Transmit options 22 0x00
Data payload 23 0x54
13
14
18 0x11
20 0x05
24 0x78
25 0x44
26 0x61
27 0x74
0xFF
0xFE
Checksum 29 0xDD
XLR PRO Radio Frequency (RF) Modem User Guide
28 0x61
79
Page 80
Operate in API mode API frame types
Remote AT Command Request frame - 0x17
Description
Used to query or set device parameters on a remote device. For parameter changes on the remote
device to take effect, you must apply changes, either by setting the Apply Changes options bit, or by
sending an AC command to the remote.
Format
The following table provides the contents of the frame. For details on frame structure, see API frame
format.
Frame data
fields Offset Description
Frame type 3 0x17
Frame ID 4
64-bit
destination
address
Reserved 13-14
Remote
command
options
AT command
Command
parameter
5-12
15
16-17
18-n If present, indicates the parameter value you request for a given register.
Identifies the data frame for the host to correlate with a subsequent ACK
(0x97). If set to 0, the device does not send a response.
MSB first, LSB last. Set to the 64-bit address of the destination device.
0x02 = Apply changes on remote. If you do not set this, you must send the
ACcommand for changes to take effect.
Set all other bits to 0.
Command name: two ASCII characters that identify the command.
If no characters are present, it queries the register.
Example
The following example sends a remote command to:
In this example, the 64-bit address of the remote device is 0x0013A200 40401122.
Frame data fields Offset Example
Start delimiter 0 0x7E
Length MSB 1 0x00
Frame type
Frame ID 4 0x01
XLR PRO Radio Frequency (RF) Modem User Guide
LSB 2 0x10
3 0x17
80
Page 81
Operate in API mode API frame types
Frame data fields Offset Example
64-bit destination address MSB 5 0x00
6 0x13
7 0xA2
8 0x00
9 0x40
10 0x40
11 0x11
LSB 12 0x22
Reserved
Remote command options 15 0x02 (apply changes)
AT command 16 0x42 (B)
Command parameter 18 0x01
Checksum 19 0xF5
13
14
17 0x48 (H)
0xFF
0xFE
XLR PRO Radio Frequency (RF) Modem User Guide
81
Page 82
Operate in API mode API frame types
AT Command Response frame - 0x88
Description
A device sends this frame in response to an AT Command (0x08 or 0x09) frame. Some commands send
back multiple frames; for example, the ND command.
Format
The following table provides the contents of the frame. For details on frame structure, see API frame
format.
Frame
data fields Offset Description
Frame type 3 0x88
Frame ID 4
AT
command
Command
status
Command
data
5-6 Command name: two ASCIIcharacters that identify the command.
7
8-n The register data in binary format. If the host sets the register, the device
Identifies the data frame for the host to correlate with a subsequent ACK. If
set to 0, the device does not send a response.
0 = OK
1 = ERROR
2 = Invalid command
3 = Invalid parameter
does not return this field.
Example
If you change the BD parameter on a local device with a frame ID of 0x01, and the parameter is valid,
the user receives the following response.
Frame data fields Offset Example
Start delimiter 0 0x7E
Length MSB 1 0x00
LSB 2 0x05
Frame type 3 0x88
Frame ID 4 0x01
AT command 5 0x42 (B)
Command status 7 0x00
XLR PRO Radio Frequency (RF) Modem User Guide
6 0x44 (D)
82
Page 83
Operate in API mode API frame types
Frame data fields Offset Example
Command data
Checksum 8 0xF0
XLR PRO Radio Frequency (RF) Modem User Guide
83
Page 84
Operate in API mode API frame types
Modem Status frame - 0x8A
Description
Devices send the status messages in this frame in response to specific conditions.
Format
The following table provides the contents of the frame. For details on frame structure, see API frame
format.
Frame data fields Offset Description
Frame type 3 0x8A
Status 4
0x00 Hardware reset
0x01 Watchdog timer reset
Example
When a device powers up, it returns the following API frame.
Frame data fields Offset Example
Start delimiter 0 0x7E
Length MSB 1 0x00
LSB 2 LSB 2 0x02
Frame type 3 0x8A
Status 4 0x00
Checksum 5 0x75
XLR PRO Radio Frequency (RF) Modem User Guide
84
Page 85
Operate in API mode API frame types
Transmit Status frame - 0x8B
Description
When a Transmit Request (0x10, 0x11) completes, the device sends a Transmit Status message out of
the serial interface. This message indicates if the Transmit Request was successful or if it failed.
Format
The following table provides the contents of the frame. For details on frame structure, see API frame
format.
Frame data
fields Offset Description
Frame type 3 0x8B
Frame ID 4 Identifies the serial interface data frame being reported. If Frame ID = 0 in
the associated request frame, no response frame is delivered.
Reserved 5-6 Set to 0xFFFE.
Transmitretry
count
Delivery
status
Discovery
status
7
8
9
The number of application transmission retries that occur.
0x00 = No discovery overhead
0x02 = Route discovery
Example
In the following example, the destination device reports a successful unicast data transmission
successful and a route discovery occurred. The outgoing Transmit Request that this response frame
uses Frame ID of 0x47.
Frame Fields Offset Example
Start delimiter 0 0x7E
Length MSB 1 0x00
LSB 2 0x07
Frame type 3 0x8B
Frame ID 4 0x47
Reserved 5 0xFF
Transmit retry count 7 0x00
XLR PRO Radio Frequency (RF) Modem User Guide
6 0xFE
85
Page 86
Operate in API mode API frame types
Frame Fields Offset Example
Delivery status 8 0x00
Discovery status 9 0x02
Checksum 10 0x2E
XLR PRO Radio Frequency (RF) Modem User Guide
86
Page 87
Operate in API mode API frame types
Receive Packet frame - 0x90
Description
When a device configured with a standard API Rx Indicator (AO = 0) receives an RF data packet, it
sends it out the serial interface using this message type.
Format
The following table provides the contents of the frame. For details on frame structure, see API frame
format.
Frame data fields Offset Description
Frame type 3 0x90
64-bit source address 4-11
Reserved
Receive options
Received data
12-13 Reserved.
14
15-n The RF data the device receives.
The sender's 64-bit address. MSB first, LSB last.
Bit field:
bit 0 = Packet acknowledged
bit 1 = Packet was a broadcast packet
bits 6 and 7:
b’01 = Point-Multipoint
b’10 = Repeater mode (directed broadcast)
Ignore all other bits.
Example
In the following example, a device with a 64-bit address of 0x0013A200 40522BAA sends a unicast
data transmission to a remote device with payload RxData. If AO=0 on the receiving device, it sends
the following frame out its serial interface.
Frame data fields Offset Example
Start delimiter 0 0x7E
Length MSB 1 0x00
Frame type
XLR PRO Radio Frequency (RF) Modem User Guide
LSB 2 0x12
3 0x90
87
Page 88
Operate in API mode API frame types
Frame data fields Offset Example
MSB 4 0x00
64-bit source address
5 0x13
6 0xA2
7 0x00
8 0x40
9 0x52
10 0x2B
LSB 11 0xAA
Reserved
Receive options 14 0x01
Received data 15 0x52
Checksum 21 0x11
12
13
16 0x78
17 0x44
18 0x61
19 0x74
20 0x61
0xFF
0xFE
XLR PRO Radio Frequency (RF) Modem User Guide
88
Page 89
Operate in API mode API frame types
Explicit Rx Indicator frame - 0x91
Description
When a device configured with explicit API Rx Indicator (AO = 1) receives an RF packet, it sends it out
the serial interface using this message type.
Format
The following table provides the contents of the frame. For details on frame structure, see API frame
format.
Frame data fields Offset Description
Frame type 3 0x91
64-bit source address
Reserved
Source endpoint
Destination endpoint
Cluster ID
Profile ID
Receive options
Received data
4-11
12-13 Reserved.
14 Endpoint of the source that initiates transmission.
15
16-17 The Cluster ID where the frame is addressed.
18-19 The Profile ID where the fame is addressed.
14
21-n Received RF data.
MSB first, LSB last. The sender's 64-bit address.
Endpoint of the destination where the message is addressed.
Bit field:
bit 0 = Packet acknowledged
bit 1 = Packet was a broadcast packet
bits 6 and 7:
b’01 = Point-Multipoint
b’10 = Repeater mode (directed broadcast)
Ignore all other bits.
Example
In the following example, a device with a 64-bit address of 0x0013A200 40522BAA sends a broadcast
data transmission to a remote device with payload RxData.
If a device sends the transmission:
n With source and destination endpoints of 0xE0
n Cluster ID = 0x2211
n Profile ID = 0xC105
If AO = 1 on the receiving device, it sends the following frame out its serial interface.
XLR PRO Radio Frequency (RF) Modem User Guide
89
Page 90
Operate in API mode API frame types
Frame data fields Offset Example
Start delimiter 0 0x7E
Length MSB 1 0x00
LSB 2 0x18
Frame type 3 0x91
64-bit source address MSB 4 0x00
5 0x13
6 0xA2
7 0x00
8 0x40
9 0x52
10 0x2B
LSB 11 0xAA
Reserved
Source endpoint 14 0xE0
Destination endpoint 15 0xE0
Cluster ID 16 0x22
Profile ID 18 0xC1
Receive options 20 0x02
Received data 21 0x52
12
13
17 0x11
19 0x05
22 0x78
23 0x44
24 0x61
25 0x74
26 0x61
0xFF
0xFE
XLR PRO Radio Frequency (RF) Modem User Guide
90
Page 91
Operate in API mode API frame types
Remote Command Response frame - 0x97
Description
If a device receives this frame in response to a Remote Command Request (0x17) frame, the device
sends an AT Command Response (0x97) frame out the serial interface.
Some commands, such as the ND command, may send back multiple frames.
Format
The following table provides the contents of the frame. For details on frame structure, see API frame
format.
Frame data
fields Offset Description
Frame type 3 0x97
Frame ID
64-bit source
(remote)
address
Reserved
AT commands
Command
status
Command data
4
5-12 The address of the remote device returning this response.
13-14
15-16
17
18-n The value of the requested register.
This is the same value passed in to the request. If Frame ID = 0 in the
associated request frame the device does not deliver a response frame.
Reserved.
The name of the command.
0 = OK
1 = ERROR
2 = Invalid Command
3 = Invalid Parameter
Example
If a device sends a remote command to a remote device with 64-bit address 0x0013A200 40522BAA to
query the SL command, and if the frame ID = 0x55, the response would look like the following
example.
Frame data fields Offset Example
Start delimiter 0 0x7E
Length MSB 1 0x00
Frame type 3 0x97
Frame ID 4 0x55
XLR PRO Radio Frequency (RF) Modem User Guide
LSB 2 0x13
91
Page 92
Operate in API mode API frame types
Frame data fields Offset Example
64-bit source (remote) address MSB 5 0x00
6 0x13
7 0xA2
8 0x00
9 0x40
10 0x52
11 0x2B
LSB 12 0xAA
Reserved
AT commands 15 0x53
Command status 17 0x00
Command data 18 0x40
Checksum 22 0xF4
13
14 0xFE
16 0x4C
19 0x52
20 0x2B
21 0xAA
0xFF
XLR PRO Radio Frequency (RF) Modem User Guide
92
Page 93
Advanced application features
Network commissioning and diagnostics 94
Local configuration 94
Remote configuration 94
Test links in a network 95
Test links between adjacent devices 96
General Purpose Flash Memory 98
Over-the-air (OTA) firmware updates 110
XLR PRO Radio Frequency (RF) Modem User Guide
93
Page 94
Advanced application features Network commissioning and diagnostics
Network commissioning and diagnostics
We call the process of discovering and configuring devices in a network for operation, "network
commissioning." Devices include several device discovery and configuration features. In addition to
configuring devices, you must develop a strategy to place devices to ensure reliable routes. To
accommodate these requirements, modules include features to aid in placing devices, configuring
devices, and network diagnostics.
Local configuration
You can configure devices locally using serial commands in Transparent or API mode, or remotely
using remote API commands. Devices that are in API mode can send configuration commands to set
or read the configuration settings of any device in the network.
Remote configuration
When you do not have access to the device's serial port, you can use a separate device in API mode to
remotely configure it. To remotely configure devices, use the following steps.
Send a remote command
To send a remote command, populate the Remote Command Request (0x17) APIframe with:
1. The 64-bit address of the remote device.
2. The correct command options value.
3. Optionally, the command and parameter data.
4. If you want a command response, set the Frame ID field to a non-zero value.
The firmware only supports unicasts of remote commands. You cannot broadcast remote commands.
XCTU has a Frames Generator tool that can assist you with building and sending a remote AT frame;
see:http://www.digi.com/resources/documentation/digidocs/90001458-13/default.htm#reference/r_
frames_generator_tool.htm
Apply changes on remote devices
When you use remote commands to change the command parameter settings on a remote device,
you must apply the parameter changes or they do not take effect. For example, if you change the BD
parameter, the actual serial interface rate does not change on the remote device until you apply the
changes. You can apply the changes using remote commands in one of three ways:
1. Set the apply changes option bit in the API frame.
2. Send an AC command to the remote device.
3. Send the WR command followed by the FR command to the remote device to save the changes
and reset the device.
Remote command response
If a local device sends a command request to a remote device, and the API frame ID is non-zero, the
remote device sends a remote command response transmission back to the local device.
When the local device receives a remote command response transmission, it sends a remote
command response API frame out its UART. The remote command response indicates:
XLR PRO Radio Frequency (RF) Modem User Guide
94
Page 95
Advanced application features Test links in a network
1. The status of the command, which is either success or the reason for failure.
2. In the case of a command query, it includes the register value.
The device that sends a remote command does not receive a remote command response frame if:
1. It could not reach the destination device.
2. You set the frame ID to 0 in the remote command request.
Test links in a network
For a network installation to be successful, you must determine where to place individual devices in
order to establish reliable links throughout a network.
To measure the performance of a network, you can send unicast data through the network from one
device to another to determine the success rate of several transmissions. To simplify link testing, the
devices support a loopback cluster ID (0x12) on the data endpoint (0xE8). The cluster ID on the data
endpoint sends any data transmitted to it back to the sender.
The following figure demonstrates how you can use the loopback cluster ID and data endpoint to
measure the link quality in a mesh network.
The configuration steps for sending data to the loopback cluster ID depend on what mode the device
is in. For details on setting the mode, see AP (API Mode). The following sections list the steps based on
the device's mode.
Transparent operating mode configuration (AP = 0)
To send data to the loopback cluster ID on the data endpoint of a remote device:
1. Set the CI command to 0x12.
2. Set the DH and DL commands to the address of the remote device.
After exiting Command mode, the device transmits any serial characters it received to the remote
device, which returns those characters to the sending device.
API operating mode configuration (AP = 1 or AP = 2)
Send an Explicit Addressing Command frame (0x11) using 0x12 as the cluster ID and 0xE8 as both the
source and destination endpoint.
The remote device echoes back the data packets it receives to the sending device.
XLR PRO Radio Frequency (RF) Modem User Guide
95
Page 96
Advanced application features Test links between adjacent devices
Test links between adjacent devices
It often helps to test the quality of a link between two adjacent modules in a network. You can use the
Test Link Request Cluster ID to send a number of test packets between any two devices in a network.
To clarify the example, we refer to "device A" and "device B" in this section.
To request that device B perform a link test against device A:
1. Use device A in API mode (AP= 1) to send an Explicit Addressing Command (0x11) frame to
device B.
2. Address the frame to the Test Link Request Cluster ID (0x0014) and destination endpoint: 0xE6.
3. Include a 12-byte payload in the Explicit Addressing Command frame with the following format:
Number of
bytes Field name Description
8 Destination
address
2 Payload size The size of the test packet. Use the NPcommand to query the
2 Iterations The number of packets to send. This must be a number between 1 and
4. Device B should transmit test link packets.
5. When device B completes transmitting the test link packets, it sends the following data packet
to device A's Test Link Result Cluster (0x0094) on endpoint (0xE6).
6. Device A outputs the following information as an API Explicit RX Indicator (0x91) frame:
Number of
bytes Field name Description
8
2 Payload size The size of the test packet device A sent to test the link.
2 Iterations The number of packets that device A sent.
Destination
address
The address the device uses to test its link. For this example, use the
device A address.
maximum payload size for the device.
4000.
The address the device used to test its link.
2 Success The number of packets that were successfully
2 Retries The number of MAC retries used to transfer all the packets.
1 Result 0x00 - the command was successful.
1 RR The maximum number of MAC retries allowed.
1 maxRSSI The strongest RSSI reading observed during the test.
1 minRSSI The weakest RSSI reading observed during the test.
1 avgRSSI The average RSSI reading observed during the test.
XLR PRO Radio Frequency (RF) Modem User Guide
acknowledged.
0x03 - invalid parameter used.
96
Page 97
Advanced application features Test links between adjacent devices
Example
Suppose that you want to test the link between device A (SH/SL = 0x0013A200 40521234) and device
B (SH/SL=0x0013A 200 4052ABCD) by transmitting 1000 40-byte packets:
Send the following API packet to the serial interface of device A.
In the following example packet, whitespace marks fields, bold text is the payload portion of the
packet:
7E 0020 11 01 0013A20040521234 FFFE E6 E6 0014 C105 00 00 0013A2004052ABCD 0028 03E8 EB
When the test is finished, the following API frame may be received:
7E 0027 91 0013A20040521234 FFFE E6 E6 0094 C105 00 0013A2004052ABCD 0028 03E8 03E7 0064
00 0A 50 53 52 9F
This means:
n 999 out of 1000 packets were successful.
n The device made 100 retries.
n RR = 10.
n maxRSSI = -80 dBm.
n minRSSI = -83 dBm.
n avgRSSI = -82 dBm.
If the Result field does not equal zero, an error has occurred. Ignore the other fields in the packet.
If the Success field equals zero, ignore the RSSI fields.
The device that sends the request for initiating the Test link and outputs the result does not need to
be the sender or receiver of the test. It is possible for a third node, "device C", to request device A to
perform a test link against device B and send the results back to device C to be output. It is also
possible for device B to request device A to perform the previously mentioned test. In other words, the
frames can be sent by either device A, device B or device C and in all cases the test is the same: device
A sends data to device B and reports the results.
RSSI indicators
The received signal strength indicator (RSSI) measures the amount of power present in a radio signal.
It is an approximate value for signal strength received on an antenna.
You can use the DB command to measure the RSSI on a device. DB returns the RSSI value measured in
-dBm of the last packet the device received. This number can be misleading in multi-hop DigiMesh
networks. The DB value only indicates the received signal strength of the last hop. If a transmission
spans multiple hops, the DB value provides no indication of the overall transmission path, or the
quality of the worst link, it only indicates the quality of the last link.
To determine the DB value in hardware:
1. Use the RSSI module pin (pin 36). When the device receives data, it sets the RSSI PWM duty
cycle to a value based on the RSSI of the packet it receives.
This value only indicates the quality of the last hop of a multi-hop transmission. You could connect this
pin to an LED to indicate if the link is stable or not.
XLR PRO Radio Frequency (RF) Modem User Guide
97
Page 98
Advanced application features General Purpose Flash Memory
Discover devices
Discover all the devices on a network
You can use the ND (Network Discovery)command to discover all devices on a network. When you
send the ND command:
1. The device sends a broadcast ND command through the network.
2. All devices that receive the command send a response that includes their addressing
information, node identifier string and other relevant information. For more information on the
node identifier string, see NI (Node Identifier).
ND is useful for generating a list of all device addresses in a network.
When a device receives the network discovery command, it waits a random time before sending its
own response. You can use the NT command to set the maximum time delay on the device that you
use to send the ND command.
n The device that sends the ND includes its NT setting in the transmission to provide a delay
window for all devices in the network.
n The default NT value is 0x82 (13 seconds).
Discover devices within RF range
n You can use the FN (Find Neighbors) command to discover the devices that are immediate
neighbors (within RF range) of a particular device.
n FN is useful in determining network topology and determining possible routes.
You can send FN locally on a device in Command mode or you can use a local AT Command (0x08)
frame.
To use FN remotely, send the target node a Remote AT Command frame (0x17) using FN as the name
of the AT command.
The device you use to send FN transmits a zero-hop broadcast to all of its immediate neighbors. All of
the devices that receive this broadcast send an RF packet to the device that transmitted the FN
command. If you sent FN remotely, the target devices respond directly to the device that sent the FN
command. The device that sends FNoutputs a response packet in the same format as an AT
Command Response (0x88) frame.
General Purpose Flash Memory
XLR PROs provide 119 512-byte blocks of flash memory that an application can read and write to. This
memory provides a non-volatile data storage area that an application uses for many purposes. Some
common uses of this data storage include:
n Storing logged sensor data
n Buffering firmware update data for a host microcontroller
n Storing and retrieving data tables needed for calculations performed by a host microcontroller
The General Purpose Memory (GPM) is also used to store a firmware update file for over-the-air
firmware updates of the device itself.
XLR PRO Radio Frequency (RF) Modem User Guide
98
Page 99
Advanced application features General Purpose Flash Memory
Access General Purpose Flash Memory
To access the GPM of a target node locally or over-the-air, send commands to the MEMORY_ACCESS
cluster ID (0x23) on the DIGI_DEVICE endpoint (0xE6) of the target node using explicit API frames. For
a description of Explicit API frames, see Operate in API mode.
To issue a GPM command, format the payload of an explicit API frame as follows:
Byte offset
in payload
0 1 GPM_CMD_ID Specific GPM commands are described
1 1 GPM_OPTIONS Command-specific options.
2 2* GPM_BLOCK_NUM The block number addressed in the
4 2* GPM_START_INDEX The byte index within the addressed
6 2* GPM_NUM_BYTES The number of bytes in the GPM_DATA
8 varies GPM_DATA
* Specify multi-byte parameters with big-endian byte ordering.
When a device sends a GPM command to another device via a unicast, the receiving device sends a
unicast response back to the requesting device's source endpoint specified in the request packet. It
does not send a response for broadcast requests. If the source endpoint is set to the DIGI_DEVICE
endpoint (0xE6) or Explicit API mode is enabled on the requesting device, then the requesting node
outputs a GPM response as an explicit API RX indicator frame (assuming it has API mode enabled).
The format of the response is similar to the request packet:
Number of
bytes Field name General field description
in detail in the topics that follow.
GPM.
GPM block.
field, or in the case of a READ, the
number of bytes requested.
Byte offset in
payload
0 1 GPM_CMD_ID This field is the same as the
1 1 GPM_STATUS Status indicating whether the
2 2* GPM_BLOCK_NUM The block number addressed in
4 2* GPM_START_INDEX The byte index within the
6 2* GPM_NUM_BYTES The number of bytes in the GPM_
8 varies GPM_DATA
XLR PRO Radio Frequency (RF) Modem User Guide
Number of
bytes Fieldname General field description
request field.
command was successful.
the GPM.
addressed GPM block.
DATA field.
99
Page 100
Advanced application features General Purpose Flash Memory
Byte offset in
payload
* Specify multi-byte parameters with big-endian byte ordering.
Number of
bytes Fieldname General field description
XLR PRO Radio Frequency (RF) Modem User Guide
100
Loading...