Generic Access Profile (le_gap)

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

le_gap commands

le_gap_bt5_set_adv_data

Set user-defined data in advertising packets, scan response packets, or periodic advertising packets. Maximum 31 bytes of data can be set for legacy advertising. Maximum 191 bytes of data can be set for connectable extended advertising. Maximum 253 bytes of data can be set for periodic and non-connectable extended advertising. For setting longer advertising data, use command le_gap_set_long_advertising_data.

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 invalid parameter error will be returned in the following situations:

  • Data length is more than 31 bytes but the advertiser can only advertise using legacy advertising PDUs.
  • Data is too long to fit into a single advertisement.
  • Set data of the advertising data packet when the advertiser is advertising in scannable mode using extended advertising PDUs.
  • Set data of the 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 a discoverable mode other than user_data.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
uint8 scan_rsp This value selects whether data is intended for advertising packets, scan response packets, periodic advertising packets, or advertising packets in OTA. Values are as follows:
  • 0: Advertising packets
  • 1: Scan response packets
  • 2: OTA advertising packets
  • 4: OTA scan response packets
  • 8: Periodic advertising packets
uint8 adv_data_len Array length.
uint8array adv_data_data Data to be set

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_bt5_set_adv_parameters

Deprecated and replaced by le_gap_set_advertise_timing command to set the advertising intervals, le_gap_set_advertise_channel_map command to set the channel map, and le_gap_set_advertise_report_scan_request command to enable and disable scan request notifications.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
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
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
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
uint8 report_scan If non-zero, enables scan request notification, and scan requests will be reported as events.

Default value: 0

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

Events generated

Event Description
le_gap_scan_request Triggered when a scan request is received during advertising if the scan request notification is enabled by this command.

le_gap_bt5_set_mode

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

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
uint8 discover Discoverable mode
uint8 connect Connectable mode
uint16 maxevents If non-zero, indicates the maximum number of advertising events to send before stopping the advertiser. Value 0 indicates no maximum number limit.
uint8 address_type Address type to use for packets

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

Events generated

Event Description
le_gap_adv_timeout Triggered when the advertising events set by this command are complete and advertising is stopped on the given advertising set.
le_connection_opened Triggered when a remote device opens a connection to the advertiser on the specified advertising set.

le_gap_clear_advertise_configuration

Disable advertising configuration flags on the given advertising set. The configuration change will take effect next time that advertising is enabled.

These configuration flags can be enabled using le_gap_set_advertise_configuration command.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
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 Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_clear_advertise_random_address

Clear the random address previously set for the advertiser address on an advertising set. A random address can be set using le_gap_set_advertise_random_address command. The default advertiser address will be used after this operation.

Wrong state error is returned if advertising has been enabled on the advertising set. Invalid parameter error is returned if the advertising set handle is invalid.

C API

/* Function */
struct gecko_msg_le_gap_clear_advertise_random_address_rsp_t *gecko_cmd_le_gap_clear_advertise_random_address(uint8 handle);

/* Response id */
gecko_rsp_le_gap_clear_advertise_random_address_id

/* Response structure */
struct gecko_msg_le_gap_clear_advertise_random_address_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_connect

Connect to an advertising device with the specified initiating PHY on which connectable advertisements on primary advertising channels are received. 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 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 can't be established (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 an event related to the connection request. To recover from this situation, the application can implement a timeout and call le_connection_close to cancel the connection request.

This command fails with the connection limit exceeded error if the number of connections attempted exceeds the configured MAX_CONNECTIONS value.

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

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

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
bd_addr address Address of the device to connect to
uint8 address_type Address type of the device to connect to
uint8 initiating_phy The initiating PHY. Value:
  • 1: 1M PHY
  • 4: Coded PHY

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes
uint8 connection Handle that will be assigned to the connection after the connection is established. This handle is valid only if the result code of this response is 0 (zero).

Events generated

Event Description
le_connection_opened This event is triggered after the connection is opened and indicates whether the devices are already bonded and whether the role of the Bluetooth device is Slave or Master.
le_connection_parameters This event indicates the connection parameters and security mode of the connection.

le_gap_discover

Deprecated and replaced by le_gap_start_discovery command. To preserve the same functionality when migrating to the new command, use 1M PHY in scanning_phy parameter.

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

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 mode Bluetooth discovery Mode. For values see link.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

Events generated

Event Description
le_gap_scan_response Each 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

Enable or disable whitelisting. The setting will be effective the next time that scanning is enabled. To add devices to the whitelist, either bond with the device or add it manually with sm_add_to_whitelist.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 enable 1 enable, 0 disable whitelisting.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_end_procedure

End the current GAP discovery procedure (i.e., scanning for advertising devices).

C 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;
}

Command does not have parameters (for BGAPI headers refer to link)

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_open

Deprecated and replaced by le_gap_connect command, which allows opening a connection with a specified PHY.

Connect to an advertising device where 1M PHY is the initiating PHY.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
bd_addr address An address of the device to connect to
uint8 address_type An address type of the device to connect to

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes
uint8 connection A handle that will be assigned to the connection when the connection is established. The handle is valid only if the result code of this response is 0 (zero).

Events generated

Event Description
le_connection_opened Triggered after the connection is opened and indicates whether the devices are already bonded and whether the role of the Bluetooth device is Slave or Master.
le_connection_parameters 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 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.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 scan_rsp This value selects if 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
uint8 adv_data_len Array length.
uint8array adv_data_data Data to be set

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_adv_parameters

Deprecated and replaced by le_gap_set_advertise_timing command to set the advertising intervals and le_gap_set_advertise_channel_map command to set the channel map.

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

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
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
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
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 Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_adv_timeout

Deprecated. Use the new command le_gap_set_advertise_timing.

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

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
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 Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_advertise_channel_map

Set the primary advertising channel map of the given advertising set. This setting will take effect next time that advertising is enabled.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
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 Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_advertise_configuration

Enable advertising configuration flags on the given advertising set. The configuration change will take effect next time that advertising is enabled.

These configuration flags can be disabled using le_gap_clear_advertise_configuration command.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
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 Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_advertise_phy

Set advertising PHYs of the given advertising set. This setting will take effect next time that advertising is enabled. The invalid parameter error is returned if a PHY value is invalid or the device does not support a given PHY.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
uint8 primary_phy The PHY on which the advertising packets are transmitted on the primary advertising channel. If legacy advertising PDUs are used, 1M PHY must be used.

Values:

  • 1: Advertising PHY is 1M PHY
  • 4: Advertising PHY is Coded PHY
Default: 1
uint8 secondary_phy The PHY on which the advertising packets are transmitted on the secondary advertising channel.

Values:

  • 1: Advertising PHY is 1M PHY
  • 2: Advertising PHY is 2M PHY
  • 4: Advertising PHY is Coded PHY
Default: 1

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_advertise_random_address

Set the advertiser on an advertising set to use a random address. This overrides the default advertiser address which is either the public device address programmed at production or the address written into persistent storage using system_set_identity_address command. This setting is stored in RAM only and does not change the identity address in persistent storage.

When setting a resolvable random address, the address parameter is ignored. The stack generates a private resolvable random address and set it as the advertiser address. The generated address is returned in the response.

To use the default advertiser address, remove this setting using le_gap_clear_advertise_random_address command.

Wrong state error is returned if advertising has been enabled on the advertising set. Invalid parameter error is returned if the advertising set handle is invalid or the address does not conforms to the Bluetooth specification.

C API

/* Function */
struct gecko_msg_le_gap_set_advertise_random_address_rsp_t *gecko_cmd_le_gap_set_advertise_random_address(uint8 handle, uint8 addr_type, bd_addr address);

/* Response id */
gecko_rsp_le_gap_set_advertise_random_address_id

/* Response structure */
struct gecko_msg_le_gap_set_advertise_random_address_rsp_t
{
  uint16 result;
  bd_addr address_out;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
uint8 addr_type Address type:
  • 1: Static device address
  • 2: Private resolvable random address
  • 3: Private non-resolvable random address. This type can only be used for non-connectable advertising.
bd_addr address The random address to set. Ignore this field when setting a resolvable random address.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes
bd_addr address_out The resolvable random address set for the advetiser. Ignore this field when setting other types of random address.

le_gap_set_advertise_report_scan_request

Enable or disable the scan request notification of a given advertising set. This setting will take effect next time that advertising is enabled.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
uint8 report_scan_req If non-zero, enables scan request notification and scan requests will be reported as events.

Default value: 0

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

Events generated

Event Description
le_gap_scan_request Triggered when a scan request is received during advertising if the scan request notification is enabled by this command.

le_gap_set_advertise_timing

Set the advertising timing parameters of the given advertising set. This setting will take effect next time that advertising is enabled.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
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
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
uint16 duration Advertising duration for this advertising set. Value 0 indicates no advertising duration limit and 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
uint8 maxevents If non-zero, indicates the maximum number of advertising events to send before the advertiser is stopped. Value 0 indicates no maximum number limit.

Default value: 0

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_advertise_tx_power

Limit the maximum advertising TX power on the given advertising set. If the value goes over the global value that was set using system_set_tx_power command, the global value will be the maximum limit. The maximum TX power of legacy advertising is further constrained to be less than +10 dBm. Extended advertising TX power can be +10 dBm and over if Adaptive Frequency Hopping is enabled.

This setting will take effect next time advertising is enabled.

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

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
int16 power TX power in 0.1 dBm steps. For example, the value of 10 is 1 dBm and 55 is 5.5 dBm.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes
int16 set_power The selected maximum advertising TX power

le_gap_set_conn_parameters

Deprecated and replaced by le_gap_set_conn_timing_parameters command for setting timing parameters.

Set the default Bluetooth connection parameters. The configured values are valid for all subsequent connections that will be established. To change the parameters of an already established connection, use the command le_connection_set_parameters.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 min_interval Minimum value for the connection event interval. This must be set less than or equal to the max_interval.
  • Time = Value x 1.25 ms
  • Range: 0x0006 to 0x0c80
  • Time Range: 7.5 ms to 4 s
Default value: 20 ms
uint16 max_interval Maximum value for the connection event interval. This must be set greater than or equal to the min_interval.
  • Time = Value x 1.25 ms
  • Range: 0x0006 to 0x0c80
  • Time Range: 7.5 ms to 4 s
Default value: 50 ms
uint16 latency Slave latency, which defines how many connection intervals the slave can skip if it has no data to send
  • Range: 0x0000 to 0x01f4
Default value: 0
uint16 timeout Supervision timeout, which defines the time that the connection is maintained although the devices can't 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
Set the supervision timeout at a value which allows communication attempts over at least a few connection intervals.

Default value: 1000 ms

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_conn_phy

Set default preferred and accepted PHYs. PHY settings will be used for all subsequent connections. Non-preferred PHY can also be set if the remote device does not accept any of the preferred PHYs.

The parameter accepted_phy is used to specify PHYs that the stack can accept in a remotely-initiated PHY update request. A PHY update will not happen if none of the accepted PHYs are present in the request.

NOTE: 2M and Coded PHYs are not supported by all devices.

C API

/* Function */
struct gecko_msg_le_gap_set_conn_phy_rsp_t *gecko_cmd_le_gap_set_conn_phy(uint8 preferred_phy, uint8 accepted_phy);

/* Response id */
gecko_rsp_le_gap_set_conn_phy_id

/* Response structure */
struct gecko_msg_le_gap_set_conn_phy_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 preferred_phy Preferred PHYs. This parameter is a bitfield and multiple PHYs can be set.
  • 0x01: 1M PHY
  • 0x02: 2M PHY
  • 0x04: Coded PHY
  • 0xff: Any PHYs
Default: 0xff (no preference)
uint8 accepted_phy Accepted PHYs in remotely-initiated PHY update request. This parameter is a bitfield and multiple PHYs can be set.
  • 0x01: 1M PHY
  • 0x02: 2M PHY
  • 0x04: Coded PHY
  • 0xff: Any PHYs
Default: 0xff (all PHYs accepted)

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_conn_timing_parameters

Set the default Bluetooth connection parameters. The configured values are valid for all subsequent connections that will be established. To change parameters of an already established connection, use the command le_connection_set_timing_parameters.

C API

/* Function */
struct gecko_msg_le_gap_set_conn_timing_parameters_rsp_t *gecko_cmd_le_gap_set_conn_timing_parameters(uint16 min_interval, uint16 max_interval, uint16 latency, uint16 timeout, uint16 min_ce_length, uint16 max_ce_length);

/* Response id */
gecko_rsp_le_gap_set_conn_timing_parameters_id

/* Response structure */
struct gecko_msg_le_gap_set_conn_timing_parameters_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 min_interval Minimum value for the connection event interval. This must be set 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
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
uint16 latency Slave latency, which defines how many connection intervals the slave can skip if it has no data to send
  • Range: 0x0000 to 0x01f4
Default value: 0
uint16 timeout Supervision timeout, which defines the time that the connection is maintained although the devices can't 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
Set the supervision timeout at a value which allows communication attempts over at least a few connection intervals.

Default value: 1000 ms
uint16 min_ce_length Minimum value for the connection event length. This must be set be less than or equal to max_ce_length.
  • Time = Value x 0.625 ms
  • Range: 0x0000 to 0xffff
Default value: 0x0000

Value is not currently used and is reserved for future. Set to 0.
uint16 max_ce_length Maximum value for the connection event length. This must be set greater than or equal to min_ce_length.
  • Time = Value x 0.625 ms
  • Range: 0x0000 to 0xffff
Default value: 0xffff

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_data_channel_classification

Specify a channel classification for data channels. This classification persists until overwritten with a subsequent command or until the system is reset.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 channel_map_len Array length.
uint8array channel_map_data 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 rest of most significant bits are reserved for future use and shall be set to 0.
At least two channels shall be marked as unknown.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_discovery_extended_scan_response

Enable or 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.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 enable Values:
  • 0: Disable extended scan response event
  • 1: Enable extended scan response event

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_discovery_timing

Set the timing parameters of scanning on the specified PHYs. If the device is currently scanning for advertising devices on PHYs, new parameters will take effect when scanning is restarted.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 phys PHYs for which the parameters are set.
  • 1: 1M PHY
  • 4: Coded PHY
  • 5: 1M PHY and Coded PHY
uint16 scan_interval Scan interval is defined as the time interval when the device starts its last scan until it begins the subsequent scan. In other words, 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

A variable delay occurs when switching channels at the end of each scanning interval, which is included in the scanning interval time. During the switch time, advertising packets are not received by the device. The switch time variation is use case-dependent. For example, if scanning while keeping active connections, the channel switch time might be longer than when scanning without any active connections. Increasing the scanning interval reduces the amount of time in which the device can't receive advertising packets because it switches channels less often.

After every scan interval, the scanner changes the frequency at which it operates. It cycles through all three advertising channels in a round robin fashion. According to the specification, all three channels must be used by a scanner.
uint16 scan_window Scan window defines the duration of the scan which must be less than or equal to the 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 the packet reception is aborted if it's started just before the scan window ends.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_discovery_type

Set the scan type on the specified PHYs. If the device is currently scanning for advertising devices on PHYs, new parameters will take effect when scanning is restarted.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 phys PHYs for which the parameters are set.
  • 1: 1M PHY
  • 4: Coded PHY
  • 5: 1M PHY and Coded PHY
uint8 scan_type Scan type. Values:
  • 0: Passive scanning
  • 1: Active scanning
  • In passive scanning mode, the device only listens to advertising packets and does not transmit packets.
  • In active scanning mode, the device sends out a scan request packet upon receiving an advertising packet from a remote device. Then, it listens to the scan response packet from the remote device.
Default value: 0

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_long_advertising_data

Set advertising data for a specified packet type and advertising set. Data currently in the system data buffer will be extracted as the advertising data. The buffer will be emptied after this command regardless of the completion status.

Prior to calling this command, add data to the buffer with one or multiple calls of system_data_buffer_write.

Maximum 31 bytes of data can be set for legacy advertising. Maximum 191 bytes of data can be set for connectable extended advertising. Maximum 1650 bytes of data can be set for periodic and non-connectable extended advertising, but advertising parameters may limit the amount of data that can be sent in a single advertisement.

See le_gap_bt5_set_adv_data for more details on advertising data.

C API

/* Function */
struct gecko_msg_le_gap_set_long_advertising_data_rsp_t *gecko_cmd_le_gap_set_long_advertising_data(uint8 handle, uint8 packet_type);

/* Response id */
gecko_rsp_le_gap_set_long_advertising_data_id

/* Response structure */
struct gecko_msg_le_gap_set_long_advertising_data_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
uint8 packet_type This value selects whether data is intended for advertising packets, scan response packets, or periodic advertising packets. Values:
  • 0: Advertising packets
  • 1: Scan response packets
  • 2: OTA advertising packets
  • 4: OTA scan response packets
  • 8: Periodic advertising packets

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_mode

Deprecated. Use le_gap_start_advertising command to enable advertising and le_gap_stop_advertising command to disable advertising.

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

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 discover Discoverable mode
uint8 connect Connectable mode

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

Events generated

Event Description
le_gap_adv_timeout Triggered when the number of advertising events is done and advertising has stopped.
le_connection_opened Triggered when a remote device opens a connection to this advertising device.

le_gap_set_privacy_mode

Enable or disable the privacy feature on all GAP roles. New privacy mode will take effect for advertising next time advertising is enabled, for scanning next time scanning is enabled, 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 a 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.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 privacy Values:
  • 0: Disable privacy
  • 1: Enable privacy
uint8 interval The minimum time interval between a private address change. This parameter is ignored if this command is issued to disable privacy mode. Values:
  • 0: Use default interval, 15 minutes
  • others: The time interval in minutes

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_set_scan_parameters

Deprecated and replaced by le_gap_set_discovery_timing command to set timing parameters, and le_gap_set_discovery_type command for the scan type.

The parameters set by this command are only effective on the 1M PHY. For Coded PHY, use the above replacement command.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 scan_interval Scanner interval is defined as the time interval when the device starts its last scan until it begins the subsequent scan. In other words, it indicates 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

A variable delay occurs when switching channels at the end of each scanning interval, which is included in the scanning interval time. During the switch time no advertising packets are received by the device. The switch time variation is use case-dependent. For example, if scanning while keeping active connections, the channel switch time might be longer than scanning without any active connections. Increasing the scanning interval reduces the amount of time in which the device can't receive advertising packets because it will switch channels less often.

After every scan interval, the scanner changes the frequency at which it operates. It cycles through all three advertising channels in a round robin fashion. According to the specification, all three channels must be used by the scanner.
uint16 scan_window Scan window defines the duration of the scan which must 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 was started before the scan window ends.
uint8 active The scan type. Values:
  • 0: Passive scanning
  • 1: Active scanning
  • In passive scanning mode, the device only listens to advertising packets and does not transmit any packets.
  • In active scanning mode, the device will send out a scan request packet upon receiving an advertising packet from a remote device and then it will listen to the scan response packet from the device.
Default value: 0

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_start_advertising

Start advertising of a given advertising set with specified discoverable and connectable modes.

The number of concurrent advertising is limited by MAX_ADVERTISERS configuration.

The number of concurrent connectable advertising 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 1M PHY. The stack will automatically select extended advertising PDUs if either of the following has occurred with the default configuration:

  1. The connectable mode is set to le_gap_connectable_non_scannable.
  2. The primary advertising PHY is set to Coded PHY by the command le_gap_set_advertise_phy.
  3. The user advertising data length is more than 31 bytes.
  4. Periodic advertising is enabled.

If currently set parameters can't be used, an error is returned. Specifically, this command fails with the connection limit exceeded error if it causes the number of connections exceeding the configured MAX_CONNECTIONS value. It fails with the invalid parameter error if one of the following use cases occurs:

  1. Non-resolvable random address is used but the connectable mode is le_gap_connectable_scannable or le_gap_connectable_non_scannable.
  2. le_gap_connectable_non_scannable is the connectable mode but using legacy advertising PDUs has been explicitly enabled with command le_gap_set_advertise_configuration.
  3. Coded PHY is the primary advertising PHY but using legacy advertising PDUs has been explicitly enabled with command le_gap_set_advertise_configuration.
  4. le_gap_connectable_scannable is the connectable mode but using extended advertising PDUs has been explicitly enabled or the primary advertising PHY is set to Coded PHY.

If advertising is enabled in user_data mode, use le_gap_bt5_set_adv_data to set advertising and scan response data before issuing this command. When advertising is enabled in modes other than user_data, 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 the 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 the device is not in privacy mode. If 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 and also advertising on the given set stops.

Event le_gap_adv_timeout will be received when the number of advertising events set by le_gap_set_advertise_timing command is done and advertising with the current set has stopped.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
uint8 discover Discoverable mode
uint8 connect Connectable mode

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

Events generated

Event Description
le_gap_adv_timeout Triggered when the number of advertising events set by le_gap_set_advertise_timing command is done and advertising has stopped on the given advertising set.
le_connection_opened Triggered when a remote device opens a connection to the advertiser on the specified advertising set and also advertising with the current set stops.

le_gap_start_discovery

Start the GAP discovery procedure to scan for advertising devices on the specified scanning PHY or to perform a device discovery. To cancel an ongoing discovery process use the le_gap_end_procedure command.

The invalid parameter error will be returned if the scanning PHY value is invalid or the device does not support the PHY.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 scanning_phy The scanning PHY. Value:
  • 1: 1M PHY
  • 4: Coded PHY
uint8 mode Bluetooth discovery Mode. For values see link.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

Events generated

Event Description
le_gap_scan_response This event is triggered each time an advertising packet is received. Packets are not filtered in any way, so multiple events will be received for every advertising device in range.
le_gap_extended_scan_response Each time an advertising packet is received and extended scan response is enabled (by le_gap_set_discovery_extended_scan_response), this event is triggered. The packets are not filtered in any way. As a result, multiple events will be received for every advertising device in range.

le_gap_start_periodic_advertising

Start periodic advertising on the given advertising set. The stack enables the advertising set automatically if the set was not enabled and the set can advertise using extended advertising PDUs beside the syncInfo (which is needed for the periodic advertising).

The invalid parameter error is returned if the application has configured legacy advertising PDUs or anonymous advertising, or the advertising set is enabled using legacy advertising PDUs.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle
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
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
uint32 flags Periodic advertising configurations. Bitmask of the following:
  • Bit 0: Include TX power in advertising PDU

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_stop_advertising

Stop the advertising of the given advertising set.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap_stop_periodic_advertising

Stop the periodic advertising on the given advertising set.

This command does not affect the enable state of the advertising set, i.e., legacy or extended advertising is not stopped.

C 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;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

le_gap events

le_gap_scan_response

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 is enabled. The extended scan response event can be enabled or disabled using command le_gap_set_discovery_extended_scan_response command.

C 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;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
int8 rssi Signal strength indicator (RSSI) in the latest received packet. Units: dBm
  • Range: -127 to +20
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 that this is received only if the device is in active scan mode.

Bits 3..4: Reserved for the future

Bits 5..6: data completeness

  • 00: Complete
  • 01: Incomplete, more data to come in new events
  • 10: Incomplete, data truncated, no more to come

Bit 7: legacy or extended advertising

  • 0: Legacy advertising PDUs used
  • 1: Extended advertising PDUs used
bd_addr address Bluetooth address of the remote device
uint8 address_type Advertiser address type. Values:
  • 0: Public address
  • 1: Random address
  • 255: No address provided (anonymous advertising)
uint8 bonding Bonding handle if the remote advertising device has previously bonded with the local device. Values:
  • 0xff: No bonding
  • Other: Bonding handle
uint8array data Advertising or scan response data

le_gap_adv_timeout

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

C API

/* event id*/
gecko_evt_le_gap_adv_timeout_id

/* event structure*/
struct gecko_msg_le_gap_adv_timeout_evt_t
{
  uint8 handle;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle The advertising set handle

le_gap_scan_request

Reports any scan request received in advertising mode if the scan request notification is enabled. Do not confuse this event with the scan response.

C 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;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 handle Advertising set handle where scan request was received
bd_addr address Bluetooth address of the scanning device
uint8 address_type Scanner address type. Values:
  • 0: Public address
  • 1: Random address
uint8 bonding Bonding handle if the remote scanning device has previously bonded with the local device. Values:
  • 0xff: No bonding
  • Other: Bonding handle

le_gap_extended_scan_response

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.

C 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;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
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 that 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
  • 01: Incomplete, more data to come in new events
  • 10: Incomplete, data truncated, no more to come

Bit 7: legacy or extended advertising

  • 0: Legacy advertising PDUs used
  • 1: Extended advertising PDUs used
bd_addr address Bluetooth address of the remote device
uint8 address_type Advertiser address type. Values:
  • 0: Public address
  • 1: Random address
  • 255: No address provided (anonymous advertising)
uint8 bonding Bonding handle if the remote advertising device has previously bonded with the local device. Values:
  • 0xff: No bonding
  • Other: Bonding handle
uint8 primary_phy The PHY on which advertising packets are transmitted on the primary advertising channel.

Values:

  • 1: 1M PHY
  • 4: Coded PHY
uint8 secondary_phy The PHY on which advertising packets are transmitted on the secondary advertising channel.

Values:

  • 1: Advertising PHY is 1M PHY
  • 2: Advertising PHY is 2M PHY
  • 4: Advertising PHY is Coded PHY
uint8 adv_sid Advertising set identifier
int8 tx_power TX power value in the received packet header. Units: dBm
  • Valid value range: -127 to 126
  • Value 127: information unavailable
int8 rssi Signal strength indicator (RSSI) in the last received packet. Units: dBm
  • Range: -127 to +20
uint8 channel The channel number on which the last packet was received
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
uint8array data Advertising or scan response 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

le_gap_phy_type

Types of PHYs used within le_gap class

Enumerations

Value Name Description
1 le_gap_phy_1m 1M PHY
2 le_gap_phy_2m 2M PHY
4 le_gap_phy_coded Coded PHY

le_gap_connectable_mode

These values define the available connectable modes, which indicate whether the device accepts connection requests or scan requests.

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 enumeration 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 using the Observation procedure.
4 le_gap_user_data Send advertising and/or scan response data defined by the user with 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

Deprecated. This can only be used in deprecated command le_gap_bt5_set_mode.

Address type to use for starting advertising with le_gap_bt5_set_mode.

Enumerations

Value Name Description
0 le_gap_identity_address Use public or static device address, or an identity address if privacy mode is enabled.
1 le_gap_non_resolvable Use non resolvable address type; advertising mode must also be non-connectable.