A Practical Guide to Using BLE on Digi XBee 3: Application Note

Digi XBee® 3 modems feature Bluetooth® Low Energy which provides numerous possibilities for wireless applications enabled with cellular, Zigbee®, DigiMesh® or 802.15.4. The addition of BLE enhances the Digi XBee 3 line with a variety of use cases for both new and existing applications.

Here’s a list of some of the additional things that you can do with Digi XBee 3 and BLE:

Securely configure an XBee 3 from a phone or other BLE capable device
Send advertisements or beacons (e.g. iBeacon) from the XBee 3
Scan advertisements or beacons from neighboring devices
Discover application services from neighboring devices
Connect to a BLE sensor
Send custom configuration or data to a host processor using user data relay frames
Securely configure one XBee 3 from another XBee 3
Securely send data between XBee 3 modems
Connect and then use BLE pairing to access GATT services
Bond to a BLE device to avoid having to repeat pairing

In order to utilize BLE on the Digi XBee 3, the XBee firmware provides the following mechanisms:

AT commands (enable, XBee API security configuration, custom advertisement name)
User data relay frames (BLE to serial or MicroPython)
MicroPython digi.ble built-in module

The following table maps common use cases and the different mechanisms that support them. Note that most of these mechanisms are not mutually exclusive and can be combined to enhance your applications:

Use Case	MicroPython	AT Commands	Use Data Relay Frames with Host Processor
AT Configuration	✓	✓	✓
XBee 3 to XBee 3 configuration	✓		✓
XBee 3 to XBee 3 data	✓		✓
Enable/disable	✓	✓
Scan and send advertisements	✓	✓
Send custom advertisements	✓	*
Receive and handle custom advertisements/beacons	✓
GATT service discovery	✓
Connect to GATT service	✓
RX/TX to GATT service	✓
Pairing and bonding	✓

* Customization limited to device name.

AT Configuration

Digi XBee 3 provides some basic AT commands for simple BLE configuration. With AT commands, you can enable or disable BLE, modify the advertised BLE device name, and enable the XBee BLE GATT service for XBee configuration and data communication. With the BT command, you enable BLE as XBee 3 devices ship with BLE disabled. The BI command customizes the name advertised in the BLE payload. There are also multiple AT commands that configure the Digi XBee 3 GATT service to enhance application security for both configuration and data transfer over BLE.

This article requires that the audience be fairly familiar with BLE already as it discusses BLE context like GATT, beacons, advertising, pairing and bonding without a glossary or definition of the concepts. See the Glossary later in this article for some basic definitions.

XBee GATT Service Authentication and Security

The enhanced application security goes beyond the security provided by standard BLE pairing and adds an additional layer to protect configuration of the XBee and data communications. You secure each XBee 3 device’s BLE connections with a zero-knowledge proof based algorithm and key to protect against compromise of the device password, meaning that the password will not be stored on the XBee in order to authenticate and secure communications to it over BLE. Connections to the XBee 3’s GATT service for either configuration or data transfer require the configuration of the XBee’s BLE authentication parameters. You should configure these parameters when integrating the XBee into your application in your manufacturing process.

Digi XCTU® provides a wizard to ease configuration of the these parameters given you choose and enter a secure password. Although the compromise of an XBee device will not reveal the password since the password is not stored, Digi still recommends that the best practice of selecting a unique password for each XBee to ensure additional protection against attackers who might gain the password through other means.

An authorized client that knows the XBee’s password issues an unlock API frame in order to authenticate the connection with the XBee. The successful negotiation of the unlock sequence also establishes session keys to ensure confidentiality of the data transferred between the client and the XBee service. The authenticated client gains access to both configuration and data transfer via sending XBee API frames over BLE.

XBee GATT service and User Data Relay API Frames

After configuring BLE authentication, a BLE client such as another XBee or a smartphone app can authenticate and securely connect to the XBee 3’s GATT service. The XBee API GATT service allows customers to configure the XBee and send and receive data to either an external host processor over serial or internally to the XBee’s MicroPython program.

More specifically, the GATT service acts as a sort of virtual serial port with two attributes: one to send data and a second to receive data over BLE. API frames can be used to configure the XBee using AT commands or send data using User Data Relay Frames. The User Data Relay Frame sent over BLE to the GATT service can be directed to a host processor over the XBee’s primary serial port (pins 2 and 3) or to MicroPython.

Likewise, the host processor connected to the serial port or MicroPython program can initiate a User Data Relay Frame to be sent from the GATT transmit attribute. This XBee GATT service allows any authorized client to connect to and configure or send and receive data to your host processor’s application.

Using a host processor and MicroPython in combination can also be a power tool to provide additional business logic to your application since the user data relay frame can be used to broker data between BLE, your application processor and your MicroPython program in the XBee.

MicroPython and digi.ble Module

For more advanced use cases, the built-in MicroPython module digi.ble provides the most powerful and flexible features for BLE. MicroPython gives customers the ability to provide additional functionality as well as offload some business logic within the XBee 3 itself. MicroPython with BLE allows you to:

Scan for specific devices or device types
Parse and respond to advertisements and beacons
Create custom advertisements beacons
Connect, pair and bond with BLE devices that offer their own GATT services (e.g. heart monitors, humidity sensors, light bulbs, etc.)

BLE advertisements can be fully customized using MicroPython to create beacon formats like Apple’s iBeacon and Google’s Eddystone. Digi hosts a GitHub repository and associated Pycharm plug-in that contains many different samples to show you how to address many BLE use cases at https://github.com/digidotcom/xbee-micropython/tree/master/samples/bluetooth. The repository also contains some useful optional modules for creating popular custom beacon formats. MicroPython also contains full support for sending and receiving user data relay frames from both the serial port and the BLE interface, so it can be used in creative ways to act as a BLE broker and filter your application’s data.

As a simple example of the power of MicroPython, the send and receive advertisement samples can be easily combined to create a BLE advertisement repeater. This repeater can then easily be enhanced with user data relay frames to send all or certain filtered advertisements out the serial port to a host processor. The host processor could send relay frames to the MicroPython program with the address or device types of advertisements that it wishes to filter.

Tools and Libraries

Digi also offers a number of tools and source code libraries to work with XBee 3 modems. The Digi XBee mobile application is available for Android and Apple iPhone devices and allows you to connect securely to a Digi XBee 3 and configure its AT parameters similar to how XCTU works over a serial port.
Digi offers a plug-in module to the popular Pycharm IDE to help you develop MicroPython code for your XBee. The plug-in features importing samples from the Digi MicroPython GitHub repository including the BLE examples and libraries.

Digi also provides open-source libraries in C, Java, Python, and C# for users on external hosts and mobile applications. These libraries support the user data relay frames to facilitate building applications that want to leverage the BLE interface. Additionally, the XBee Android and XBee C# libraries are powerful tools and references for creating your own configuration tools and contain libraries to make it easy to configure and authenticate with XBee 3 devices over BLE.

Compatibility and Hardware Specifications

The Digi XBee 3 BLE stack fully supports BLE version 4.2 and is capable of interoperating with BLE 5.0 devices that support the 1M Phy. The XBee 3 is capable of 5.0 and is software upgradable to 5.0 (planned for a future release).

Digi XBee 3 Model	BLE version**	Output power*	Sensitivity	Indoor	Outdoor/LoS
Cellular (Cat 1 or LTE-M/NB)	4.2	6.3 mW (8 dBm)	-95 dBm	Up to 15 m	Up to 300 m
ZB/DigiMesh/802.15.4	4.2	6.3 mW (8 dBm)	-95 dBm	Up to 15 m	Up to 300 m

*Adjustable down to -20 dBm
** Hardware is 5.0 capable. Version 5.0 is not yet enabled except for payload extensions.

Limitations

Digi XBee 3 does not support adding generic GATT services from the modem over BLE. This limitation means that the XBee 3 cannot perform the roles of specific BLE device types such as a light bulb, fitness monitor, humidity sensor, etc. The current released versions of Digi XBee 3 cannot interoperate with 2M services of BLE 5.0 but continue to check back as this may be available in a future software update.

Glossary

Generic Access Profile (GAP) defines how devices advertise and scan in a BLE network.
Generic Attribute Profile (GATT) defines how devices offer services and characteristics to other BLE devices.
Line of Sight (LoS) idealized wireless operating environment between devices without interference.
Advertisements broadcast messages sent from BLE devices to facilitate discovery or convey other broadcast data.
Beacons are customized advertisements to relay application specific data.