Declaring a characteristic

A Characteristic must only be declared inside a Service. It belongs to the most recently declared Service, so the GATT Database must always begin with a Service declaration.

The Characteristic declaration attribute has the following UUID, as defined by the Bluetooth SIG:

  • 0x2803 a.k.a. <<Characteristic>>

The Characteristic declaration attribute value contains:

  • the Characteristic UUID

  • the Characteristic Value ’s declaration handle

  • the Characteristic Properties – Read, Write, Notify, and so on. (1 byte of flags)

The Characteristic Rangestarts from the Characteristic declaration and ends before a new Characteristic or a Service declaration.

After the Characteristic declaration these follow:

  • A Characteristic Value declaration (mandatory; immediately after the Characteristic declaration).

  • Zero or more Characteristic Descriptor declarations.

Characteristic declaration macros

The following macros are used to declare Characteristics:

  • CHARACTERISTIC (name, uuid16, properties)

  • CHARACTERISTIC_UUID32 (name, uuid32, properties)

  • CHARACTERISTIC _UUID128 (name, uuid128, properties*)***

See Service declaration for uuidXXX parameter explanation.

The properties parameter is a bit mask. The flags are defined in the gattCharacteristicPropertiesBitFields_t.

Parent topic:Declaring a characteristic

Declaring characteristic values

The Characteristic Value declaration immediately follows the Characteristic declaration and uses one of the following macros:

  • VALUE (name, uuid16, permissions, valueLength, valueByte1, valueByte2, …)

  • VALUE_UUID32 (name, uuid32, permissions, valueLength, valueByte1, valueByte2, …)

  • VALUE _UUID128(name, uuid128, permissions, valueLength, valueByte1, valueByte2, …)

    • See Declaring a service for description of the uuidXXX parameter.

    • The permissions parameter is a bit mask, whose flags are defined in gattAttributePermissionsBitFields_t .

    • The valueLength is the number of bytes to be allocated for the Characteristic Value. After this parameter, exactly [valueLength ] bytes follow in 0xZZ format, representing the initial value of this Characteristic.

These macros are used to declare Characteristic Values of fixed lengths.

Some Characteristics have variable length values. For those, the following macros are used:

  • VALUE_VARLEN (name, uuid16, permissions, maximumValueLength, initialValueLength, valueByte1, valueByte2, …)

  • VALUE_UUID32_VARLEN (name, uuid32, permissions, maximumValueLength, initialValueLength, valueByte1, valueByte2, …)

  • VALUE_UUID128_VARLEN (name, uuid128, permissions, maximumValueLength, initialValueLength, valueByte1, valueByte2, …)

    • The number of bytes allocated for this Characteristic Value is maximumValueLength.

    • The number of valueByteXXX parameters shall be equal to initialValueLength.

Obviously, initialValueLength is, at most, equal to maximumValueLength.

Parent topic:Declaring a characteristic

Declaring characteristic descriptors

Characteristic’s Descriptors are declared after the Characteristic Value declaration and before the next Characteristic declaration.

The macros used to declare Characteristic Descriptors are very similar to those used to declare fixed-length Characteristic Values:

  • DESCRIPTOR (name, uuid16, permissions, descriptorValueLength, descriptorValueByte1, descriptorValueByte2, …)

  • DESCRIPTOR_UUID32 (name, uuid32, permissions, descriptorValueLength, descriptorValueByte1, descriptorValueByte2, …)

  • DESCRIPTOR_UUID128(name, uuid128, permissions, descriptorValueLength, descriptorValueByte1, descriptorValueByte2, …)

A special Characteristic Descriptor that is used very often is the Client Characteristic Configuration Descriptor (CCCD). This is the descriptor where clients write some of the bits to activate Server notifications and/or indications. It has a reserved, 2-byte, SIG-defined UUID (0x2902), and its attribute value consists of only 1 byte (out of which 2 bits are used for configuration, the other 6 are reserved).

Because the CCCD appears very often in Characteristic definitions for standard Bluetooth Low Energy profiles, a special macro is used for CCCD declaration:

  • CCCD (name)

This simple macro is basically equivalent to the following Descriptor declaration:

* DESCRIPTOR \(name, *
    *0x2902, *
    (gGattAttPermAccessReadable_c
    | gGattAttPermAccessWritable_c),
    2, 0x00, 0x00)

Parent topic:Declaring a characteristic

Parent topic:Creating static GATT database