0x63 - sd_ble_gap_adv_start

Function packet format

Frame format encoding of the sd_ble_gap_adv_start packet.

Operation Code = 0x63 (99) for sd_ble_gap_adv_start, see BLE_GAP_SVCS.

The parameter provided as input to sd_ble_gap_adv_start is encoded in the following order:

- 1 byte:		Operation Code, Value = 0x63 (99)
- 8 ... 201 bytes:	ble_gap_adv_params_t	GAP Advertising Parameters (See Figure 1 for details on encoding)

As can also be seen in Figure 1 some fields in the encoded data are optional, i.e. ble_gap_adv_params_t::p_peer_addr and ble_gap_adv_params_t::p_whitelist .

The encoded field 'Peer Address Present' identifies if a NULL pointer was provided in ble_gap_adv_params_t::p_peer_addr. If a NULL pointer was provided, the value of 'Peer Address Present' will be set to '0x00' and no data will be encoded. Otherwise it will be set to '0x01, and the encoding of the Peer Address field will follow immediately, as seen in Figure 2.

The encoded field 'GAP Whitelist Present' identifies if a NULL pointer was provided in ble_gap_adv_params_t::p_whitelist. If a NULL pointer was provided, the value of 'GAP Whitelist Present' will be set to '0x00', and no data will be encoded. Otherwise it will be set to '0x01, and the encoding of the GAP Whitelist structure will follow immediately, as seen in Figure 3.

The data inside ble_gap_adv_start_params_t are encoded as:

- 1 byte:		GAP Advertising Type
- 1 byte:		Peer Address Present
		0x00 Field not present
		0x01 Field present and follows immediately in the packet
- 7 bytes:	ble_gap_adv_params_t::p_peer_addr	Conditional: Peer Address
		Encoding details can be seen in Figure 2
- 1 byte:	GAP Advertising filter policies	Filter Policy
- 1 byte:		GAP Whitelist Present
		0x00 Field not present
		0x01 Field present and follows immediately in the packet
- 2 ... 186 bytes:	ble_gap_adv_params_t::p_whitelist	Conditional: GAP Whitelist
		Encoding details can be seen in Figure 3

Figure 1: Packet format for sd_ble_gap_adv_start function.

Encoding of Peer Address

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

The data inside ble_gap_addr_t are encoded as:

- 1 byte:		Address type, see GAP Address types
- 6 bytes:		Address

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, then the encoding of the 'GAP Whitelist' will follow.
'GAP Whitelist' is a 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 pointing to an array of whitelist addresses, and a pointer ble_gap_whitelist_t::pp_irks pointing to an array of IRKs.

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 are encoded as:

- 1 byte:		Address Counter
- 0 ... 56 bytes:		Address list
		'Address Counter' specifies the actual number of addresses encoded.
- 1 byte:		IRK Counter
- 0 ... 128 bytes:		IRK list
		'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 start with the 'Whitelist Count' according to the value in ble_gap_whitelist_t::addr_count.
If, the value of 'Whitelist Count' is 0, then no whitelist addresses are encoded, and the 'Whitelist Count' 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. Each address is 7 bytes, with first byte specifying the address type.

The Whitelist addresses are encoded as:

- 1 byte:

Whitelist Address Count

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

- 1 byte:		Address Type, see GAP Address types
- 6 bytes:		Address

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.
If, the value of 'IRK Count' is 0, then no IRKs are encoded, and the 'IRK Count' 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. Each IRK is 16 bytes.

The IRKs are encoded as:

- 1 byte:

IRK Count

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

- 16 bytes:

IRK

Figure 5: Encoding of Whitelist IRKs.

Response packet format

Frame format encoding of the sd_ble_gap_adv_start response packet.

In case of an error, the following data is encoded:

- 1 byte:		Operation Code, Value = 0x63 (99)
- 4 byte:		nRF Error Code

Figure 2: Packet format for sd_ble_gap_adv_start error response.

In case of a successful command, i.e. 'nRF Error Code' = NRF_SUCCESS, the following data is encoded:

- 1 byte:		Operation Code, Value = 0x63 (99)
- 4 bytes:		nRF Error Code

Figure 3: Packet format for sd_ble_gap_adv_start success response.