Introduction

This SimpleLink Academy lab introduces the reader to the fundamentals of DMM, and it is recommended to use this lab as a starting point for any DMM implementation done on a CC13xx or CC26xx device.

The Dynamic Multi-protocol Manager (DMM) allows multiple wireless stacks to coexist and operate concurrently on a single radio on a CC13xx or CC26xx device. DMM allows the user to define and control the priorities and timing constraints of each stack at run-time.

This lab will show how to use a single device as an TI 15.4-Stack Sensor on a sub-1 GHz radio frequency (RF) network while simultaneously acting as a Bluetooth LE peripheral.

It is assumed that the user has previous knowledge of the Bluetooth® Low Energy (BLE) protocol and the TI 15.4-Stack Sensor and Collector topology. You can learn about this in the BLE and TI 15.4-Stack RF SimpleLink Academy labs.

Additional examples

This lab focuses on explaining the fundamentals of using DMM, which is why the DMM example with BLE Peripheral and TI 15.4-Stack is used. DMM is not limited to this combination. There are other DMM examples in the SimpleLink CC13xx / CC26xx SDK with different wireless stack combinations, such as a TI 15.4 Sensor or ZigBee End Device with a BLE Peripheral.

For more information on available combinations and limitations, please refer to the DMM User's Guide.

Prerequisites

Hardware

Note

Depending on which LaunchPad is used as the DMM device, the antenna will be tuned for different frequency bands. This is also reflected in the TI 15.4-Stack examples for the LaunchPad in question.

For the Sensor to be able to communicate with the Collector, the two devices must have compatible settings. If using the same LaunchPad version for both the Sensor and Collector, the examples will have matching settings per default.

Software

It is recommended to read the DMM User's Guide, BLE5-Stack User's Guide, and TI 15.4-Stack User's Guide alongside this lab for details and further information.

Before you start

Attention

The steps in this lab make reference to the CC1352R1 LaunchPad. Please note that the same steps apply when using either boards listed under required hardware.

  1. Install the SimpleLink CC13xx/CC26xx SDK.

  2. Install Code Composer Studio (CCS). These instructions assume that you install CCS with support for the CC13xx and CC26xx devices.

Setup CCS Workspace

Before we start, create an empty CCS workspace and import the following example projects:

  • dmm_154sensor_remote_display_app, found under <SDK>/examples/rtos/<BOARD>/dmm/.

  • collector, found under <SDK>/examples/rtos/<BOARD>/ti154stack/.

where <SDK> is the install location of the SimpleLink SDK, and <BOARD> must correspond to the board being used for that example project.

To import an example from the SimpleLink SDK, follow these steps within your workspace in Code Composer Studio:

  1. Select ProjectImport CCS Projects... to open the import dialog.

  2. Browse to the path of the example as the search directory. Click Select Folder.

  3. Select the example project, and click Finish to import the example application.

  4. Repeat the process for the other example project.

Project README

You can refer to the project's README file for a functional description of each example.

  • dmm_154sensor_remote_display_app: README

  • collector: README

Group Training – Additional Requirements

If you are working in groups, make sure to always use your designated frequency to avoid interfering with other operations. Also, change the Bluetooth LE scan response to output a uniquely identifiable name.

Feel free to skip this section if you are not participating in a group training.

Frequency Allocation

In order to avoid interfering with other groups when operating on the same frequency band, use a unique channel during this lab.

Ask your Instructor

If you are part of a group training, please ask the instructor for a specific channel or unique PAN ID to use during this lab.

For simplicity, it is possible to select a base frequency (915.0 MHz, 868.0 MHz, 433.0 MHz), and update the channel mask as explained below:

Updating the channel mask

  • The stack can be configured to enable any of the supported channels. If more than one channel is enabled, the best ("most quiet") channel is selected by the collector when starting the network. When the sensor looks for a network to join, it scans all the enabled channels until it finds the collector.

  • To enabled the required channel and disable the other channels, you will need to edit the channel mask definition. This configuration item is a bitmask representing all the available channels, this is represented as a drop down menu and you can select the channels you want transmit on by checking the box.

  • Each student should update the definition of this configuration item such that only its designated channel is enabled, and all other channels are disabled. For example, student #10 should have it defined as Channel 9.

  • Note that the number of supported channels may be limited, depending on the frequency band being used. Please make sure to select a channel within the supported range - see the note box below.

Available channels

  • The number of supported channels depend on the selected frequency band:
    • 915 MHz band - channels 0 to 128 - total of 129 channels
    • 868 MHz band - channels 0 to 33 - total of 34 channels
    • 433 MHz band - channels 0 to 6 - total of 7 channels

Multiple ways to prevent conflicts

In this lab, each student uses a different channel, in order to avoid conflicts. Using TI 15.4-Stack, there is another way to avoid conflicts, which allows using the same channels by everybody. This method involves pre-assigning the same PAN-ID to every device in the intended network, and different PAN-IDs to different networks. The stack will automatically filter and accept only the packets targeted for its PAN. The downside of this would be that in a large classroom with many setups this could lead to channel congestion and a high rate of dropped packets.

More info

For more information regarding the available configuration settings, please see the TI 15.4-Stack User's Guide.

The frequency band, PAN ID, and channel mask are configured in both examples with SysConfig as such:

  1. Open SysConfig by double clicking on the *.syscfg file.

    • dmm_154sensor_remote_display.syscfg for dmm_154sensor_remote_display_app.

    • collector.syscfg for collector.

  2. In SysConfig, navigate to TI 15.4 StackRadio and change the value of Sub-1 GHz Frequency to the desired frequency band.

  3. In SysConfig, navigate to TI 15.4 StackNetwork and change the value of Pan ID and Channel Mask to their unique values.

Bluetooth LE Scan Response

To make it easier for the operators to distinguish between the Bluetooth LE advertisements, it is recommended to change the Bluetooth LE scan response to output a unique identifiable name.

Ask your Instructor

If you are part of a group training, please ask the instructor for a unique number to use in your scan response during this lab.

The Bluetooth LE scan response is configured in dmm_154sensor_remote_display_app with SysConfig as such:

  1. Open SysConfig by double clicking on the dmm_154sensor_remote_display.syscfg file.

  2. In SysConfig, navigate to BLEGeneral ConfigurationDevice Name.

  3. Change the value of Device Name to the unique identifiable name.

Dynamic Multi-protocol Manager (DMM)

DMM is a layer between the RF protocol stacks and the RF Driver. It provides hooks to the RF driver, replacing the default scheduling behavior. It will modify the order in which RF commands are scheduled based on constraints and requirements from the applications and stacks. For a full description of DMM, please refer to the DMM User's Guide.

DMM consists of two modules:

  • The DMM Policy Manager – determines the current DMM policy from the DMM policy table, based on the current combination of stack states and stack activities as reported by the applications and protocol stacks, respectively.
  • The DMM Scheduler – manages the scheduling and conflict resolution of the queued RF commands.

A block diagram of DMM in relation to the stack applications and the RF driver is given in the following figure:

DMM is configured in SysConfig under the Multi-Protocol section. Below is an overview of that configuration page.

Protocol stack roles are unique IDs assigned to each stack application, and is used to identify which stack application is updating its application state to DMM. Each stack application has a set of one or more application states, and is configurable by the developer.

In the case of the dmm_154stack_remote_display_app example, a set of application states has already been defined for both the BLE and TI 15.4 application. Note the special application state ANY, which is used to match any application state when making a DMM policy.

The current application state of both stack applications results in an active DMM policy from the DMM policy table. A DMM policy is the scheduling rule for both stack applications and the DMM policy table makes up the complete set these scheduling rules used in the system. This is explained in more detail later.

Quiz

How does DMM know what application state the BLE peripheral application is in?

DMM Policy Manager

The primary goal of the DMM policy manager is to determine which stack application has priority over the other at any given time. This is used by the DMM scheduler when a protocol stack schedules an RF command which creates a conflict with a different protocol stack.

In order to determine which stack application has priority over the other, the DMM policy manager keeps track of the current DMM policy, combined with scheduled RF activities. A DMM policy decides the scheduling rules for both protocol stacks, and in the end determines which protocol stack has priority over the other. The complete set of all DMM policies used in the system are stored in the DMM policy table.

DMM Policy Table Order

The order of policy table entries matter, since the search of the active DMM policy is done in ascending order and will return on the first match.

Priorities are set by the Global Priority Table (GPT). GPT defines the base priority for all stack activities. It is this base priority, combined with the weight from the active DMM Policy, that determines which stack has priority over the other for a given stack activity.

GPT is not configured in SysConfig. TI provides pre-made GPTs in the SDK, found under <SDK>/source/ti/dmm/. These GPTs are named dmm_priority_{stacks}.h/c, and serves as a starting point with tested default values. Please refer to the source code for more documentation and overview of each GPT.

Priority Tiebreaker

The GPT and DMM policy table should be designed to avoid ties; how else are you supposed to decide who has priority?

In the unlikely event of a tie, the last DMM policy entry in the policy table, also known as the default policy, acts as a tiebreaker. The stack with the higher priority in that policy wins.

A DMM policy tells the scheduler which stack has priority in a certain application state and whether submitted RF commands can be deferred or not. From the policy, the scheduler can deduce how a scheduling conflict shall be resolved. Each policy within the structure represents a comprehensive system state for each stack application and consists of the following parameters:

  • Weight – an application weight where a higher value represents a higher priority
  • Paused Stack – callback notification if the stack application must pause or resume the radio activity
  • Application States – one or more application states for which this policy is valid for
  • Applied Activity – none or more stack activities for which this policy applies to

Below is a DMM policy from the dmm_154stack_remote_display_app, which configures the following:

  • BLE Peripheral application
    • must be in the BLE OAD application state; where
    • weight is not applied to any stack activity; and
    • no pause requirements
  • TI 15.4-Stack Sensor application
    • can be in Any application state; where
    • weight is not applied to any stack activity; and
    • radio activity must be paused

This DMM policy could be described in words as such: when the Bluetooth LE application is in some OAD operation, regardless of what radio activity, and the TI 15.4-Stack Sensor is in whatever state and radio activity, they both have equal weight, but the TI 15.4-Stack Sensor application must pause its radio activity.

This example is not OAD enabled

While it exists policies hinting about OAD capabilities, this example is actually not OAD enabled. For OAD enabled versions of the DMM examples, use the examples with "oad" in the name.

In SysConfig, the same DMM policy would be configured as such:

Balanced Mode

Looking closer at the policy table, one will notice the "Balanced Mode" dropdown option. To learn more about this feature and how it impacts the DMM scheduling behavior, please see the DMM User's Guide.

Applications use the DMMPolicy_updateStackState() API to notify DMM of an application state change, which takes a protocol stack role and the new application state as arguments. Calling this functions multiple times in a row with the same arguments will not change the active DMM policy, it will only cause unnecessary overhead and is generally recommended to avoid.

Quiz

Study the DMM policy table in SysConfig. Which of the following statements are true?

DMM Scheduler

As illustrated in the DMM block diagram, the DMM Scheduler handles some of the interactions with the RF driver while most of them are routed to the RF Driver without any modification. A core concept of DMM is that the wireless protocol stack does not need to be directly aware that DMM is present. In other words, it should be able to operate as normal no matter if it is running in a DMM context or not.

In order for DMM to inject itself in-between the wireless protocol stacks and the RF driver without directly changing the RF driver API calls, some RF Driver API functions are re-mapped to the equivalent DMM function. In both the BLE Peripheral and TI 15.4-Stack Sensor, the DMM RF map header file is included instead of the RF driver when DMM is used.

#ifndef USE_DMM
#include <ti/drivers/rf/RF.h>
#else
#include <dmm/dmm_rfmap.h>
#endif //USE_DMM

rd_ble_user_config.c – the RF driver remapping to DMM is included instead of the RF driver when USE_DMM is defined

Note that the define USE_DMM is used as a feature flag to differentiate between a DMM and non-DMM application. If you take a look at the file dmm/dmm_rfmap.h you can see which RF driver functions are redefined.

RF Driver Concepts

To fully understand the DMM scheduler you need to understand how the RF driver operates with RF commands and the internal RF command queue. This can be read in more detail in the Proprietary RF User's Guide.

When a wireless protocol stack submits an RF command, the RF driver will invoke the scheduler function supplied by the DMM to schedule the command. The DMM Scheduler acts according to the following criteria:

  • What are the current stack priorities?
  • What are the timing constraints of the scheduled RF command?
  • Are there any commands in the RF queue, and what priority do they have?

At first, the DMM scheduler will try to simply schedule the new command directly based on its start time. If the DMM scheduler is not able to schedule the command due to a conflict with another stack, it will try to resolve the conflict using the current stack priority and timing constraints.

When it is time to run the next command in the RF command queue, the RF driver will invoke the DMM execution function to get a decision on how to process the next command. The DMM Scheduler will act according to the active policy just like it did during scheduling, resolving any potential conflict that might exist between the (potentially) running command and the next one.

Quiz

Which of the following statements is the expected behavior for the DMM Scheduler?

Task 1 – Setup the DMM Device

The first task is to setup the DMM example application on the DMM device.

  1. Build the DMM example (dmm_154sensor_remote_display_app) by doing one of the following:

    • Right clicking on the project in the project explorer and selecting Build Project

    • Clicking ProjectBuild Project

    • Clicking the hammer icon

    • Ctrl + B

  2. Debug the DMM example by doing one of the following:

    • Right clicking on the project in the project explorer and selecting Debug AsCode Composer Studio Debug Session

    • Clicking RunDebug

    • Clicking the green bug icon

    • F11

    If you have multiple debug probes are connected to your computer, CCS will prompt you to select one. This serial number will be set as the debug connection for this target configuration.

  3. Once the debug session has flashed the device, the debugging session should halt a main(). Allow the example application to free run by:

    • Clicking RunResume

    • Clicking the green resume button

    • F8

  4. End the debugging session by clicking the red stop button.

  5. Connect a terminal program to see the serial output from the device. This is described in the BLE Fundamentals SimpleLink Academy lab. When you press play, the device will output the following:

  6. Verify the device is advertising over Bluetooth LE with a smartphone. Steps for connecting to a smartphone are given in the BLE Fundamentals SimpleLink Academy lab.

    The device will either advertise with the default name "DMM 15.4 Sensor RD" as seen below, or using the name chosen following the group training recommendations.

DMM Device is now setup

You now have a device that is concurrently running as a TI 15.4-Stack Sensor and as a BLE Peripheral.

Task 2 – Setup the TI 15.4-Stack Collector

The DMM device is a TI 15.4-Stack Sensor. We need a TI 15.4-Stack Collector to connect to it in order to see the Sub-1 GHz network. Setting up a TI 15.4-Stack Collector is described in the SimpleLink Academy module TI 15.4-Stack Project Zero.

  • Press BTN-1 on the collector to start the network, the red LED on the collector should turn on after a short while, and the LEDs on the sensor should both remain off. The red LED on the collector means that it has successfully created a network. The collector terminal will now also say "Started--Mode=NBCN, Addr=0xaabb, PanId=0x0001, Ch=x, PermitJoin=Off", where x will be the number of the actual channel that was selected.

  • Press BTN-2 on the collector to allow new devices to join the network. The red LED will start blinking, meaning that the network is now open for joining, and the collector's terminal will say "PermitJoin=On".

  • Press BTN-1 on the sensor to start looking for a network to connect to.

    Observe and Understand

    The sensor will join the network after a short while, indicated by the sensor red LED turning on (otherwise, see Troubleshooting below). The collector's terminal will say "Joined: 0xX" where 0xX is the sensor ID, and the sensor's terminal will say "Status: Joined--Mode=NBCN, Addr=0xX, PanId=0x0001, Ch=x" (0xX is the sensor ID), indicating successful network connection.

    Troubleshooting

    If the sensor does not join after a short while, please reset it using the reset button.

You may have noticed that the TI 15.4-Stack Sensor outputs "Temp" and "RSSI" measurements. You can now see that this information is transmitted to the concentrator.

We now have two devices connected to the DMM device over two different RF protocols. With your phone, you can use the Remote Display Service to interact with the 15.4-Stack network.

Interacting with the sensor and collector over Bluetooth LE

While connected to the TI 15.4-Stack Sensor over Bluetooth LE it is possible to interact with both the TI 15.4-Stack Sensor and Collector via the Sensor). Information on how to interact with the TI 15.4-Stack network is found inside the dmm_154stack_remote_display_app README.

Limitations

Unlike Task scheduling in TI-RTOS, RF scheduling cannot be preempted and resumed at a later time. Instead, DMM will use the policy table to resolve scheduling conflicts between the stacks. Whenever there is a scheduling conflict, DMM will either reject the new command or abort the conflicting command in favor of the new command. This means that there are limitations to which DMM use-cases that are feasible.

When looking at the Global Priority Table, we can see that the Bluetooth LE stack in the "normal" priority case is always assigned a lower weight then that of the TI 15.4-Stack. This remains true for most weights when comparing the two stacks on a priority bases. The only cases where the Bluetooth LE stack is assigned a higher weight when comparing priority levels is in the "high connection establishment" and "urgent connection" case.

/* Global Priority Table: BLE connection is lower than 15.4 data */
StackActivity activityBLE_bleL154SensorH[ACTIVITY_NUM_BLE*PRIORITY_NUM] =
{

    DMM_GLOBAL_PRIORITY(DMM_BLE_CONNECTION, DMM_StackPNormal, 70),
    DMM_GLOBAL_PRIORITY(DMM_BLE_CONNECTION, DMM_StackPHigh, 170),
    DMM_GLOBAL_PRIORITY(DMM_BLE_CONNECTION, DMM_StackPUrgent, 250),

    DMM_GLOBAL_PRIORITY(DMM_BLE_CON_EST, DMM_StackPNormal, 70),
    DMM_GLOBAL_PRIORITY(DMM_BLE_CON_EST, DMM_StackPHigh, 200),
    DMM_GLOBAL_PRIORITY(DMM_BLE_CON_EST, DMM_StackPUrgent, 220),

    DMM_GLOBAL_PRIORITY(DMM_BLE_BROADCASTING, DMM_StackPNormal, 60),
    DMM_GLOBAL_PRIORITY(DMM_BLE_BROADCASTING, DMM_StackPHigh, 160),
    DMM_GLOBAL_PRIORITY(DMM_BLE_BROADCASTING, DMM_StackPUrgent, 210),

    DMM_GLOBAL_PRIORITY(DMM_BLE_OBSERVING, DMM_StackPNormal, 60),
    DMM_GLOBAL_PRIORITY(DMM_BLE_OBSERVING, DMM_StackPHigh, 60),
    DMM_GLOBAL_PRIORITY(DMM_BLE_OBSERVING, DMM_StackPUrgent, 85),
};


StackActivity activity154_bleL154SensorH[ACTIVITY_NUM_154*PRIORITY_NUM] =
{

#if (CONFIG_PHY_ID == APIMAC_5KBPS_915MHZ_PHY_129 || CONFIG_PHY_ID == APIMAC_5KBPS_868MHZ_PHY_131)
    DMM_GLOBAL_PRIORITY(DMM_154_DATA, DMM_StackPNormal, 175),
#else
    DMM_GLOBAL_PRIORITY(DMM_154_DATA, DMM_StackPNormal, 80),
#endif
    DMM_GLOBAL_PRIORITY(DMM_154_DATA, DMM_StackPHigh, 180),
    DMM_GLOBAL_PRIORITY(DMM_154_DATA, DMM_StackPUrgent, 240),

    DMM_GLOBAL_PRIORITY(DMM_154_LINK_EST, DMM_StackPNormal, 100),
    DMM_GLOBAL_PRIORITY(DMM_154_LINK_EST, DMM_StackPHigh, 195),
    DMM_GLOBAL_PRIORITY(DMM_154_LINK_EST, DMM_StackPUrgent, 230),

    DMM_GLOBAL_PRIORITY(DMM_154_TX_BEACON, DMM_StackPNormal, 90),
    DMM_GLOBAL_PRIORITY(DMM_154_TX_BEACON, DMM_StackPHigh, 190),
    DMM_GLOBAL_PRIORITY(DMM_154_TX_BEACON, DMM_StackPUrgent, 240),

    DMM_GLOBAL_PRIORITY(DMM_154_RX_BEACON, DMM_StackPNormal, 90),
    DMM_GLOBAL_PRIORITY(DMM_154_RX_BEACON, DMM_StackPHigh, 190),
    DMM_GLOBAL_PRIORITY(DMM_154_RX_BEACON, DMM_StackPUrgent, 240),

#if (CONFIG_PHY_ID == APIMAC_5KBPS_915MHZ_PHY_129 || CONFIG_PHY_ID == APIMAC_5KBPS_868MHZ_PHY_131)
    DMM_GLOBAL_PRIORITY(DMM_154_FH, DMM_StackPNormal, 175),
#else
    DMM_GLOBAL_PRIORITY(DMM_154_FH, DMM_StackPNormal, 90),
#endif
    DMM_GLOBAL_PRIORITY(DMM_154_FH, DMM_StackPHigh, 190),
    DMM_GLOBAL_PRIORITY(DMM_154_FH, DMM_StackPUrgent, 240),

    DMM_GLOBAL_PRIORITY(DMM_154_SCAN, DMM_StackPNormal, 50),
    DMM_GLOBAL_PRIORITY(DMM_154_SCAN, DMM_StackPHigh, 190),
    DMM_GLOBAL_PRIORITY(DMM_154_SCAN, DMM_StackPUrgent, 215),

#if (CONFIG_PHY_ID == APIMAC_5KBPS_915MHZ_PHY_129 || CONFIG_PHY_ID == APIMAC_5KBPS_868MHZ_PHY_131)
    DMM_GLOBAL_PRIORITY(DMM_154_RXON, DMM_StackPNormal, 175),
#else
    DMM_GLOBAL_PRIORITY(DMM_154_RXON, DMM_StackPNormal, 80),
#endif
    DMM_GLOBAL_PRIORITY(DMM_154_RXON, DMM_StackPHigh, 80),
    DMM_GLOBAL_PRIORITY(DMM_154_RXON, DMM_StackPUrgent, 80),
};

dmm_priority_ble_154sensor.c – Default Global Priority Table for the dmm_154sensor_remote_display_app example

In this example, the BLE Peripheral is set to advertise at a 100ms interval while the TI 15.4-Stack Sensor is set to transmit a packet every three seconds. This means that for most of the time there will be no scheduling conflicts, and if one was to arise the TI 15.4-Stack Sensor would have higher priority. In theory, assuming ideal conditions, the TI 15.4-Stack Collector would never miss a TI 15.4-Stack Sensor packet while the BLE Peripheral is in advertising mode.

Connecting to the BLE Peripheral will for a moment change the application state which will result in a momentary increase in weight in addition to the GPT, making the TI 15.4-Stack Sensor low priority. Once the connection is established the application state will again change back to one where the TI 15.4-Stack Sensor has priority.

As the BLE peripheral connects to the central, the Bluetooth LE activity could increase depending on the negotiated interval. You can read about the connection interval negotiation in the BLE connection lab. This means that when connecting to the BLE Peripheral, we are more likely to get a conflict where the Bluetooth LE stack is denied radio access.

Bluetooth LE connection interval

The BLE peripheral has no control over the final connection interval as it is controlled by the BLE central.

The BLE peripheral being denied radio access is typically not an issue as it will always retry the transmission during the next connection interval. As long as the BLE peripheral is able to respond to one such event during the negotiated supervision timeout, the connection will remain active. If the BLE peripheral is denied radio access too many times and risks losing the connection to the central, the Bluetooth LE stack would update the stack GPT priority. It would start by raising the priority to "high" and if that is not enough, "urgent".

As noted earlier, an "urgent connection" in the scope of the GPT has the heaviest weight and as a result, this command would always succeed to run. This allows the Bluetooth LE stack to keep the connection alive, even if it is considered the lowest priority stack in the system. This is the strength of the GPT, allowing the user to consider special case scenarios in the stack without having to implement application logic to handle these using the application policy table.

This is illustrated in the packet diagram below where the aborted packets are in the background of the higher priority one. The diagram provide an example of what one could expect to happen depending on the state of the Bluetooth LE stack, being in an active connection or not.

Quiz

Which of the following aspects are important in the context of DMM when considering running two stack applications?

Task 3 – Enable Statistics

Let us setup our DMM project to observe some TI 15.4-Stack Sensor PER stats! The TI 15.4-Stack Sensor application already keeps track of some statistics, but we need to enable the printouts of these statistics. We do this by doing the following:

  1. Navigate to dmm_154sensor_remote_display_app.opts, found in TOOLS/defines/

  2. Find the define -DxDISPLAY_PER_STATS and change to -DDISPLAY_PER_STATS.

  3. Build project and flash the DMM device.

While already tracking PER percentage, the TI 15.4-Stack Sensor does not track the exact number of failed commands per default. We will need to modify the TI 15.4-Stack Sensor application to specify the numbers of failed packages.

Inside ssf.c, found under application/sensor/, navigate to the Ssf_displayPerStats() function and specify the number of packets which failed out of the total number attempted.

#if defined(DISPLAY_PER_STATS)
/*!
 * @brief       The application calls this function to print updated sensor stats to the display.
 */
void Ssf_displayPerStats(Smsgs_msgStatsField_t* pstats)
{
    int per;
    int failures = pstats->macAckFailures + pstats->otherDataRequestFailures;
    per = (100000 * failures) / (pstats->msgsSent + failures);

    CUI_statusLinePrintf(ssfCuiHndl, perStatusLine, "%d.%03d%%, %d failed of %d packets attempted",
                         (per / 1000), (per % 1000), failures, pstats->msgsSent + failures);
}
#endif /* DISPLAY_PER_STATS */

ssf.c – Ssf_displayPerStats()

Build and download the changed project to the DMM device. When pressing play, the terminal output from the device should look something like this:

Ideally, you should not see the TI 15.4-Stack Sensor missing any packages. Based on how our DMM policy table is setup, we would expect the TI 15.4-Stack Sensor to be of highest priority (almost) all of the time.

Messing With The Priorities

Now, let us see what happens if we alter the GPT to instead favor Bluetooth LE in DMM_154_DATA scenarios. We do this by modifying the dmm_priority_ble_154sensor.c file found under dmm/application_policy/ in the imported project.

/* Global Priority Table: BLE connection is lower than 15.4 data */
StackActivity activityBLE_bleL154SensorH[ACTIVITY_NUM_BLE*PRIORITY_NUM] =
{

    DMM_GLOBAL_PRIORITY(DMM_BLE_CONNECTION, DMM_StackPNormal, 100),
    DMM_GLOBAL_PRIORITY(DMM_BLE_CONNECTION, DMM_StackPHigh, 100),
    DMM_GLOBAL_PRIORITY(DMM_BLE_CONNECTION, DMM_StackPUrgent, 100),

    DMM_GLOBAL_PRIORITY(DMM_BLE_CON_EST, DMM_StackPNormal, 100),
    DMM_GLOBAL_PRIORITY(DMM_BLE_CON_EST, DMM_StackPHigh, 100),
    DMM_GLOBAL_PRIORITY(DMM_BLE_CON_EST, DMM_StackPUrgent, 100),

    DMM_GLOBAL_PRIORITY(DMM_BLE_BROADCASTING, DMM_StackPNormal, 100),
    DMM_GLOBAL_PRIORITY(DMM_BLE_BROADCASTING, DMM_StackPHigh, 100),
    DMM_GLOBAL_PRIORITY(DMM_BLE_BROADCASTING, DMM_StackPUrgent, 100),

    DMM_GLOBAL_PRIORITY(DMM_BLE_OBSERVING, DMM_StackPNormal, 100),
    DMM_GLOBAL_PRIORITY(DMM_BLE_OBSERVING, DMM_StackPHigh, 100),
    DMM_GLOBAL_PRIORITY(DMM_BLE_OBSERVING, DMM_StackPUrgent, 100),
};


StackActivity activity154_bleL154SensorH[ACTIVITY_NUM_154*PRIORITY_NUM] =
{

#if (CONFIG_PHY_ID == APIMAC_5KBPS_915MHZ_PHY_129 || CONFIG_PHY_ID == APIMAC_5KBPS_868MHZ_PHY_131)
    DMM_GLOBAL_PRIORITY(DMM_154_DATA, DMM_StackPNormal, 175),
#else
    DMM_GLOBAL_PRIORITY(DMM_154_DATA, DMM_StackPNormal, 50),
#endif
    DMM_GLOBAL_PRIORITY(DMM_154_DATA, DMM_StackPHigh, 50),
    DMM_GLOBAL_PRIORITY(DMM_154_DATA, DMM_StackPUrgent, 240),

    DMM_GLOBAL_PRIORITY(DMM_154_LINK_EST, DMM_StackPNormal, 100),
    DMM_GLOBAL_PRIORITY(DMM_154_LINK_EST, DMM_StackPHigh, 195),
    DMM_GLOBAL_PRIORITY(DMM_154_LINK_EST, DMM_StackPUrgent, 230),

    DMM_GLOBAL_PRIORITY(DMM_154_TX_BEACON, DMM_StackPNormal, 90),
    DMM_GLOBAL_PRIORITY(DMM_154_TX_BEACON, DMM_StackPHigh, 190),
    DMM_GLOBAL_PRIORITY(DMM_154_TX_BEACON, DMM_StackPUrgent, 240),

    DMM_GLOBAL_PRIORITY(DMM_154_RX_BEACON, DMM_StackPNormal, 90),
    DMM_GLOBAL_PRIORITY(DMM_154_RX_BEACON, DMM_StackPHigh, 190),
    DMM_GLOBAL_PRIORITY(DMM_154_RX_BEACON, DMM_StackPUrgent, 240),

#if (CONFIG_PHY_ID == APIMAC_5KBPS_915MHZ_PHY_129 || CONFIG_PHY_ID == APIMAC_5KBPS_868MHZ_PHY_131)
    DMM_GLOBAL_PRIORITY(DMM_154_FH, DMM_StackPNormal, 175),
#else
    DMM_GLOBAL_PRIORITY(DMM_154_FH, DMM_StackPNormal, 90),
#endif
    DMM_GLOBAL_PRIORITY(DMM_154_FH, DMM_StackPHigh, 190),
    DMM_GLOBAL_PRIORITY(DMM_154_FH, DMM_StackPUrgent, 240),

    DMM_GLOBAL_PRIORITY(DMM_154_SCAN, DMM_StackPNormal, 50),
    DMM_GLOBAL_PRIORITY(DMM_154_SCAN, DMM_StackPHigh, 190),
    DMM_GLOBAL_PRIORITY(DMM_154_SCAN, DMM_StackPUrgent, 215),

#if (CONFIG_PHY_ID == APIMAC_5KBPS_915MHZ_PHY_129 || CONFIG_PHY_ID == APIMAC_5KBPS_868MHZ_PHY_131)
    DMM_GLOBAL_PRIORITY(DMM_154_RXON, DMM_StackPNormal, 175),
#else
    DMM_GLOBAL_PRIORITY(DMM_154_RXON, DMM_StackPNormal, 80),
#endif
    DMM_GLOBAL_PRIORITY(DMM_154_RXON, DMM_StackPHigh, 80),
    DMM_GLOBAL_PRIORITY(DMM_154_RXON, DMM_StackPUrgent, 80),
};

dmm_priority_ble_154sensor.c – Modified Global Priority Table(s)

Looking at the modification above, we would expect the Bluetooth LE stack to have higher priority when the TI 15.4-Stack application is using DMM_154_DATA activity for all but "urgent" cases. Build and download the changed project to the DMM device and study the connection statistics of the TI 15.4-Stack Sensor once more.

The picture above show the new "worst case" scenario where the Bluetooth LE stack is entering a connected state and the communication is more frequent. We can see that the TI 15.4-Stack Sensor has experienced a failed packet. This indicates that there has been conflicts between the two stacks where the Bluetooth LE side was favored, just as we expect. Otherwise, the Bluetooth LE has missed events as well due to the GPT favoring TI 15.4-Stack activities.

Whether the TI 15.4-Stack Sensor missed an ACK from the TI 15.4-Stack Collector due to an interrupted RX or that the TI 15.4-Stack Senosr was not able to schedule an RX or TX command, it will still able to send the package at a later time. Furthermore, the TI 15.4-Stack application does not schedule transmissions at an absolute time which allows the DMM to postpone already scheduled commands to a later time in case of a conflict.

When missing an ACK from the Collector, the Sensor will try to re-transmit the packet a specific number of times before it is counted as a failed packet. The number of retries the TI 15.4-Stack Sensor will perform is defined by CONFIG_MAX_RETRIES inside application/sensor/advanced_config.c. If all of these retries fails, the TI 15.4-Stack Sensor will increase the "failed" statistic. The sync between Sensor and Collector nodes will be lost after consecutive failures exceeding the limit defined by CONFIG_MAX_DATA_FAILURES.

Feeling adventurous?

Try playing with the Global Priority Table to see how this would further impact the current modified project. What happens if you set the Bluetooth LE stacks' "urgent" priority values to be higher than those of the TI 15.4-Stack?

Congratulations!

You have successfully reached the end of the DMM Fundamentals lab. To learn even more about how to leverage the DMM and the SDK examples, see the other DMM trainings.
DMM Customizing Use Case – Shows how to modify an existing example to fit another use-case
DMM Integration – Shows how to create a DMM BLE project from scratch and how to integrate a proprietary stack along side it.

Creative Commons License
This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.