Generic Attribute Profile (gatt)#

The commands and events in this class can be used to browse and manage attributes in a remote GATT server.

Commands#

gatt_discover_characteristics#

This command can be used to discover all characteristics of the defined GATT service from a remote GATT database. This command generates a unique gatt_characteristic event for every discovered characteristic. Received gatt_procedure_completed event indicates that this GATT procedure has succesfully completed or failed with error.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x05

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x03

method

Message ID

4

uint8

connection

Connection handle

5-8

uint32

service

GATT service handle. This value is normally received from the gatt_service event.

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x03

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_discover_characteristics_rsp_t *gecko_cmd_gatt_discover_characteristics(uint8 connection, uint32 service);

/* Response id */
gecko_rsp_gatt_discover_characteristics_id

/* Response structure */
struct gecko_msg_gatt_discover_characteristics_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_characteristic

Discovered characteristic from remote GATT database.

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_discover_characteristics_by_uuid#

This command can be used to discover all the characteristics of the specified GATT service in a remote GATT database having the specified UUID. This command generates a unique gatt_characteristic event for every discovered characteristic having the specified UUID. Received gatt_procedure_completed event indicates that this GATT procedure has successfully completed or failed with error.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x06

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x04

method

Message ID

4

uint8

connection

Connection handle

5-8

uint32

service

GATT service handle. This value is normally received from the gatt_service event.

9

uint8array

uuid

Characteristic UUID

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x04

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_discover_characteristics_by_uuid_rsp_t *gecko_cmd_gatt_discover_characteristics_by_uuid(uint8 connection, uint32 service, uint8 uuid_len, const uint8 *uuid_data);

/* Response id */
gecko_rsp_gatt_discover_characteristics_by_uuid_id

/* Response structure */
struct gecko_msg_gatt_discover_characteristics_by_uuid_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_characteristic

Discovered characteristic from remote GATT database.

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_discover_descriptors#

This command can be used to discover all the descriptors of the specified remote GATT characteristics in a remote GATT database. This command generates a unique gatt_descriptor event for every discovered descriptor. Received gatt_procedure_completed event indicates that this GATT procedure has succesfully completed or failed with error.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x03

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x06

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

characteristic

GATT characteristic handle. This value is normally received from the gatt_characteristic event.

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x06

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_discover_descriptors_rsp_t *gecko_cmd_gatt_discover_descriptors(uint8 connection, uint16 characteristic);

/* Response id */
gecko_rsp_gatt_discover_descriptors_id

/* Response structure */
struct gecko_msg_gatt_discover_descriptors_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_descriptor

Discovered descriptor from remote GATT database.

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_discover_primary_services#

This command can be used to discover all the primary services of a remote GATT database. This command generates a unique gatt_service event for every discovered primary service. Received gatt_procedure_completed event indicates that this GATT procedure has successfully completed or failed with error.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x01

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x01

method

Message ID

4

uint8

connection

Connection handle

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x01

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_discover_primary_services_rsp_t *gecko_cmd_gatt_discover_primary_services(uint8 connection);

/* Response id */
gecko_rsp_gatt_discover_primary_services_id

/* Response structure */
struct gecko_msg_gatt_discover_primary_services_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_service

Discovered service from remote GATT database

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_discover_primary_services_by_uuid#

This command can be used to discover primary services with the specified UUID in a remote GATT database. This command generates unique gatt_service event for every discovered primary service. Received gatt_procedure_completed event indicates that this GATT procedure has succesfully completed or failed with error.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x02

method

Message ID

4

uint8

connection

Connection handle

5

uint8array

uuid

Service UUID

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x02

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_discover_primary_services_by_uuid_rsp_t *gecko_cmd_gatt_discover_primary_services_by_uuid(uint8 connection, uint8 uuid_len, const uint8 *uuid_data);

/* Response id */
gecko_rsp_gatt_discover_primary_services_by_uuid_id

/* Response structure */
struct gecko_msg_gatt_discover_primary_services_by_uuid_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_service

Discovered service from remote GATT database.

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_execute_characteristic_value_write#

This command can be used to commit or cancel previously queued writes to a long characteristic of a remote GATT server. Writes are sent to queue with prepare_characteristic_value_write command. Content, offset and length of queued values are validated by this procedure. A received gatt_procedure_completed event indicates that all data has been written successfully or that an error response has been received.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x0c

method

Message ID

4

uint8

connection

Connection handle

5

uint8

flags

Unsigned 8-bit integer

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x0c

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_execute_characteristic_value_write_rsp_t *gecko_cmd_gatt_execute_characteristic_value_write(uint8 connection, uint8 flags);

/* Response id */
gecko_rsp_gatt_execute_characteristic_value_write_id

/* Response structure */
struct gecko_msg_gatt_execute_characteristic_value_write_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_find_included_services#

This command can be used to find out if a service of a remote GATT database includes one or more other services. This command generates a unique gatt_service_completed event for each included service. This command generates a unique gatt_service event for every discovered service. Received gatt_procedure_completed event indicates that this GATT procedure has successfully completed or failed with error.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x05

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x10

method

Message ID

4

uint8

connection

Connection handle

5-8

uint32

service

GATT service handle. This value is normally received from the gatt_service event.

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x10

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_find_included_services_rsp_t *gecko_cmd_gatt_find_included_services(uint8 connection, uint32 service);

/* Response id */
gecko_rsp_gatt_find_included_services_id

/* Response structure */
struct gecko_msg_gatt_find_included_services_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_service

Discovered service from remote GATT database.

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_prepare_characteristic_value_reliable_write#

This command can be used to add a characteristic value to the write queue of a remote GATT server and verify if the value was correctly received by the server. Received gatt_procedure_completed event indicates that this GATT procedure has succesfully completed or failed with error. Specifically, error code 0x0194 (data_corrupted) will be returned if the value received from the GATT server's response failed to pass the reliable write verification. At most ATT_MTU - 5 amount of data can be sent once. Writes are executed or cancelled with the execute_characteristic_value_write command. Whether the writes succeeded or not are indicated in the response of the execute_characteristic_value_write command.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x06

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x13

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

characteristic

GATT characteristic handle. This value is normally received from the gatt_characteristic event.

7-8

uint16

offset

Offset of the characteristic value

9

uint8array

value

Value to write into the specified characteristic of the remote GATT database

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x04

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x13

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

6-7

uint16

sent_len

The length of data sent to the remote GATT server

API#

/* Function */
struct gecko_msg_gatt_prepare_characteristic_value_reliable_write_rsp_t *gecko_cmd_gatt_prepare_characteristic_value_reliable_write(uint8 connection, uint16 characteristic, uint16 offset, uint8 value_len, const uint8 *value_data);

/* Response id */
gecko_rsp_gatt_prepare_characteristic_value_reliable_write_id

/* Response structure */
struct gecko_msg_gatt_prepare_characteristic_value_reliable_write_rsp_t
{
  uint16 result,
  uint16 sent_len
}

Events generated#

Event

Description

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_prepare_characteristic_value_write#

This command can be used to add a characteristic value to the write queue of a remote GATT server. This command can be used in cases where very long attributes need to be written, or a set of values needs to be written atomically. At most ATT_MTU - 5 amount of data can be sent once. Writes are executed or cancelled with the execute_characteristic_value_write command. Whether the writes succeeded or not are indicated in the response of the execute_characteristic_value_write command.

In all cases where the amount of data to transfer fits into the BGAPI payload the command gatt_write_characteristic_value is recommended for writing long values since it transparently performs the prepare_write and execute_write commands.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x06

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x0b

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

characteristic

GATT characteristic handle. This value is normally received from the gatt_characteristic event.

7-8

uint16

offset

Offset of the characteristic value

9

uint8array

value

Value to write into the specified characteristic of the remote GATT database

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x04

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x0b

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

6-7

uint16

sent_len

The length of data sent to the remote GATT server

API#

/* Function */
struct gecko_msg_gatt_prepare_characteristic_value_write_rsp_t *gecko_cmd_gatt_prepare_characteristic_value_write(uint8 connection, uint16 characteristic, uint16 offset, uint8 value_len, const uint8 *value_data);

/* Response id */
gecko_rsp_gatt_prepare_characteristic_value_write_id

/* Response structure */
struct gecko_msg_gatt_prepare_characteristic_value_write_rsp_t
{
  uint16 result,
  uint16 sent_len
}

Events generated#

Event

Description

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_read_characteristic_value#

This command can be used to read the value of a characteristic from a remote GATT database. A single gatt_characteristic_value event is generated if the characteristic value fits in one ATT PDU. Otherwise more than one gatt_characteristic_value events are generated because the firmware will automatically use the "read long" GATT procedure. A received gatt_procedure_completed event indicates that all data has been read successfully or that an error response has been received.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x03

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x07

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

characteristic

GATT characteristic handle. This value is normally received from the gatt_characteristic event.

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x07

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_read_characteristic_value_rsp_t *gecko_cmd_gatt_read_characteristic_value(uint8 connection, uint16 characteristic);

/* Response id */
gecko_rsp_gatt_read_characteristic_value_id

/* Response structure */
struct gecko_msg_gatt_read_characteristic_value_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_characteristic_value

This event contains the data belonging to a characteristic sent by the GATT Server.

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_read_characteristic_value_by_uuid#

This command can be used to read the characteristic value of a service from a remote GATT database by giving the UUID of the characteristic and the handle of the service containing this characteristic. A single gatt_characteristic_value event is generated if the characteristic value fits in one ATT PDU. Otherwise more than one gatt_characteristic_value events are generated because the firmware will automatically use the "read long" GATT procedure. A received gatt_procedure_completed event indicates that all data has been read successfully or that an error response has been received.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x06

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x08

method

Message ID

4

uint8

connection

Connection handle

5-8

uint32

service

GATT service handle. This value is normally received from the gatt_service event.

9

uint8array

uuid

Characteristic UUID

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x08

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_read_characteristic_value_by_uuid_rsp_t *gecko_cmd_gatt_read_characteristic_value_by_uuid(uint8 connection, uint32 service, uint8 uuid_len, const uint8 *uuid_data);

/* Response id */
gecko_rsp_gatt_read_characteristic_value_by_uuid_id

/* Response structure */
struct gecko_msg_gatt_read_characteristic_value_by_uuid_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_characteristic_value

This event contains the data belonging to a characteristic sent by the GATT Server.

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_read_characteristic_value_from_offset#

This command can be used to read a partial characteristic value with specified offset and maximum length from a remote GATT database. It is equivalent to gatt_read_characteristic_value if both the offset and maximum length parameters are 0. A single gatt_characteristic_value event is generated if the value to read fits in one ATT PDU. Otherwise more than one gatt_characteristic_value events are generated because the firmware will automatically use the "read long" GATT procedure. A received gatt_procedure_completed event indicates that all data has been read successfully or that an error response has been received.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x07

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x12

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

characteristic

GATT characteristic handle. This value is normally received from the gatt_characteristic event.

7-8

uint16

offset

Offset of the characteristic value

9-10

uint16

maxlen

Maximum bytes to read. If this parameter is 0 all characteristic value starting at given offset will be read.

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x12

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_read_characteristic_value_from_offset_rsp_t *gecko_cmd_gatt_read_characteristic_value_from_offset(uint8 connection, uint16 characteristic, uint16 offset, uint16 maxlen);

/* Response id */
gecko_rsp_gatt_read_characteristic_value_from_offset_id

/* Response structure */
struct gecko_msg_gatt_read_characteristic_value_from_offset_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_characteristic_value

This event contains the data belonging to a characteristic sent by the GATT Server.

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_read_descriptor_value#

This command can be used to read the descriptor value of a characteristic in a remote GATT database. A single gatt_descriptor_value event is generated if the descriptor value fits in one ATT PDU. Otherwise more than one gatt_descriptor_value events are generated because the firmware will automatically use the "read long" GATT procedure. A received gatt_procedure_completed event indicates that all data has been read successfully or that an error response has been received.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x03

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x0e

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

descriptor

GATT characteristic descriptor handle

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x0e

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_read_descriptor_value_rsp_t *gecko_cmd_gatt_read_descriptor_value(uint8 connection, uint16 descriptor);

/* Response id */
gecko_rsp_gatt_read_descriptor_value_id

/* Response structure */
struct gecko_msg_gatt_read_descriptor_value_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_descriptor_value

Descriptor value received from the remote GATT server.

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_read_multiple_characteristic_values#

This command can be used to read the values of multiple characteristics from a remote GATT database at once. gatt_characteristic_value events are generated as the values are returned by the remote GATT server. A received gatt_procedure_completed event indicates that either all data has been read successfully or that an error response has been received.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x11

method

Message ID

4

uint8

connection

Connection handle

5

uint8array

characteristic_list

Little endian encoded uint16 list of characteristics to be read.

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x11

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_read_multiple_characteristic_values_rsp_t *gecko_cmd_gatt_read_multiple_characteristic_values(uint8 connection, uint8 characteristic_list_len, const uint8 *characteristic_list_data);

/* Response id */
gecko_rsp_gatt_read_multiple_characteristic_values_id

/* Response structure */
struct gecko_msg_gatt_read_multiple_characteristic_values_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_characteristic_value

This event contains the data belonging to a characteristic sent by the GATT Server.

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_send_characteristic_confirmation#

This command must be used to send a characteristic confirmation to a remote GATT server after receiving an indication. The gatt_characteristic_value_event carries the att_opcode containing handle_value_indication (0x1d) which reveals that an indication has been received and this must be confirmed with this command. Confirmation needs to be sent within 30 seconds, otherwise the GATT transactions between the client and the server are discontinued.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x01

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x0d

method

Message ID

4

uint8

connection

Connection handle

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x0d

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_send_characteristic_confirmation_rsp_t *gecko_cmd_gatt_send_characteristic_confirmation(uint8 connection);

/* Response id */
gecko_rsp_gatt_send_characteristic_confirmation_id

/* Response structure */
struct gecko_msg_gatt_send_characteristic_confirmation_rsp_t
{
  uint16 result
}

gatt_set_characteristic_notification#

This command can be used to enable or disable the notifications and indications being sent from a remote GATT server. This procedure discovers a characteristic client configuration descriptor and writes the related configuration flags to a remote GATT database. A received gatt_procedure_completed event indicates that this GATT procedure has successfully completed or that is has failed with an error.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x04

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x05

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

characteristic

GATT characteristic handle. This value is normally received from the gatt_characteristic event.

7

uint8

flags

Characteristic client configuration flags

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x05

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_set_characteristic_notification_rsp_t *gecko_cmd_gatt_set_characteristic_notification(uint8 connection, uint16 characteristic, uint8 flags);

/* Response id */
gecko_rsp_gatt_set_characteristic_notification_id

/* Response structure */
struct gecko_msg_gatt_set_characteristic_notification_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_characteristic_value

If an indication or notification has been enabled for a characteristic, this event is triggered whenever an indication or notification is sent by the remote GATT server. The triggering conditions on the GATT server side are defined by an upper level, for example by a profile; so it is possible that no values are ever received, or that it may take time, depending on how the server is configured.

gatt_set_max_mtu#

This command can be used to set the maximum size of ATT Message Transfer Units (MTU). If the given value is too large according to the maximum BGAPI payload size, the system will select the maximal possible value as the maximum ATT_MTU. If maximum ATT_MTU is larger than 23, MTU is exchanged automatically after a Bluetooth connection has been established.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x00

method

Message ID

4-5

uint16

max_mtu

Maximum size of Message Transfer Units (MTU) allowed. (Range: 23 to 250, Default: 247 ).

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x04

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x00

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

6-7

uint16

max_mtu

The maximum ATT_MTU selected by the system if this command succeeded

API#

/* Function */
struct gecko_msg_gatt_set_max_mtu_rsp_t *gecko_cmd_gatt_set_max_mtu(uint16 max_mtu);

/* Response id */
gecko_rsp_gatt_set_max_mtu_id

/* Response structure */
struct gecko_msg_gatt_set_max_mtu_rsp_t
{
  uint16 result,
  uint16 max_mtu
}

gatt_write_characteristic_value#

This command can be used to write the value of a characteristic in a remote GATT database. If the given value does not fit in one ATT PDU, "write long" GATT procedure is used automatically. Received gatt_procedure_completed event indicates that all data has been written successfully or that an error response has been received.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x04

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x09

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

characteristic

GATT characteristic handle. This value is normally received from the gatt_characteristic event.

7

uint8array

value

Characteristic value

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x09

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_write_characteristic_value_rsp_t *gecko_cmd_gatt_write_characteristic_value(uint8 connection, uint16 characteristic, uint8 value_len, const uint8 *value_data);

/* Response id */
gecko_rsp_gatt_write_characteristic_value_id

/* Response structure */
struct gecko_msg_gatt_write_characteristic_value_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

gatt_write_characteristic_value_without_response#

This command can be used to write the value of a characteristic in a remote GATT server. This command does not generate any event. All failures on the server are ignored silently. For example, if an error is generated in the remote GATT server and the given value is not written into database no error message will be reported to the local GATT client. Note that this command cannot be used to write long values. At most ATT_MTU - 3 amount of data can be sent once.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x04

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x0a

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

characteristic

GATT characteristic handle. This value is normally received from the gatt_characteristic event.

7

uint8array

value

Characteristic value

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x04

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x0a

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

6-7

uint16

sent_len

The length of data sent to the remote GATT server

API#

/* Function */
struct gecko_msg_gatt_write_characteristic_value_without_response_rsp_t *gecko_cmd_gatt_write_characteristic_value_without_response(uint8 connection, uint16 characteristic, uint8 value_len, const uint8 *value_data);

/* Response id */
gecko_rsp_gatt_write_characteristic_value_without_response_id

/* Response structure */
struct gecko_msg_gatt_write_characteristic_value_without_response_rsp_t
{
  uint16 result,
  uint16 sent_len
}

gatt_write_descriptor_value#

This command can be used to write the value of a characteristic descriptor in a remote GATT database. If the given value does not fit in one ATT PDU, "write long" GATT procedure is used automatically. Received gatt_procedure_completed event indicates that all data has been written succesfully or that an error response has been received.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x04

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x0f

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

descriptor

GATT characteristic descriptor handle

7

uint8array

value

Descriptor value

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x0f

method

Message ID

4-5

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */
struct gecko_msg_gatt_write_descriptor_value_rsp_t *gecko_cmd_gatt_write_descriptor_value(uint8 connection, uint16 descriptor, uint8 value_len, const uint8 *value_data);

/* Response id */
gecko_rsp_gatt_write_descriptor_value_id

/* Response structure */
struct gecko_msg_gatt_write_descriptor_value_rsp_t
{
  uint16 result
}

Events generated#

Event

Description

gatt_procedure_completed

Procedure has been successfully completed or failed with error.

Events#

gatt_mtu_exchanged#

This event indicates that an ATT_MTU exchange procedure has been completed. Parameter mtu describes new MTU size. MTU size 23 is used before this event is received.

Event#

Byte

Type

Name

Description

0

0xa0

hilen

Message type: Event

1

0x03

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x00

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

mtu

Exchanged ATT_MTU

API#

/* event id*/
gecko_evt_gatt_mtu_exchanged_id

/* event structure*/
struct gecko_msg_gatt_mtu_exchanged_evt_t
{
  uint8 connection,
  uint16 mtu
}

gatt_service#

This event indicates that a GATT service in the remote GATT database was discovered. This event is generated after issuing either the gatt_discover_primary_services or gatt_discover_primary_services_by_uuid command.

Event#

Byte

Type

Name

Description

0

0xa0

hilen

Message type: Event

1

0x06

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x01

method

Message ID

4

uint8

connection

Connection handle

5-8

uint32

service

GATT service handle

9

uint8array

uuid

Service UUID

API#

/* event id*/
gecko_evt_gatt_service_id

/* event structure*/
struct gecko_msg_gatt_service_evt_t
{
  uint8 connection,
  uint32 service,
  uint8array uuid
}

gatt_characteristic#

This event indicates that a GATT characteristic in the remote GATT database was discovered. This event is generated after issuing either the gatt_discover_characteristics or gatt_discover_characteristics_by_uuid command.

Event#

Byte

Type

Name

Description

0

0xa0

hilen

Message type: Event

1

0x05

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x02

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

characteristic

GATT characteristic handle

7

uint8

properties

Characteristic properties

8

uint8array

uuid

Characteristic UUID

API#

/* event id*/
gecko_evt_gatt_characteristic_id

/* event structure*/
struct gecko_msg_gatt_characteristic_evt_t
{
  uint8 connection,
  uint16 characteristic,
  uint8 properties,
  uint8array uuid
}

gatt_descriptor#

This event indicates that a GATT characteristic descriptor in the remote GATT database was discovered. This event is generated after issuing the gatt_discover_descriptors command.

Event#

Byte

Type

Name

Description

0

0xa0

hilen

Message type: Event

1

0x04

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x03

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

descriptor

GATT characteristic descriptor handle

7

uint8array

uuid

Descriptor UUID

API#

/* event id*/
gecko_evt_gatt_descriptor_id

/* event structure*/
struct gecko_msg_gatt_descriptor_evt_t
{
  uint8 connection,
  uint16 descriptor,
  uint8array uuid
}

gatt_characteristic_value#

This event indicates that the value of a characteristic in the remote GATT server was received. This event is triggered as a result of several commands: gatt_read_characteristic_value, gatt_read_characteristic_value_from_offset, gatt_read_characteristic_value_by_uuid, gatt_read_multiple_characteristic_values; and when the remote GATT server sends indications or notifications after enabling notifications with gatt_set_characteristic_notification. The parameter att_opcode reveals which type of GATT transaction triggered this event. In particular, if the att_opcode type is handle_value_indication (0x1d), the application needs to confirm the indication with gatt_send_characteristic_confirmation.

Event#

Byte

Type

Name

Description

0

0xa0

hilen

Message type: Event

1

0x07

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x04

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

characteristic

GATT characteristic handle. This value is normally received from the gatt_characteristic event.

7

uint8

att_opcode

Attribute opcode which informs the GATT transaction used

8-9

uint16

offset

Value offset

10

uint8array

value

Characteristic value

API#

/* event id*/
gecko_evt_gatt_characteristic_value_id

/* event structure*/
struct gecko_msg_gatt_characteristic_value_evt_t
{
  uint8 connection,
  uint16 characteristic,
  uint8 att_opcode,
  uint16 offset,
  uint8array value
}

gatt_descriptor_value#

This event indicates that the value of a descriptor in the remote GATT server was received. This event is generated by the gatt_read_descriptor_value command.

Event#

Byte

Type

Name

Description

0

0xa0

hilen

Message type: Event

1

0x06

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x05

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

descriptor

GATT characteristic descriptor handle

7-8

uint16

offset

Value offset

9

uint8array

value

Descriptor value

API#

/* event id*/
gecko_evt_gatt_descriptor_value_id

/* event structure*/
struct gecko_msg_gatt_descriptor_value_evt_t
{
  uint8 connection,
  uint16 descriptor,
  uint16 offset,
  uint8array value
}

gatt_procedure_completed#

This event indicates that the current GATT procedure has been completed successfully or that it has failed with an error. All GATT commands excluding gatt_write_characteristic_value_without_response and gatt_send_characteristic_confirmation will trigger this event, so the application must wait for this event before issuing another GATT command (excluding the two aforementioned exceptions).

Event#

Byte

Type

Name

Description

0

0xa0

hilen

Message type: Event

1

0x03

lolen

Minimum payload length

2

0x09

class

Message class:Generic Attribute Profile

3

0x06

method

Message ID

4

uint8

connection

Connection handle

5-6

uint16

result

Result code:

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* event id*/
gecko_evt_gatt_procedure_completed_id

/* event structure*/
struct gecko_msg_gatt_procedure_completed_evt_t
{
  uint8 connection,
  uint16 result
}

Enumerations#

gatt_att_opcode#

These values indicate which attribute request or response has caused the event.

Enumerations#

Value

Name

Description

8

gatt_read_by_type_request

Read by type request

9

gatt_read_by_type_response

Read by type response

10

gatt_read_request

Read request

11

gatt_read_response

Read response

12

gatt_read_blob_request

Read blob request

13

gatt_read_blob_response

Read blob response

14

gatt_read_multiple_request

Read multiple request

15

gatt_read_multiple_response

Read multiple response

18

gatt_write_request

Write request

19

gatt_write_response

Write response

82

gatt_write_command

Write command

22

gatt_prepare_write_request

Prepare write request

23

gatt_prepare_write_response

Prepare write response

24

gatt_execute_write_request

Execute write request

25

gatt_execute_write_response

Execute write response

27

gatt_handle_value_notification

Notification

29

gatt_handle_value_indication

Indication

gatt_client_config_flag#

These values define whether the client is to receive notifications or indications from a remote GATT server.

Enumerations#

Value

Name

Description

0

gatt_disable

Disable notifications and indications

1

gatt_notification

Notification

2

gatt_indication

Indication

gatt_execute_write_flag#

These values define whether the GATT server is to cancel all queued writes or commit all queued writes to a remote database.

Enumerations#

Value

Name

Description

0

gatt_cancel

Cancel all queued writes

1

gatt_commit

Commit all queued writes