Connection#

Connection.

Detailed Description#

Connection.

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

Enumeration Type Documentation#

◆sl_bt_connection_security_t#

Indicate the Bluetooth Security Mode.

◆sl_bt_connection_power_reporting_mode_t#

These values define transmit power reporting modes in LE power control.

◆sl_bt_connection_tx_power_flag_t#

This enum defines the flag values for a reported transmit power level.

Function Documentation#

◆sl_bt_connection_set_default_parameters()#

Set default Bluetooth connection parameters. The values are valid for all subsequent connections initiated by this device.

min_ce_length and max_ce_length specify the preference of the connection event length so that the Link Layer can prioritize tasks accordingly in simultaneous connections, or scanning and so on. A connection event starts at an anchor point of a connection interval and lasts until the lesser of max_ce_length and the actual connection interval. Packets that do not fit into the connection event will be sent in the next connection interval.

To change parameters of an already established connection, use the command sl_bt_connection_set_parameters.

Parameters

• 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 | Peripheral latency, which defines how many connection intervals the peripheral can skip if it has no data to send* Range: 0x0000 to 0x01f3

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 + 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 | | [in] | min_ce_length | Minimum length of the connection event. It must be less than or equal to max_ce_length. This value defines the minimum time that should be given to the connection event in a situation where other tasks need to run immediately after the connection event. When the value is very small, the connection event still has at least one TX/RX operation. If this value is increased, more time is reserved for the connection event so it can transmit and receive more packets in a connection interval. Use the default value if the application doesn't care about the connection event length or doesn't want to do fine tuning.* Time = Value x 0.625 ms

• Range: 0x0000 to 0xffff

Default value: 0x0000 | | [in] | max_ce_length | Maximum length of the connection event. It must be greater than or equal to min_ce_length. This value is used for limiting the connection event length so that a connection that has large amounts of data to transmit or receive doesn't block other tasks. Limiting the connection event is a hard stop. If there is no enough time to send or receive a packet, the connection event will be closed. If the value is set to 0, the connection event still has at least one TX/RX operation. This is useful to limit power consumption or leave more time to other tasks. Use the default value if the application doesn't care about the connection event length or doesn't want to do fine tuning.* Time = Value x 0.625 ms

• Range: 0x0000 to 0xffff

Default value: 0xffff |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_connection_set_default_preferred_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

• 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) |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_connection_open()#

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

• sl_bt_gap_static_address (0x1): Static device address

• sl_bt_gap_random_resolvable_address (0x2): Resolvable private random address

• sl_bt_gap_random_nonresolvable_address (0x3): Non-resolvable private random address | | [in] | initiating_phy | Enum sl_bt_gap_phy_t. The initiating PHY. Values:* sl_bt_gap_phy_1m (0x1): 1M PHY

• sl_bt_gap_phy_coded (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). |

ReturnsSL_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 the role of the device in this connection.

• sl_bt_evt_connection_parameters - This event indicates the connection parameters and security mode of the connection.

◆sl_bt_connection_set_parameters()#

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

min_ce_length and max_ce_length specify the preference of the connection event length so that the Link Layer can prioritize tasks accordingly in simultaneous connections, or scanning and so on. A connection event starts at an anchor point of a connection interval and lasts until the lesser of max_ce_length and the actual connection interval. Packets that do not fit into the connection event will be sent in the next connection interval.

Parameters

• 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 | Peripheral latency, which defines how many connection intervals the peripheral can skip if it has no data to send* Range: 0x0000 to 0x01f3 | | [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 + 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. | | [in] | min_ce_length | Minimum length of the connection event. It must be less than or equal to max_ce_length. This value defines the minimum time that should be given to the connection event in a situation where other tasks need to run immediately after the connection event. When the value is very small, the connection event still has at least one TX/RX operation. If this value is increased, more time is reserved for the connection event so it can transmit and receive more packets in a connection interval. Use the default value if the application doesn't care about the connection event length or doesn't want to do fine tuning.* Time = Value x 0.625 ms

• Range: 0x0000 to 0xffff

Default value: 0x0000 | | [in] | max_ce_length | Maximum length of the connection event. It must be greater than or equal to min_ce_length. This value is used for limiting the connection event length so that a connection that has large amounts of data to transmit or receive doesn't block other tasks. Limiting the connection event is a hard stop. If there is no enough time to send or receive a packet, the connection event will be closed. If the value is set to 0, the connection event still has at least one TX/RX operation. This is useful to limit power consumption or leave more time to other tasks. Use the default value if the application doesn't care about the connection event length or doesn't want to do fine tuning.* Time = Value x 0.625 ms

• Range: 0x0000 to 0xffff

Default value: 0xffff |

ReturnsSL_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()#

Set preferred and accepted PHYs for a 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

• 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) |

ReturnsSL_STATUS_OK if successful. Error code otherwise. Events

• sl_bt_evt_connection_phy_status

◆sl_bt_connection_disable_slave_latency()#

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

Parameters

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_connection_get_rssi()#

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

Parameters

ReturnsSL_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()#

Read channel map for a specified connection.

Parameters

• 1: Channel n is used.

The most significant bits are reserved for future use. |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_connection_set_power_reporting()#

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

• sl_bt_connection_power_reporting_enable (0x1): Enable transmit power reporting |

ReturnsSL_STATUS_OK if successful. Error code otherwise. Events

• sl_bt_evt_connection_tx_power

◆sl_bt_connection_set_remote_power_reporting()#

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

• sl_bt_connection_power_reporting_enable (0x1): Enable transmit power reporting |

ReturnsSL_STATUS_OK if successful. Error code otherwise. Events

• sl_bt_evt_connection_remote_tx_power

◆sl_bt_connection_get_tx_power()#

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

Parameters

• sl_bt_gap_phy_coding_2m_uncoded (0x2): 2M PHY

• sl_bt_gap_phy_coding_125k_coded (0x4): 125k Coded PHY (S=8)

• sl_bt_gap_phy_coding_500k_coded (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

• SL_BT_CONNECTION_TX_POWER_UNAVAILABLE (0x7F): Transmit power level is not available. | | [out] | max_level | The maximum transmit power level of the PHY on the connection. Values: Range -127 to +20 in dBm. |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_connection_get_remote_tx_power()#

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

• sl_bt_gap_phy_coding_2m_uncoded (0x2): 2M PHY

• sl_bt_gap_phy_coding_125k_coded (0x4): 125k Coded PHY (S=8)

• sl_bt_gap_phy_coding_500k_coded (0x8): 500k Coded PHY (S=2) |

ReturnsSL_STATUS_OK if the command is accepted. Error code otherwise. Events

• sl_bt_evt_connection_get_remote_tx_power_completed

◆sl_bt_connection_close()#

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

ReturnsSL_STATUS_OK if successful. Error code otherwise. Events

• sl_bt_evt_connection_closed

◆sl_bt_connection_read_remote_used_features()#

Read link layer features supported by the remote device.

Parameters

ReturnsSL_STATUS_OK if successful. Error code otherwise. Events

• sl_bt_evt_connection_remote_used_features

◆sl_bt_connection_get_security_status()#

Get the security status of the connection.

Parameters

• 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 | | [out] | key_size | The size of encryption key | | [out] | bonding_handle | Bonding handle. Values:* SL_BT_INVALID_BONDING_HANDLE (0xff): No bonding

• Other: Bonding handle |

ReturnsSL_STATUS_OK if successful. Error code otherwise.