sd_ble_gap_phy_update()

uint32_t sd_ble_gap_phy_update	(	uint16_t	conn_handle,
		ble_gap_phys_t const *	p_gap_phys )

#include <ble_gap.h>

Initiate or respond to a PHY Update Procedure.

This function is used to initiate or respond to a PHY Update Procedure. It will always generate a BLE_GAP_EVT_PHY_UPDATE event if successfully executed. If this function is used to initiate a PHY Update procedure and the only option provided in ble_gap_phys_t::tx_phys and ble_gap_phys_t::rx_phys is the currently active PHYs in the respective directions, the SoftDevice will generate a BLE_GAP_EVT_PHY_UPDATE with the current PHYs set and will not initiate the procedure in the Link Layer.

If ble_gap_phys_t::tx_phys or ble_gap_phys_t::rx_phys is BLE_GAP_PHY_AUTO, then the stack will select PHYs based on the peer's PHY preferences and the local link configuration. The PHY Update procedure will for this case result in a PHY combination that respects the time constraints configured with sd_ble_cfg_set and the current link layer data length.

When acting as a central, the SoftDevice will select the fastest common PHY in each direction.

If the peer responds the PHY Update Procedure with unknown response, then the resulting BLE_GAP_EVT_PHY_UPDATE event will have a status set to BLE_HCI_UNSUPPORTED_REMOTE_FEATURE.

If the PHY Update procedure was rejected by the peer due to a procedure collision, the status will be BLE_HCI_STATUS_CODE_LMP_ERROR_TRANSACTION_COLLISION or BLE_HCI_DIFFERENT_TRANSACTION_COLLISION. If the peer responds to the PHY Update procedure with invalid parameters, the status will be BLE_HCI_STATUS_CODE_INVALID_LMP_PARAMETERS. If the PHY Update procedure was rejected by the peer for a different reason, the status will contain the reason as specified by the peer.

Events generated

BLE_GAP_EVT_PHY_UPDATE

Result of the PHY Update Procedure.

Relevant Message Sequence Charts

Central PHY Update

Peripheral PHY Update

Parameters

[in]	conn_handle	Connection handle to indicate the connection for which the PHY Update is requested.
[in]	p_gap_phys	Pointer to PHY structure.

Return values

NRF_SUCCESS	Successfully requested a PHY Update.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid connection handle supplied.
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied.
BLE_ERROR_UNSUPPORTED_REMOTE_FEATURE	Peer has indicated before that it does not support PHY Update procedure. Note that this only applies if the PHY Update procedure is self initiated.
NRF_ERROR_NOT_SUPPORTED	Unsupported PHYs supplied to the call.
NRF_ERROR_INVALID_STATE	No link has been established.
NRF_ERROR_BUSY	Procedure is already in progress or not allowed at this time. Process pending events and wait for the pending procedure to complete and retry.