- Short range radio modules
- Positioning chips and modules
u-blox Products
- Product selector
- Previous generations
- Contact sales
Find products
- Product documentation
Documentation
7 GATT Server
GATT Server
7.1 AT Commands
AT Command | Description |
|---|---|
GATT Service define | |
GATT Characteristic define | |
GATT Host Controlled Characteristic | |
GATT Descriptor define | |
GATT Service Activate | |
GATT Read Request Respond | |
GATT Notification Send | |
GATT Indication Send | |
GATT Attribute Value | |
GATT Read Request Respond with error code | |
GATT Write Respond with Error code | |
GATT Write Request Respond | |
GATT Service Changed Indication |
7.1.1 AT+UBTGS - GATT Service define
Command to define a GATT service according to a 16-bit Service Assigned Number from Bluetooth SIG or a 128-bit user defined service number.
Syntax
AT Command | Description |
|---|---|
AT+UBTGS=<uuid> | Defines a service. |
Response | Description |
|---|---|
+UBTGS:<ser_handle> | Successful write response. |
Defined values
Parameter | Type | Description |
|---|---|---|
uuid | byte_array | UUID of service. This can be either 16 bit or 128 bit. |
ser_handle | integer | Handle of the created service. |
7.1.2 AT+UBTGC - GATT Characteristic define
Command to add a GATT characteristic to the most recent GATT service record created with AT+UBTGS.
Syntax
AT Command | Description |
|---|---|
AT+UBTGC=<uuid>,<properties>,<security_read>,<security_write>,<value>[,<max_length>] | Create a new characteristic in the GATT table for a GATT server. The CCCD for the characteristic, if applicable, is created here. Extended properties such as CPFD, CUDD, and SCCD are not supported. |
Response | Description |
|---|---|
+UBTGC:<value_handle>,<cccd_handle> | Successful write response. |
Defined values
Parameter | Type | Description |
|---|---|---|
uuid | byte_array | UUID of characteristic. This can be either 16 bit or 128 bit. |
value | byte_array | Default characteristic value before any value is pushed to it. A characteristic value can be 244 bytes long. |
max_length | integer | Maximum length of the characteristic in bytes. The maximum value is 244 bytes. Valid values: 1..244 |
value_handle | integer | Added characteristic handle. |
cccd_handle | integer | CCCD characteristic handle. This value is zero if there is no CCCD. |
properties | byte_array | Property value (a bit field): Broadcast: 0x01 - If set, it allows broadcasts of the Characteristic Value using Characteristic Configuration Descriptor. Read: 0x02 - If set, it allows reads of the Characteristic Value. Write Without Response: 0x04 - If set, it allows writing of the Characteristic Value without response. Write: 0x08 - If set, it allows writing of the Characteristic Value with response. Notify: 0x10 - If set, it allows notifications of a characteristic value. Indicate: 0x20 - If set, it allows indication of a characteristic value with acknowledgement. Authenticated Signed Writes: 0x40 - If set, it allows signed writes to the characteristic value. Reserved Bit: 0x80 - Do not use. Reserved for future use. Valid length: 1 only |
security_read | enumerator | Valid values: 1: No encryption required. 2: Unauthenticated encryption required. 3: Authenticated encryption required. |
security_write | enumerator | Valid values: 1: No encryption required. 2: Unauthenticated encryption required. 3: Authenticated encryption required. |
7.1.3 AT+UBTGHCC - GATT Host Controlled Characteristic
Create a new host controlled characteristic in the GATT table for a GATT server. The CCCD for the characteristic, if applicable, is created here. Extended properties such as CPFD, CUDD, and SCCD are not supported.
Syntax
AT Command | Description |
|---|---|
AT+UBTGHCC=<uuid>,<properties>,<security_read>,<security_write> | Define a characteristic. |
Response | Description |
|---|---|
+UBTGHCC:<value_handle>,<cccd_handle> | Successful write response. |
Defined values
Parameter | Type | Description |
|---|---|---|
uuid | byte_array | UUID of characteristic. This can be either 16 bit or 128 bit. |
value_handle | integer | Value handle of the added characteristic. |
cccd_handle | integer | Client Characteristic Configuration Descriptor (CCCD) handle of the added characteristic. This value is zero if there is no CCCD. |
properties | byte_array | Property value (a bit field): Broadcast: 0x01 - If set, it allows broadcasts of the Characteristic Value using Characteristic Configuration Descriptor. Read: 0x02 - If set, it allows reads of the Characteristic Value. Write Without Response: 0x04 - If set, it allows writing of the Characteristic Value without response. Write: 0x08 - If set, it allows writing of the Characteristic Value with response. Notify: 0x10 - If set, it allows notifications of a characteristic value. Indicate: 0x20 - If set, it allows indication of a characteristic value with acknowledgement. Authenticated Signed Writes: 0x40 - If set, it allows signed writes to the characteristic value. Reserved Bit: 0x80 - Do not use. Reserved for future use. Valid length: 1 only |
security_read | enumerator | Valid values: 1: No encryption required. 2: Unauthenticated encryption required. 3: Authenticated encryption required. |
security_write | enumerator | Valid values: 1: No encryption required. 2: Unauthenticated encryption required. 3: Authenticated encryption required. |
7.1.4 AT+UBTGD - GATT Descriptor define
Define a vendor defined descriptor. Standard Bluetooth low energy descriptors such as CCCD are created while creating the characteristic in AT+UBTGC command.
Syntax
AT Command | Description |
|---|---|
AT+UBTGD=<uuid>,<security_read>,<security_write>,<value>[,<max_length>] | Define descriptor. |
Response | Description |
|---|---|
+UBTGD:<desc_handle> | Successful write response. |
Defined values
Parameter | Type | Description |
|---|---|---|
uuid | byte_array | UUID of characteristic. This can be either 16 bit or 128 bit. |
value | byte_array | Descriptor value. This can be 23 bytes long. |
max_length | integer | Maximum length of the descriptor in bytes. The maximum value is 23 bytes. Valid values: 1..23 |
desc_handle | integer | Handle of the created descriptor. |
security_read | enumerator | Valid values: 1: No encryption required. 2: Unauthenticated encryption required. 3: Authenticated encryption required. |
security_write | enumerator | Valid values: 1: No encryption required. 2: Unauthenticated encryption required. 3: Authenticated encryption required. |
7.1.5 AT+UBTGSA - GATT Service Activate
Activate the service defined with the AT+UBTGS command. After this command is issued, it is not possible to add more characteristics or descriptors to the service.
Syntax
AT Command | Description |
|---|---|
AT+UBTGSA | Activate current defined service. |
7.1.6 AT+UBTGRRR - GATT Read Request Respond
Respond to an unsolicited request to read (see +UEBTGRR) from a remote GATT client.
Syntax
AT Command | Description |
|---|---|
AT+UBTGRRR=<conn_handle>,<value> | Responds to read request. |
Defined values
Parameter | Type | Description |
|---|---|---|
conn_handle | integer | GAP handle of the connected device. |
value | byte_array | Characteristic value. This can be 244 bytes long. |
7.1.7 AT+UBTGNS - GATT Notification Send
Send notifications to a remote client. This also updates the value of the characteristic.
Syntax
AT Command | Description |
|---|---|
AT+UBTGNS=<conn_handle>,<char_handle>,<value> | Send notification |
Defined values
Parameter | Type | Description |
|---|---|---|
conn_handle | integer | GAP handle of the connected device. |
char_handle | integer | Characteristic value handle. |
value | byte_array | Characteristic value. The maximum length is the current MTU size - 3. |
7.1.8 AT+UBTGIS - GATT Indication Send
Send indication to a remote client. This also updates the value of the characteristic.
Syntax
AT Command | Description |
|---|---|
AT+UBTGIS=<conn_handle>,<char_handle>,<value> | Send notification |
Defined values
Parameter | Type | Description |
|---|---|---|
conn_handle | integer | GAP handle of the connected device. |
char_handle | integer | Characteristic value handle. |
value | byte_array | Characteristic value. The maximum length is the current MTU size - 3. |
7.1.9 AT+UBTGAV - GATT Attribute Value
Update the value of an attribute. In case of characteristics which allow indications and notifications, this command will update the value without sending any indications or notifications to the remote side.
Syntax
AT Command | Description |
|---|---|
AT+UBTGAV=<attr_handle>,<value> | Set attribute value. |
Defined values
Parameter | Type | Description |
|---|---|---|
attr_handle | integer | Attribute handle. |
value | byte_array | Characteristic value. This can be 244 bytes long. |
7.1.10 AT+UBTGRRRE - GATT Read Request Respond with error code
Respond to read request with application error code.
Syntax
AT Command | Description |
|---|---|
AT+UBTGRRRE=<conn_handle>,<error_code> | Respond with error code. |
Defined values
Parameter | Type | Description |
|---|---|---|
conn_handle | integer | GAP handle of connected device. |
error_code | byte_array | Application error code. Allowed value range: 0x80-0x9F Valid length: 1 only |
7.1.11 AT+UBTGWRE - GATT Write Respond with Error code
Respond to write operation with application error code.
Syntax
AT Command | Description |
|---|---|
AT+UBTGWRE=<conn_handle>,<error_code> | Respond with error code. |
Defined values
Parameter | Type | Description |
|---|---|---|
conn_handle | integer | GAP handle of connected device. |
error_code | byte_array | Application error code. Allowed value range: 0x80-0x9F Valid length: 1 only |
7.1.12 AT+UBTGWRR - GATT Write Request Respond
Accept write request from GATT client.
Syntax
AT Command | Description |
|---|---|
AT+UBTGWRR=<conn_handle> | Respond to write request. |
Defined values
Parameter | Type | Description |
|---|---|---|
conn_handle | integer | GAP handle of connected device. |
7.1.13 AT+UBTGSCI - GATT Service Changed Indication
Sends an indication to the remote peer client that the attribute table of the local GATT server has changed.
Syntax
AT Command | Description |
|---|---|
AT+UBTGSCI=<conn_handle>,<start_handle>,<end_handle> | Send Service Changed Indication. |
Defined values
Parameter | Type | Description |
|---|---|---|
conn_handle | integer | GAP handle of connected device. |
start_handle | integer | Start of the affected attribute handle range. |
end_handle | integer | End of the affected attribute handle range. |
7.2 Unsolicited Response Codes
Unsolicited Response Code | Description |
|---|---|
Event GATT Server Write | |
Event GATT Server Read Response | |
Event GATT Server Indication Confirmation |
7.2.1 +UEBTGCW - Event GATT Server Write
Unsolicited response code for GATT Server. This event occurs when a remote client writes to an attribute.
Syntax
+UEBTGCW:<conn_handle>,<value_handle>,<value>,<options>Defined values
Parameter | Type | Description |
|---|---|---|
conn_handle | integer | GAP connection handle. |
value_handle | integer | Characteristic value handle. |
value | byte_array | The data as hex string. For example, 070809AABBCC |
options | enumerator | Valid values: 0: Write without Response performed 1: Write with Response performed 2: Write long performed |
7.2.2 +UEBTGRR - Event GATT Server Read Response
Unsolicited response code for GATT Server. This event occurs when a remote client reads an attribute over the air. The event should be responded with AT+UBTGRRR.
Syntax
+UEBTGRR:<conn_handle>,<value_handle>Defined values
Parameter | Type | Description |
|---|---|---|
conn_handle | integer | Handle of the connected device. |
value_handle | integer | Handle of the characteristic value. |
7.2.3 +UEBTGIC - Event GATT Server Indication Confirmation
Unsolicited response code for GATT Server. This event occurs when a remote GATT client acknowledges the receipt of an indication message sent using AT+UBTGIS.
Syntax
+UEBTGIC:<conn_handle>,<char_handle>Defined values
Parameter | Type | Description |
|---|---|---|
conn_handle | integer | Connected device handle. |
char_handle | integer | Characteristic value handle. |
Last updated: 04 March 2025
Need help?Contact Support
Questions?Contact us