1. Introduction

This guide demonstrates the creation and usage of custom user-created GATT services and characteristics. For a simplified version of the GATT console, please refer to: GATT server console service

API: GATT server API

1.2 Features

• Ability to dynamically create GATT services and GATT characteristics.

• Variable-length characteristic value for GATT client read operations.

• Capability to easily identify characteristics during updates of characteristic values and upon data reception from GATT clients, using both UUIDs and user references.

• Ability to automatically send notifications to the subscribers when the characteristic value changes.

1.3 Limitations

The current implementation of a GATT server has the following limitations:

• Up to 10 services are available for creation

• Up to 13 characteristics are available for creation, of which up to 7 can be subscribable.

• Up to 40 GATT attributes can be used.

• Up to 200 bytes can be used for characteristic value/buffer update.

• Up to 220 bytes can be received from the GATT client.

• Memory pool for all characteristics is limited to 1112 bytes.

2. Steps to create a working GATT server

2.1 Initialising Bluetooth and GATT server

This step is needed to initialise Bluetooth and GATT callbacks.

2.2 Creating services and characteristics

Upon initialization, GATT services and characteristics may be registered in accordance with the GATT server architecture: initially, a service must be registered, followed by the registration of all characteristics associated with that service. Subsequently, additional services and their corresponding characteristics can be registered. It is important to note that only 128-bit (16-byte) UUIDs are supported.

The initial step involves registering a service, as characteristics cannot be registered independently.

To create a GATT service, call bt_gatt_service_create(uuid[]) function with the custom UUID buffer.

To create a GATT characteristic, call bt_gatt_chrc_create(uuid[], properties, chrc_val_size, user_ref). The UUID argument refers to the characteristic's assigned UUID. properties indicate available operations for that characteristic to the GATT client. The chrc_val_size parameter allocates memory for characteristics possessing the read attribute; a value of 0 is permissible only when this property is not used. user_ref helps to identify the characteristic when updating its value or receiving data from the GATT client. For more info refer to https://it.confluence.xirgo.com/wiki/spaces/MT/pages/679510071.

In the following example, two services are created: the first service includes a characteristic with the read property and a 10-byte buffer. The second service comprises one characteristic that exclusively sends notifications to the GATT client, while the other characteristic possesses the write property and solely receives data from the GATT client to the script callback.

This code results in the following GATT server architecture:

Open

2.3 Starting the GATT server

After all services and characteristics are created, gatt_server_start() must be called. This function registers all script services and makes them visible to the GATT client.

2.4 Enabling security (optional)

To enable level 4 GATT connection security with data encryption, a 6-digit passkey must be set. There are two ways to set it:

1. GATT server settings

   1. In GATT server settings, ensure that “Enabled” is selected in the “Passkey enable”.

   2. Enter the desired passkey in the field below.

Open

2. Script

   1. If the GATT server passkey needs to be set or modified in a script, untick the “Passkey enable” option to prevent the settings passkey from being applied.

      Open

      

       

   2. Use bt_gatt_server_passkey_set() function to set the passkey in the script.

2.5 Setting up advertisement

The connectable advertisement can be set up in two ways. When using a system service, the device automatically advertises its name in the scan response packet. If GATT settings or system services are not used, or custom advertisement data is needed, this can be configured via the script.

1. Using GATT server settings

   1. Enable a system service.

   2. In the “Advertised device name” field enter device name.

Open

2. Using script functions

   1. Set the desired advertisement data by using bt_adv_conn_data_set().

   2. Start the advertisement by using bt_adv_conn_start().

2.6 Operating the server

There are a few commands possible when the server is running:

1. Characteristic value can be updated. For this, two characteristic identification ways can be used:

   1. bt_gatt_chrc_update_by_uuid(uuid[], data[], data_length) - Uses the full UUID for the characteristic identification, updates value from the data buffer, limited with the data_length argument.

   2. bt_gatt_chrc_buf_update_by_ref(user_ref, data[], data_length)- Uses the user reference assigned in the bt_gatt_chrc_create() for characteristic identification, updates value from the data buffer, limited with the data_length argument.

2. Utilize the function bt_gatt_server_receive() to obtain data from the GATT client. Upon the client writing data to a characteristic, a BT_GATT_SERVER_RX callback is invoked, enabling the script to access the transmitted data.