Connection#

Connection.


Modules
sl_bt_evt_connection_opened
Indicates that a new connection was opened.
sl_bt_evt_connection_parameters
Triggered whenever the connection parameters are changed and at any time a connection is established.
sl_bt_evt_connection_phy_status
Indicates that PHY update procedure is completed.
sl_bt_evt_connection_rssi
Triggered when an connection_get_rssi command has completed.
sl_bt_evt_connection_get_remote_tx_power_completed
Indicates that reading remote transmit power initiated by sl_bt_connection_get_remote_tx_power command has completed.
sl_bt_evt_connection_tx_power
Reports a transmit power change on the local device of a connection if transmit power reporting has been enabled.
sl_bt_evt_connection_remote_tx_power
Reports a transmit power change on the remote device of a connection if transmit power reporting has been enabled.
sl_bt_evt_connection_closed
Indicates that a connection was closed.


Enumerations
enum	sl_bt_connection_security_t { sl_bt_connection_mode1_level1 = 0x0, sl_bt_connection_mode1_level2 = 0x1, sl_bt_connection_mode1_level3 = 0x2, sl_bt_connection_mode1_level4 = 0x3 }
	Security Modes. More...
enum	sl_bt_connection_power_reporting_mode_t { sl_bt_connection_power_reporting_disable = 0x0, sl_bt_connection_power_reporting_enable = 0x1 }
	Transmit Power Reporting Mode. More...
enum	sl_bt_connection_tx_power_flag_t { sl_bt_connection_tx_power_at_minimum = 0x1, sl_bt_connection_tx_power_at_maximum = 0x2 }
	Transmit Power Level Flags. More...


Functions
sl_status_t	sl_bt_connection_set_default_parameters (uint16_t min_interval, uint16_t max_interval, uint16_t latency, uint16_t timeout, uint16_t min_ce_length, uint16_t max_ce_length)
sl_status_t	sl_bt_connection_set_default_preferred_phy (uint8_t preferred_phy, uint8_t accepted_phy)
sl_status_t	sl_bt_connection_open (bd_addr address, uint8_t address_type, uint8_t initiating_phy, uint8_t *connection)
sl_status_t	sl_bt_connection_set_parameters (uint8_t connection, uint16_t min_interval, uint16_t max_interval, uint16_t latency, uint16_t timeout, uint16_t min_ce_length, uint16_t max_ce_length)
sl_status_t	sl_bt_connection_set_preferred_phy (uint8_t connection, uint8_t preferred_phy, uint8_t accepted_phy)
sl_status_t	sl_bt_connection_disable_slave_latency (uint8_t connection, uint8_t disable)
sl_status_t	sl_bt_connection_get_rssi (uint8_t connection)
sl_status_t	sl_bt_connection_read_channel_map (uint8_t connection, size_t max_channel_map_size, size_t channel_map_len, uint8_t channel_map)
sl_status_t	sl_bt_connection_set_power_reporting (uint8_t connection, uint8_t mode)
sl_status_t	sl_bt_connection_set_remote_power_reporting (uint8_t connection, uint8_t mode)
sl_status_t	sl_bt_connection_get_tx_power (uint8_t connection, uint8_t phy, int8_t current_level, int8_t max_level)
sl_status_t	sl_bt_connection_get_remote_tx_power (uint8_t connection, uint8_t phy)
sl_status_t	sl_bt_connection_close (uint8_t connection)


Transmit Power Reporting Constants
Constants in transmit power reporting
#define	SL_BT_CONNECTION_TX_POWER_UNMANAGED 0x7e
#define	SL_BT_CONNECTION_TX_POWER_UNAVAILABLE 0x7f
#define	SL_BT_CONNECTION_TX_POWER_CHANGE_UNAVAILABLE 0x7f

Detailed Description#

Connection.

The commands and events in this class are related to managing connection establishment, parameter setting, and disconnection procedures.

Data Structure Documentation#

SL_BT_CONNECTION_TX_POWER_UNMANAGED#

#define SL_BT_CONNECTION_TX_POWER_UNMANAGED 0x7e

Remote device is not managing power levels.

SL_BT_CONNECTION_TX_POWER_UNAVAILABLE#

#define SL_BT_CONNECTION_TX_POWER_UNAVAILABLE 0x7f

Transmit power level is not available.

SL_BT_CONNECTION_TX_POWER_CHANGE_UNAVAILABLE#

#define SL_BT_CONNECTION_TX_POWER_CHANGE_UNAVAILABLE 0x7f

Change is not available or is out of range.

Enumeration Type Documentation#

sl_bt_connection_security_t#

enum sl_bt_connection_security_t

Security Modes.


Enumerator
sl_bt_connection_mode1_level1	(0x0) No security
sl_bt_connection_mode1_level2	(0x1) Unauthenticated pairing with encryption
sl_bt_connection_mode1_level3	(0x2) Authenticated pairing with encryption
sl_bt_connection_mode1_level4	(0x3) Authenticated Secure Connections pairing with encryption using a 128-bit strength encryption key

sl_bt_connection_power_reporting_mode_t#

enum sl_bt_connection_power_reporting_mode_t

Transmit Power Reporting Mode.


Enumerator
sl_bt_connection_power_reporting_disable	(0x0) Disable transmit power reporting
sl_bt_connection_power_reporting_enable	(0x1) Enable transmit power reporting

sl_bt_connection_tx_power_flag_t#

enum sl_bt_connection_tx_power_flag_t

Transmit Power Level Flags.


Enumerator
sl_bt_connection_tx_power_at_minimum	(0x1) Transmit power level is at minimum level.
sl_bt_connection_tx_power_at_maximum	(0x2) Transmit power level is at maximum level.

Function Documentation#

sl_bt_connection_set_default_parameters()#



sl_status_t sl_bt_connection_set_default_parameters	(	uint16_t	`min_interval,`
		uint16_t	`max_interval,`
		uint16_t	`latency,`
		uint16_t	`timeout,`
		uint16_t	`min_ce_length,`
		uint16_t	`max_ce_length`
	)

Set the default Bluetooth connection parameters. The values are valid for all subsequent connections initiated by this device. To change parameters of an already established connection, use the command sl_bt_connection_set_parameters.

Parameters



[in]	`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
[in]	`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
[in]	`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
[in]	`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 + Set the supervision timeout at a value which allows communication attempts over at least a few connection intervals. Default value: 1000 ms
[in]	`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.
[in]	`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

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_connection_set_default_preferred_phy()#



sl_status_t sl_bt_connection_set_default_preferred_phy	(	uint8_t	`preferred_phy,`
		uint8_t	`accepted_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.

Parameters



[in]	`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)
[in]	`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)

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_connection_open()#



sl_status_t sl_bt_connection_open	(	bd_addr	`address,`
		uint8_t	`address_type,`
		uint8_t	`initiating_phy,`
		uint8_t *	`connection`
	)

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 sl_bt_scanner_set_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 sl_bt_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 sl_bt_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.

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

Parameters



[in]	`address`	Address of the device to connect to
[in]	`address_type`	Enum sl_bt_gap_address_type_t. Address type of the device to connect to. Values: sl_bt_gap_public_address (0x0): Public device address

sl_bt_gap_static_address (0x1): Static device address
sl_bt_gap_random_resolvable_address (0x2): Private resolvable random address
sl_bt_gap_random_nonresolvable_address (0x3): Private non-resolvable random address | | [in] | initiating_phy | Enum sl_bt_gap_phy_type_t. The initiating PHY. Values:* sl_bt_gap_1m_phy (0x1): 1M PHY
sl_bt_gap_coded_phy (0x4): Coded PHY, 125k (S=8) or 500k (S=2) | | [out] | 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). |

Returns SL_STATUS_OK if successful. Error code otherwise.

Events

sl_bt_evt_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.
sl_bt_evt_connection_parameters - This event indicates the connection parameters and security mode of the connection.

◆sl_bt_connection_set_parameters()#



sl_status_t sl_bt_connection_set_parameters	(	uint8_t	`connection,`
		uint16_t	`min_interval,`
		uint16_t	`max_interval,`
		uint16_t	`latency,`
		uint16_t	`timeout,`
		uint16_t	`min_ce_length,`
		uint16_t	`max_ce_length`
	)

Request a change in the connection parameters of a Bluetooth connection.

Parameters



[in]	`connection`	Connection Handle
[in]	`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
[in]	`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
[in]	`latency`	Slave latency, which defines how many connection intervals the slave can skip if it has no data to send Range: 0x0000 to 0x01f4 Use 0x0000 for default value
[in]	`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 + Set the supervision timeout at a value which allows communication attempts over at least a few connection intervals.
[in]	`min_ce_length`	Minimum value for the connection event length. This must be set less than or equal to `max_ce_length`. Time = Value x 0.625 ms Range: 0x0000 to 0xffff Value is not currently used and is reserved for future. Set to 0.
[in]	`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 Use 0xffff for no limitation.

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

sl_bt_evt_connection_parameters - Triggered after new connection parameters are applied on the connection.

sl_bt_connection_set_preferred_phy()#



sl_status_t sl_bt_connection_set_preferred_phy	(	uint8_t	`connection,`
		uint8_t	`preferred_phy,`
		uint8_t	`accepted_phy`
	)

Sets preferred and accepted PHYs for the given connection. Event sl_bt_evt_connection_phy_status is received when PHY update procedure is completed. Non-preferred PHY can also be set if remote device does not accept any of the preferred PHYs.

The parameter accepted_phy is used for specifying the PHYs that the stack can accept in a remote initiated PHY update request. A PHY update will not occur if none of the accepted PHYs presents in the request.

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

Parameters



[in]	`connection`	Connection handle
[in]	`preferred_phy`	Preferred PHYs. This parameter is a bitfield and multiple PHYs can be set. 0x01: 1M PHY 0x02: 2M PHY 0x04: 125k Coded PHY (S=8) 0x08: 500k Coded PHY (S=2) Default: 0xff (no preference)
[in]	`accepted_phy`	Accepted PHYs in remotely-initiated PHY update requests. 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)

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

sl_bt_evt_connection_phy_status

sl_bt_connection_disable_slave_latency()#



sl_status_t sl_bt_connection_disable_slave_latency	(	uint8_t	`connection,`
		uint8_t	`disable`
	)

Temporarily enable or disable slave latency. Used only when Bluetooth device is acting as slave. When slave latency is disabled, the slave latency connection parameter is not set to 0 but the device will wake up on every connection interval to receive and send packets.

Parameters



[in]	`connection`	Connection Handle
[in]	`disable`	0 enable, 1 disable slave latency. Default: 0

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_connection_get_rssi()#

sl_status_t sl_bt_connection_get_rssi ( uint8_t connection )

Get the latest RSSI value of a Bluetooth connection. The RSSI value will be reported in a sl_bt_evt_connection_rssi event.

Parameters



[in]	`connection`	Connection handle

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

sl_bt_evt_connection_rssi - Triggered when this command has completed.

sl_bt_connection_read_channel_map()#



sl_status_t sl_bt_connection_read_channel_map	(	uint8_t	`connection,`
		size_t	`max_channel_map_size,`
		size_t *	`channel_map_len,`
		uint8_t *	`channel_map`
	)

Read channel map for a specified connection.

Parameters



[in]	`connection`	Connection Handle
[in]	`max_channel_map_size`	Size of output buffer passed in `channel_map`
[out]	`channel_map_len`	On return, set to the length of output data written to `channel_map`
[out]	`channel_map`	This parameter is 5 bytes and contains 37 1-bit fields. The nth field (in the range 0 to 36) contains the value for the link layer channel index n. 0: Channel n is unused. 1: Channel n is used. The most significant bits are reserved for future use.

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_connection_set_power_reporting()#



sl_status_t sl_bt_connection_set_power_reporting	(	uint8_t	`connection,`
		uint8_t	`mode`
	)

Enable or disable the transmit power reporting for the local device on a connection. When transmit power reporting is enabled, event sl_bt_evt_connection_tx_power is generated when transmit power on the local device changes.

By default power reporting for local device is enabled.

Parameters



[in]	`connection`	Handle of the connection
[in]	`mode`	Enum sl_bt_connection_power_reporting_mode_t. Transmit power reporting mode. Values: sl_bt_connection_power_reporting_disable (0x0): Disable transmit power reporting sl_bt_connection_power_reporting_enable (0x1): Enable transmit power reporting

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

sl_bt_evt_connection_tx_power

sl_bt_connection_set_remote_power_reporting()#



sl_status_t sl_bt_connection_set_remote_power_reporting	(	uint8_t	`connection,`
		uint8_t	`mode`
	)

Enable or disable the transmit power reporting for the remote device on a connection. When transmit power reporting is enabled, event sl_bt_evt_connection_remote_tx_power is generated when transmit power on the remote device changes.

By default, power reporting for the remote device is disabled.

Parameters



[in]	`connection`	Handle of the connection
[in]	`mode`	Enum sl_bt_connection_power_reporting_mode_t. Transmit power reporting mode. Values: sl_bt_connection_power_reporting_disable (0x0): Disable transmit power reporting sl_bt_connection_power_reporting_enable (0x1): Enable transmit power reporting

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

sl_bt_evt_connection_remote_tx_power

sl_bt_connection_get_tx_power()#



sl_status_t sl_bt_connection_get_tx_power	(	uint8_t	`connection,`
		uint8_t	`phy,`
		int8_t *	`current_level,`
		int8_t *	`max_level`
	)

Get the transmit power of the local device on the given connection and PHY.

Parameters



[in]	`connection`	Handle of the connection
[in]	`phy`	Enum sl_bt_gap_phy_and_coding_type_t. The PHY. Values: sl_bt_gap_1m_phy_uncoded (0x1): 1M PHY sl_bt_gap_2m_phy_uncoded (0x2): 2M PHY sl_bt_gap_coded_phy_125k (0x4): 125k Coded PHY (S=8) sl_bt_gap_coded_phy_500k (0x8): 500k Coded PHY (S=2)
[out]	`current_level`	The current transmit power level of the PHY on the connection. Values: Range -127 to 20: The transmit power level in dBm
[out]	`max_level`	The maximum transmit power level of the PHY on the connection. Values: Range -127 to +20 in dBm.

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_connection_get_remote_tx_power()#



sl_status_t sl_bt_connection_get_remote_tx_power	(	uint8_t	`connection,`
		uint8_t	`phy`
	)

Get the transmit power of the remote device on the given connection and PHY. Transmit power levels are returned in event sl_bt_evt_connection_get_remote_tx_power_completed after the operation completed.

Parameters



[in]	`connection`	Handle of the connection
[in]	`phy`	Enum sl_bt_gap_phy_and_coding_type_t. The PHY. Values: sl_bt_gap_1m_phy_uncoded (0x1): 1M PHY sl_bt_gap_2m_phy_uncoded (0x2): 2M PHY sl_bt_gap_coded_phy_125k (0x4): 125k Coded PHY (S=8) sl_bt_gap_coded_phy_500k (0x8): 500k Coded PHY (S=2)

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

sl_bt_evt_connection_get_remote_tx_power_completed

sl_bt_connection_close()#

sl_status_t sl_bt_connection_close ( uint8_t connection )

Close a Bluetooth connection or cancel an ongoing connection establishment process. The parameter is a connection handle which is reported in sl_bt_evt_connection_opened event or sl_bt_connection_open command response.

Parameters



[in]	`connection`	Handle of the connection to be closed

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

sl_bt_evt_connection_closed