Generic Attribute Profile Server (gatt_server)

These commands and events are used by the local GATT server to manage the local GATT database.

gatt_server commands

gatt_server_find_attribute

This command can be used to find attributes of certain type from a local GATT database. Type is usually given as 16-bit or 128-bit UUID.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x03 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
3 0x06 method Message ID
4-5 uint16 start Search start index
6 uint8array type Variable length byte array. The first byte defines the length of the data that follows, 0 - 255 bytes.

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x04 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
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
6-7 uint16 attribute Attribute handle

API

/* Function */
struct gecko_msg_gatt_server_find_attribute_rsp_t *gecko_cmd_gatt_server_find_attribute(uint16 start, uint8 type_len, const uint8 *type_data);

/* Response id */
gecko_rsp_gatt_server_find_attribute_id

/* Response structure */
struct gecko_msg_gatt_server_find_attribute_rsp_t
{
  uint16 result,
  uint16 attribute
}

gatt_server_read_attribute_type

This command can be used to read the type of an attribute from a local GATT database. The type is a UUID, usually 16 or 128 bits long.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x02 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
3 0x01 method Message ID
4-5 uint16 attribute Attribute handle

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x03 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
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
6 uint8array type Variable length byte array. The first byte defines the length of the data that follows, 0 - 255 bytes.

API

/* Function */
struct gecko_msg_gatt_server_read_attribute_type_rsp_t *gecko_cmd_gatt_server_read_attribute_type(uint16 attribute);

/* Response id */
gecko_rsp_gatt_server_read_attribute_type_id

/* Response structure */
struct gecko_msg_gatt_server_read_attribute_type_rsp_t
{
  uint16 result,
  uint8array type
}

gatt_server_read_attribute_value

This command can be used to read the value of an attribute from a local GATT database. Only (maximum BGAPI payload size - 3) amount of data can be read once. The application can continue reading with increased offset value if it receives (maximum BGAPI payload size - 3) amount of data.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x04 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
3 0x00 method Message ID
4-5 uint16 attribute Attribute handle
6-7 uint16 offset Value offset

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x03 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
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 uint8array value Variable length byte array. The first byte defines the length of the data that follows, 0 - 255 bytes.

API

/* Function */
struct gecko_msg_gatt_server_read_attribute_value_rsp_t *gecko_cmd_gatt_server_read_attribute_value(uint16 attribute, uint16 offset);

/* Response id */
gecko_rsp_gatt_server_read_attribute_value_id

/* Response structure */
struct gecko_msg_gatt_server_read_attribute_value_rsp_t
{
  uint16 result,
  uint8array value
}

gatt_server_send_characteristic_notification

This command can be used to send notifications or indications to one or more remote GATT clients. At most ATT_MTU - 3 amount of data can be sent once.

A notification or indication is sent only if the client has enabled it by setting the corresponding flag to the Client Characteristic Configuration descriptor. In case the Client Characteristic Configuration descriptor supports both notification and indication, the stack will always send a notification even when the client has enabled both.

A new indication to a GATT client cannot be sent until an outstanding indication procedure with the same client has completed. The procedure is completed when a confirmation from the client has been received. The confirmation is indicated by gatt_server_characteristic_status event.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x04 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
3 0x05 method Message ID
4 uint8 connection Handle of the connection over which the notification or indication is sent. Values:
  • 0xff: Sends notification or indication to all connected devices.
  • Other: Connection handle
5-6 uint16 characteristic Characteristic handle
7 uint8array value Value to be notified or indicated

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x04 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
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
6-7 uint16 sent_len The length of data sent out if only one connected device is the receiver; otherwise unused value

API

/* Function */
struct gecko_msg_gatt_server_send_characteristic_notification_rsp_t *gecko_cmd_gatt_server_send_characteristic_notification(uint8 connection, uint16 characteristic, uint8 value_len, const uint8 *value_data);

/* Response id */
gecko_rsp_gatt_server_send_characteristic_notification_id

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

gatt_server_send_user_read_response

This command must be used to send a response to a user_read_request event. The response needs to be sent within 30 second, otherwise no more GATT transactions are allowed by the remote side. If attr_errorcode is set to 0 the characteristic value is sent to the remote GATT client in the normal way. Other attr_errorcode values will cause the local GATT server to send an attribute protocol error response instead of the actual data. At most ATT_MTU - 1 amount of data can be sent once. Client will continue reading by sending new read request with increased offset value if it receives ATT_MTU - 1 amount of data.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x05 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
3 0x03 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_errorcode Attribute protocol error code
  • 0: No error
  • Non-zero: See Bluetooth specification, Host volume, Attribute Protocol, Error Codes table.
8 uint8array value Characteristic value to send to the GATT client. Ignored if att_errorcode is not 0.

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x04 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
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
6-7 uint16 sent_len The length of data sent to the remote GATT client

API

/* Function */
struct gecko_msg_gatt_server_send_user_read_response_rsp_t *gecko_cmd_gatt_server_send_user_read_response(uint8 connection, uint16 characteristic, uint8 att_errorcode, uint8 value_len, const uint8 *value_data);

/* Response id */
gecko_rsp_gatt_server_send_user_read_response_id

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

gatt_server_send_user_write_response

This command must be used to send a response to a gatt_server_user_write_request event when parameter att_opcode in the event is Write Request (see att_opcode). The response needs to be sent within 30 seconds, otherwise no more GATT transactions are allowed by the remote side. If attr_errorcode is set to 0 the ATT protocol's write response is sent to indicate to the remote GATT client that the write operation was processed successfully. Other values will cause the local GATT server to send an ATT protocol error response.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x04 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
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_errorcode Attribute protocol error code
  • 0: No error
  • Non-zero: See Bluetooth specification, Host volume, Attribute Protocol, Error Codes table.

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
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_server_send_user_write_response_rsp_t *gecko_cmd_gatt_server_send_user_write_response(uint8 connection, uint16 characteristic, uint8 att_errorcode);

/* Response id */
gecko_rsp_gatt_server_send_user_write_response_id

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

gatt_server_set_capabilities

This command can be used to set which capabilities should be enabled in the local GATT database. A service is visible to remote GATT clients if at least one of its capabilities has been enabled. The same applies to a characteristic and its attributes. Capability identifiers and their corresponding bit flag values can be found in the auto-generated database header file. See UG118 for how to declare capabilities in GATT database.

Changing the capabilities of a database effectively causes a database change (attributes being added or removed) from a remote GATT client point of view. If the database has a Generic Attribute service and Service Changed characteristic, the stack will monitor local database change status and manage service changed indications for a GATT client that has enabled the indication configuration of the Service Changed characteristic.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x08 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
3 0x08 method Message ID
4-7 uint32 caps Bit flags of capabilities to enable.
8-11 uint32 reserved Value 0 should be used on this reserved field. None-zero values are reserved for future, do not use now.

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
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_server_set_capabilities_rsp_t *gecko_cmd_gatt_server_set_capabilities(uint32 caps, uint32 reserved);

/* Response id */
gecko_rsp_gatt_server_set_capabilities_id

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

gatt_server_set_database

Deprecated. Use GATT capability feature for dynamic configuration of services and characteristics in the local GATT database. See gatt_server_set_capabilities command for the details.

This command can be used to set the local GATT database. The database should not be changed while this device is connected as peripheral since it may cause GATT attributes and data synchronization problems. If the database is changed during advertising mode, advertising packets will not be updated until the advertising is restarted.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x04 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
3 0x07 method Message ID
4-7 uint32 ptr The pointer to the GATT database

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
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_server_set_database_rsp_t *gecko_cmd_gatt_server_set_database(uint32 ptr);

/* Response id */
gecko_rsp_gatt_server_set_database_id

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

gatt_server_write_attribute_value

This command can be used to write the value of an attribute in the local GATT database. Writing the value of a characteristic of the local GATT database will not trigger notifications or indications to the remote GATT client in case such characteristic has property of indicate or notify and the client has enabled notification or indication. Notifications and indications are sent to the remote GATT client using gatt_server_send_characteristic_notification command.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x05 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
3 0x02 method Message ID
4-5 uint16 attribute Attribute handle
6-7 uint16 offset Value offset
8 uint8array value Value

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
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_server_write_attribute_value_rsp_t *gecko_cmd_gatt_server_write_attribute_value(uint16 attribute, uint16 offset, uint8 value_len, const uint8 *value_data);

/* Response id */
gecko_rsp_gatt_server_write_attribute_value_id

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

gatt_server events

gatt_server_attribute_value

This event indicates that the value of an attribute in the local GATT database has been changed by a remote GATT client. Parameter att_opcode describes which GATT procedure was used to change the value.

Event

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x07 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
3 0x00 method Message ID
4 uint8 connection Connection handle
5-6 uint16 attribute Attribute Handle
7 uint8 att_opcode Attribute opcode which informs the procedure from which attribute the value was received
8-9 uint16 offset Value offset
10 uint8array value Value

API

/* event id*/
gecko_evt_gatt_server_attribute_value_id

/* event structure*/
struct gecko_msg_gatt_server_attribute_value_evt_t
{
  uint8 connection,
  uint16 attribute,
  uint8 att_opcode,
  uint16 offset,
  uint8array value
}

gatt_server_user_read_request

This event indicates that a remote GATT client is attempting to read a value of an attribute from the local GATT database, where the attribute was defined in the GATT XML firmware configuration file to have type="user". Parameter att_opcode informs which GATT procedure was used to read the value. The application needs to respond to this request by using the gatt_server_send_user_read_response command within 30 seconds, otherwise this GATT connection is dropped by remote side.

Event

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x06 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
3 0x01 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 procedure from which attribute the value was received
8-9 uint16 offset Value offset

API

/* event id*/
gecko_evt_gatt_server_user_read_request_id

/* event structure*/
struct gecko_msg_gatt_server_user_read_request_evt_t
{
  uint8 connection,
  uint16 characteristic,
  uint8 att_opcode,
  uint16 offset
}

gatt_server_user_write_request

This event indicates that a remote GATT client is attempting to write a value of an attribute in to the local GATT database, where the attribute was defined in the GATT XML firmware configuration file to have type="user". Parameter att_opcode informs which attribute procedure was used to write the value. If the att_opcode is Write Request (see att_opcode), the application needs to respond to this request by using the gatt_server_send_user_write_response command within 30 seconds, otherwise this GATT connection is dropped by the remote side. If the value of att_opcode is Execute Write Request, it indicates that this is a queued prepare write request received earlier and now the GATT server is processing the execute write. The event gatt_server_execute_write_completed will be emitted after all queued requests have been processed.

Event

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x07 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
3 0x02 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 procedure from which attribute the value was received
8-9 uint16 offset Value offset
10 uint8array value Value

API

/* event id*/
gecko_evt_gatt_server_user_write_request_id

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

gatt_server_characteristic_status

This event indicates either that a local Client Characteristic Configuration descriptor has been changed by the remote GATT client, or that a confirmation from the remote GATT client was received upon a successful reception of the indication. Confirmation by the remote GATT client should be received within 30 seconds after an indication has been sent with the gatt_server_send_characteristic_notification command, otherwise further GATT transactions over this connection are disabled by the stack.

Event

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x06 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
3 0x03 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 status_flags Describes whether Client Characteristic Configuration was changed or if confirmation was received.
8-9 uint16 client_config_flags This field carries the new value of the Client Characteristic Configuration. If the status_flags is 0x2 (confirmation received), the value of this field can be ignored.

API

/* event id*/
gecko_evt_gatt_server_characteristic_status_id

/* event structure*/
struct gecko_msg_gatt_server_characteristic_status_evt_t
{
  uint8 connection,
  uint16 characteristic,
  uint8 status_flags,
  uint16 client_config_flags
}

gatt_server_execute_write_completed

Execute write completed event indicates that the execute write command from a remote GATT client has completed with the given result.

Event

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x03 lolen Minimum payload length
2 0x0a class Message class:Generic Attribute Profile Server
3 0x04 method Message ID
4 uint8 connection Connection handle
5-6 uint16 result Execute write result

API

/* event id*/
gecko_evt_gatt_server_execute_write_completed_id

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

gatt_server enumerations

gatt_server_characteristic_status_flag

These values describe whether characteristic client configuration was changed or whether a characteristic confirmation was received.

Enumerations

Value Name Description
1 gatt_server_client_config Characteristic client configuration has been changed.
2 gatt_server_confirmation Characteristic confirmation has been received.