bt_gatt_chrc_create()

Description

Function to create a GATT characteristic in a GATT service. Only 128-bit (16-byte) UUIDs are available for creation.

GATT server is limited to 40 attributes, 10 services, 13 characteristics of which 7 can be used for notifications. Also a 1112-byte memory pool is shared among all characteristics where chrc_value_size is used.

Take note that system services also use these limits. Refer to the system services page for more information.

It is required to create at least one GATT service prior to the creation of any GATT characteristic.

Syntax

bt_gatt_chrc_create(chrc_uuid[], properties, chrc_value_size, user_reference);

Parameters

Variable	Input

Variable	Input
`chrc_uuid[]`	Characteristic UUID. Must up to 16 bytes (128-bits) length.
`properties`	Characteristic properties allow certain characteristic operations to be permitted. Multiple properties can be set by using `\|` (logical “OR” operation) symbol. Available characteristic properties are listed below.
`chrc_value_size`	Characteristic value size. This argument reserves the specified number of bytes for this characteristic. Maximum value is 200 bytes. Value must be higher than `0` if the characteristic has a `read` property, but can be `0` if a characteristic only has `notify` or `write` properties.
`user_reference`	Optional user-defined characteristic reference. Range: 1-240 or 0 to disable. References must be unique if used. This reference could be used as an argument to update characteristic values and when reading data received from the GATT client.

Characteristic properties

Property	Value	Description

Property	Value	Description
`GATT_CHRC_PROP_NONE`	0x00	Characteristic with no properties.
`GATT_CHRC_PROP_READ`	0x02	Allows reading of the characteristic value.
`GATT_CHRC_PROP_WRITE_NO_RESP`	0x04	Allows writing to the characteristic value without waiting for a response.
`GATT_CHRC_PROP_WRITE`	0x08	Allows writing to the characteristic value.
`GATT_CHRC_PROP_NOTIFY`	0x10	Allows subscribing to receive notifications when the characteristic value changes.
`GATT_CHRC_PROP_INDICATE`	0x20	Allows subscribing to receive indications when the characteristic value changes.
`GATT_CHRC_PROP_AUTH`	0x40	Allows signed writes to the characteristic, requests authentication.

Returns

Return value	Return explanation
SCRIPT_OPERATION_SUCCESS	Successfully created a GATT characteristic.
SCRIPT_OPERATION_FAILED	Failed to create a GATT characteristic. Reasons: Trying to create a characteristic when no script service was registered first. Trying to create a characteristic to GATT console service. Requested characteristic value buffer is too large. The server's mempool size limits were exceeded. GATT server characteristic or attribute count was exceeded.
SCRIPT_NO_ACCESS	Bluetooth gatt server is not initialized.
SCRIPT_PARAM_INVALID	Reasons: Trying to create a characteristic with read permissions with invalid characteristic value size. Reference ID out of range. Trying to create a characteristic with a reserved UUID. Reserved UUID list: https://it.confluence.xirgo.com/wiki/x/AYBDKg

Function call example

#include <io>
#include <read>
#include <float>
#include <string>
#include <core>
#include <write>
#include <define>
#include <socket>
#include <bluetooth>

new service_uuid[UUID_LENGTH_128_BIT] = [0x08, 0x07, 0x06, 0x05, 0x00, 0x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0x80, 0x5F, 0x9B, 0x34, 0xFB];
new chrc_uuid_1[UUID_LENGTH_128_BIT] = [0x05, 0x12, 0x96, 0x99, 0x00, 0x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0x80, 0x5F, 0x9B, 0x34, 0xFB];
new chrc_uuid_2[UUID_LENGTH_128_BIT] = [0x05, 0x12, 0x97, 0x99, 0x00, 0x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0x80, 0x5F, 0x9B, 0x34, 0xFB];
new chrc_reference_2 = 2;

main()
{   
    bt_init();
    bt_gatt_server_init();
    bt_gatt_service_create(service_uuid);
    bt_gatt_chrc_create(chrc_uuid_1, GATT_CHRC_PROP_READ | GATT_CHRC_PROP_NOTIFY, 20, 0);
    bt_gatt_chrc_create(chrc_uuid_2, GATT_CHRC_PROP_WRITE, 0, chrc_reference_2);
    
    for(;;)
    {
        Delay(100);
    }
}