1. Import the Host Test project in CCS from the blestack example folder in the SDK.

2 In the Stack Library project, open TOOLS → build_config.opt. You will need to enable GAP Bond Manager by defining the following line:

/* Include GAP Bond Manager */
-DGAP_BOND_MGR

3. Build the Stack/Stack Library project and flash the host_test app project.

4. Open BTool and open the COM Port associated with your Host Test device. If you are new to BTool, review the basic usage in the Bluetooth 4.2 Basics lab.

After the intial Host Test setup is done, we will configure the GAP Bond Manager parameters to enable Just Works Pairing.

5. Click the Adv. Commands tab and expand the GAP section. Scroll down the list until you find the GAP_BondSetParam command. Click on the command to display the parameters below.

6. In the paramID field, select GAPBOND_PAIRING MODE. Set value to "02". This is value for GAPBOND_PAIRING_MODE_INITIATE. Using this mode will allow our Central device to send a Pairing Request when a connection has been formed. Hit the "Send Command" button to set this parameter in the GAP Bond Manager.

7. In the paramID field, select GAPBOND_IO_CAPABILITIES. Set value to "03". This is value for GAPBOND_IO_CAP_NO_INPUT_NO_OUTPUT. This will set the IO Capabilities we want to send in our pairing request. Hit the "Send Command" button to set this parameter in the GAP Bond Manager.

8. In the Discover/Connect tab, scan for devices. When the GAP_DeviceDiscoveryDone event is received, look through the list for a device matching the Project Zero address displayed in your PuTTY window.

9. In the Establish Link Slave BDA list, select your Project Zero device and click "Establish". Once a connection is formed, click the Pairing Bonding tab and ensure that the Bonding Enabled and the Authentication (MITM) Enabled box are unchecked. Click Send Pairing request and the devices will begin the pairing process. When the link is encrypted, you will receive a GAP_AuthenticationComplete event with a status of Success in BTool and the Project Zero PuTTY window will display "Pairing completed sucessfully."

10. In BTool, close the Host Test COM Port by selecting Device – Close Device.

1. Using your iOS device, find the LightBlue Explorer app (or any Bluetooth Client application you prefer) & open it.

2. The app should begin scanning for BLE devices automatically but you can refresh the list by pulling down.

3. You should see Project Zero advertising as "Project Zero R2". Connect to the device by clicking on the name.

4. After connecting, your serial window will look something like this:

Great! We've connected. However, this behavior seems identical to the unmodified behavior of Project Zero. So what gives?

iOS devices do not send pairing requests automatically and encryption cannot be requested from the mobile app.

Does this mean iOS devices do not support encryption? No, but it takes a special prompt to get the iOS device to initiate a pairing request. According to the Apple Bluetooth Accessory Design Guidelines for Apple Products in order to prompt the Apple device to send a pairing request:

"the Peripheral should reject [a] ATT request using the Insufficient Authentication error code, as appropriate."

We will go through this exercise in the next task.

1. Start BLE Scanner

Using your Android device, find the BLE Scanner app and open it.

2. Scan for BLE devices

The app should begin scanning for BLE devices automatically but you can toggle scanning on and off by clicking on the magnifying glass in the top right corner of the app. A "Scanning stop" message will appear.

3. Connect to Project Zero

You should see Project Zero advertising as "Project Zero R2". Connect to the device by clicking "Connect".

After connecting, your serial window will look something like this:

Great! We've connected. However, this behavior seems identical to the unmodified behavior of Project Zero. So what gives?

Android Bluetooth behavior varies depending on device and application used.

Some devices allow you to pair directly from the app, some require you to initiate pairing through the Bluetooth settings. Refer to Android development guidelines when you are designing your embedded experience.

Using the slave Security Request procedure may work with some Android devices and not others. To achieve the best interoperability, it is advised to use an characteristic permissions to prompt the Android device to send a Pairing Request.

We will go through this exercise in the next task.

1. Reopen the connection to your Host Test device in BTool.

2. Without performing any additional setup, scan and connect to Project Zero. This time, the GAP_AuthenticationComplete event does not follow the GAP_EstablishLink event.

3. Perform a GATT Discovery by right-clicking on the Handle in Connection Info and selecting Discover UUIDs.

4. After receiving the ATT_FindInfoRsp event with a status of 0x1A (The Procedure is Completed), scroll through the GATT Table at the bottom of BTool and find the String Char.

5. Read the value of the characteristic by clicking in the Value field for the String Char. An error message stating you have insufficient authentication to read this characteristic will occur.

6. Click the Pairing/Bonding tab. Make sure bonding and MITM are not enabled, then click Send Pairing Request.

7. Single-click on the String Char value field. This time, the message "This is a pretty long string, isn't it!" will display in the value field.

8. In BTool, close the Host Test COM Port by selecting Device – Close Device.

1. Connect to Project Zero using LightBlue Explorer.

2. Find the Characteristic with the Data Service String Characteristic UUID. (For a refresher on this, see Bluetooth 4.2 Basics)

3. Click on the Characteristic with the Data Service String Characteristic UUID.

4. Now a window asking you to pair the devices will pop up. Accept the pairing prompt by clicking "Pair". When the pairing process has completed, the Project Zero terminal window will display "Pairing completed successfully".

5. Click "Read Again". This time, a value will display under "Cloud Connect". Click "Hex" in the top right corner of the app. Now you can switch between display formats. Select UTF-8 to see the value as a string.

1. Connect to Project Zero using BLE Scanner

2. Find the Characteristic with the Data Service String Characteristic UUID. (For a refresher on this, see Bluetooth 4.2 Basics)

3. Click on the circled R next to the Data Service String Characteristic UUID to read the value of the newly encrypted characteristic.

The following message should appear in your terminal window:

4. Now that we have an encrypted link, try reading the characteristic value again by pressing on the R button again. Now the value of the String Characteristic should display in BLE Scanner:

1. BTool will automatically send the default passkey (000000) to the controller. Therefore you must revert the changes done above in ProjectZero and set the default passkey back to "000000".

    case APP_MSG_SEND_PASSCODE: /* Message about pairing PIN request */
      {
        passcode_req_t *pReq = (passcode_req_t *)pMsg->pdu;
        Log_info2("BondMgr Requested passcode. We are %s passcode %06d",
                  (IArg)(pReq->uiInputs?"Sending":"Displaying"),
                  DEFAULT_PASSCODE);
        // Send passcode response.
        GAPBondMgr_PasscodeRsp(pReq->connHandle, SUCCESS, DEFAULT_PASSCODE);
      }
      break;

2. Use BTool to discover and connect to Project Zero.

3. In the Pairing/Bonding tab, select "Authentication Enabled", and initiate pairing. Connect to Project Zero device. BTool may automatically send the default passcode (000000) to the controller. If BTool does not automatically send the default passcode, then fill in the Passkey field with the default passcode(000000) and click Send PassKey

1. Connect to Project Zero using LightBlue Explorer.

2. Find the Characteristic with the Data Service String Characteristic UUID.

3. Click on the Characteristic with the Data Service String Characteristic UUID.

4. Now a window asking you to pair the devices will pop up. This time, a passkey entry field will appear. Check the ProjectZero terminal window for the random passcode. Accept the pairing prompt by typing the code in the passkey box. When the pairing process has completed, the Project Zero terminal window will display "Pairing completed successfully".

5. Click "Read Again". This time, a value will display under "Cloud Connect". Click "Hex" in the top right corner of the app. Now you can switch between display formats. Select UTF-8 to see the value as a string.

1. Connect to Project Zero using BLE Scanner

2. Read the Encrypted Data Service String Characteristic as done in Task 2.

3. Now a window asking you to pair the devices will pop up. This time, a passkey entry field will appear. Check the ProjectZero terminal window for the random passcode. Accept the pairing prompt by typing the code in the passkey box as presented in the Project Zero terminal window.

4. When the pairing process has completed, the Project Zero terminal window will display "Pairing completed successfully" and you will be able to read your Encrypted Characteristic as in Task 2.

1. Use BTool to discover and connect to Project Zero

2. In the Pairing/Bonding tab, select "Bonding Enabled", "Authentication Enabled", and initiate pairing. Connect to Project Zero device. BTool will automatically send the correct passcode (000000) to the controller.

3. After receiving the "Bond Save Success" message in your Project Zero terminal window, enable notifications on the Button Service by writing "01:00" to the Button0 Client Characteristic Configuration handle in BTool.

4. Verify that notifications are being sent by pressing the right button on the LaunchPad and observing the Value of the Button0 State characteristic. When the button is pressed, the value should be 01. When the button is released, the value should be 0.

5. Disconnect from Project Zero.

7. Reconnect to the Project Zero device. Now you should receive a "WriteAttrCB (CCCD): param: 1 connHandle: 0 - restoring bonded state" message in your Project Zero terminal window.

8. Press a Button - notification will be sent without having to re-enable.

1. Connect to Project Zero using LightBlue Explorer.

2. Follow steps in Task 3 to pair with Project Zero using the Passkey Entry method.

3. After receiving the "Pairing completed successfully" message, disconnect from Project Zero.

4. Reconnect to Project Zero. This time, the Project Zero terminal window will display a new message: "Re-established pairing from stored bond info."

5. Read the Encrypted Data Service String Characteristic. This time, the value will display without needing to re-enter the passkey.

1. Connect to Project Zero using BLE Scanner

2. Follow steps in Task 3 to pair with Project Zero using the Passkey Entry method.

3. After receiving the "Pairing completed successfully" message, disconnect from Project Zero.

4. Reconnect to Project Zero. This time, the Project Zero terminal window will display a new message: "Re-established pairing from stored bond info."

5. Read the Encrypted Data Service String Characteristic. This time, the value will display without needing to re-enter the passkey.

1. Use GAP_ConfigDeviceAddr to configure Project Zero to use a Resolvable Private Address. GAP_ConfigDeviceAddr must be called after receiving the GAP_DEVICE_INIT_DONE_EVENT but before any BLE activity. A good place for this is in the gapRole_processGAPMsg function of peripheral.c after gapRole_state = GAPROLE_STARTED;:

    gapRole_state = GAPROLE_STARTED;

    stat = GAP_ConfigDeviceAddr(ADDRMODE_PRIVATE_RESOLVE, NULL);

    if (stat != SUCCESS)
    {
        gapRole_state = GAPROLE_ERROR;
    }

    // Update the advertising data
    stat = GAP_UpdateAdvertisingData(selfEntity,
                        TRUE, gapRole_AdvertDataLen, gapRole_AdvertData);

2. To change the timeout value between address changes, use GAP_SetParamValue to set the TGAP_PRIVATE_ADDR_INT parameter. The value is in minutes:

    //Set timeout value to 5 minute
    GAP_SetParamValue( TGAP_PRIVATE_ADDR_INT , 5);

3. In GAP Bond Manager initialization, use same settings as in previous task:

  // ******************************************************************
  // BLE Bond Manager initialization
  // ******************************************************************
  uint32_t passkey = 0; // passkey "000000"
  uint8_t pairMode = GAPBOND_PAIRING_MODE_WAIT_FOR_REQ;
  uint8_t mitm = TRUE;
  uint8_t ioCap = GAPBOND_IO_CAP_DISPLAY_ONLY;
  uint8_t bonding = TRUE;

  GAPBondMgr_SetParameter(GAPBOND_PAIRING_MODE, sizeof(uint8_t), &pairMode);
  GAPBondMgr_SetParameter(GAPBOND_MITM_PROTECTION, sizeof(uint8_t), &mitm);
  GAPBondMgr_SetParameter(GAPBOND_IO_CAPABILITIES, sizeof(uint8_t), &ioCap);
  GAPBondMgr_SetParameter(GAPBOND_BONDING_ENABLED, sizeof(uint8_t), &bonding);

4. Use BTool to discover Project Zero. The ProjectZero now use a resolvable private address generated from its Identity Address and it's local IRK. The address presented on the ProjectZero terminal window is the identity address. We don't know the generated RPA used, therefore you must search through the BTool log to find the GAP_ADTYPE_LOCAL_NAME_COMPLETE that is sent in the ProjectZero advertising payload and find the corresponding matching random address. This is illustrated in the screen shot below where "Project Zero R2" is found in the advertising payload.

5. Use BTool to connect to Project Zero. Make sure to select the address found from the step above and select the correct address type as shown below (0x01 ADDRTYPE RANDOM). If you try to connect with the wrong AddrType you might have to restart BTool and start over. You may also have to restart Project Zero.

6. In BTool, Send pairing request with Bonding Enabled and Authentication (MITM) Enabled checked. The default Passkey should be sent automatically. If not, enter the correct passkey and press "Send Passkey".

7. In your Project Zero terminal window, the "Pairing completed successfully." message will display. In BTool, you will receive GAP_AuthenticationComplete with a status of SUCCESS. In the Long-Term Key Data section, save the data to a file and disconnect from Project Zero.

8. Scan again for device. This time, the Address Type shown in BTool should be Public ID - which indicates that the controller has resolved the private address to an identity address by using the stored IRK.

9. Reconnect to the Project Zero device. Remember to make sure the correct Address Type is set (0x02 ADDRTYPE PUBLIC ID).

iOS does not display peer address information at the application level. In order to complete this exercise, we will switch our Project Zero device to run the Host Test application and use our iOS device in peripheral mode to demonstrate RPA usage.

1. Import the Host Test project from <SDK_INSTALL_PATH> → examples → rtos → CC2640R2_LAUNCHXL → blestack → host_test into CCS

2. The Host Test project does not use the GAP Bond Manager by default. To enable the Bond Manager, open TOOLS → build_config.opt in the Host Test Stack Library project. Uncomment the -DGAP_BOND_MGR line as shown below:

/* Include GAP Bond Manager */
-DGAP_BOND_MGR

3. Build the Stack Library project then build and flash the Host Test app project.

4. Open BTool located in the <SDK_INSTALL_PATH> → tools → blestack → btool directory.

5. Open the COM port for your LaunchPad. If you still have a terminal window open from a previous task, you will need to close it first.

6. In your iPhone settings, clear bonds from the previous task by going to Settings → Bluetooth. Remove the bond by tapping the info button next to the "Project Zero R2" device listing and selecting Forget This Device.

7. Open LightBlue and create a Virtual Peripheral with a Characteristic that has a Notify property. We will demonstrate with the default Heart Rate Peripheral. Start advertising by clicking the circle to the left of the Peripheral name.

8. In order to keep the connection to the iOS device alive, we will need to quickly encrypt the connection. However, to avoid a Link Layer collision with an iOS control procedure (Version Exchange), we cannot initiate encryption immediately upon connection. This means we cannot use the GAPBOND_PAIRING_MODE_INITIATE setting. Instead, we will initiate the pairing process by using the GAP_Authenticate command. We will set the GAP_Authenticate parameters as follows:

9. Use the Scan button in the Discover/Connect tab to discover your mobile device. The scan results will display in the log section of BTool. Find the entry that shows the name of the Peripheral you are advertising as in the Rx dump.

10. In the Link Control section, select the Slave BDA (Bluetooth Device Address) that is in the GAP_DeviceInformation Event.

11. When the connection has established, go to the Adv. Commands tab and issue the GAP_Authenticate command that you set up in step 11.

12. When the the Connection Info will appear in the right-pane of the BTool window. Right-click on the Handle and select Discover UUIDs.

13. The Service Discovery will take place and the GATT table for the Peripheral will appear in the bottom of the BTool window.

14. Double click on the last characteristic handle for the Heart Rate Measurement CCCD and write a value of 01:00 to enable notifications. If notifications are successfully enabled, the BTool log will begin reporting the current Heart Rate Measurement value as shown below:

15. Save the BTool log to retrieve the LTK that will be used to restore encryption by right-clicking in the BTool log window and selecting "Save Log".

16. Open the btool log in your favorite text editor and search for the string "GAP_AuthenticationComplete". This event contains the LTK that you will need to restore encryption upon a reconnection as well as the Identity Address that can now be resolved. If your BTool log does not contain this string, repeat steps 10-15 again.

17. Disconnect from the iOS device by clicking the Terminate button in the Discover/Connect tab.

18. To restore encryption without pairing, we will need to issue the GAP_Bond command after connecting. In order to do this quickly, we will pre-set the parameters using what was given to us in the GAP_AuthenticationComplete event:

19. We will also want to write to the previously discovered CCCD to keep the connection alive. You can preset the values in the Read/Write tab to quickly issue this command.

20. Discover devices by clicking the Scan button in the Discover/Connect tab. Now, the results will display using the Identity Address and Address Type exchanged during the pairing process.

21. Reconnect by selecting the corresponding Slave BDA and clicking Establish.

22. After the connection has established, go to the Adv. Commands tab and restore encryption by issuing the GAP_Bond command as set up in Step 19.

23. Re-enable notifications by writing to the Heart Rate Measurements CCCD as set up in Step 20.

24. If everything was issued correctly, you should begin receiving ATT_HandleValueNotifications with the current value of the Heart Rate Measurement characteristics.

1. Use GAP_ConfigDeviceAddr to configure Project Zero to use a Resolvable Private Address. GAP_ConfigDeviceAddr must be called after receiving the GAP_DEVICE_INIT_DONE_EVENT but before any BLE activity. A good place for this is in the gapRole_processGAPMsg function of peripheral.c (in the Profiles folder) after gapRole_state = GAPROLE_STARTED;:

    gapRole_state = GAPROLE_STARTED;

    stat = GAP_ConfigDeviceAddr(ADDRMODE_PRIVATE_RESOLVE, NULL);

    if (stat != SUCCESS)
    {
        gapRole_state = GAPROLE_ERROR;
    }

    // Update the advertising data
    stat = GAP_UpdateAdvertisingData(selfEntity,
                        TRUE, gapRole_AdvertDataLen, gapRole_AdvertData);

2. To change the timeout value between address changes, use GAP_SetParamValue to set the TGAP_PRIVATE_ADDR_INT parameter. The value is in minutes:

    //Set timeout value to 5 minute
    GAP_SetParamValue( TGAP_PRIVATE_ADDR_INT , 5);

3. In GAP Bond Manager initialization, use same settings as in previous task:

  // ******************************************************************
  // BLE Bond Manager initialization
  // ******************************************************************
  uint32_t passkey = 0; // passkey "000000"
  uint8_t pairMode = GAPBOND_PAIRING_MODE_WAIT_FOR_REQ;
  uint8_t mitm = TRUE;
  uint8_t ioCap = GAPBOND_IO_CAP_DISPLAY_ONLY;
  uint8_t bonding = TRUE;

  GAPBondMgr_SetParameter(GAPBOND_PAIRING_MODE, sizeof(uint8_t), &pairMode);
  GAPBondMgr_SetParameter(GAPBOND_MITM_PROTECTION, sizeof(uint8_t), &mitm);
  GAPBondMgr_SetParameter(GAPBOND_IO_CAPABILITIES, sizeof(uint8_t), &ioCap);
  GAPBondMgr_SetParameter(GAPBOND_BONDING_ENABLED, sizeof(uint8_t), &bonding);

4. Rebuild the project and flash your LaunchPad

5. Open BLE Scanner and look for Project Zero advertising. This time, you will notice that the address that is advertised does not match what is in the Project Zero terminal window. In BLE Scanner, you see the Random Private Address that the CC2640R2 is currently using. In the terminal window, you see the same address from the previous tasks.

6. Hit the LaunchPad reset button. You will see a new Project Zero R2 device advertise. After a few seconds, the old Project Zero address will disappear as the scanner no longer sees the old RPA. You can also refresh the scan list manually by pulling down on the device list. Notice, the Identity Address displayed in the Project Zero terminal window does not change.

7. Connect and bond to Project Zero using the process detailed in Task 4.

8. Disconnect and return to the Near By devices view. Now, if you hit the reset button on the LaunchPad, the device continues to display the same address. This is because, no matter what address the LaunchPad uses, the phone is able to resolve the Private Address to its Identity Address using the IRK exchanged during bonding. It is able to recognize and remember the device, even after the RPA has changed.

9. Reconnect to Project Zero and disconnect a couple times. Observe the Peer Address in the terminal window on the initial connection, before bonding, to the Peer Address on the connections after bonding. Project Zero is also able to resolve the RPA that the phone is using to its Identity Address after bonding.

10. Depending on your mobile device and OS, you may be able to confirm the Bluetooth Identity Address being used. Look up the instructions for finding the Bluetooth device address on your device.

Congrats! You have created a Project Zero that cannot be tracked except by the phone you have bonded to. Look up device specific instructions to clear BLE bonding information from your phone if you wish to try this task again.

In the BTool and Android instructions, Privacy and RPA is enabled on ProjectZero. It is possible to read the local address with HCI_LE_ReadLocalResolvableAddressCmd. Please refer to the TI BLE-Stack for Bluetooth 4.2 API Documentation for more information. The code snippets below will print the first RPA used after boot.

// Display device address
char *cstr_ownAddress = Util_convertBdAddr2Str(ownAddress);
Log_info1("GAP is started. Our address: \x1b[32m%s\x1b[0m", (IArg)cstr_ownAddress);

HCI_LE_ReadLocalResolvableAddressCmd();

// Process HCI message
switch(pMsg->status)
{
    case HCI_COMMAND_COMPLETE_EVENT_CODE:
    // Process HCI Command Complete Event
    Log_info0("HCI Command Complete Event received");

    hciEvt_CmdComplete_t *pMsgHci = (hciEvt_CmdComplete_t*) pMsg;

    //Find which command this command complete is for
    switch (pMsgHci->cmdOpcode)
    {
        case HCI_LE_READ_LOCAL_RESOLVABLE_ADDRESS:

        if (pMsgHci->pReturnParam[0] == HCI_SUCCESS)
        {
            // Copy RPA.
            uint8_t localRpa[6];
            memcpy(localRpa, &(pMsgHci->pReturnParam[1]), 6);
            uint8_t *pLocalRpa = localRpa;

            // Convert byte array to string START
            uint8_t charCnt;
            char hex[] = "0123456789ABCDEF";
            static char str[(2 * 6) + 3];
            char *pStr = str;

            *pStr++ = '0';
            *pStr++ = 'x';

            // Start from end of addr
            pLocalRpa += 6;

            for (charCnt = 6; charCnt > 0; charCnt--)
            {
                *pStr++ = hex[*--pLocalRpa >> 4];
                *pStr++ = hex[*pLocalRpa & 0x0F];
            }
            // Convert byte array to string STOP

            Log_info0("RPA read SUCCESS");
            Log_info1("Local RPA: \x1b[32m%s\x1b[0m",
                    (IArg )str);
        }
        else
        {
            Log_info0("RPA read FAIL");
        }
        break;

        default:
        break;
    }
    break;

    default:
    // do nothing
    break;
}