Skip to end of metadata
Go to start of metadata

Document Revision
Document number: 15925256
Release: Apr 14, 2015 15:44
Document version: 3

Abstract

This document describes AT commands for the Generic Attribute Profile(GATT) that is part of the Bluetooth Low Energy/Smart technology.

Table of Content

 

Related documents

[1] Bluetooth Low Energy Serial Port Adapter - Getting Started: Describes the basic concepts for the Bluetooth Serial Port Adapter. This document is written for the classical Bluetooth Serial Port Adapter but the concepts are the same also for the Bluetooth Low Energy solutions.

[2] Bluetooth Low Energy Serial Port Adapter - Getting Started: Describes how to use the connectBlue Bluetooth Low Energy Serial Port Adapter modules.

GATT mode

The GATT AT commands are enabled when Low Energy is enabled. Indications for service changed might be received any time if the remote device supports the Serial port service. Before GATT AT commands can be used an ACL connection must exist to the remote device. Use the extensions for ADCP, and ADCC described below to connect and disconnect. Note that an ACL connection and Serial Port connection can not be made in parallel to the same device.

GATT security

The security modes used for the serial port service are not used when using the GATT AT-commands. Security is triggered when an attribute on the server side requires it and can currently not be enforced by the client.

AT commands reference

Low Energy ACL connection

ACL connection to a remote device (AT*ADCP)

AT CommandDescription
AT*ADCP=<bd_addr>, 17, 0, 0<CR>Make an ACL connection to a remote device supporting Low Energy.

The connection shall be used in data mode.
When the host connects to a service on a remote device it implicitly registers to receive the "Connection Data Mode Closed" event.

ResponsesDescription
<CR><LF>*ADCP:<acl_connection_handle><CR><LF>OK<CR><LF>Successful response.
<CR><LF>ERROR<CR><LF>Error response.
ParametersTypeValue
bd_addrBd_AddrBluetooth device address of the device to connect to.
acl_connection_handleinteger

The connection handle identifies the connection. The connection handle is used when closing the connection.

Note that this handle might collide with the Serial Connection handle used when connecting to another device with classic Serial port or Low Energy Serial Port service. When using multi-point the host should keep track of whether the connection was made as a pure ACL connection or as a Serial port connection together with the handle.

ModelConstraint
cB-OEMSPA3xx, cB-OBS410, cB-OLS425/426Not supported
cB-OBS421, cB-RBE221s, cB-RBS421Supported for Client-Central and Server-Central configuration.The command is not supported for the Client-Peripheral and Server-Peripheral configuration

Close ACL connection (AT*ADCC)

AT CommandDescription
AT*ADCC=<connection_handle>,1<CR>Close an existing ACL connection
ResponsesDescription
<CR><LF>OK<CR><LF>Successful response.
<CR><LF>ERROR<CR><LF>Error response.
ParametersTypeValue
connection_handleintegerThe connection handle identifies the connection.
ModelConstraint
cB-OLS425/426, cB-OEMSPA3xx, cB-OBS410Not supported.
cB-OBS421, cB-RBE221s, cB-RBS421Supported in Low Energy mode.

ACL connection closed (*ADCCO)

EventDescription
*ADCCO:<connection_handle>,<reason>,1<CR><LF>A connection to a remote device has been disconnected.
Event ParametersTypeValue
connection_handleintegerIdentifies the connection.
reasonenumerator

0: Disconnected by command
1: Disconnected by link loss
255: Reason unknown

ModelConstraint
cB-OLS425/426Not supported.
cB-OBS421, cB-RBE221s, cB-RBS421Supported in Low Energy mode.

 

GATT AT commands

Discover All Primary Services(AT*GATTDP)

AT CommandDescription
AT*GATTDP=<handle><CR>

Discovers all primary services on the remote device.

ResponsesDescription
<CR><LF>*GATTDP: <handle>,<start>,<end>,<uuid>This response is sent for every service found

<CR><LF>OK<CR><LF>

Successful response.

<CR><LF>ERROR<CR><LF>

Error response.

Parameters

Type

Value

handleintegerHandle of the connected device
startintegerStart handle of the service
endintegerEnd handle of the service
uuidhex stringUUID of the service. This can be either 16 bit or 128 bit e.g. 2A00

 

Discover Primary Services by UUID(AT*GATTDPU)

AT CommandDescription
AT*GATTDPU=<handle>,<uuid>CR>

Discovers all primary services by UUID on the remote device.

ResponsesDescription
<CR><LF>*GATTDPU: <handle>,<start>,<end>This response is sent for every service found

<CR><LF>OK<CR><LF>

Successful response.

<CR><LF>ERROR<CR><LF>

Error response.

Parameters

Type

Value

handleintegerHandle of the connected device
startintegerStart handle of the service
endintegerEnd handle of the service
uuidhex stringUUID of the service. This can be either 16 bit or 128 bit e.g. 2A00

Find Included Services(AT*GATTFI)

AT CommandDescription
AT*GATTFI=<handle>,<start_handle>,<end_handle><CR>

Find all included services on the remote device between start handle and end handle.

ResponsesDescription
<CR><LF>*GATTFI: <handle>,<attr_handle>,<start>,<end>,<uuid>This response is sent for every service found

<CR><LF>OK<CR><LF>

Successful response.

<CR><LF>ERROR<CR><LF>

Error response.

Parameters

Type

Value

handleintegerHandle of the connected device
attr_handleintegerAttribute handle of the included service
startintegerStart handle of the service
endintegerEnd handle of the service
uuidhex stringUUID of the service. This can be either 16 bit or 128 bit e.g. 2A00

Discover All Characteristics of Service(AT*GATTDCS)

AT CommandDescription
AT*GATTDCS=<handle>,<start>,<end>CR>

Discovers all characteristics of a service.

ResponsesDescription
<CR><LF>*GATTDCS: <handle>,<attr_handle>,<properties>,<value_handle>,<uuid>This response is sent for every characteristic found

<CR><LF>OK<CR><LF>

Successful response.

<CR><LF>ERROR<CR><LF>

Error response.

Parameters

Type

Value

handleintegerHandle of the connected device
startintegerStart handle of the service
endintegerEnd handle of the service
attr_handleintegerAttribute handle of the characteristic
propertieshex byte

Bit mask describing the properties of the characteristic
Bit 0: Broadcast
Bit 1: Readable
Bit 2: Writable with no response
Bit 3: Writable
Bit 4: Notify
Bit 5: Indicate
Bit 6: Authenticated signed write
Bit 7: Extended property available

value_handleintegerAttribute handle of the characteristic value
uuidhex stringUUID of the service. This can be either 16 bit or 128 bit e.g. 2A00

Discover All Characteristic Descriptors(AT*GATTDCD)

AT CommandDescription
AT*GATTDCD=<handle>,<val_handle>,<service_end_handle>CR>

Discovers all descriptors of a characteristic

ResponsesDescription
<CR><LF>*GATTDCD: <handle>,<char_handle>,<desc_handle>,<uuid>This response is sent for every descriptor found

<CR><LF>OK<CR><LF>

Successful response.

<CR><LF>ERROR<CR><LF>

Error response.

Parameters

Type

Value

handleintegerHandle of the connected device
char_handleintegerHandle for the characteristic
service_end_handleintegerEnd handle of the service which the characteristic belongs to
desc_handleintegerHandle of the descriptor
value_handleintegerHandle of the characteristic value
uuidhex stringUUID of the service. This can be either 16 bit or 128 bit e.g. 2A00

Read Characteristic(AT*GATTR)

AT CommandDescription
AT*GATTR=<handle>,<val_handle>CR>

Reads the characteristic. It will read all bytes in the characteristic.

ResponsesDescription
<CR><LF>*GATTR: <handle>,<val_handle>,<hex_data>This response is sent if read data is found. If all bytes do not fit on one response line the data will continue as a new response but with the same value handle.

<CR><LF>OK<CR><LF>

Successful response.

<CR><LF>ERROR<CR><LF>

Error response.

Parameters

Type

Value

handleintegerHandle of the connected device
val_handleintegerHandle of the characteristic value
hex_datahex stringThe read data as hex string e.g. 070809AABBCC

Read Characteristic by UUID(AT*GATTRU)

AT CommandDescription
AT*GATTRU=<handle>,<start>,<end>,<uuid>CR>

Reads all characteristics by UUID. It will read all bytes in each characteristic.

ResponsesDescription
<CR><LF>*GATTRU: <handle>,<val_handle>,<hex_data>This response is sent if read data is found. If all bytes do not fit on one response line the data will continue as a new response but with the same value handle.

<CR><LF>OK<CR><LF>

Successful response.

<CR><LF>ERROR<CR><LF>

Error response.

Parameters

Type

Value

handleintegerHandle of the connected device
val_handleintegerHandle of the characteristic value
startintegerStart handle
endintegerEnd handle
uuidhex stringUUID of the service. This can be either 16 bit or 128 bit e.g. 2A00
hex_datahex stringThe read data as hex string e.g. 070809AABBCC

 

Read Multiple Characteristics(AT*GATTRM)

AT CommandDescription
AT*GATTRM=<handle>,<attrHandleList><CR>

Reads all characteristics in the attrHandleList. Note that it will not be possible to distinguish individual values in the response. Thus the length of all attributes except the last one must be known beforehand.

ResponsesDescription
<CR><LF>*GATTRM: <handle>,<val_handle>,<hex_data>This response is sent if read data is found. If all bytes do not fit on one response line the data will continue as a new response but with the same value handle.

<CR><LF>OK<CR><LF>

Successful response.

<CR><LF>ERROR<CR><LF>

Error response.

Parameters

Type

Value

handleintegerHandle of the connected device
val_handleintegerHandle of the first characteristic value that is read
attrHandleListhex stringThe attribute handles as a  list e.g. 00010002
hex_datahex stringThe read data as hex string e.g. 070809AABBCC

 

Write Characteristic(AT*GATTW)

AT CommandDescription
AT*GATTW=<handle>,<val_handle>,<hex_data><CR>

Write characteristic. Note that this should only be used for small data transfers i.e. < 20 bytes. For larger writes use AT*GATTWL.

ResponsesDescription

<CR><LF>OK<CR><LF>

Successful response.

<CR><LF>ERROR<CR><LF>

Error response.

Parameters

Type

Value

handleintegerHandle of the connected device
val_handleintegerHandle of the characteristic value
hex_datahex stringThe data as hex string e.g. 070809AABBCC

 

Write Client Characteristic Configuration(AT*GATTWC)

AT CommandDescription
AT*GATTWC=<handle>,<desc_handle>,<config><CR>

Write client characteristic configuration.

ResponsesDescription

<CR><LF>OK<CR><LF>

Successful response.

<CR><LF>ERROR<CR><LF>

Error response.

Parameters

Type

Value

handleintegerHandle of the connected device
desc_handleintegerHandle of the descriptor
configinteger

The client configuration as integer:
0: None
1: Enable notifications
2: Enable indications
3: Enable notification and indications

The server configuration as integer:
0: None
1: Enable broadcasts

 

Write Characteristic with No Response(AT*GATTWN)

AT CommandDescription
AT*GATTWN=<handle>,<val_handle>,<hex_data><CR>

Write characteristic with no response. Note that this should only be used for small data transfers i.e. < 20 bytes. For larger writes use AT*GATTWL.

ResponsesDescription

<CR><LF>OK<CR><LF>

Successful response.

<CR><LF>ERROR<CR><LF>

Error response.

Parameters

Type

Value

handleintegerHandle of the connected device
val_handleintegerHandle of the characteristic value
hex_datahex stringThe data as hex string e.g. 070809AABBCC

 

Write Long Characteristic(AT*GATTWL)

AT CommandDescription
AT*GATTWL=<handle>,<val_handle>,<hex_data><reliable>,<flag>,<offset><CR>

Write long characteristic. This is used to write a characteristic longer than 20 bytes or when a reliable write is required. 

ResponsesDescription

<CR><LF>OK<CR><LF>

Successful response.

<CR><LF>ERROR<CR><LF>

Error response.

Parameters

Type

Value

handleintegerHandle of the connected device
val_handleintegerHandle of the characteristic value
hex_datahex stringThe data as hex string e.g. 070809AABBCC
reliableintegerSend the data as reliable or not. If using reliable the returned data will be checked.
0: Not reliable
1: Reliable
flaginteger

Optional flag which is used when sending several packets or when data is canceled. If sending several packets all but the last packet should set the flag to more data. The last data packet should set the flag to final.
0: Final data, (default)
1: More data
2: Cancel data writing

offsetintegerOptional offset of the data to write(0 is default). Is used when several packets need to be sent to write a complete data value.

 

Notification(*GATTN)

AT EventDescription
*GATTN:<handle>,<val_handle>,<hex_data><CR>This event is received when the remote side sends a notification

Parameters

Type

Value

handleintegerHandle of the connected device
val_handleintegerHandle of the characteristic value
hex_datahex stringThe data as hex string e.g. 070809AABBCC

 

Indication(*GATTI)

AT EventDescription
*GATTI:<handle>,<val_handle>,<hex_data><CR>This event is received when the remote side sends an indication.

Parameters

Type

Value

handleintegerHandle of the connected device
val_handleintegerHandle of the characteristic value
hex_datahex stringThe data as hex string e.g. 070809AABBCC