6. The Bluetooth® Device Name

As we observed in the previous section, our device currently advertises the name DIALOG-TMPL. Chances are that you would like to use some other name for your product,

so let’s change it following these steps:

Open up the user_config.h file
Scroll down and change the definition of USER_DEVICE_NAME from DIALOG-TMPL to My Product:
```
/// Device name
#define USER_DEVICE_NAME        "My Product"
```
Build the project (F7)
Start and stop the debugger (press Ctrl + F5 twice) and use your BLE explorer app to verify that the device name has changed as intended

Show changed BD name in iOS

If you’re using a BLE explorer app on an iOS device, you may not immediately see the changed name due to iOS caching. To refresh and display the updated name, connect and disconnect from the device using the BLE explorer app. After scanning again, the new name should appear.

Add Unicode Emojis to Your Device Name!

The device name can contain Unicode emojis. Using colorful emojis in the device name can make it much easier to quickly identify your device in a scan list.

Now, change the device name to \xF0\x9F\x98\x8E

/// Device name
#define USER_DEVICE_NAME        "\xF0\x9F\x98\x8E"

Build the project and load it to target. You should be able to see the emoji as shown below (remember to clear the cache as described above if you are using an iOS based device):

Figure 13 Screen shot of the SmartBond app

You can find a bunch more emojis here: https://apps.timwhitlock.info/emoji/tables/unicode

6.1. Bluetooth® Device Name at runtime

Sometimes, you might want to create the device name during runtime. For example, if you wish to include a serial number in the advertised device name, you can dynamically construct it. In this example, we’ll keep things simple and hard-code a number, as reading from OTP is beyond the scope of this tutorial

A little bit of information on advertising data is appropriate at this time.Advertising data consists of a number of data segments each consisting of:

A one octet length field that contains the numbers of octets in the segment including the type, but excluding the length itself.
A one octet type field that specifies the type of data contained in the segment. The type options are listed in the gap.h file of the SDK as the enumeration gap_ad_type. The BD name type we used in the previous example was GAP_AD_TYPE_COMPLETE_NAME or 0x09
Any number of data bytes depending on the type field

The advertising data can contain multiple individual data segments that must all follow the rules listed above. The advertising data is limited to 31 octets and must 1 contain the flags (GAP_AD_TYPE_FLAGS) segment which leaves 28 octets for other usage. SDK6 automatically populates the flags segment.

_images/adv_data_format.png — Figure 14 The format of a single segment in the BLE advertising data

A scan response of 31 octets can be used to provide additional information to a Bluetooth® scanner. The scan response must also observe the rules listed above. Scan responses are returned to the scanner upon the reception of a scan request.

Now, back to changing the BD name at runtime. First, we will have to prevent the default construction of the advertising data by the SDK, and instead construct our own.

We do this by re-routing the callback from the default advertise operation to our user space:

In user_callback_config.h, modify:

static const struct default_app_operations user_default_app_operations = {
   .default_operation_adv = default_advertise_operation,
};

to this:

static const struct default_app_operations user_default_app_operations = {
   .default_operation_adv = user_advertise_operation,
};

Re-routing to user space, requires that we put a prototype for this function in user_empty_peripheral_template.h:
void user_advertise_operation(void);

We are now ready to implement our own function. We will retrieve the settings from the configuration file so that we only have to manage our desired changes.

In user_empty_peripheral_template.c implement our function as shown here:

void user_advertise_operation(void)
{
   // Copy the current default advertising data specified in user_config.h
   struct gapm_start_advertise_cmd* adv_cmd; // Retained version
   struct gapm_start_advertise_cmd* cmd;     // Version we send
   cmd = app_advertise_start_msg_create();   // Create an empty advertise start command

   // Get the advertising properties from the app_easy function
   adv_cmd = app_easy_gap_undirected_advertise_get_active();
   // Make a copy of the advertising properties
   memcpy(cmd, adv_cmd, sizeof(struct gapm_start_advertise_cmd));

   // Specify the advertise data (we are just changing the BD name)
   // Adv. data segment with length of 0x05, type is BD name and name is a Lady Bug emoji
   uint8_t adv_data[] = {0x05, GAP_AD_TYPE_COMPLETE_NAME, 0xF0, 0x9F, 0x90, 0x9E};
   cmd->info.host.adv_data_len = sizeof(adv_data);
   memcpy(&cmd->info.host.adv_data, &adv_data, sizeof(adv_data));

   // Send message to GAP task
   ke_msg_send(cmd);

   // We are now connectable
   ke_state_set(TASK_APP, APP_CONNECTABLE);
}

Build the project and load it onto target
Use your BLE explorer app to see if the device now advertises its Bluetooth® device name as a lady bug emoji

When connecting with the SmartBond app on an iOS device, the name on the info tab will be cached and still displays the smiley with shades emoji. This is because Bluetooth® peripherals expose their device name in 2 different contexts:

The advertised local BD name. This can either be the full name or a shortened version of the full name the SmartBond app will show this name in the scan list
The full local BD name which can be accessed during a Bluetooth® connection. This name field can be up to 248 characters long. The SmartBond app will show this on the info tab when connected

The changes we made above only affected the advertised device name. The full name has not been affected. To change the full name, we will need to do a little more work:

At the bottom of our newly implemented user_advertise_operation function in empty_peripheral_template.c, add the following code which will copy the relevant data into the full BD name:

// Copy the BD name from the advertising data (ignore the size and the type fields)
device_info.dev_name.length =  sizeof(adv_data) - 2;
memcpy(device_info.dev_name.name , &adv_data[2], device_info.dev_name.length);

Build the project and load it to target. You should see the lady bug emoji show up correctly in any BLE explorer app at this time.

BLE Explorer issues

You will notice that the various BLE Explorer apps have different issues when it comes to distinguishing between the advertised BD name and the full BD name. None of the apps make it clear what BD name they are displaying, and it is also unclear whether the displayed name is cached or not.

Footnotes:

1: The flags segment, GAP_AD_TYPE_FLAGS, is only mandatory in the advertising data when a BLE peripheral is connectable. This leaves 31 octets available in non-connectable implementations