Note: This KBA has been marked as deprecated. A more updated KBA and example can be found here:

Different Value Types of Characteristics

Different Value Types of Characteristics Example

This article is about the differences among the types of a characteristic value. In the profile toolkit, there are 3 types of value can be used, hex, utf-8 and user. You can find detailed description in UG118, chapter 2.5.3.

Values:
hex: Value type is hex
utf-8: Value is a string
user: When the characteristic type is marked as type="user" the application is responsible of initializing the characteristic value and also providing it for example when read operation occurs. The Bluetooth stack does not initialize the value, nor automatically provide the value when it's being read. When this is set the Bluetooth stack generates gatt_server_user_read_request or gatt_server_user_write_request which must be handled by the application.
Default: utf-8

Introduction

The idea of this article is to give both examples of type "user" and "hex" to help users choosing the right property of a characteristic value.

The most significant difference between the type “user” and the other two types is where the data is stored.

• Type – user

If you use "user" as the data type, the value of the characteristic is stored in the application layer. And you need to respond to write/read requests by sending write/read response back via API gecko_cmd_gatt_server_send_user_read_response(…) and gecko_cmd_gatt_server_send_user_write_response(…).

For example, there is a characteristic with length 20, you need to allocate a 20-byte buffer in the application layer to store its value.

• When read request received, gecko_evt_gatt_server_user_read_request_id event is generated, you should respond the buffer value via gecko_cmd_gatt_server_send_user_read_response(…)
• When write request received, gecko_evt_gatt_server_user_write_request_id event is generated, you should modify the local buffer with the data in write request and respond it via gecko_cmd_gatt_server_send_user_write_response(…)

• Type – hex or utf-8
  
  If you use the property other than "user", the stack will allocate and manage the buffer for the characteristic value automatically.
  • When read request received, the read response will be filled with the characteristic value and sent back to the peer device all by the stack.
  • When received write request, the stack will modify the characteristic value and generate a gecko_evt_gatt_server_attribute_value_id  event to notify the user.
  • If you want to read or write the characteristic value locally, use these 2 APIs gecko_cmd_gatt_server_read_attribute_value(...) and gecko_cmd_gatt_server_write_attribute_value(...). 

2 Notes: 

1. DO NOT use the APIs gecko_cmd_gatt_server_read_attribute_value(...) and gecko_cmd_gatt_server_write_attribute_value(...) to read or write a characteristic value whose type is "user", because the data buffer is in your application code and stack never knows its value.
2. DO NOT forget to respond to the read and write requests if the characteristic value type is “user”, otherwise no other GATT operation can be issued until GATT timeout.

Example

IDE – Simplicity Studio 4

Software -  Bluetooth SDK v2.7.0 or newer

Hardware – Bluetooth Compatiable Boards

1. Create “SoC-Empty” example as the starting point and specify the project name and compiler (GCC or IAR).
2. Open the .isc file in the project, modify the GATT database. In this example, one service and two characteristics are added into the GATT database.

• User type characteristic – the value type is “user”, its properties are “read” and “write”
• Hex type characteristic – the value type is “hex”, its properties are “read” and “write”
• Because the type “utf-8” has the same operation procedure as “hex”, there is no other characteristic with “utf-8” type.

Note: DO NOT FORGET TO CLICK “GENERATE” BUTTON AFTER YOU MODIFY THE FILE.

1. Copy and paste the main.c app.c and app.h files to your project root directory.

Test the example

The example code shows where to handle the read and write requests to the characteristic with user type, as well as the event generated by write request to the characteristic with hex/utf-8 type.

Follow below steps to test the example:

• Build and program the project to the specified board
• Use Blue Gecko app to connect
• Try to read and write the 2 characteristics and think why the initial value of these 2 characteristics are different, where the initial value is set?

Conclusion

When to use "user" and when to use "hex"?

• Type hex/utf-8
  • Advantage – Stack will handle the read and write request to the characteristics
  • Disadvantage – User has to use BlueGecko APIs to read and write the value locally
• Type user
  • Advantage – The buffer storing the characteristic value is in the application layer, it’s easier to read and modify the value.
  • Disadvantage – User must respond to the read and write requests by calling BlueGecko APIs. If user doesn’t do it, no other GATT operation can be issued until GATT timeout.