Generic Access Profile (le_gap)#

The commands and events in this class are related to Generic Access Profile (GAP) in Bluetooth.

le_gap commands#

le_gap_bt5_set_adv_data#

This command can be used to set user defined data in advertising packets, scan response packets or periodic advertising packets.

If advertising mode is currently enabled the new advertising data will be used immediately. Advertising mode can be enabled using command le_gap_start_advertising. Periodic advertising mode can be enabled using command le_gap_start_periodic_advertising.

The maximum data length is 31 bytes for legacy advertising and 191 bytes for extended advertising.

The invalid parameter error will be returned in following situations:

  • The data length is more than 31 bytes but the advertiser can only advertise using legacy advertising PDUs;

  • The data length is more than 191 bytes when the advertiser can advertise using extended advertising PDUs;

  • Set the data of advertising data packet when the advertiser is advertising in scannable mode using extended advertising PDUs;

  • Set the data of scan response data packet when the advertiser is advertising in connectable mode using extended advertising PDUs.

Note that the user defined data may be overwritten by the system when the advertising is later enabled in other discoverable mode than user_data.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x03

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x0c

method

Message ID

4

uint8

handle

Advertising set handle, number of sets available is

defined in stack configuration

5

uint8

scan_rsp

This value selects if the data is intended for

advertising packets, scan response packets, periodic advertising packets or

advertising packet in OTA. Values:

  • 0: Advertising packets

  • 1: Scan response packets

  • 2: OTA advertising packets

  • 4: OTA scan response packets

  • 8: Periodic advertising packets

6 | uint8array | adv_data | Data to be set. Maximum data length:

  • 31 bytes for legacy advertising;

  • 191 bytes for extended advertising

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x0c

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_bt5_set_adv_data_rsp_t *gecko_cmd_le_gap_bt5_set_adv_data(uint8 handle, uint8 scan_rsp, uint8 adv_data_len, const uint8 *adv_data_data);  
  
/* Response id */  
gecko_rsp_le_gap_bt5_set_adv_data_id  
  
/* Response structure */  
struct gecko_msg_le_gap_bt5_set_adv_data_rsp_t  
{  
  uint16 result  
}  

le_gap_bt5_set_adv_parameters#

Deprecated. Replacements are le_gap_set_advertise_timing command for setting the advertising intervals, le_gap_set_advertise_channel_map command for setting the channel map, and le_gap_set_advertise_report_scan_request command for enabling and disabling scan request notifications.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x07

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x0b

method

Message ID

4

uint8

handle

Advertising set handle, number of sets available is

defined in stack configuration

5-6

uint16

interval_min

Minimum advertising interval. Value in units

of 0.625 ms

  • Range: 0x20 to 0xFFFF

  • Time range: 20 ms to 40.96 s

Default value: 100 ms
7-8 | uint16 | interval_max | Maximum advertising interval. Value in units of 0.625 ms

  • Range: 0x20 to 0xFFFF

  • Time range: 20 ms to 40.96 s

  • Note: interval_max should be bigger than interval_min

Default value: 200 ms
9 | uint8 | channel_map | Advertising channel map which determines which of the three channels will be used for advertising. This value is given as a bitmask. Values:

  • 1: Advertise on CH37

  • 2: Advertise on CH38

  • 3: Advertise on CH37 and CH38

  • 4: Advertise on CH39

  • 5: Advertise on CH37 and CH39

  • 6: Advertise on CH38 and CH39

  • 7: Advertise on all channels

Recommended value: 7

Default value: 7
10 | uint8 | report_scan | If non-zero, enables scan request notification, and scan requests will be reported as events.

Default value: 0

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x0b

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_bt5_set_adv_parameters_rsp_t *gecko_cmd_le_gap_bt5_set_adv_parameters(uint8 handle, uint16 interval_min, uint16 interval_max, uint8 channel_map, uint8 report_scan);  
  
/* Response id */  
gecko_rsp_le_gap_bt5_set_adv_parameters_id  
  
/* Response structure */  
struct gecko_msg_le_gap_bt5_set_adv_parameters_rsp_t  
{  
  uint16 result  
}  

Events generated#

Event

Description

le_gap_scan_request

Triggered when a scan request has been received during

the advertising if scan request notification has been enabled by this command.

le_gap_bt5_set_mode#

Deprecated. Replacements are le_gap_start_advertising command to start the advertising, and le_gap_stop_advertising command to stop the advertising. le_gap_set_advertise_timing command can be used for setting the maxevents and command le_gap_set_advertise_configuration can be used to for setting address types.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x06

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x0a

method

Message ID

4

uint8

handle

Advertising set handle, number of sets available is

defined in stack configuration

5

uint8

discover

Discoverable mode

6

uint8

connect

Connectable mode

7-8

uint16

maxevents

If non-zero, indicates the maximum number of

advertising events to send before stopping advertiser. Value 0 indicates no

maximum number limit.

9

uint8

address_type

Address type to use for packets

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x0a

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_bt5_set_mode_rsp_t *gecko_cmd_le_gap_bt5_set_mode(uint8 handle, uint8 discover, uint8 connect, uint16 maxevents, uint8 address_type);  
  
/* Response id */  
gecko_rsp_le_gap_bt5_set_mode_id  
  
/* Response structure */  
struct gecko_msg_le_gap_bt5_set_mode_rsp_t  
{  
  uint16 result  
}  

Events generated#

Event

Description

le_gap_adv_timeout

Triggered when the number of advertising events set by

this command has been done and advertising is stopped on the given advertising

set.

le_connection_opened

Triggered when a remote device opened a connection to

the advertiser on the specified advertising set.

le_gap_clear_advertise_configuration#

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x05

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x13

method

Message ID

4

uint8

handle

Advertising set handle

5-8

uint32

configurations

Advertising configuration flags to disable.

This value can be a bitmask of multiple flags. See

le_gap_set_advertise_configuration for possible flags.

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x13

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_clear_advertise_configuration_rsp_t *gecko_cmd_le_gap_clear_advertise_configuration(uint8 handle, uint32 configurations);  
  
/* Response id */  
gecko_rsp_le_gap_clear_advertise_configuration_id  
  
/* Response structure */  
struct gecko_msg_le_gap_clear_advertise_configuration_rsp_t  
{  
  uint16 result  
}  

le_gap_connect#

This command can be used to connect an advertising device with the specified initiating PHY. The Bluetooth stack will enter a state where it continuously scans for the connectable advertising packets from the remote device which matches the Bluetooth address given as a parameter. Scan parameters set in le_gap_set_discovery_timing are used in this operation. Upon receiving the advertising packet, the module will send a connection request packet to the target device to initiate a Bluetooth connection. To cancel an ongoing connection process use the le_connection_close command with the handle received in the response from this command.

A connection is opened in no-security mode. If the GATT client needs to read or write the attributes on GATT server requiring encryption or authentication, it must first encrypt the connection using an appropriate authentication method.

If a connection cannot be established at all for some reason (for example, the remote device has gone out of range, has entered into deep sleep, or is not advertising), the stack will try to connect forever. In this case the application will not get any event related to the connection request. To recover from this situation, application can implement a timeout and call le_connection_close to cancel the connection request.

This command fails with "Connection Limit Exceeded" error if the number of connections attempted to be opened exceeds the configured MAX_CONNECTIONS value.

This command fails with "Invalid Parameter" error if the initiating PHY value is invalid or the device does not support the PHY.

Later calls of this command have to wait for the ongoing command to complete. A received event le_connection_opened indicates connection opened successfully and a received event le_connection_closed indicates connection failures have occurred.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x08

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x1a

method

Message ID

4-9

bd_addr

address

Address of the device to connect to

10

uint8

address_type

Address type of the device to connect to

11

uint8

initiating_phy

The initiating PHY. Value:

  • 1: LE 1M PHY

  • 4: LE Coded PHY

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x03

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x1a

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes
6 | uint8 | connection | Handle that will be assigned to the connection once the connection will be established. This handle is valid only if the result code of this response is 0 (zero).

API#

/* Function */  
struct gecko_msg_le_gap_connect_rsp_t *gecko_cmd_le_gap_connect(bd_addr address, uint8 address_type, uint8 initiating_phy);  
  
/* Response id */  
gecko_rsp_le_gap_connect_id  
  
/* Response structure */  
struct gecko_msg_le_gap_connect_rsp_t  
{  
  uint16 result,  
  uint8 connection  
}  

Events generated#

Event

Description

le_connection_opened

This event is triggered after the connection has been

opened, and indicates whether the devices are already bonded and what is the

role of the Bluetooth device (Slave or Master).

le_connection_parameters

This event indicates the connection parameters and

security mode of the connection.

le_gap_discover#

Deprecated. Replacement is le_gap_start_discovery command. To preserve the same functionality when migrating to this new command, use LE 1M PHY in scanning_phy parameter.

This command can be used to start the GAP discovery procedure to scan for advertising devices on LE 1M PHY. To cancel an ongoing discovery process use the le_gap_end_procedure command.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x01

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x02

method

Message ID

4

uint8

mode

Bluetooth discovery Mode. For values see link

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x02

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_discover_rsp_t *gecko_cmd_le_gap_discover(uint8 mode);  
  
/* Response id */  
gecko_rsp_le_gap_discover_id  
  
/* Response structure */  
struct gecko_msg_le_gap_discover_rsp_t  
{  
  uint16 result  
}  

Events generated#

Event

Description

le_gap_scan_response

Every time an advertising packet is received, this

event is triggered. The packets are not filtered in any way, so multiple

events will be received for every advertising device in range.

le_gap_enable_whitelisting#

This command is used to enable whitelisting. To add devices to the whitelist either bond with the device or add it manually with sm_add_to_whitelist

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x01

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x21

method

Message ID

4

uint8

enable

1 enable, 0 disable whitelisting.

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x21

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_enable_whitelisting_rsp_t *gecko_cmd_le_gap_enable_whitelisting(uint8 enable);  
  
/* Response id */  
gecko_rsp_le_gap_enable_whitelisting_id  
  
/* Response structure */  
struct gecko_msg_le_gap_enable_whitelisting_rsp_t  
{  
  uint16 result  
}  

le_gap_end_procedure#

This command can be used to end a current GAP procedure.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x00

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x03

method

Message ID

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x03

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_end_procedure_rsp_t *gecko_cmd_le_gap_end_procedure();  
  
/* Response id */  
gecko_rsp_le_gap_end_procedure_id  
  
/* Response structure */  
struct gecko_msg_le_gap_end_procedure_rsp_t  
{  
  uint16 result  
}  

le_gap_open#

Deprecated. Replacement is le_gap_connect command which allows to open a connection with a specified PHY.

This command can be used to connect an advertising device with initiating PHY being the LE 1M PHY.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x07

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x00

method

Message ID

4-9

bd_addr

address

Address of the device to connect to

10

uint8

address_type

Address type of the device to connect to

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x03

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x00

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes
6 | uint8 | connection | Handle that will be assigned to the connection once the connection will be established. This handle is valid only if the result code of this response is 0 (zero).

API#

/* Function */  
struct gecko_msg_le_gap_open_rsp_t *gecko_cmd_le_gap_open(bd_addr address, uint8 address_type);  
  
/* Response id */  
gecko_rsp_le_gap_open_id  
  
/* Response structure */  
struct gecko_msg_le_gap_open_rsp_t  
{  
  uint16 result,  
  uint8 connection  
}  

Events generated#

Event

Description

le_connection_opened

This event is triggered after the connection has been

opened, and indicates whether the devices are already bonded and what is the

role of the Bluetooth device (Slave or Master).

le_connection_parameters

This event indicates the connection parameters and

security mode of the connection.

le_gap_set_adv_data#

Deprecated. Use le_gap_bt5_set_adv_data command to set the advertising data and scan response data.

This command is only effective on the first advertising set (handle value 0). Other advertising sets are not affected.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x07

method

Message ID

4

uint8

scan_rsp

This value selects if the data is intended for

advertising packets, scan response packets or advertising packet in OTA.

Values:

  • 0: Advertising packets

  • 1: Scan response packets

  • 2: OTA advertising packets

  • 4: OTA scan response packets

5 | uint8array | adv_data | Data to be set. Maximum data length:

  • 31 bytes for legacy advertising;

  • 191 bytes for extended advertising

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x07

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_adv_data_rsp_t *gecko_cmd_le_gap_set_adv_data(uint8 scan_rsp, uint8 adv_data_len, const uint8 *adv_data_data);  
  
/* Response id */  
gecko_rsp_le_gap_set_adv_data_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_adv_data_rsp_t  
{  
  uint16 result  
}  

le_gap_set_adv_parameters#

Deprecated. Replacements are le_gap_set_advertise_timing command for setting the advertising intervals, and le_gap_set_advertise_channel_map command for setting the channel map.

This command is only effective on the first advertising set (handle value 0). Other advertising sets are not affected.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x05

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x04

method

Message ID

4-5

uint16

interval_min

Minimum advertising interval. Value in units

of 0.625 ms

  • Range: 0x20 to 0xFFFF

  • Time range: 20 ms to 40.96 s

Default value: 100 ms
6-7 | uint16 | interval_max | Maximum advertising interval. Value in units of 0.625 ms

  • Range: 0x20 to 0xFFFF

  • Time range: 20 ms to 40.96 s

  • Note: interval_max should be bigger than interval_min

Default value: 200 ms
8 | uint8 | channel_map | Advertising channel map which determines which of the three channels will be used for advertising. This value is given as a bitmask. Values:

  • 1: Advertise on CH37

  • 2: Advertise on CH38

  • 3: Advertise on CH37 and CH38

  • 4: Advertise on CH39

  • 5: Advertise on CH37 and CH39

  • 6: Advertise on CH38 and CH39

  • 7: Advertise on all channels

Recommended value: 7

Default value: 7

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x04

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_adv_parameters_rsp_t *gecko_cmd_le_gap_set_adv_parameters(uint16 interval_min, uint16 interval_max, uint8 channel_map);  
  
/* Response id */  
gecko_rsp_le_gap_set_adv_parameters_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_adv_parameters_rsp_t  
{  
  uint16 result  
}  

le_gap_set_adv_timeout#

Deprecated. New command le_gap_set_advertise_timing should be used for this functionality.

This command is only effective on the first advertising set (handle value 0). Other advertising sets are not affected.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x01

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x08

method

Message ID

4

uint8

maxevents

If non-zero, indicates the maximum number of

advertising events to send before stopping advertiser. Value 0 indicates no

maximum number limit.

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x08

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_adv_timeout_rsp_t *gecko_cmd_le_gap_set_adv_timeout(uint8 maxevents);  
  
/* Response id */  
gecko_rsp_le_gap_set_adv_timeout_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_adv_timeout_rsp_t  
{  
  uint16 result  
}  

le_gap_set_advertise_channel_map#

This command can be used to set the primary advertising channel map of the given advertising set. This setting will take effect on the next advertising enabling.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x0f

method

Message ID

4

uint8

handle

Advertising set handle

5

uint8

channel_map

Advertisement channel map which determines which

of the three channels will be used for advertising. This value is given as a

bitmask. Values:

  • 1: Advertise on CH37

  • 2: Advertise on CH38

  • 3: Advertise on CH37 and CH38

  • 4: Advertise on CH39

  • 5: Advertise on CH37 and CH39

  • 6: Advertise on CH38 and CH39

  • 7: Advertise on all channels

Recommended value: 7

Default value: 7

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x0f

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_advertise_channel_map_rsp_t *gecko_cmd_le_gap_set_advertise_channel_map(uint8 handle, uint8 channel_map);  
  
/* Response id */  
gecko_rsp_le_gap_set_advertise_channel_map_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_advertise_channel_map_rsp_t  
{  
  uint16 result  
}  

le_gap_set_advertise_configuration#

This command can be used to enable advertising configuration flags on the given advertising set. The configuration change will take effects on the next advertising enabling.

These configuration flags can be disabled using le_gap_clear_advertise_configuration command.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x05

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x12

method

Message ID

4

uint8

handle

Advertising set handle

5-8

uint32

configurations

Advertising configuration flags to enable.

This value can be a bitmask of multiple flags. Flags:

  • 1 (Bit 0): Use legacy advertising PDUs.

  • 2 (Bit 1): Omit advertiser's address from all PDUs (anonymous advertising). This flag is effective only in extended advertising.

  • 4 (Bit 2): Use le_gap_non_resolvable address type. Advertising must be in non-connectable mode if this configuration is enabled.

  • 8 (Bit 3): Include TX power in advertising packets. This flag is effective only in extended advertising.

Default value: 1

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x12

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_advertise_configuration_rsp_t *gecko_cmd_le_gap_set_advertise_configuration(uint8 handle, uint32 configurations);  
  
/* Response id */  
gecko_rsp_le_gap_set_advertise_configuration_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_advertise_configuration_rsp_t  
{  
  uint16 result  
}  

le_gap_set_advertise_phy#

This command can be used to set the advertising PHYs of the given advertising set. This setting will take effect on the next advertising enabling. "Invalid Parameter" error will be returned if a PHY value is invalid or the device does not support a given PHY.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x03

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x11

method

Message ID

4

uint8

handle

Advertising set handle

5

uint8

primary_phy

The PHY on which the advertising packets are

transmitted on the primary advertising channel. If legacy advertising PDUs are

being used, the PHY must be LE 1M.

Values:

  • 1: Advertising PHY is LE 1M

  • 4: Advertising PHY is LE Coded

Default: 1

6 | uint8 | secondary_phy | The PHY on which the advertising packets are transmitted on the secondary advertising channel.

Values:

  • 1: Advertising PHY is LE 1M

  • 2: Advertising PHY is LE 2M

  • 4: Advertising PHY is LE Coded

Default: 1

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x11

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_advertise_phy_rsp_t *gecko_cmd_le_gap_set_advertise_phy(uint8 handle, uint8 primary_phy, uint8 secondary_phy);  
  
/* Response id */  
gecko_rsp_le_gap_set_advertise_phy_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_advertise_phy_rsp_t  
{  
  uint16 result  
}  

le_gap_set_advertise_report_scan_request#

This command can be used to enable or disable the scan request notification of the given advertising set. This setting will take effect on the next advertising enabling.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x10

method

Message ID

4

uint8

handle

Advertising set handle

5

uint8

report_scan_req

If non-zero, enables scan request

notification, and scan requests will be reported as events.

Default value: 0

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x10

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_advertise_report_scan_request_rsp_t *gecko_cmd_le_gap_set_advertise_report_scan_request(uint8 handle, uint8 report_scan_req);  
  
/* Response id */  
gecko_rsp_le_gap_set_advertise_report_scan_request_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_advertise_report_scan_request_rsp_t  
{  
  uint16 result  
}  

Events generated#

Event

Description

le_gap_scan_request

Triggered when a scan request has been received during

the advertising if scan request notification has been enabled by this command.

le_gap_set_advertise_timing#

This command can be used to set the advertising timing parameters of the given advertising set. This setting will take effect on the next advertising enabling.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x0c

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x0e

method

Message ID

4

uint8

handle

Advertising set handle

5-8

uint32

interval_min

Minimum advertising interval. Value in units

of 0.625 ms

  • Range: 0x20 to 0xFFFF

  • Time range: 20 ms to 40.96 s

Default value: 100 ms
9-12 | uint32 | interval_max | Maximum advertising interval. Value in units of 0.625 ms

  • Range: 0x20 to 0xFFFF

  • Time range: 20 ms to 40.96 s

  • Note: interval_max should be bigger than interval_min

Default value: 200 ms
13-14 | uint16 | duration | The advertising duration for this advertising set. Value 0 indicates no advertising duration limit and the advertising continues until it is disabled. A non-zero value sets the duration in units of 10 ms. The duration begins at the start of the first advertising event of this advertising set.

  • Range: 0x0001 to 0xFFFF

  • Time range: 10 ms to 655.35 s

Default value: 0
15 | uint8 | maxevents | If non-zero, indicates the maximum number of advertising events to send before stopping advertiser. Value 0 indicates no maximum number limit.

Default value: 0

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x0e

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_advertise_timing_rsp_t *gecko_cmd_le_gap_set_advertise_timing(uint8 handle, uint32 interval_min, uint32 interval_max, uint16 duration, uint8 maxevents);  
  
/* Response id */  
gecko_rsp_le_gap_set_advertise_timing_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_advertise_timing_rsp_t  
{  
  uint16 result  
}  

le_gap_set_advertise_tx_power#

This command can be used to limit the maximum advertising TX power on the given advertising set. If the value goes over the global value that has been set using system_set_tx_power command, the global value will be the maximum limit. The maximum TX power of legacy advertising is further constrainted to not go over +10 dBm. Extended advertising TX power can be +10 dBm and over if Adaptive Frequency Hopping has been enabled.

This setting will take effect on the next advertising enabling.

By default, maximum advertising TX power is limited by the global value.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x03

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x1b

method

Message ID

4

uint8

handle

Advertising set handle

5-6

int16

power

TX power in 0.1dBm steps, for example the value of 10

is 1dBm and 55 is 5.5dBm

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x04

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x1b

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes
6-7 | int16 | set_power | The selected maximum advertising TX power

API#

/* Function */  
struct gecko_msg_le_gap_set_advertise_tx_power_rsp_t *gecko_cmd_le_gap_set_advertise_tx_power(uint8 handle, int16 power);  
  
/* Response id */  
gecko_rsp_le_gap_set_advertise_tx_power_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_advertise_tx_power_rsp_t  
{  
  uint16 result,  
  int16 set_power  
}  

le_gap_set_conn_parameters#

This command can be used to set the default Bluetooth connection parameters. The configured values are valid for all subsequent connections that will be established. For changing the parameters of an already established connection use the command le_connection_set_parameters.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x08

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x05

method

Message ID

4-5

uint16

min_interval

Minimum value for the connection event

interval. This must be set be less than or equal to max_interval.

  • Time = Value x 1.25 ms

  • Range: 0x0006 to 0x0c80

  • Time Range: 7.5 ms to 4 s

Default value: 20 ms
6-7 | uint16 | max_interval | Maximum value for the connection event interval. This must be set greater than or equal to min_interval.

  • Time = Value x 1.25 ms

  • Range: 0x0006 to 0x0c80

  • Time Range: 7.5 ms to 4 s

Default value: 50 ms
8-9 | uint16 | latency | Slave latency. This parameter defines how many connection intervals the slave can skip if it has no data to send

  • Range: 0x0000 to 0x01f4

Default value: 0
10-11 | uint16 | timeout | Supervision timeout. The supervision timeout defines for how long the connection is maintained despite the devices being unable to communicate at the currently configured connection intervals.

  • Range: 0x000a to 0x0c80

  • Time = Value x 10 ms

  • Time Range: 100 ms to 32 s

  • The value in milliseconds must be larger than (1 + latency) max_interval 2, where max_interval is given in milliseconds

It is recommended that the supervision timeout is set at a value which allows communication attempts over at least a few connection intervals.

Default value: 1000 ms

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x05

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_conn_parameters_rsp_t *gecko_cmd_le_gap_set_conn_parameters(uint16 min_interval, uint16 max_interval, uint16 latency, uint16 timeout);  
  
/* Response id */  
gecko_rsp_le_gap_set_conn_parameters_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_conn_parameters_rsp_t  
{  
  uint16 result  
}  

le_gap_set_data_channel_classification#

This command can be used to specify a channel classification for data channels. This classification persists until overwritten with a subsequent command or until the system is reset.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x01

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x19

method

Message ID

4

uint8array

channel_map

This parameter is 5 bytes and contains 37

1-bit fields.

The nth such field (in the range 0 to 36) contains the value for the link

layer channel index n.

  • 0: Channel n is bad.

  • 1: Channel n is unknown.

The most significant bits are reserved and shall be set to 0 for future use.
At least two channels shall be marked as unknown.

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x19

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_data_channel_classification_rsp_t *gecko_cmd_le_gap_set_data_channel_classification(uint8 channel_map_len, const uint8 *channel_map_data);  
  
/* Response id */  
gecko_rsp_le_gap_set_data_channel_classification_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_data_channel_classification_rsp_t  
{  
  uint16 result  
}  

le_gap_set_discovery_extended_scan_response#

This command can be used to enable and disable the extended scan response event. When the extended scan response event is enabled, it replaces le_gap_scan_response, that is, the stack will generate either le_gap_extended_scan_response or le_gap_scan_response, but not both at a time.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x01

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x1c

method

Message ID

4

uint8

enable

Values:

  • 0: Disable extended scan response event

  • 1: Enable extended scan response event

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x1c

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_discovery_extended_scan_response_rsp_t *gecko_cmd_le_gap_set_discovery_extended_scan_response(uint8 enable);  
  
/* Response id */  
gecko_rsp_le_gap_set_discovery_extended_scan_response_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_discovery_extended_scan_response_rsp_t  
{  
  uint16 result  
}  

le_gap_set_discovery_timing#

This command can be used to set the timing parameters of the specified PHYs. If the device is currently scanning for advertising devices the PHYs, new parameters will take effect when the scanning is restarted.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x05

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x16

method

Message ID

4

uint8

phys

The PHYs for which the parameters are set.

  • 1: LE 1M PHY

  • 4: LE Coded PHY

  • 5: LE 1M PHY and LE Coded PHY

5-6 | uint16 | scan_interval | Scan interval. This is defined as the time interval from when the device started its last scan until it begins the subsequent scan, that is how often to scan

  • Time = Value x 0.625 ms

  • Range: 0x0004 to 0xFFFF

  • Time Range: 2.5 ms to 40.96 s

Default value: 10 ms

There is a variable delay when switching channels at the end of each scanning interval which is included in the scanning interval time itself. During this switch time no advertising packets will be received by the device. The switch time variation is dependent on use case, for example in case of scanning while keeping active connections the channel switch time might be longer than when only scanning without any active connections. Increasing the scanning interval will reduce the amount of time in which the device cannot receive advertising packets as it will switch channels less often.

After every scan interval the scanner will change the frequency it operates at. It will cycle through all the three advertising channels in a round robin fashion. According to the specification all three channels must be used by a scanner.

7-8 | uint16 | scan_window | Scan window. The duration of the scan. scan_window shall be less than or equal to scan_interval

  • Time = Value x 0.625 ms

  • Range: 0x0004 to 0xFFFF

  • Time Range: 2.5 ms to 40.96 s

Default value: 10 ms Note that packet reception is aborted if it has been started before scan window ends.

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x16

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_discovery_timing_rsp_t *gecko_cmd_le_gap_set_discovery_timing(uint8 phys, uint16 scan_interval, uint16 scan_window);  
  
/* Response id */  
gecko_rsp_le_gap_set_discovery_timing_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_discovery_timing_rsp_t  
{  
  uint16 result  
}  

le_gap_set_discovery_type#

This command can be used to set the scan type of the specified PHYs. If the device is currently scanning for advertising devices on the PHYs, new parameters will take effect when the scanning is restarted

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x17

method

Message ID

4

uint8

phys

The PHYs for which the parameters are set.

  • 1: LE 1M PHY

  • 4: LE Coded PHY

  • 5: LE 1M PHY and LE Coded PHY

5 | uint8 | scan_type | Scan type indicated by a flag. Values:

  • 0: Passive scanning

  • 1: Active scanning

  • In passive scanning mode the device only listens to advertising packets and will not transmit any packet

  • In active scanning mode the device will send out a scan request packet upon receiving advertising packet from a remote device and then it will listen to the scan response packet from remote device

Default value: 0

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x17

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_discovery_type_rsp_t *gecko_cmd_le_gap_set_discovery_type(uint8 phys, uint8 scan_type);  
  
/* Response id */  
gecko_rsp_le_gap_set_discovery_type_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_discovery_type_rsp_t  
{  
  uint16 result  
}  

le_gap_set_mode#

Deprecated. Use le_gap_start_advertising command for enabling the advertising, and le_gap_stop_advertising command for disabling the advertising.

This command is only effective on the first advertising set (handle value 0). Other advertising sets are not affected.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x01

method

Message ID

4

uint8

discover

Discoverable mode

5

uint8

connect

Connectable mode

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x01

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_mode_rsp_t *gecko_cmd_le_gap_set_mode(uint8 discover, uint8 connect);  
  
/* Response id */  
gecko_rsp_le_gap_set_mode_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_mode_rsp_t  
{  
  uint16 result  
}  

Events generated#

Event

Description

le_gap_adv_timeout

Triggered when the number of advertising events has been

done and advertising is stopped.

le_connection_opened

Triggered when a remote device opened a connection to

this advertising device.

le_gap_set_privacy_mode#

This command can be used to enable or disable privacy feature on all GAP roles. The new privacy mode will take effect for advertising on the next advertising enabling, for scanning on the next scan enabling, and for initiating on the next open connection command. When privacy is enabled and the device is advertising or scanning, the stack will maintain a periodic timer with the specified time interval as timeout value. At each timeout the stack will generate a new private resolvable address and use it in advertising data packets and scanning requests.

By default, privacy feature is disabled.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x0d

method

Message ID

4

uint8

privacy

Values:

  • 0: Disable privacy

  • 1: Enable privacy

5 | uint8 | interval | The minimum time interval between private address change. This parameter is ignored if this command is issued for disabling privacy mode. Values:

  • 0: Use default interval, 15 minutes

  • others: The time interval in minutes

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x0d

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_privacy_mode_rsp_t *gecko_cmd_le_gap_set_privacy_mode(uint8 privacy, uint8 interval);  
  
/* Response id */  
gecko_rsp_le_gap_set_privacy_mode_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_privacy_mode_rsp_t  
{  
  uint16 result  
}  

le_gap_set_scan_parameters#

Deprecated. Replacements are le_gap_set_discovery_timing command for setting timing parameters, and le_gap_set_discovery_type command for the scan type.

The parameters set by this command is only effective on the LE 1M PHY. For LE Coded PHY, above replacement command must be used.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x05

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x06

method

Message ID

4-5

uint16

scan_interval

Scanner interval. This is defined as the

time interval from when the device started its last scan until it begins the

subsequent scan, that is how often to scan

  • Time = Value x 0.625 ms

  • Range: 0x0004 to 0x4000

  • Time Range: 2.5 ms to 10.24 s

Default value: 10 ms

There is a variable delay when switching channels at the end of each scanning interval which is included in the scanning interval time itself. During this switch time no advertising packets will be received by the device. The switch time variation is dependent on use case, for example in case of scanning while keeping active connections the channel switch time might be longer than when only scanning without any active connections. Increasing the scanning interval will reduce the amount of time in which the device cannot receive advertising packets as it will switch channels less often.

After every scan interval the scanner will change the frequency it operates at. It will cycle through all the three advertising channels in a round robin fashion. According to the specification all three channels must be used by a scanner.

6-7 | uint16 | scan_window | Scan window. The duration of the scan. scan_window shall be less than or equal to scan_interval

  • Time = Value x 0.625 ms

  • Range: 0x0004 to 0x4000

  • Time Range: 2.5 ms to 10.24 s

Default value: 10 ms Note that packet reception is aborted if it has been started before scan window ends.
8 | uint8 | active | Scan type indicated by a flag. Values:

  • 0: Passive scanning

  • 1: Active scanning

  • In passive scanning mode the device only listens to advertising packets and will not transmit any packet

  • In active scanning mode the device will send out a scan request packet upon receiving advertising packet from a remote device and then it will listen to the scan response packet from remote device

Default value: 0

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x06

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_set_scan_parameters_rsp_t *gecko_cmd_le_gap_set_scan_parameters(uint16 scan_interval, uint16 scan_window, uint8 active);  
  
/* Response id */  
gecko_rsp_le_gap_set_scan_parameters_id  
  
/* Response structure */  
struct gecko_msg_le_gap_set_scan_parameters_rsp_t  
{  
  uint16 result  
}  

le_gap_start_advertising#

This command can be used to start the advertising of the given advertising set with specified discoverable and connectable modes.

The number of concurrent connectable advertisings is also limited by MAX_CONNECTIONS configuration. For example, only one connectable advertising can be enabled if the device has (MAX_CONNECTIONS - 1) connections when this command is called. The limitation does not apply to non-connectable advertising.

The default advertising configuration in the stack is set to using legacy advertising PDUs on LE 1M PHY. The stack will automatically select extended advertising PDUs if either of the followings has occurred under the default configuration:

  1. The connectable mode is set to le_gap_connectable_non_scannable.

  2. The primary advertising PHY has been set to LE Coded PHY by command le_gap_set_advertise_phy.

  3. The user advertising data length is more than 31 bytes.

  4. Periodic advertising has been enabled.

If currently set parameters can't be used then an error will be returned. Specifically, this command fails with "Connection Limit Exceeded" error if it may cause the number of connections exceeding the configured MAX_CONNECTIONS value. It fails with "Invalid Parameter" error if one of the following cases occur:

  1. Non-resolvable random address is used but the connectable mode is le_gap_connectable_scannable or le_gap_connectable_non_scannable.

  2. The connectable mode is le_gap_connectable_non_scannable, but using legacy advertising PDUs has been explicitly enabled with command le_gap_set_advertise_configuration.

  3. The primary advertising PHY is LE Coded PHY but using legacy advertising PDUs has been explicitly enabled with command le_gap_set_advertise_configuration.

  4. The connectable mode is le_gap_connectable_scannable but using extended advertising PDUs has been explicitly enabled or the primary advertising PHY has been set to LE Coded PHY.

If advertising will be enabled in user_data mode, le_gap_bt5_set_adv_data should be used to set advertising and scan response data before issuing this command. When the advertising is enabled in other modes than user_data, the advertising and scan response data is generated by the stack using the following procedure:

  1. Add a Flags field to advertising data.

  2. Add a TX power level field to advertising data if TX power service exists in the local GATT database.

  3. Add a Slave Connection Interval Range field to advertising data if the GAP peripheral preferred connection parameters characteristic exists in the local GATT database.

  4. Add a list of 16-bit Service UUIDs to advertising data if there are one or more 16-bit service UUIDs to advertise. The list is complete if all advertised 16-bit UUIDs are in advertising data; otherwise the list is incomplete.

  5. Add a list of 128-bit service UUIDs to advertising data if there are one or more 128-bit service UUIDs to advertise and there is still free space for this field. The list is complete if all advertised 128-bit UUIDs are in advertising data; otherwise the list is incomplete. Note that an advertising data packet can contain at most one 128-bit service UUID.

  6. Try to add the full local name to advertising data if device is not in privacy mode. In case the full local name does not fit into the remaining free space, the advertised name is a shortened version by cutting off the end if the free space has at least 6 bytes; Otherwise, the local name is added to scan response data.

Event le_connection_opened will be received when a remote device opens a connection to the advertiser on this advertising set.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x03

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x14

method

Message ID

4

uint8

handle

Advertising set handle

5

uint8

discover

Discoverable mode

6

uint8

connect

Connectable mode

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x14

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_start_advertising_rsp_t *gecko_cmd_le_gap_start_advertising(uint8 handle, uint8 discover, uint8 connect);  
  
/* Response id */  
gecko_rsp_le_gap_start_advertising_id  
  
/* Response structure */  
struct gecko_msg_le_gap_start_advertising_rsp_t  
{  
  uint16 result  
}  

Events generated#

Event

Description

le_gap_adv_timeout

Triggered when the number of advertising events set by

this command has been done and advertising is stopped on the given advertising

set.

le_connection_opened

Triggered when a remote device opened a connection to

the advertiser on the specified advertising set.

le_gap_start_discovery#

This command can be used to start the GAP discovery procedure to scan for advertising devices on the specified scanning PHY, that is to perform a device discovery. To cancel an ongoing discovery process use the le_gap_end_procedure command.

"Invalid Parameter" error will be returned if the scanning PHY value is invalid or the device does not support the PHY.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x18

method

Message ID

4

uint8

scanning_phy

The scanning PHY. Value:

  • 1: LE 1M PHY

  • 4: LE Coded PHY

5 | uint8 | mode | Bluetooth discovery Mode. For values see link

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x18

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_start_discovery_rsp_t *gecko_cmd_le_gap_start_discovery(uint8 scanning_phy, uint8 mode);  
  
/* Response id */  
gecko_rsp_le_gap_start_discovery_id  
  
/* Response structure */  
struct gecko_msg_le_gap_start_discovery_rsp_t  
{  
  uint16 result  
}  

Events generated#

Event

Description

le_gap_scan_response

Every time an advertising packet is received, this

event is triggered. The packets are not filtered in any way, so multiple

events will be received for every advertising device in range.

le_gap_start_periodic_advertising#

This command can be used to start periodic advertising on the given advertising set. The stack will enable the advertising set automatically if the set has not been enabled and the set can advertise using extended advertising PDUs.

"Invalid Parameter" error will be returned if the application has configured to use legacy advertising PDUs or anonymous advertising, or advertising set has been enabled using legacy advertising PDUs.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x09

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x1d

method

Message ID

4

uint8

handle

Advertising set handle

5-6

uint16

interval_min

Minimum periodic advertising interval. Value

in units of 1.25 ms

  • Range: 0x06 to 0xFFFF

  • Time range: 7.5 ms to 81.92 s

Default value: 100 ms
7-8 | uint16 | interval_max | Maximum periodic advertising interval. Value in units of 1.25 ms

  • Range: 0x06 to 0xFFFF

  • Time range: 7.5 ms to 81.92 s

  • Note: interval_max should be bigger than interval_min

Default value: 200 ms
9-12 | uint32 | flags | Periodic advertising configurations. Bitmask of followings:

  • Bit 0: Include TX power in advertising PDU

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x1d

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_start_periodic_advertising_rsp_t *gecko_cmd_le_gap_start_periodic_advertising(uint8 handle, uint16 interval_min, uint16 interval_max, uint32 flags);  
  
/* Response id */  
gecko_rsp_le_gap_start_periodic_advertising_id  
  
/* Response structure */  
struct gecko_msg_le_gap_start_periodic_advertising_rsp_t  
{  
  uint16 result  
}  

le_gap_stop_advertising#

This command can be used to stop the advertising of the given advertising set.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x01

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x15

method

Message ID

4

uint8

handle

Advertising set handle

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x15

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_stop_advertising_rsp_t *gecko_cmd_le_gap_stop_advertising(uint8 handle);  
  
/* Response id */  
gecko_rsp_le_gap_stop_advertising_id  
  
/* Response structure */  
struct gecko_msg_le_gap_stop_advertising_rsp_t  
{  
  uint16 result  
}  

le_gap_stop_periodic_advertising#

This command can be used to stop the periodic advertising on the given advertising set.

This command does not affect the enable state of the advertising set.

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x01

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x1f

method

Message ID

4

uint8

handle

Advertising set handle

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x1f

method

Message ID

4-5

uint16

result

Result code

  • 0: success

  • Non-zero: an error occurred

For other values refer to the Error codes

API#

/* Function */  
struct gecko_msg_le_gap_stop_periodic_advertising_rsp_t *gecko_cmd_le_gap_stop_periodic_advertising(uint8 handle);  
  
/* Response id */  
gecko_rsp_le_gap_stop_periodic_advertising_id  
  
/* Response structure */  
struct gecko_msg_le_gap_stop_periodic_advertising_rsp_t  
{  
  uint16 result  
}  

le_gap events#

le_gap_scan_response#

This event reports any advertising or scan response packet that is received by the device's radio while in scanning mode.

Note that this event will be replaced by le_gap_extended_scan_response if extended scan response event has been enabled. The extended scan response event can be enabled or disabled using command le_gap_set_discovery_extended_scan_response command.

Event#

Byte

Type

Name

Description

0

0xa0

hilen

Message type: Event

1

0x0b

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x00

method

Message ID

4

int8

rssi

Signal strength indicator (RSSI) in the latest received

packet. Units: dBm

  • Range: -127 to +20

5 | uint8 | packet_type |

Bits 0..2 : advertising packet type

  • 000 : Connectable scannable undirected advertising

  • 001 : Connectable undirected advertising

  • 010 : Scannable undirected advertising

  • 011 : Non-connectable non-scannable undirected advertising

  • 100 : Scan Response. Note: this is received only if the device is in active scan mode.

Bits 3..4 : Reserved for future

Bits 5..6 : data completeness

  • 00: Complete

  • 10: Incomplete, data truncated, no more to come

Bit 7 : legacy or extended advertising

  • 0: Legacy advertising PDUs used

  • 1: Extended advertising PDUs used

6-11 | bd_addr | address | Bluetooth address of the remote device
12 | uint8 | address_type | Advertiser address type. Values:

  • 0: Public address

  • 1: Random address

  • 255: No address provided (anonymous advertising)

13 | uint8 | bonding | Bonding handle if the remote advertising device has previously bonded with the local device. Values:

  • 0xff: No bonding

  • Other: Bonding handle

14 | uint8array | data | Advertising or scan response data

API#

/* event id*/  
gecko_evt_le_gap_scan_response_id  
  
/* event structure*/  
struct gecko_msg_le_gap_scan_response_evt_t  
{  
  int8 rssi,  
  uint8 packet_type,  
  bd_addr address,  
  uint8 address_type,  
  uint8 bonding,  
  uint8array data  
}  

le_gap_adv_timeout#

This event indicates that the advertiser has completed the configured number of advertising events in the advertising set and advertising is stopped. The maximum number of advertising events can be configured by the maxevents parameter in command le_gap_set_advertise_timing.

Event#

Byte

Type

Name

Description

0

0xa0

hilen

Message type: Event

1

0x01

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x01

method

Message ID

4

uint8

handle

The advertising set handle

API#

/* event id*/  
gecko_evt_le_gap_adv_timeout_id  
  
/* event structure*/  
struct gecko_msg_le_gap_adv_timeout_evt_t  
{  
  uint8 handle  
}  

le_gap_scan_request#

This event reports any scan request received in advertising mode if scan request notification is enabled

Event#

Byte

Type

Name

Description

0

0xa0

hilen

Message type: Event

1

0x09

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x02

method

Message ID

4

uint8

handle

The advertising set handle where scan request was

received

5-10

bd_addr

address

Bluetooth address of the scanning device

11

uint8

address_type

Scanner address type. Values:

  • 0: Public address

  • 1: Random address

12 | uint8 | bonding | Bonding handle if the remote scanning device has previously bonded with the local device. Values:

  • 0xff: No bonding

  • Other: Bonding handle

API#

/* event id*/  
gecko_evt_le_gap_scan_request_id  
  
/* event structure*/  
struct gecko_msg_le_gap_scan_request_evt_t  
{  
  uint8 handle,  
  bd_addr address,  
  uint8 address_type,  
  uint8 bonding  
}  

le_gap_extended_scan_response#

This event reports an advertising or scan response packet that is received by the device's radio while in scanning mode.

By default this event is disabled and the stack will not generate it. The application needs to enable it using le_gap_set_discovery_extended_scan_response command. When this event is enabled it replaces le_gap_scan_response, that is, the stack will generate either this event or le_gap_scan_response, but not both at a time.

Event#

Byte

Type

Name

Description

0

0xa0

hilen

Message type: Event

1

0x12

lolen

Minimum payload length

2

0x03

class

Message class:Generic Access Profile

3

0x04

method

Message ID

4

uint8

packet_type

Bits 0..2 : advertising packet type

  • 000 : Connectable scannable undirected advertising

  • 001 : Connectable undirected advertising

  • 010 : Scannable undirected advertising

  • 011 : Non-connectable non-scannable undirected advertising

  • 100 : Scan Response. Note: this is received only if the device is in active scan mode.

Bits 3..4 : Reserved for future

Bits 5..6 : data completeness

  • 00: Complete

  • 10: Incomplete, data truncated, no more to come

Bit 7 : legacy or extended advertising

  • 0: Legacy advertising PDUs used

  • 1: Extended advertising PDUs used

5-10 | bd_addr | address | Bluetooth address of the remote device
11 | uint8 | address_type | Advertiser address type. Values:

  • 0: Public address

  • 1: Random address

  • 255: No address provided (anonymous advertising)

12 | uint8 | bonding | Bonding handle if the remote advertising device has previously bonded with the local device. Values:

  • 0xff: No bonding

  • Other: Bonding handle

13 | uint8 | primary_phy | The PHY on which advertising packets are transmitted on the primary advertising channel.

Values:

  • 1: LE 1M PHY

  • 4: LE Coded PHY

14 | uint8 | secondary_phy | The PHY on which advertising packets are transmitted on the secondary advertising channel.

Values:

  • 1: Advertising PHY is LE 1M

  • 2: Advertising PHY is LE 2M

  • 4: Advertising PHY is LE Coded

15 | uint8 | adv_sid | Advertising set identifier
16 | int8 | tx_power | TX power value in the received packet header. Units: dBm

  • Valid value range: -127 to 126

  • Value 127: information unavailable

17 | int8 | rssi | Signal strength indicator (RSSI) in the last received packet. Units: dBm

  • Range: -127 to +20

18 | uint8 | channel | The channel number on which the last packet was received
19-20 | uint16 | periodic_interval | The periodic advertising interval. Value 0 indicates no periodic advertising. Otherwise,

  • Range: 0x06 to 0xFFFF

  • Unit: 1.25 ms

  • Time range: 7.5 ms to 81.92 s

21 | uint8array | data | Advertising or scan response data

API#

/* event id*/  
gecko_evt_le_gap_extended_scan_response_id  
  
/* event structure*/  
struct gecko_msg_le_gap_extended_scan_response_evt_t  
{  
  uint8 packet_type,  
  bd_addr address,  
  uint8 address_type,  
  uint8 bonding,  
  uint8 primary_phy,  
  uint8 secondary_phy,  
  uint8 adv_sid,  
  int8 tx_power,  
  int8 rssi,  
  uint8 channel,  
  uint16 periodic_interval,  
  uint8array data  
}  

le_gap enumerations#

le_gap_address_type#

These values define the Bluetooth Address types used by the stack.

Enumerations#

Value

Name

Description

0

le_gap_address_type_public

Public address

1

le_gap_address_type_random

Random address

2

le_gap_address_type_public_identity

Public identity address resolved by

stack

3

le_gap_address_type_random_identity

Random identity address resolved by

stack

le_gap_phy_type#

Types of PHYs used within le_gap class.

Enumerations#

Value

Name

Description

1

le_gap_phy_1m

LE 1M PHY

2

le_gap_phy_2m

LE 2M PHY

4

le_gap_phy_coded

LE Coded PHY

le_gap_connectable_mode#

These values define the available connectable modes.

Enumerations#

Value

Name

Description

0

le_gap_non_connectable

Non-connectable non-scannable.

1

le_gap_directed_connectable

Directed connectable (RESERVED, DO NOT USE)

2

le_gap_undirected_connectable

Undirected connectable scannable.

Deprecated , replaced by enum le_gap_connectable_scannable.

This mode can only be used in legacy advertising PDUs.
2 | le_gap_connectable_scannable | Undirected connectable scannable. This mode can only be used in legacy advertising PDUs.
3 | le_gap_scannable_non_connectable | Undirected scannable (Non-connectable but responds to scan requests)
4 | le_gap_connectable_non_scannable | Undirected connectable non-scannable. This mode can only be used in extended advertising PDUs.

le_gap_discoverable_mode#

These values define the available Discoverable Modes, which dictate how the device is visible to other devices.

Enumerations#

Value

Name

Description

0

le_gap_non_discoverable

Not discoverable

1

le_gap_limited_discoverable

Discoverable using both limited and general

discovery procedures

2

le_gap_general_discoverable

Discoverable using general discovery

procedure

3

le_gap_broadcast

Device is not discoverable in either limited or generic

discovery procedure, but may be discovered by using the Observation procedure

4

le_gap_user_data

Send advertising and/or scan response data defined by

the user using le_gap_bt5_set_adv_data. The limited/general discoverable flags

are defined by the user.

le_gap_discover_mode#

These values indicate which Bluetooth discovery mode to use when scanning for advertising devices.

Enumerations#

Value

Name

Description

0

le_gap_discover_limited

Discover only limited discoverable devices

1

le_gap_discover_generic

Discover limited and generic discoverable

devices

2

le_gap_discover_observation

Discover all devices

le_gap_adv_address_type#

Address type to use for advertising

Enumerations#

Value

Name

Description

0

le_gap_identity_address

Use public or static device address, or identity

address if privacy mode is enabled

1

le_gap_non_resolvable

Use non resolvable address type, advertising mode

must also be non-connectable