BLE S120 GAP Functions

Table of Contents

• 0x70 - sd_ble_gap_address_set
  • Function packet format
  • Response packet format
• 0x71 - sd_ble_gap_address_get
  • Function packet format
  • Response packet format
• 0x72 - sd_ble_gap_adv_data_set
  • Function packet format
  • Response packet format
• 0x73 - sd_ble_gap_adv_start
  • Function packet format
  • Encoding of Peer Address
  • Encoding of GAP Whitelist
  • Encoding of GAP Whitelist Addresses Array
  • Encoding of GAP Whitelist IRKs Array
  • Encoding of Channel Mask
  • Response packet format
• 0x74 - sd_ble_gap_adv_stop
  • Function packet format.
  • Response packet format
• 0x75 - sd_ble_gap_conn_param_update
  • Function packet format
  • Response packet format
• 0x76 - sd_ble_gap_disconnect
  • Function packet format
  • Response packet format
• 0x77 - sd_ble_gap_tx_power_set
  • Function packet format
  • Response packet format
• 0x78 - sd_ble_gap_appearance_set
  • Function packet format
  • Response packet format
• 0x79 - sd_ble_gap_appearance_get
  • Function packet format
  • Response packet format
• 0x7A - sd_ble_gap_ppcp_set
  • Function packet format
  • Response packet format
• 0x7B - sd_ble_gap_ppcp_get
  • Function packet format
  • Response packet format
• 0x7C - sd_ble_gap_device_name_set
  • Function packet format
  • Response packet format
• 0x7D - sd_ble_gap_device_name_get
  • Function packet format
  • Response packet format
  • Device name data length
• 0x7E - sd_ble_gap_authenticate
  • Function packet format
  • Encoding of Bond, MITM, IO caps, and OOB
  • Encoding of Key Distribution Bitmaps
  • Response packet format
• 0x7F - sd_ble_gap_sec_params_reply
  • Function packet format
  • Encoding of Bond, MITM, IO caps, and OOB
  • Encoding of Key Distribution Bitmap
  • Encoding of Keyset Structure
  • Response packet format
• 0x80 - sd_ble_gap_auth_key_reply
  • Function packet format
  • Response packet format
• 0x81 - sd_ble_gap_encrypt
  • Function packet format
  • Response packet format
• 0x82 - sd_ble_gap_sec_info_reply
  • Function packet format
  • Response packet format
• 0x83 - sd_ble_gap_conn_sec_get
  • Function packet format
  • Response packet format
• 0x84 - sd_ble_gap_rssi_start
  • Function packet format
  • Response packet format
• 0x85 - sd_ble_gap_rssi_stop
  • Function packet format
  • Response packet format
• 0x86 - sd_ble_gap_scan_start
  • Function packet format
  • Response packet format
• 0x87 - sd_ble_gap_scan_stop
  • Function packet format
  • Response packet format
• 0x88 - sd_ble_gap_connect
  • Function packet format
  • Response packet format
• 0x89 - sd_ble_gap_connect_cancel
  • Function packet format
  • Response packet format
• 0x8A - sd_ble_gap_rssi_get
  • Function packet format
  • Response packet format

0x70 - sd_ble_gap_address_set

Function packet format

Frame format encoding of the sd_ble_gap_address_set packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x70, see BLE_GAP_SVCS
1 byte	Address Cycle Mode	See sd_ble_gap_address_set
1 byte	Address present	0x00 - not present, 0x01 - present
7 bytes	Address	See ble_gap_addr_t

As can also be seen inside Figure 1, the 7 bytes inside ble_gap_addr_t are encoded as:

Length	Parameter	Value
1 byte	Address Type	See ble_gap_addr_t::addr_type
6 bytes	Address	See ble_gap_addr_t::addr

Figure 1: Packet format for sd_ble_address_set function.

Response packet format

Frame format encoding of the sd_ble_gap_address_set response packet:

Length	Parameter	Value
1 byte	Operation Code	0x70, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_address_set

Figure 2: Packet format for sd_ble_gap_address_set response.

0x71 - sd_ble_gap_address_get

Function packet format

Frame format encoding of the sd_ble_gap_address_get packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x71, see BLE_GAP_SVCS
1 byte	Address present	0x00 - not present, 0x01 - present

Figure 1: Packet format for sd_ble_gap_address_get function.

Response packet format

If a command was executed successfully, so that 'nRF Error Code' = NRF_SUCCESS, the nRF Error Code is followed by conditional data.

Frame format encoding of the sd_ble_gap_address_get response packet:

Length	Parameter	Value
1 byte	Operation Code	0x71, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_address_get
7 bytes	Conditional: Address	See ble_gap_addr_t

ble_gap_addr_t is encoded as:

Length	Parameter	Value
1 byte	Address Type	See ble_gap_addr_t::addr_type
6 bytes	Address	See ble_gap_addr_t::addr

Figure 2: Packet format for sd_ble_gap_address_get response.

0x72 - sd_ble_gap_adv_data_set

Function packet format

Frame format encoding of the sd_ble_gap_adv_data_set packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x72, see BLE_GAP_SVCS
1 byte	Advertising Data Length	See sd_ble_gap_adv_data_set
1 byte	Advertising Data Present	0x00 - not present, 0x01 - present
n bytes	Advertising Data	See sd_ble_gap_adv_data_set
1 byte	Scan Response Data Length	See sd_ble_gap_adv_data_set
1 byte	Scan Response Data Present	0x00 - not present, 0x01 - present
n bytes	Scan Response Data	See sd_ble_gap_adv_data_set

Figure 1: Packet format for sd_ble_gap_adv_set function.

Response packet format

Frame format encoding of the sd_ble_gap_adv_data_set response packet:

Length	Parameter	Value
1 byte	Operation Code	0x72, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_adv_data_set

Figure 2: Packet format for sd_ble_gap_adv_data_set success response.

0x73 - sd_ble_gap_adv_start

Function packet format

Frame format encoding of the sd_ble_gap_adv_start packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x73, see BLE_GAP_SVCS
1 byte	Advertising Parameters Present	0x00 Fields not present, 0x01 Fields present
9 ... 220 bytes	GAP Advertising Parameters	See ble_gap_adv_params_t

The data inside ble_gap_adv_start_params_t is encoded as:

Length	Parameter	Value
1 byte	GAP Advertising Type	See ble_gap_adv_params_t::type
1 byte	Peer Address Present	0x00 - not present, 0x01 - present
7 bytes	Conditional: Peer Address	See ble_gap_adv_params_t::p_peer_addr (Encoding details can be seen in Figure 2)
1 byte	Filter Policy	See ble_gap_adv_params_t::fp
1 byte	GAP Whitelist Present	0x00 - not present, 0x01 - present
4 ... 204 bytes	Conditional: GAP Whitelist	See ble_gap_adv_params_t::p_whitelist (Encoding details can be seen in Figure 3)
2 bytes	Interval	See ble_gap_adv_params_t::interval
2 bytes	Timeout	See ble_gap_adv_params_t::timeout
1 byte	Channel Mask (bitfields): - ch_37_off: 1 bit, - ch_38_off: 1 bit, - ch_39_off: 1 bit	See ble_gap_adv_params_t::channel_mask

Figure 1: Packet format for sd_ble_gap_adv_start function.

Encoding of Peer Address

If 'Peer Address Present' = 0x01, the encoding of the 'Peer Address' will follow. 'Peer Address' is of type ble_gap_addr_t.

The data inside ble_gap_addr_t is encoded as:

Length	Parameter	Value
1 byte	Address type	See ble_gap_addr_t::addr_type
6 bytes	Address	See ble_gap_addr_t::addr

If 'Peer Address Present' = 0x00, the encoding of 'Filter Policy' will follow, and hence no 'Peer Address' will be encoded in the packet.

Figure 2: Encoding of peer address if present.

Encoding of GAP Whitelist

If 'GAP Whitelist Present' = 0x01, the encoding of the 'GAP Whitelist' will follow. 'GAP Whitelist' is of type ble_gap_whitelist_t.

ble_gap_whitelist_t contains two counters, ble_gap_whitelist_t::addr_count and ble_gap_whitelist_t::irk_count, as well as two pointers to arrays. One pointer (ble_gap_whitelist_t::pp_addrs) points to an array of device address pointers (which point to addresses to be used in the whitelist. The other pointer (ble_gap_whitelist_t::pp_irks) points to an array of Identity Resolving Key (IRK) pointers (which each point to an IRK in the whitelist).

The encoded 'GAP whitelist' will first contain the address counter, followed by the encoding of each address. Then the IRK counter, followed by the encoding of each IRK.

The data inside ble_gap_whitelist_t is encoded as:

Length	Parameter	Value
1 byte	Address Counter	See ble_gap_whitelist_t::addr_count
1 byte	Address list present	0x00 - not present, 0x01 - present
0 ... 64 bytes	Address list	See ble_gap_addr_t ('Address Counter' specifies the actual number of addresses encoded)
1 byte	IRK Counter	See ble_gap_whitelist_t::irk_count
1 byte	IRK list present	0x00 - not present, 0x01 - present
0 ... 136 bytes	IRK list	See ble_gap_irk_t ('IRK Counter' specifies the actual number of IRKs encoded)

If 'GAP Whitelist Present' = 0x00, the encoding of 'Interval' will follow, and hence no 'GAP Whitelist' will be encoded in the packet.

Figure 3: Encoding of GAP Whitelist if present.

Encoding of GAP Whitelist Addresses Array

The encoding of whitelist addresses starts with the 'Whitelist Address Count' according to the value in ble_gap_whitelist_t::addr_count. It is followed by the 'Address list present' field, which indicates whether the ble_gap_whitelist_t::pp_addrs pointer equals NULL. If the value of 'Address list present' is 0, no whitelist addresses are encoded, and the 'Address list present' will be followed by the 'IRK Count' as seen in the top of Figure 4. Otherwise each whitelist address (ble_gap_addr_t) will be encoded as specified by the counter. Before each address, the 'Address present' field is encoded indicating whether the pointer to the address is NULL. Each address is 7 bytes, with the first byte specifying the address type.

The whitelist addresses are encoded as:

Length	Parameter	Value
1 byte	Address list present	0x00 - not present, 0x01 - present
1 byte	Whitelist Address Count	See ble_gap_whitelist_t::addr_count

For each address, as defined by 'Whitelist Address Count', the following data is encoded:

Length	Parameter	Value
1 byte	Address present	0x00 - not present, 0x01 - present
1 byte	Address type	See ble_gap_addr_t::addr_type
6 bytes	Address	See ble_gap_addr_t::addr

Figure 4: Encoding of Whitelist Addresses.

Encoding of GAP Whitelist IRKs Array

The encoding of whitelist IRKs start with the 'IRK Count' according to the value in ble_gap_whitelist_t::irk_count. It is followed by the 'IRK list present' field, which indicates whether the ble_gap_whitelist_t::pp_irks pointer equals NULL. If the value of 'IRK list present' is 0, no IRKs are encoded, and the 'IRK list present' will be followed by the 'Interval' field as seen in the top of Figure 5. Otherwise each IRK (ble_gap_irk_t) will be encoded as specified by the counter. Before each IRK, the 'IRK present' field is encoded indicating whether the pointer to IRK is NULL. Each IRK is 16 bytes.

The IRKs are encoded as:

Length	Parameter	Value
1 byte	IRK list present	0x00 - not present, 0x01 - present
1 byte	IRK Count	See ble_gap_whitelist_t::irk_count

For each IRK, as defined by 'IRK Count', the following data is encoded:

Length	Parameter	Value
1 byte	IRK present	0x00 - not present, 0x01 - present
16 bytes	IRK	See ble_gap_irk_t

Figure 5: Encoding of Whitelist IRKs.

Encoding of Channel Mask

The channel mask structure consists of 3 bitfields that are encoded in one byte as follows:

Figure 2: Encoding of channel mask.

Response packet format

Frame format encoding of the sd_ble_gap_adv_start response packet:

Length	Parameter	Value
1 byte	Operation Code	0x73, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_adv_start

Figure 6: Packet format for sd_ble_gap_adv_start response.

0x74 - sd_ble_gap_adv_stop

Function packet format.

Frame format encoding of the sd_ble_gap_adv_stop packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x74, see BLE_GAP_SVCS

Figure 1: Packet format for sd_ble_gap_adv_stop function.

Response packet format

Frame format encoding of the sd_ble_gap_adv_stop response packet:

Length	Parameter	Value
1 byte	Operation Code	0x74, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_adv_stop

Figure 2: Packet format for sd_ble_gap_adv_stop response.

0x75 - sd_ble_gap_conn_param_update

Function packet format

Frame format encoding of the sd_ble_gap_conn_param_update packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x75, see BLE_GAP_SVCS
2 bytes	Connection Handle	Handle value
1 byte	Connection Parameters Present	0x00 - not present, 0x01 - present
8 bytes	Conditional: Connection Parameters	See ble_gap_conn_params_t

As can also be seen inside Figure 1, the 8 bytes inside ble_gap_conn_params_t are encoded as:

Length	Parameter	Value
2 bytes	Minimum Connection Interval	See ble_gap_conn_params_t::min_conn_interval
2 bytes	Maximum Connection Interval	See ble_gap_conn_params_t::max_conn_interval
2 bytes	Slave Latency in number of connection events	See ble_gap_conn_params_t::slave_latency
2 bytes	Connection Supervision Timeout	See ble_gap_conn_params_t::conn_sup_timeout

Figure 1: Packet format for sd_ble_gap_conn_param_update function.

Response packet format

Frame format encoding of the sd_ble_gap_conn_param_update response packet:

Length	Parameter	Value
1 byte	Operation Code	0x75 (117)
4 bytes	nRF Error Code	See sd_ble_gap_conn_param_update

Figure 2: Packet format for sd_ble_gap_conn_param_update response.

0x76 - sd_ble_gap_disconnect

Function packet format

Frame format encoding of the sd_ble_gap_disconnect packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x76, see BLE_GAP_SVCS
2 bytes	Connection Handle	Handle
1 byte	HCI Status Code	See Bluetooth status codes

Figure 1: Packet format for sd_ble_gap_disconnect function.

Response packet format

Frame format encoding of the sd_ble_gap_disconnect response packet:

Length	Parameter	Value
1 byte	Operation Code	0x76, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_disconnect

Figure 2: Packet format for sd_ble_gap_disconnect response.

0x77 - sd_ble_gap_tx_power_set

Function packet format

Frame format encoding of the sd_ble_gap_tx_power_set packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x77, see BLE_GAP_SVCS
1 byte	TX Power in dBm	See sd_ble_gap_tx_power_set

Figure 1: Packet format for sd_ble_gap_tx_power_set function.

Response packet format

Frame format encoding of the sd_ble_gap_tx_power_set response packet:

Length	Parameter	Value
1 byte	Operation Code	0x77, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_tx_power_set

Figure 2: Packet format for sd_ble_gap_tx_power_set response.

0x78 - sd_ble_gap_appearance_set

Function packet format

Frame format encoding of the sd_ble_gap_appearance_set packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x78, see BLE_GAP_SVCS
2 bytes	Appearance	See Bluetooth Appearance values

Figure 1: Packet format for sd_ble_gap_appearance_set function.

Response packet format

Frame format encoding of the sd_ble_gap_appearance_set response packet:

Length	Parameter	Value
1 byte	Operation Code	0x78, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_appearance_set

Figure 2: Packet format for sd_ble_gap_appearance_set response.

0x79 - sd_ble_gap_appearance_get

Function packet format

Frame format encoding of the sd_ble_gap_appearance_get packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x79, see BLE_GAP_SVCS
1 byte	Appearance present	0x00 - not present, 0x01 - present

Figure 1: Packet format for sd_ble_gap_appearance_get function.

Response packet format

Frame format encoding of the sd_ble_gap_appearance_get response packet:

Length	Parameter	Value
1 byte	Operation Code	0x79, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_appearance_get
2 bytes	Conditional: Appearance	See sd_ble_gap_appearance_get

Figure 2: Packet format for sd_ble_gap_appearance_get function response.

0x7A - sd_ble_gap_ppcp_set

Function packet format

Frame format encoding of the sd_ble_gap_ppcp_set packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x7A, see BLE_GAP_SVCS
1 byte	Next Field Present	0x00 - not present, 0x01 - present
8 bytes	GAP Connection Parameters	See ble_gap_conn_params_t

GAP Connection Parameters are encoded in the following order:

Length	Parameter	Value
2 bytes	Minimum Connection Interval	See ble_gap_conn_params_t::min_conn_interval
2 bytes	Maximum Connection Interval	See ble_gap_conn_params_t::max_conn_interval
2 bytes	Slave Latency	See ble_gap_conn_params_t::slave_latency
2 bytes	Connection Supervision Timeout	See ble_gap_conn_params_t::conn_sup_timeout

Figure 1: Packet format for sd_ble_gap_ppcp_set function.

Response packet format

Frame format encoding of the sd_ble_gap_ppcp_set response packet:

Length	Parameter	Value
1 byte	Operation Code	0x7A, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_ppcp_set

Figure 2: Packet format for sd_ble_gap_ppcp_set response.

0x7B - sd_ble_gap_ppcp_get

Function packet format

Frame format encoding of the sd_ble_gap_ppcp_get packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x7B, see BLE_GAP_SVCS
1 byte	Peripheral Preferred Connection Parameters field present	0x00 - not present, 0x01 - present

Figure 1: Packet format for sd_ble_gap_ppcp_get function.

Response packet format

If a command was executed successfully, so that 'nRF Error Code' = NRF_SUCCESS, the nRF Error Code is followed by conditional data.

Frame format encoding of the sd_ble_gap_ppcp_get response packet:

Length	Parameter	Value
1 byte	Operation Code	0x7B, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_ppcp_get
8 bytes	Conditional: Connection Parameters	See ble_gap_conn_params_t

GAP Connection Parameters are encoded in the following order:

Length	Parameter	Value
2 bytes	Minimum Connection Interval	See ble_gap_conn_params_t::min_conn_interval
2 bytes	Maximum Connection Interval	See ble_gap_conn_params_t::max_conn_interval
2 bytes	Slave Latency	See ble_gap_conn_params_t::slave_latency
2 bytes	Connection Supervision Timeout	See ble_gap_conn_params_t::conn_sup_timeout

Figure 2: Packet format for sd_ble_gap_ppcp_get response.

0x7C - sd_ble_gap_device_name_set

Function packet format

Frame format encoding of the sd_ble_gap_device_name_set packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x7C, see BLE_GAP_SVCS
1 byte	Next Field Present	0x00 - not present, 0x01 - present
1 byte	Conditional: Write Permissions	See ble_gap_conn_sec_mode_t
2 bytes	Device Name Length	See sd_ble_gap_device_name_set
1 byte	Next Field Present	0x00 - not present, 0x01 - present
n bytes	Conditional: Device Name	See sd_ble_gap_device_name_set

The bit fields of Write Permissions are encoded as:

Length	Parameter	Value
bit 0 to 3	Security Mode	See ble_gap_conn_sec_mode_t::sm
bit 4 to 7	Security Level	See ble_gap_conn_sec_mode_t::lv

Figure 1: Packet format for sd_ble_gap_device_name_set function.

Response packet format

Frame format encoding of the sd_ble_gap_device_name_set response packet:

Length	Parameter	Value
1 byte	Operation Code	0x7C, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_device_name_set

Figure 2: Packet format for sd_ble_gap_device_name_set response.

0x7D - sd_ble_gap_device_name_get

Function packet format

Frame format encoding of the sd_ble_gap_device_name_get packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x7D, see BLE_GAP_SVCS
1 byte	Device Name Length Present	0x00 - not present, 0x01 - present
2 bytes	Conditional: Device Name Length	See sd_ble_gap_device_name_get
2 bytes	Device Name Buffer Present	0x00 - not present, 0x01 - present

Figure 1: Packet format for sd_ble_gap_device_name_get function.

Response packet format

If a command was executed successfully, so that 'nRF Error Code' = NRF_SUCCESS, the nRF Error Code is followed by conditional data.

Frame format encoding of the sd_ble_gap_device_name_get response packet:

Length	Parameter	Value
1 byte	Operation Code	0x7D, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_device_name_get
2 bytes	Conditional: Device Name Length	See sd_ble_gap_device_name_get
1 byte	Conditional: Next Field Present	0x00 - not present, 0x01 - present
n bytes	Conditional: Device Name	See sd_ble_gap_device_name_get

Figure 2: Packet format for sd_ble_gap_device_name_get response.

Device name data length

The device name length and device name data will not be returned if the device name length in sd_ble_gap_device_name_get is larger than the internal connectivity buffer size. The caller of the function cannot indicate a larger buffer than what the command decoder can provide to the SoftDevice. An NRF_ERROR_DATA_SIZE will be returned in the error code field of the packet, and no device name length or data will be returned.

0x7E - sd_ble_gap_authenticate

Function packet format

Frame format encoding of the sd_ble_gap_authenticate packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x7E, see BLE_GAP_SVCS
2 bytes	Connection Handle	See sd_ble_gap_authenticate
1 byte	Security Parameters Present	0x00 - not present, 0x01 - present
5 bytes	Conditional: Security Parameters	See sd_ble_gap_authenticate

ble_gap_sec_params_t are encoded in the following order:

Length	Parameter	Value
1 byte	Bond, MITM, IO Caps and OOB	See ble_gap_sec_params_t
1 byte	Minimum Key Size	See ble_gap_sec_params_t::min_key_size
1 byte	Maximum Key Size	See ble_gap_sec_params_t::max_key_size
1 byte	Peripheral Key Distribution Bitmap	See ble_gap_sec_params_t::kdist_periph
1 byte	Peripheral Key Distribution Bitmap	See ble_gap_sec_params_t::kdist_central

Figure 1: Packet format for sd_ble_gap_authenticate function.

The Bond, MITM, IO Capabilities, and OOB fields are all bitfields inside 1 byte, as seen in Figure 2.

Encoding of Bond, MITM, IO caps, and OOB

Figure 2: Encoding of Bond, MITM, IO caps, and OOB inside a sd_sd_ble_gap_authenticate function packet.

Encoding of Key Distribution Bitmaps

Figure 2: Encoding of Key Distribution Bitmap inside a sd_sd_ble_gap_authenticate function packet.

Response packet format

Frame format encoding of the sd_ble_gap_authenticate response packet:

Length	Parameter	Value
1 byte	Operation Code	0x7E, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_authenticate

Figure 3: Packet format for sd_ble_gap_authenticate response.

0x7F - sd_ble_gap_sec_params_reply

Function packet format

Frame format encoding of the sd_ble_gap_sec_params_reply packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x7F, see BLE_GAP_SVCS
2 bytes	Connection Handle	Handle value
1 byte	Security Status	Status code
1 byte	Security Parameters Present	0x00 - not present, 0x01 - present
1 byte	Conditional: bitfields of ble_gap_sec_params_t	Bond, MITM, IO capabilites, and OOB bitfield
1 byte	Conditional: ble_gap_sec_params_t::min_key_size	Minimum encryption key size in octets
1 byte	Conditional: ble_gap_sec_params_t::max_key_size	Maximum encryption key size in octets
1 byte	Conditional: bitfields of ble_gap_sec_params_t::kdist_periph	Peripheral key distribution bitmap
1 byte	Conditional: bitfields of ble_gap_sec_params_t::kdist_central	Central key distribution bitmap
1 byte	Security Keyset Present	0x00 - not present, 0x01 - present
1 byte	Conditional: Peripheral Encryption Keys Present	0x00 - not present, 0x01 - present
16 bytes	Conditional: Encryption Info: Long Term Key	See ble_gap_enc_info_t::ltk
1 bytes	Conditional: Encryption Info: bitfields	See ble_gap_enc_info_t::auth, ble_gap_enc_info_t::ltk_len
2 bytes	Conditional: Master identification: Encrypted Diversifier	See ble_gap_master_id_t::ediv
8 bytes	Conditional: Master identification: Random Number	See ble_gap_master_id_t::ediv
1 byte	Conditional: Peripheral Identity Keys Present	0x00 - not present, 0x01 - present
16 bytes	Conditional: Identity Resolving Key	See ble_gap_id_key_t::id_info
1 byte	Conditional: Identity Address Info: Address Type	See ble_gap_id_key_t::id_addr_info
6 bytes	Conditional: Identity Address Info: Address	See ble_gap_id_key_t::id_addr_info
1 byte	Conditional: Peripheral Signing Information Present	0x00 - not present, 0x01 - present
16 bytes	Conditional: Connection Signature Resolving Key	See ble_gap_sign_info_t
1 byte	Conditional: Central Encryption Keys Present	0x00 - not present, 0x01 - present
16 bytes	Conditional: Encryption Info: Long Term Key	See ble_gap_enc_info_t::ltk
1 bytes	Conditional: Encryption Info: bitfields	See ble_gap_enc_info_t::auth, ble_gap_enc_info_t::ltk_len
2 bytes	Conditional: Master identification: Encrypted Diversifier	See ble_gap_master_id_t::ediv
8 bytes	Conditional: Master identification: Random Number	See ble_gap_master_id_t::ediv
1 byte	Conditional: Central Identity Keys Present	0x00 - not present, 0x01 - present
16 bytes	Conditional: Identity Resolving Key	See ble_gap_id_key_t::id_info
1 byte	Conditional: Identity Address Info: Address Type	See ble_gap_id_key_t::id_addr_info
6 bytes	Conditional: Identity Address Info: Address	See ble_gap_id_key_t::id_addr_info
1 byte	Conditional: Central Signing Information Present	0x00 - not present, 0x01 - present
16 bytes	Conditional: Connection Signature Resolving Key	See ble_gap_sign_info_t

Figure 1: Packet format for sd_ble_gap_sec_params_reply function.

The Bond, MITM, IO capabilities, and OOB fields are all bitfields inside 1 byte, as seen in Figure 2. The Key Distribution Bitmap is a structure containing bitfields inside 1 byte, as seen in Figure 3. The Security Keyset Structure is encoded as shown in Figures 4 and 5.

When sd_ble_gap_sec_params_reply is called, a security context is created using conn_ble_gap_sec_context_create and app_ble_gap_sec_context_create on Connectivity and Application processors respectively. The context is used to handle security keys. It is released using conn_ble_gap_sec_context_destroy and app_ble_gap_sec_context_destroy when BLE_GAP_EVT_AUTH_STATUS is received.

Encoding of Bond, MITM, IO caps, and OOB

Figure 2: Encoding of Bond, MITM, IO caps, and OOB inside a sd_ble_gap_sec_params_reply function packet.

Encoding of Key Distribution Bitmap

Figure 3: Encoding of Key Distribution Bitmap inside a sd_ble_gap_sec_params_reply function packet.

Encoding of Keyset Structure

Figure 4: Encoding of Keyset Structure inside a sd_ble_gap_sec_params_reply function packet.

Each member of the Keyset Structure (Peripheral Keys and Central Keys) is encoded the same way. Encoding details are shown in Figure 5.

Figure 5: Encoding of Security Keys in Keyset Structure inside a sd_ble_gap_sec_params_reply function packet.

Response packet format

Frame format encoding of the sd_ble_gap_sec_params_reply response packet:

Length	Parameter	Value
1 byte	Operation Code	0x7F, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_sec_params_reply
1 byte	Security Keyset Present	0x00 - not present, 0x01 - present
6 ... 138 byte	Security Keyset	See ble_gap_sec_keyset_t

The Security Keyset field in the response packet is encoded the same way as in the command packet (see Figures 4 and 5).

Figure 6: Packet format for sd_ble_gap_sec_params_reply response.

0x80 - sd_ble_gap_auth_key_reply

Function packet format

Frame format encoding of the sd_ble_gap_auth_key_reply packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x80, see BLE_GAP_SVCS
2 bytes	Connection Handle	Handle value
1 byte	Key Type	See GAP Authentication Key Types
1 byte	Key Present	0x00 - not present, 0x01 - present
6 or 16 bytes	Conditional: Key	Key value

Figure 1: Packet format for sd_ble_gap_auth_key_reply function.

Response packet format

Frame format encoding of the sd_ble_gap_auth_key_reply response packet:

Length	Parameter	Value
1 byte	Operation Code	0x80 (128)
4 bytes	nRF Error Code	See sd_ble_gap_auth_key_reply

Figure 2: Packet format for sd_ble_gap_auth_key_reply response.

0x81 - sd_ble_gap_encrypt

Function packet format

Frame format encoding of the sd_ble_gap_encrypt packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x81, see BLE_GAP_SVCS
2 bytes	Connection Handle	Handle value
1 byte	Master Identification Present	0x00 - not present, 0x01 - present
10 bytes	Conditional: Master Identification	See ble_gap_master_id_t
1 byte	Encryption Information Present	0x00 - not present, 0x01 - present
17 bytes	Conditional: Encryption Information	See ble_gap_enc_info_t

Figure 1: Packet format for sd_ble_gap_encrypt function.

Response packet format

Frame format encoding of the sd_ble_gap_encrypt response packet:

Length	Parameter	Value
1 byte	Operation Code	0x81, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_encrypt

Figure 4: Packet format for sd_ble_gap_encrypt response.

0x82 - sd_ble_gap_sec_info_reply

Function packet format

Frame format encoding of the sd_ble_gap_sec_info_reply packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x82, see BLE_GAP_SVCS
2 bytes	Connection Handle	Handle value
1 byte	Encryption Information Present	0x00 - not present, 0x01 - present
17 bytes	Conditional: Encryption Information	See ble_gap_enc_info_t
1 byte	Identity Information Present	0x00 - not present, 0x01 - present
16 bytes	Conditional: Identity Information	See ble_gap_irk_t
1 byte	Signing Information Present	0x00 - not present, 0x01 - present
16 bytes	Conditional: Signing Information	See ble_gap_sign_info_t

Figure 1: Packet format for sd_ble_gap_sec_info_reply function.

The bit fields of Encryption Information are encoded as below and depicted in Figure 2 and Figure 3:

Figure 2: Contents of Encryption information.

Length	Parameter	Value
bit 0	Authenticated Key	See ble_gap_enc_info_t::auth
bit 1 to 7	LTK length in octets	See ble_gap_enc_info_t::ltk_len

Figure 3: Bit Ordering of LTK and Authenticated Key fields.

Response packet format

Frame format encoding of the sd_ble_gap_sec_info_reply response packet:

Length	Parameter	Value
1 byte	Operation Code	0x82, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_sec_info_reply

Figure 4: Packet format for sd_ble_gap_sec_info_reply response.

0x83 - sd_ble_gap_conn_sec_get

Function packet format

Frame format encoding of the sd_ble_gap_conn_sec_get packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x83, see BLE_GAP_SVCS
2 bytes	Connection Handle	Handle value
1 byte	Connection Security field present	0x00 - not present, 0x01 - present

Figure 1: Packet format for sd_ble_gap_conn_sec_get function.

Response packet format

If a command was executed successfully, so that 'nRF Error Code' = NRF_SUCCESS, the nRF Error Code is followed by conditional data.

Frame format encoding of the sd_ble_gap_conn_sec_get response packet:

Length	Parameter	Value
1 byte	Operation Code	0x83, see BLE_GAP_SVCS
4 bytes	nRF Error Code	See sd_ble_gap_ppcp_get
1 byte	Conditional: Connection Security field present	0x00 - not present, 0x01 - present
2 bytes	Conditional: Connection Security	See ble_gap_conn_sec_t

Figure 2: Packet format for sd_ble_gap_conn_sec_get response.

0x84 - sd_ble_gap_rssi_start

Function packet format

Frame format encoding of the sd_ble_gap_rssi_start packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x84, see BLE_GAP_SVCS
2 bytes	Connection Handle	Handle value
1 byte	Threshold	Threshold value in dBm
1 byte	Skip count	Number of RSSI samples

Figure 1: Packet format for sd_ble_gap_rssi_start function.

Response packet format

Frame format encoding of the sd_ble_gap_rssi_start response packet:

Length	Parameter	Value
1 byte	Operation Code	0x84
4 bytes	nRF Error Code	See sd_ble_gap_rssi_start

Figure 2: Packet format for sd_ble_gap_rssi_start response.

0x85 - sd_ble_gap_rssi_stop

Function packet format

Frame format encoding of the sd_ble_gap_rssi_stop packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x85, see BLE_GAP_SVCS
2 bytes	Connection Handle	Handle value

Figure 1: Packet format for sd_ble_gap_rssi_stop function.

Response packet format

Frame format encoding of the sd_ble_gap_rssi_stop response packet:

Length	Parameter	Value
1 byte	Operation Code	0x85
4 bytes	nRF Error Code	See sd_ble_gap_rssi_stop

Figure 2: Packet format for sd_ble_gap_rssi_stop response.

0x86 - sd_ble_gap_scan_start

Function packet format

Frame format encoding of the sd_ble_gap_scan_start packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x86, see BLE_GAP_SVCS
1 byte	Scan Params field present	0x00 - not present, 0x01 - present
1 byte	Active, selective fields	See ble_gap_scan_params_t::active and ble_gap_scan_params_t::selective
1 byte	GAP Whitelist field present	0x00 - not present, 0x01 - present
2...186 bytes	GAP Whitelist	See 0x73 - sd_ble_gap_adv_start codec for encoding details
2 bytes	Scan interval	See ble_gap_scan_params_t::interval
2 bytes	Scan window	See ble_gap_scan_params_t::window
2 bytes	Scan timeout	See ble_gap_scan_params_t::timeout

Figure 1: Packet format for sd_ble_gap_scan_start function.

Response packet format

Frame format encoding of the sd_ble_gap_scan_start response packet:

Length	Parameter	Value
1 byte	Operation Code	0x86
4 bytes	nRF Error Code	See sd_ble_gap_scan_start

Figure 2: Packet format for sd_ble_gap_scan_start response.

0x87 - sd_ble_gap_scan_stop

Function packet format

Frame format encoding of the sd_ble_gap_scan_stop packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x87, see BLE_GAP_SVCS

Figure 1: Packet format for sd_ble_gap_scan_stop function.

Response packet format

Frame format encoding of the sd_ble_gap_scan_stop response packet:

Length	Parameter	Value
1 byte	Operation Code	0x87
4 bytes	nRF Error Code	See sd_ble_gap_scan_stop

Figure 2: Packet format for sd_ble_gap_scan_stop response.

0x88 - sd_ble_gap_connect

Function packet format

Frame format encoding of the sd_ble_gap_connect packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x88, see BLE_GAP_SVCS
1 byte	Peer Address Present	0x00 - not present, 0x01 - present
7 bytes	Peer Address	See Function packet format for encoding details
1 byte	Scan Parameters Present	0x00 - not present, 0x01 - present
8...194 bytes	Scan Parameters	See Function packet format for encoding details
1 byte	Connection Parameters Present	0x00 - not present, 0x01 - present
8 bytes	Connection Parameters	See Function packet format for encoding details

Figure 1: Packet format for sd_ble_gap_connect function.

Response packet format

Frame format encoding of the sd_ble_gap_connect response packet:

Length	Parameter	Value
1 byte	Operation Code	0x88
4 bytes	nRF Error Code	See sd_ble_gap_connect

Figure 2: Packet format for sd_ble_gap_connect response.

0x89 - sd_ble_gap_connect_cancel

Function packet format

Frame format encoding of the sd_ble_gap_connect_cancel packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x89, see BLE_GAP_SVCS

Figure 1: Packet format for sd_ble_gap_connect_cancel function.

Response packet format

Frame format encoding of the sd_ble_gap_connect_cancel response packet:

Length	Parameter	Value
1 byte	Operation Code	0x89
4 bytes	nRF Error Code	See sd_ble_gap_connect

Figure 2: Packet format for sd_ble_gap_connect_cancel response.

0x8A - sd_ble_gap_rssi_get

Function packet format

Frame format encoding of the sd_ble_gap_rssi_get packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0x8A, see BLE_GAP_SVCS
2 bytes	Connection handle	Handle value
1 byte	RSSI field present	0x00 - not present, 0x01 - present

Figure 1: Packet format for sd_ble_gap_rssi_get function.

Response packet format

If a command was executed successfully, so that 'nRF Error Code' = NRF_SUCCESS, the nRF Error Code is followed by conditional data.

Frame format encoding of the sd_ble_gap_rssi_get response packet:

Length	Parameter	Value
1 byte	Operation Code	0x8A
4 bytes	nRF Error Code	See sd_ble_gap_rssi_get
1 byte	Conditional: RSSI	Measured RSSI

Figure 2: Packet format for sd_ble_gap_rssi_get response.