BLE GAP

GAP, which stands for the Generic Access Profile, governs advertising and connections with Bluetooth Low Energy devices.

The following commands can be used to configure the GAP settings on the BLE module.

You can use these commands to modify the advertising data (for ex. the device name that appears during the advertising process), to retrieve information about the connection that has been established between two devices, or the disconnect if you no longer wish to maintain a connection.

AT+GAPCONNECTABLE

This command can be used to prevent the device from being 'connectable'.

Codebase Revision: 0.7.0

Parameters: Whether or not the device should advertise itself as connectable, using one of the following values:

  • yes
  • no
  • 1
  • 0

Output: The 'connectable' state of the device if no parameter is provided

# Make the device non-connectable (advertising only)
AT+GAPCONNECTABLE=0
OK

# Check the current connectability status
AT+GAPCONNECTABLE
1
OK

AT+GAPGETCONN

Diplays the current connection status (if we are connected to another BLE device or not).

Codebase Revision: 0.3.0

Parameters: None

Output: 1 if we are connected, otherwise 0

# Connected
AT+GAPGETCONN
1
OK
  
# Not connected
AT+GAPGETCONN
0
OK

AT+GAPDISCONNECT

Disconnects to the external device if we are currently connected.

Codebase Revision: 0.3.0

Parameters: None

Output: None

AT+GAPDISCONNECT
OK

AT+GAPDEVNAME

Gets or sets the device name, which is included in the advertising payload for the Bluefruit LE module

Codebase Revision: 0.3.0

Parameters:

  • None to read the current device name
  • The new device name if you want to change the value

Output: The device name if the command is executed in read mode

Updating the device name will persist the new value to non-volatile memory, and the updated name will be used when the device is reset. To reset the device to factory settings and clean the config data from memory run the AT+FACTORYRESET command.
# Read the current device name
AT+GAPDEVNAME
UART
OK
  
# Update the device name to 'BLEFriend'
AT+GAPDEVNAME=BLEFriend
OK
# Reset to take effect
ATZ
OK

AT+GAPDELBONDS

Deletes and bonding information stored on the Bluefruit LE module.

Codebase Revision: 0.3.0

Parameters: None

Output: None

AT+GAPDELBONDS
OK

AT+GAPINTERVALS

Gets or sets the various advertising and connection intervals for the Bluefruit LE module.

Be extremely careful with this command since it can be easy to cause problems changing the intervals, and depending on the values selected some mobile devices may no longer recognize the module or refuse to connect to it.

Codebase Revision: 0.3.0

Parameters: If updating the GAP intervals, the following comma-separated values can be entered:

  • Minimum connection interval (in milliseconds)
  • Maximum connection interval (in milliseconds)
  • Fast Advertising interval (in milliseconds)
  • Fast Advertising timeout (in seconds)
  • >= 0.7.0: Low power advertising interval (in milliseconds), default = 417.5 ms
To save power, the Bluefruit modules automatically drop to a lower advertising rate after 'fast advertising timeout' seconds. The default value is 30 seconds ('Fast Advertising Timeout'). The low power advertising interval is hard-coded to approximately 0.6s in firmware < 0.7.0. Support to control the low power interval was added in the 0.7.0 firmware release via an optional fifth parameter.

Please note the following min and max limitations for the GAP parameters:

  • Absolute minimum connection interval: 10ms
  • Absolute maximum connection interval: 4000ms
  • Absolute minimum fast advertising interval: 20ms
  • Absolute maximum fast advertisting interval: 10240ms
  • Absolute minimum low power advertising interval: 20ms
  • Absolute maximum low power advertising interval: 10240ms
If you only wish to update one interval value, leave the other comma-separated values empty (ex. ',,110,' will only update the third value, advertising interval).

Output: If reading the current GAP interval settings, the following comma-separated information will be displayed:

  • Minimum connection interval (in milliseconds)
  • Maximum connection interval (in milliseconds)
  • Advertising interval (in milliseconds)
  • Advertising timeout (in milliseconds)
Updating the GAP intervals will persist the new values to non-volatile memory, and the updated values will be used when the device is reset. To reset the device to factory settings and clean the config data from memory run the AT+FACTORYRESET command.
# Read the current GAP intervals
AT+GAPINTERVALS
20,100,100,30
  
# Update all values
AT+GAPINTERVALS=20,200,200,30
OK
  
# Update only the advertising interval
AT+GAPINTERVALS=,,150,
OK

AT+GAPSTARTADV

Causes the Bluefruit LE module to start transmitting advertising packets if this isn't already the case (assuming we aren't already connected to an external device).

Codebase Revision: 0.3.0

Parameters: None

Output: None

# Command results when advertising data is not being sent
AT+GAPSTARTADV
OK
  
# Command results when we are already advertising
AT+GAPSTARTADV
ERROR
  
# Command results when we are connected to another device
AT+GAPSTARTADV
ERROR

AT+GAPSTOPADV

Stops advertising packets from being transmitted by the Bluefruit LE module.

Codebase Revision: 0.3.0

Parameters: None

Output: None

AT+GAPSTOPADV
OK

AT+GAPSETADVDATA

Sets the raw advertising data payload to the specified byte array (overriding the normal advertising data), following the guidelines in the Bluetooth 4.0 or 4.1 Core Specification.

In particular, Core Specification Supplement (CSS) v4 contains the details on common advertising data fields like 'Flags' (Part A, Section 1.3) and the various Service UUID lists (Part A, Section 1.1). A list of all possible GAP Data Types is available on the Bluetooth SIG's Generic Access Profile page.

The Advertising Data payload consists of Generic Access Profile data that is inserted into the advertising packet in the following format: [U8:LEN] [U8:Data Type Value] [n:Value]

WARNING: This command requires a degree of knowledge about the low level details of the Bluetooth 4.0 or 4.1 Core Specification, and should only be used by expert users. Misuse of this command can easily cause your device to be undetectable by central devices in radio range.
WARNING: This command will override the normal advertising payload and may prevent some services from acting as expected.
To restore the advertising data to the normal default values use the AT+FACTORYRESET command.

For example, to insert the 'Flags' Data Type (Data Type Value 0x01), and set the value to 0x06/0b00000110 (BR/EDR Not Supported and LE General Discoverable Mode) we would use the following byte array:

02-01-06
  • 0x02 indicates the number of bytes in the entry
  • 0x01 is the 'Data Type Value' and indicates that this is a 'Flag'
  • 0x06 (0b00000110) is the Flag value, and asserts the following fields (see Core Specification 4.0, Volume 3, Part C, 18.1):
    • LE General Discoverable Mode (i.e. anyone can discover this device)
    • BR/EDR Not Supported (i.e. this is a Bluetooth Low Energy only device)

If we also want to include two 16-bit service UUIDs in the advertising data (so that listening devices know that we support these services) we could append the following data to the byte array:

05-02-0D-18-0A-18
  • 0x05 indicates that the number of bytes in the entry (5)
  • 0x02 is the 'Data Type Value' and indicates that this is an 'Incomplete List of 16-bit Service Class UUIDs'
  • 0x0D 0x18 is the first 16-bit UUID (which translates to 0x180D, corresponding to the Heart Rate Service).
  • 0x0A 0x18 is another 16-bit UUID (which translates to 0x180A, corresponding to the Device Information Service).
Including the service UUIDs is important since some mobile applications will only work with devices that advertise a specific service UUID in the advertising packet. This is true for most apps from Nordic Semiconductors, for example.

Codebase Revision: 0.3.0

Parameters: The raw byte array that should be inserted into the advertising data section of the advertising packet, being careful to stay within the space limits defined by the Bluetooth Core Specification.

Response: None

# Advertise as Discoverable and BLE only with 16-bit UUIDs 0x180D and 0x180A
AT+GAPSETADVDATA=02-01-06-05-02-0d-18-0a-18
OK

The results of this command can be seen in the screenshot below, taken from a sniffer analyzing the advertising packets in Wireshark. The advertising data payload is higlighted in blue in the raw byte array at the bottom of the image, and the packet analysis is in the upper section:

Last updated on 2016-06-23 at 03.13.46 PM Published on 2014-11-19 at 03.16.20 PM