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: