Connection Monitor (CM) Example Guide

Table of Contents

Introduction

The Connection Monitor (CM) project utilizes the monitor role from the TI __Micro BLE Stack Overview__ to collect connection data from external BLE connections without having to formally participate in a BLE connection. The monitor role is not an official BLE Specification defined role. It is designed to follow an active BLE connection given the following parameters:

  1. Access Address
  2. Connection Interval
  3. Hop Increment Value
  4. Channel Map
  5. Master Sleep Clock Accuracy (mSCA)

The CM performs an initial scan and listens on a data channel to capture a packet and establish an anchor point for the specified connection. Once established, it will continue to monitor the connection by capturing the master and slave packets involved in the connection. The CM can return information about the connection such as a packet's RSSI value and timestamp.

See the __Micro BLE Stack Overview__ for more information.

The Connection Monitor example comes with two separate build configurations:

  1. __CM_FlashOnly_MultiMode__ - CM Flash-Only Multi-Mode
  2. __uNPI_CM_FlashOnly_MultiMode__ - __Unified Network Processing Interface (UNPI)__ CM Flash-Only Multi-Mode
CM Build Configuration Description
__CM_FlashOnly_MultiMode__ Base application showing how to use Micro BLE Stack in the CM role
__uNPI_CM_FlashOnly_MultiMode__ Same as the __CM_FlashOnly_MultiMode__, except with added UNPI support to receive data from a host

The __CM_FlashOnly_MultiMode__ (embedded) configuration requires information regarding the BLE connection parameters to be hard-coded into the CM project. The __uNPI_CM_FlashOnly_MultiMode__ configuration uses the UNPI to receive information regarding the BLE connection parameters from the host.

The uNPI_CM_FlashOnly_MultiMode build configuration relies on receiving the BLE connection parameters via a serial bus. Due to this delay, the __uNPI_CM_FlashOnly_MultiMode__ configuration sets its initial scan on _data channel 0_.

The CM_FlashOnly_MultiMode build configuration has the benefit of having the BLE connection parameters provided in the connection monitor's application memory. This configuration allows the application to use the same data channel as the BLE secure connection without receiving the connection parameters externally. This build configuration may be useful when evaluating Connection Monitor; however, it is not representative of a "real-world" use case.

Limitations

Connection Monitor currently has the following limitations:

Hardware Prerequisites

The __CM_FlashOnly_MultiMode__ and __uNPI_CM_FlashOnly_MultiMode__ configurations of the connection monitor application are both designed to run on the LAUNCHXL-CC2640R2.

Up to two additional LAUNCHXL-CC2640R2 may be required to create a connection to monitor. One LaunchPad must be flashed with the __host_test__ or __simple_central__ examples to act as a BLE central node. A second LaunchPad may optionally be flashed with the __simple_peripheral__ example to act as a BLE peripheral. This LaunchPad would form a connection with the LaunchPad flashed with the __host_test__ or __simple_central__ example. This second LaunchPad may be replaced with another BLE peripheral such as a phone.

Software Prerequisites

For information regarding versions of CCS and IAR Embedded Workbench, refer to the Release Notes located in the _docs/blestack_ folder. For information on how to import, build, and run the connection monitor example in each IDE, refer to '__The CC2640R2F Platform__' section in the __BLE-Stack User Guide for Bluetooth 4.2__.

Python is not required for users utilizing the __CM_FlashOnly_MultiMode__ configuration. In order to utilize _npi_cm_host.py_ for the __uNPI_CM_FlashOnly_MultiMode__ configuration, you will need a valid installation of __Python 2.7__. Alternatively, the _npi_cm_host.exe_ executable can be used which does not require Python. Instructions using the _npi_cm_host.exe_ are detailed later.

Versions newer than Python 2.7 are currently __not__ supported! Verify the correct version of python in your environment by running the following command in your shell. bash python --version Alternatively, you can explicitly specify the path to your python installation. bash C:\Python27\python.exe

Required Python Modules

The _npi_cm_host.py_ script requires the following python modules to be installed:

A _requirements.txt_ is provided which contains a list required python modules. This can be used with the __pip__ utility to install all dependencies:

pip install -r requirements.txt

_requirements.txt_ and _npi_cm_host.py_ are both located in <SDK_INSTALL_DIR>/tools/blestack/connection_monitor.

Usage

The connection monitor example can be used one of two ways: 1. uNPI_CM_FlashOnly_MultiMode 2. CM_FlashOnly_MultiMode

Setup and User Guide For uNPI_CM_FlashOnly_MultiMode

Set Up

  1. Flash the __uNPI_CM_FlashOnly_MultiMode__ project onto a LaunchPad and connect it to the host computer via USB. This will be the Connection Monitor LaunchPad.

  2. Flash the second LaunchPad with the __host_test__ project and connect it to the host computer via USB. This will be the central device LaunchPad.

  3. The __uNPI_CM_FlashOnly_MultiMode__ project utilizes the UART peripheral through the UNPI. This requires the host computer to open a serial session. Open a serial session (e.g. using <code>PuTTY</code>, etc.) to the appropriate COM port.

    • The COM port can be determined via Device Manager in Windows or via ls /dev/tty* in Linux. Each LaunchPad will enumerate as two COM ports. The port labeled as "XDS110 Class Application/User UART" interfaces with the application UART. The connection should have the following settings
    Baud-rate:  115200
    Data bits:       8
    Stop bits:       1
    Parity:       None
    Flow Control: None

  <img src="resource/cm_comport_selection.png" width="390" height="85" />

> Note which COM port belongs to the __uNPI\_CM\_FlashOnly\_MultiMode__
  LaunchPad and which belongs to the __host\_test__ LaunchPad.

  1. If using a third LaunchPad as a BLE peripheral, flash the final LaunchPad with the __simple_peripheral__ application. After flashing is completed, record the Bluetooth _Device Address_.

    • This can be found by opening a serial session with the LaunchPad running __simple_peripheral__. The Bluetooth _Device Address_ will be displayed in the UART terminal. Refer to _step 3_ (previous step) for instructions opening a serial session.

    • Once the Bluetooth __Device Address__ is noted, the LaunchPad is only required to be powered; therefore, there is no need to have a serial session or software debugger connected.

Running _npi_cm_host.py_ Manually with No Arguments

Some modifications to _npi_cm_host.py_ are required prior to use. The following modifications configure the script to control the correct devices (LaunchPads) and enables the LaunchPad with the __host_test__ application to connect to the correct BLE peripheral.

Refer to the following code snippet from _npi_cm_host.py_ when making modifications for the steps below:

  if __name__ == '__main__':
      global peerAddrs
      version_control()
      rtn_args = parse_args()

  if(len(sys.argv) < 4):
      print '\nUsing Default Hardcoded Values: '
      print 'or enter 3 default(cm_port host_port peerAddress) arguments.'
      print 'See -h help.\n'
      #set your own hard coded com ports
      host_port = 'COM104'
      cm_port     = 'COM105'
      strPeerAddress = '0xB0912265CBE2'
  1. Update host_port with the COM port of the LaunchPad running __host_test__.
  2. Update cm_port with the COM port of the LaunchPad running __uNPI_CM_FlashOnly_MultiMode__.
  3. Update strPeerAddress with the Bluetooth _Device Address_ of the BLE peripheral. This is the _Device Address_ noted in _step 4_ of the previous section.
  4. Run the _npi_cm_host.py_ script using Python. command C:\Python27\python.exe <SDK_INSTALL_DIR>\tools\blestack\connection_monitor\npi_cm_host.py

Running the Python Script or Executable with Command Line arguments

To run _npi_cm_host.py_ without modifications, the configuration information can be passed into the script as command line arguments. Additionally, an _npi_cm_host.exe_ executable is also provided which allows you to utilize __uNPI_CM_FlashOnly_MultiMode__ project without using Python. Command line arguments must be provided to _npi_cm_host.exe_.

Command line arguments are expected to be in the following order:

Argument 1 Argument 2 Argument 3
CM COM PORT host_test COM PORT Peripheral Bluetooth Device Address 
C:\Python27\python.exe <SDK_INSTALL_DIR>\tools\blestack\connection_monitor\npi_cm_host.py COM4 COM5 0xB0912265CBE2

<SDK_INSTALL_DIR>\tools\blestack\connection_monitor\npi_cm_host.exe COM4 COM5 0xB0912265CBE2

Script Execution and Output

The _npi_cm_host_ script will send commands to the LaunchPad running the __host_test__ application. The __host_test__ application acts as a central device and connects to the BLE peripheral. Once a connection with the BLE peripheral is established, the _npi_cm_host_ script will query the __host_test__ for the current connection parameters. Finally it will launch the connection monitor with the retrieved connection parameters. A continuous stream of RSSI data and timestamps from the connection monitor of master and slave devices at each connection event will appear in the terminal after a short delay.

The default connection interval of connection events is 100ms.

Additional Information

The script _npi_cm_host.py_ contains in-line comments. These comments describe script behavior.

Setup and User Guide For CM_FlashOnly_MultiMode

Set Up

  1. Flash a LaunchPad with the __simple_central__ application and connect it to the host computer via USB. This will be the central device LaunchPad. This central device requires the host computer to open a serial session. Open a serial session (e.g. using <code>PuTTY</code>, etc.) to the appropriate COM port.

    • The COM port can be determined via Device Manager in Windows or via ls /dev/tty* in Linux. Each LaunchPad will enumerate as two COM ports. The port labeled as "XDS110 Class Application/User UART" interfaces with the application UART.
    • Refer to __Simple Central Guide__ for serial settings.

  2. If using a third LaunchPad as a BLE peripheral, flash the final LaunchPad with the __simple_peripheral__ application. After flashing is completed, record the Bluetooth _Device Address_.

    • This can be found by opening a serial session with the LaunchPad running __simple_peripheral__. The Bluetooth _Device Address_ will be displayed in the UART terminal. Refer to _step 1_ (previous step) for instructions opening a serial session.
    • Once the Bluetooth __Device Address__ is noted, the LaunchPad is only required to be powered; therefore, there is no need to have a serial session or software debugger connected.

  3. Form a connection between the __simple_central__ and __simple_peripheral__ LaunchPads by utilizing the __simple_central's__ two button interface. This process consist of scanning for devices and connecting to the advertising __simple_peripheral__. You should verify the correct Bluetooth _Device Address_ noted in _step 3_.

  4. Once a connection is formed, use the Connection Info menu option to extract the connection parameters required by the Connection Monitor.

    • Access Address
    • Connection Interval

    • Hop Value Ensure that the connection is maintained.

  5. Open the __CM_FlashOnly_MultiMode__ project and open the micro_cm_demo.c source file. Find the MicroCmDemo_init function and input the connection parameters retrieved in _step 4_. Refer to the code snippet below.

__CM_FlashOnly_MultiMode__ does not utilize UNPI and thus has no transport layer interface to the UART peripheral. In order to configure the connection monitor, connection parameters must be manually placed into application code and compiled.

/* Initialize Connection Monitor */
if (ubCm_init() == true)
{
    /*
     * The ubCM_Start() is called here to kick off CM sessions as a demo.
     * This API should be called from host uNPI once the uNPI host
     * if available. The currentStartTime, access address, and scan duration
     * are hard-coded. They should be provided by the host. In this demo, the
     * very first ubCM_start() call will cover UB_MAX_MONITOR_DURATION.
     */
    ubCMConnInfo.ArrayOfConnInfo[0].accessAddr = 0x87318ba3;
    ubCMConnInfo.ArrayOfConnInfo[0].currentStartTime = 0;
    ubCMConnInfo.ArrayOfConnInfo[0].nextStartTime = RF_getCurrentTime() + 100 * BLE_TO_RAT;
    ubCMConnInfo.ArrayOfConnInfo[0].scanDuration = UB_MAX_MONITOR_DURATION; // 40.96s
    ubCMConnInfo.ArrayOfConnInfo[0].connInterval = 1600;
    ubCMConnInfo.ArrayOfConnInfo[0].hopValue = 15;
    ubCMConnInfo.ArrayOfConnInfo[0].combSCA = 90; // Master+Slave = 50+40
    ubCMConnInfo.ArrayOfConnInfo[0].chanMap[0] = 0xFF;
    ubCMConnInfo.ArrayOfConnInfo[0].chanMap[1] = 0xFF;
    ubCMConnInfo.ArrayOfConnInfo[0].chanMap[2] = 0xFF;
    ubCMConnInfo.ArrayOfConnInfo[0].chanMap[3] = 0xFF;
    ubCMConnInfo.ArrayOfConnInfo[0].chanMap[4] = 0x1F;
}
  1. Build and flash a LaunchPad with the __CM_FlashOnly_MultiMode__ application and connect it to the host computer via USB. This will be the Connection Monitor LaunchPad.

Observing the Monitored Information

  1. Open a serial session (e.g. using <code>PuTTY</code>, etc.) to the connection monitor's COM port (LaunchPad running the __CM_FlashOnly_MultiMode__ application.

    • The COM port can be determined via Device Manager in Windows or via ls /dev/tty* in Linux. Each LaunchPad will enumerate as two COM ports. The port labeled as "XDS110 Class Application/User UART" interfaces with the application UART.

  2. After a maximum of 40 seconds, RSSI and timestamp information should appear. This is information reported by the connection monitor as it follows the BLE connection between the central (__simple_central__) and the BLE peripheral.

Keeping Track of the Connection

ubCM_ConnInfo_t struct

The ubCM_ConnInfo_t struct keeps track of values required to monitor a connection and stores the information gathered from a scanned packet:

typedef struct
{
  uint8_t   sessionId;                           //! Number 1-255 assigned as they are created identifying each connection monitor session
  uint8_t   timesScanned;                        //! track count of recent events monitored to determine next priority CM session to avoid starvation
  uint8_t   timesMissed;                         //! missed count of recent events monitored
  uint32_t  accessAddr;                          //! return error code if failed to get conn info
  uint16_t  connInterval;                        //! connection interval time, range 12 to 6400 in  625us increments (7.5ms to 4s)
  uint16_t  scanDuration;                        //! Required scan window to capture minimum of 1 packet from Master and Slave up to max possible packet size
  uint8_t   hopValue;                            //! Hop value for conn alg 1, integer range (5,16)
  uint16_t  combSCA;                             //! mSCA + cmSCA
  uint8_t   prevChan;                            //! previous channel
  uint8_t   currentChan;                         //! current data channel
  uint8_t   nextChan;                            //! next data channel
  uint8_t   chanMap[CM_NUM_BYTES_FOR_CHAN_MAP];  //! bitmap of used channels, use to reconstruct chanTableMap
  uint8_t   masterAddress[CM_DEVICE_ADDR_LEN];   //! BLE address of connection master
  uint8_t   slaveAddress[CM_DEVICE_ADDR_LEN];    //! BLE address of connection slave
  uint8_t   rssiMaster;                          //! last Rssi value master
  uint8_t   rssiSlave;                           //! last Rssi value slave
  uint32_t  timeStampMaster;                     //! last timeStamp master
  uint32_t  timeStampSlave;                      //! last timeStamp slave
  uint32_t  currentStartTime;                    //! Current anchor point
  uint32_t  nextStartTime;                       //! Record next planned scan anchor point to compare with competing CM sessions
  uint32_t  timerDrift;                          //! Clock timer drift
} ubCM_ConnInfo_t;

Generally, members of the ubCM_ConnInfo_t struct should __not__ be modified as they are self-maintained by connection monitor.

In the case that fine tuning is required for the scan window the following should be understood:

    x ms / 0.625 ms = RAT ticks

where __x__ is the desired time in ms.