GATT Vendor Specific API¶

GATT Commands¶

All GATT commands have the following format:

Name	Size (bytes)	Description
Opcode	2	PDU operation code
Connection Handle	2	Connection handle of the link
Command PDU	Variable	Command Parameters

For the command parameters, please see the corresponding section below.

Note: The connection handle of 0xFFFE is considered as the loopback connection. All messages sent to this connection will be loop backed to the local host.

Events Generated

For each GATT command,when it is received, the host will send the CommandStatus Event with the Status parameter. If a command will return additional events, it will be noted in the description below.

GATT_ExchangeMTU¶

Opcode: 0xFD82
Command Description: This sub-procedure is used by a client to set the ATT_MTU to the maximum possible value that can be supported by both devices when the client supports a value greater than the default ATT_MTU for the Attribute Protocol. This sub-procedure shall only be initiated once during a connection.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

clientRxMTU

Attribute client receive MTU size

Size: 2 byte(s)
Default: 23
Range: Any 2 byte value

Events Generated

This sub-procedure is complete when either ATT_ExchangeMTURsp (with SUCCESS or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_DiscAllPrimaryServices¶

Opcode: 0xFD90
Command Description: This sub-procedure is used by a client to discover all the primary services on a server.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

Events Generated

This sub-procedure is complete when either ATT_ReadByGrpTypeRsp (with bleProcedureComplete or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_DiscPrimaryServiceByUUID¶

Opcode: 0xFD86
Command Description: This sub-procedure is used by a client to discover a specific primary service on a server when only the Service UUID is known. The specific primary service may exist multiple times on a server. The primary service being discovered is identified by the service UUID.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

value

Attribute value to find

Size: input byte(s)
Default: “”
Range: Any (0 to (ATT_MTU - 7) byte) value

Events Generated

This sub-procedure is complete when either ATT_FindByTypeValueRsp (with bleProcedureComplete or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_FindIncludedServices¶

Opcode: 0xFDB0
Command Description: This sub-procedure is used by a client to find include service declarations within a service definition on a server. The service specified is identified by the service handle range.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

startHandle

First requested handle number

Size: 2 byte(s)
Default: 0x0001
Range: Any 2 byte value

endHandle

Last requested handle number

Size: 2 byte(s)
Default: 0xFFFF
Range: Any 2 byte value

Events Generated

This sub-procedure is complete when either ATT_ReadByTypeRsp (with bleProcedureComplete or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_DiscAllChars¶

Opcode: 0xFDB2
Command Description: This sub-procedure is used by a client to find all the characteristic declarations within a service definition on a server when only the service handle range is known. The service specified is identified by the service handle range.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

startHandle

First requested handle number

Size: 2 byte(s)
Default: 0x0001
Range: Any 2 byte value

endHandle

Last requested handle number

Size: 2 byte(s)
Default: 0xFFFF
Range: Any 2 byte value

Events Generated

This sub-procedure is complete when either ATT_ReadByTypeRsp (with bleProcedureComplete or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_DiscCharsByUUID¶

Opcode: 0xFD88
Command Description: This sub-procedure is used by a client to discover service characteristics on a server when only the service handle ranges are known and the characteristic UUID is known. The specific service may exist multiple times on a server. The characteristic being discovered is identified by the characteristic UUID.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

startHandle

First requested handle number

Size: 2 byte(s)
Default: 0x0001
Range: Any 2 byte value

endHandle

Last requested handle number

Size: 2 byte(s)
Default: 0xFFFF
Range: Any 2 byte value

type

2 or 16 octet UUID

Size: input byte(s)
Default: “00:00”
Range: Any 2 or 16 byte value

Events Generated

This sub-procedure is complete when either ATT_ReadByTypeRsp (with bleProcedureComplete or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_DiscAllCharDescs¶

Opcode: 0xFD84
Command Description: This sub-procedure is used by a client to find all the characteristic descriptors Attribute Handles and Attribute Types within a characteristic definition when only the characteristic handle range is known. The characteristic specified is identified by the characteristic handle range.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

startHandle

First requested handle number

Size: 2 byte(s)
Default: 0x0001
Range: Any 2 byte value

endHandle

Last requested handle number

Size: 2 byte(s)
Default: 0xFFFF
Range: Any 2 byte value

Events Generated

This sub-procedure is complete when either ATT_FindInfoRsp (with bleProcedureComplete or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_ReadCharValue¶

Opcode: 0xFD8A
Command Description: This sub-procedure is used to read a Characteristic Value from a server when the client knows the Characteristic Value Handle. The Read Response returns the Characteristic Value in the Attribute Value parameter.The Read Response only contains a Characteristic Value that is less than or equal to (ATT_MTU - 1) octets in length. If the Characteristic Value is greater than (ATT_MTU - 1) octets in length, GATT_ReadLongCharValue may be used if the rest of the Characteristic Value is required.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

handle

The handle of the attribute to be read

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

Events Generated

This sub-procedure is complete when either ATT_FindInfoRsp (with bleProcedureComplete or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_ReadUsingCharUUID¶

Opcode: 0xFDB4
Command Description: This sub-procedure is used to read a Characteristic Value from a server when the client knows the Characteristic Value Handle. The Read Response returns the Characteristic Value in the Attribute Value parameter. The Read Response only contains a Characteristic Value that is less than or equal to (ATT_MTU - 1) octets in length. If the Characteristic Value is greater than (ATT_MTU - 1) octets in length, GATT_ReadLongCharValue may be used if the rest of the Characteristic Value is required.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

startHandle

First requested handle number

Size: 2 byte(s)
Default: 0x0001
Range: Any 2 byte value

endHandle

Last requested handle number

Size: 2 byte(s)
Default: 0xFFFF
Range: Any 2 byte value

type

2 or 16 octet UUID

Size: input byte(s)
Default: “00:00”
Range: Any 2 or 16 byte value

Events Generated

This sub-procedure is complete when either ATT_ReadByTypeRsp (with bleProcedureComplete or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_ReadLongCharValue¶

Opcode: 0xFD8C
Command Description: This sub-procedure is used to read a Characteristic Value from a server when the client knows the Characteristic Value Handle and the length of the Characteristic Value is longer than can be sent in a single Read Response Attribute Protocol message.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

handle

The handle of the attribute to be read

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

offset

The offset of the first octet to be read

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

Events Generated

This sub-procedure is complete when either ATT_ReadBlobRsp (with bleProcedureComplete or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_ReadMultiCharValues¶

Opcode: 0xFD8E
Command Description: This sub-procedure is used to read multiple Characteristic Values from a server when the client knows the Characteristic Value Handles. The Attribute Protocol Read Multiple Requests is used with the Set Of Handles parameter set to the Characteristic Value Handles. The ATT_ReadMultiRsp returns the Characteristic Values in the Set Of Values parameter.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

handles

A set of two or more two-byte attribute handles

Size: input byte(s)
Default: “”
Range: Any (4 to (ATT_MTU-1) byte) value

Events Generated

This sub-procedure is complete when either ATT_ReadMultiRsp (with SUCCESS or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_WriteNoRsp¶

Opcode: 0xFDB6
Command Description: This sub-procedure is used to write a Characteristic Value to a server when the client knows the Characteristic Value Handle and the client does not need an acknowledgment that the write was successfully performed. This sub-procedure only writes the first (ATT_MTU - 3) octets of a Characteristic Value. This sub-procedure can not be used to write a long characteristic; instead GATT_ReadLongCharValue should be used.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

handle

The handle of the attribute to be set

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

value

The value to be written to the attribute

Size: input byte(s)
Default: “”
Range: Any (0 to (ATT_MTU - 3) byte) value

Events Generated

No response will be sent to the calling application task for this sub-procedure. If the Characteristic Value write request is the wrong size, or has an invalid value as defined by the profile, then the write will not succeed and no error will be generated by the server.

GATT_SignedWriteNoRsp¶

Opcode: 0xFDB8
Command Description: This sub-procedure is used to write a Characteristic Value to a server when the client knows the Characteristic Value Handle and the ATT Bearer is not encrypted. This sub-procedure shall only be used if the Characteristic Properties authenticated bit is enabled and the client and server device share a bond as defined in the GAP. This sub-procedure only writes the first (ATT_MTU - 15) octets of an Attribute Value. This sub-procedure cannot be used to write a long Attribute.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

handle

The handle of the attribute to be set

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

value

The value to be written to the attribute

Size: input byte(s)
Default: “”
Range: Any (0 to (ATT_MTU - 3) byte) value.

Events Generated

No response will be sent to the calling application task for this sub-procedure. If the authenticated Characteristic Value that is written is the wrong size, or has an invalid value as defined by the profile, or the signed value does not authenticate the client, then the write will not succeed and no error will be generated by the server.

GATT_WriteCharValue¶

Opcode: 0xFD92
Command Description: This sub-procedure is used write a characteristic value to a server when the client knows the characteristic value handle. This sub-procedure only writes the first (ATT_MTU-3) octets of a characteristic value. This sub-procedure can not be used to write a long attribute; instead the Write Long Characteristic Values sub-procedure should be used.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

handle

The handle of the attribute to be set

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

value

The value to be written to the attribute

Size: input byte(s)
Default: “”
Range: Any (0 to (ATT_MTU - 3) byte) value

Events Generated

This sub-procedure is complete when either ATT_WriteRsp (with SUCCESS or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_WriteLongCharValue¶

Opcode: 0xFD96
Command Description: This sub-procedure is used to write a Characteristic Value to a server when the client knows the Characteristic Value Handle but the length of the Characteristic Value is longer than can be sent in a single Write Request Attribute Protocol message.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

handle

The handle of the attribute to be written

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

offset

The offset of the first octet to be written

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

value

The value of the attribute to be written. Note: the stack implementation supports the maximum length of 512 octets but this is always bound by the physical interface used to communicate with the device

Size: input byte(s)
Default: “”
Range: Any 0 to 512 byte value.

Events Generated

This sub-procedure is complete when either ATT_PrepareWriteRsp (with bleTimeout status), ATT_ExecuteWriteRsp (with SUCCESS or bleTimeout status), or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_ReadCharDesc¶

Opcode: 0xFDBC
Command Description: This sub-procedure is used to read a Characteristic Descriptor from a server when the client knows the Characteristic Descriptors Handle.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

handle

The handle of the attribute to be read

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

Events Generated

This sub-procedure is complete when either ATT_ReadRsp (with bleProcedureComplete or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_ReadLongCharDesc¶

Opcode: 0xFDBE
Command Description: This sub-procedure is used to read a Characteristic Descriptor from a server when the client knows the Characteristic Descriptor Declarations Attribute Handle and the length of the Characteristic Descriptor Declaration is longer than can be sent in a single Read Response Attribute Protocol message.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

handle

The handle of the attribute to be read

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

offset

The offset of the first octet to be read

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

Events Generated

This sub-procedure is complete when either ATT_ReadBlobRsp (with bleProcedureComplete or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_WriteCharDesc¶

Opcode: 0xFDC0
Command Description: This sub-procedure is used write a characteristic descriptor to a server when the client knows the characteristic descriptor handle.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

handle

The handle of the attribute to be set

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

value

The value to be written to the attribute

Size: input byte(s)
Default: “”
Range: Any (0 to (ATT_MTU - 3) byte) value

Events Generated

This sub-procedure is complete when either ATT_WriteRsp (with SUCCESS or bleTimeout status) or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_WriteLongCharDesc¶

Opcode: 0xFDC2
Command Description: This sub-procedure is used to write a Characteristic Value to a server when the client knows the Characteristic Value Handle but the length of the Characteristic Value is longer than can be sent in a single Write Request Attribute Protocol message.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

handle

The handle of the attribute to be written

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

offset

The offset of the first octet to be written

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

value

The value of the attribute to be written. Note: the stack implementation supports the maximum length of 512 octets but this is always bound by the physical interface used to communicate with the device

Size: input byte(s)
Default: “”
Range: Any 0 to 512 byte value.

Events Generated

This sub-procedure is complete when either ATT_PrepareWriteRsp (with bleTimeout status), ATT_ExecuteWriteRsp (with SUCCESS or bleTimeout status), or ATT_ErrorRsp (with SUCCESS status) is received by the calling application task.

GATT_Notification¶

Opcode: 0xFD9B
Command Description: This sub-procedure is used when a server is configured to notify a characteristic value to a client without expecting any attribute protocol layer acknowledgment that the notification was successfully received. Note: A notification may be sent at any time and does not invoke a confirmation.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

authenticated

Whether or not an authenticated link is required

Size

1 byte(s)

Default

0x00

Range

Value	Description
0x00	No
0x01	Yes

handle

The handle of the attribute

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

value

The current value of the attribute

Size: input byte(s)
Default: “”
Range: Any (0 to (ATT_MTU - 3) byte) byte value.

Events Generated

This command only returns the CommandStatus event

GATT_Indication¶

Opcode: 0xFD9D
Command Description: This sub-procedure is used when a server is configured to indicate a characteristic value to a client and expects an attribute protocol layer acknowledgment that the indication was successfully received.

Command Parameters

Connection Handle

Identifies the connection.

Size: 2 byte(s)
Default: 0x0000
Range: 0x0000 to 0xFFFD

authenticated

Whether or not an authenticated link is required

Size

1 byte(s)

Default

0x00

Range

Value	Description
0x00	No
0x01	Yes

handle

The handle of the attribute

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

value

The current value of the attribute

Size: input byte(s)
Default: “”
Range: Any (0 to (ATT_MTU - 3) byte) value

Events Generated

This sub-procedure is complete when ATT_HandleValueCfm (with SUCCESS or bleTimeout status) is received by the calling application task.

GATT_AddService¶

Opcode: 0xFDFC
Command Description: This command is used to add a new service to the GATT Server on the Network Processor when the GATT Database is implemented on the Application Processor. The GATT_AddAttribute must be used to add additional attributes to the service. The new service will be automatically registered with the GATT Server if it has no additional attribute to be added. Note: The Command Status Event will have the Start Handle and End Handle for the service registered with the GATT Server. No ATT request is used to perform this command.

Command Parameters

UUID

The type of the service to be added (primary or secondary)

Size

2 byte(s)

Default

0x2800

Range

Value	Description
0x2800	PrimaryService
0x2801	SecondaryService

numAttrs

The number of the attributes in the service (including the service attribute)

Size: 2 byte(s)
Default: 1
Range: Any 2 byte value

encKeySize

The minimum encryption key size (in octets) required by the service.

Size: 1 byte(s)
Default: 16
Range: 7-16

Events Generated

This command only returns the CommandStatus event

GATT_DelService¶

Opcode: 0xFDFD
Command Description: This command is used to delete a service from the GATT Server on the Network Processor when the GATT Database is implemented on the Application Processor.

Command Parameters

handle

The handle of the service to be deleted

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

Events Generated

This command only returns the CommandStatus event

GATT_AddAttribute¶

Opcode: 0xFDFE
Command Description: This command is used to add a new attribute to the service being added to the GATT Server on the Network Processor when the GATT Database is implemented on the Application Processor. The service will be automatically registered with the GATT Server when its last attribute is added. Note: The Command Status Event will have the Start Handle and End Handle for the service registered with the GATT Server.

Command Parameters

UUID

The type of the attribute to be added

Size: input byte(s)
Default: “”
Range: Any 2 byte value

permissions

Attribute access permissions

Size

1 byte(s)

Default

0x01

Range

Value	Description
0x01	GATT_PERMIT_READ
0x02	GATT_PERMIT_WRITE
0x04	GATT_PERMIT_AUTHEN_READ
0x08	GATT_PERMIT_AUTHEN_WRITE
0x10	GATT_PERMIT_AUTHOR_READ
0x20	GATT_PERMIT_AUTHOR_WRITE
0x40	GATT_PERMIT_ENCRYPT_READ
0x80	GATT_PERMIT_ENCRYPT_WRITE
0x40	GATT_PERMIT_ENCRYPT_READ

Events Generated

This command only returns the CommandStatus event

GATT_UpdateMTU¶

Opcode: 0xFDFF
Command Description: This command is used to notify the stack of an updated MTU size for a given connection.

Command Parameters

handle

The handle of the service to be deleted

Size: 2 byte(s)
Default: 0
Range: Any 2 byte value

MTU

The new MTU

Size: 2 byte(s)
Default: 23
Range

Events Generated

This command only returns the CommandStatus event

GATT Events¶

All GATT events have the following format:

Name	Size (bytes)	Description
Opcode	2	PDU operation code
Status	1	Event status
Connection Handle	2	Connection handle of the link
PDU length	1	Length of event PDU
Event PDU	Variable	Event parameters

For the event parameters, please see the corresponding section below.

Note: The connection handle of 0xFFFE is considered as the loopback connection. All messages sent to this connection will be loop backed to the local host.

GATT_ClientCharCfgUpdated¶

Opcode: 0x0580
Event Description: A GATT Client Characteristic Configuration has been updated.

Event Parameters

Status

Size

1 byte(s)

Range

Value	Description
0x00	SUCCESS
0x12	bleIncorrectMode
0x02	INVALIDPARAMETER

connectionHandle

Connection handle of the link

Size: 2 byte(s)
Range: Any 2 byte value

pduLen

PDU length

Size: 1 byte(s)
Range: Any 1 byte value

attributeHandle

Handle of the CCC

Size: 2 byte(s)
Range

value

New Value of the CCC.

Size: 2 byte(s)
Range