You are viewing documentation for version: 2.13 This version works with Simplicity Studio 4 only | **For the latest and prior versions see Version History
Connection Management (le_connection)
The commands and events in this class are related to managing connection establishment, parameter setting, and disconnection procedures.
le_connection commands
le_connection_close
Close a Bluetooth connection or cancel an ongoing
connection establishment process. The parameter is a connection handle which is reported in le_connection_opened event or le_gap_connect response.
C API
/* Function */
struct gecko_msg_le_connection_close_rsp_t *gecko_cmd_le_connection_close(uint8 connection);
/* Response id */
gecko_rsp_le_connection_close_id
/* Response structure */
struct gecko_msg_le_connection_close_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint8 |
connection |
Handle of the connection to be closed |
Response Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint16 |
result |
Result code
- 0: success
- Non-zero: an error has occurred
For other values see Error codes
|
Events generated
le_connection_disable_slave_latency
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.
C API
/* Function */
struct gecko_msg_le_connection_disable_slave_latency_rsp_t *gecko_cmd_le_connection_disable_slave_latency(uint8 connection, uint8 disable);
/* Response id */
gecko_rsp_le_connection_disable_slave_latency_id
/* Response structure */
struct gecko_msg_le_connection_disable_slave_latency_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint8 |
connection |
Connection Handle |
uint8 |
disable |
0 enable, 1 disable slave latency. Default: 0 |
Response Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint16 |
result |
Result code
- 0: success
- Non-zero: an error has occurred
For other values see Error codes
|
le_connection_get_rssi
Get the latest RSSI value of a Bluetooth connection. The RSSI value will be reported in a le_connection_rssi event.
C API
/* Function */
struct gecko_msg_le_connection_get_rssi_rsp_t *gecko_cmd_le_connection_get_rssi(uint8 connection);
/* Response id */
gecko_rsp_le_connection_get_rssi_id
/* Response structure */
struct gecko_msg_le_connection_get_rssi_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint8 |
connection |
Connection handle |
Response Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint16 |
result |
Result code
- 0: success
- Non-zero: an error has occurred
For other values see Error codes
|
Events generated
le_connection_read_channel_map
Read channel map for a specified connection.
C API
/* Function */
struct gecko_msg_le_connection_read_channel_map_rsp_t *gecko_cmd_le_connection_read_channel_map(uint8 connection);
/* Response id */
gecko_rsp_le_connection_read_channel_map_id
/* Response structure */
struct gecko_msg_le_connection_read_channel_map_rsp_t
{
uint16 result;
uint8array channel_map;
}
Command Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint8 |
connection |
Connection Handle |
Response Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint16 |
result |
Result code
- 0: success
- Non-zero: an error has occurred
For other values see Error codes
|
uint8array |
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.
|
le_connection_set_parameters
Deprecated and replaced by le_connection_set_timing_parameters command.
Request a change in the connection parameters of a Bluetooth connection.
C API
/* Function */
struct gecko_msg_le_connection_set_parameters_rsp_t *gecko_cmd_le_connection_set_parameters(uint8 connection, uint16 min_interval, uint16 max_interval, uint16 latency, uint16 timeout);
/* Response id */
gecko_rsp_le_connection_set_parameters_id
/* Response structure */
struct gecko_msg_le_connection_set_parameters_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint8 |
connection |
Connection Handle |
uint16 |
min_interval |
Minimum value for the connection event interval. This must be set be 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
|
uint16 |
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
|
uint16 |
latency |
Slave latency, which defines how many connection intervals the slave can skip if it has no data to sendUse 0x0000 for default value
|
uint16 |
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.
|
Response Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint16 |
result |
Result code
- 0: success
- Non-zero: an error has occurred
For other values see Error codes
|
Events generated
le_connection_set_phy
Deprecated and replaced by le_connection_set_preferred_phy command.
Set preferred PHYs for a connection. Preferred PHYs are connection-specific. Event le_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.
NOTE: 2 Mbit and Coded PHYs are not supported by all devices.
C API
/* Function */
struct gecko_msg_le_connection_set_phy_rsp_t *gecko_cmd_le_connection_set_phy(uint8 connection, uint8 phy);
/* Response id */
gecko_rsp_le_connection_set_phy_id
/* Response structure */
struct gecko_msg_le_connection_set_phy_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint8 |
connection |
|
uint8 |
phy |
Preferred PHYs for connection. This parameter is a bitfield and multiple PHYs can be preferred by setting multiple bits.
- 0x01: 1M PHY
- 0x02: 2M PHY
- 0x04: 125k Coded PHY (S=8)
- 0x08: 500k Coded PHY (S=2)
|
Response Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint16 |
result |
Result code
- 0: success
- Non-zero: an error has occurred
For other values see Error codes
|
Events generated
le_connection_set_preferred_phy
Sets preferred and accepted PHYs for the given connection. Event
le_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.
C API
/* Function */
struct gecko_msg_le_connection_set_preferred_phy_rsp_t *gecko_cmd_le_connection_set_preferred_phy(uint8 connection, uint8 preferred_phy, uint8 accepted_phy);
/* Response id */
gecko_rsp_le_connection_set_preferred_phy_id
/* Response structure */
struct gecko_msg_le_connection_set_preferred_phy_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint8 |
connection |
Connection handle |
uint8 |
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)
|
uint8 |
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)
|
Response Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint16 |
result |
Result code
- 0: success
- Non-zero: an error has occurred
For other values see Error codes
|
Events generated
le_connection_set_timing_parameters
Request a change in the connection parameters of a Bluetooth connection.
C API
/* Function */
struct gecko_msg_le_connection_set_timing_parameters_rsp_t *gecko_cmd_le_connection_set_timing_parameters(uint8 connection, uint16 min_interval, uint16 max_interval, uint16 latency, uint16 timeout, uint16 min_ce_length, uint16 max_ce_length);
/* Response id */
gecko_rsp_le_connection_set_timing_parameters_id
/* Response structure */
struct gecko_msg_le_connection_set_timing_parameters_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint8 |
connection |
Connection Handle |
uint16 |
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
|
uint16 |
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
|
uint16 |
latency |
Slave latency, which defines how many connection intervals the slave can skip if it has no data to sendUse 0x0000 for default value
|
uint16 |
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.
|
uint16 |
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.
|
uint16 |
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.
|
Response Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint16 |
result |
Result code
- 0: success
- Non-zero: an error has occurred
For other values see Error codes
|
Events generated
le_connection events
le_connection_opened
Indicates that a new connection was opened. This event does not indicate that the connection was established (i.e., that a data packet was received within 6 connection interval). If the connection does not get established, an le_connection_closed event may immediately follow.
This event also reports whether the connected devices are already bonded, and what the role of the Bluetooth device (Slave or Master) is. An open connection can be closed with the le_connection_close command by giving the connection handle obtained from this event.
C API
/* event id*/
gecko_evt_le_connection_opened_id
/* event structure*/
struct gecko_msg_le_connection_opened_evt_t
{
bd_addr address;
uint8 address_type;
uint8 master;
uint8 connection;
uint8 bonding;
uint8 advertiser;
}
Event Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
bd_addr |
address |
Remote device address |
uint8 |
address_type |
Remote device address type |
uint8 |
master |
Device role in connection. Values:
|
uint8 |
connection |
Handle for new connection |
uint8 |
bonding |
Bonding handle. Values:
- 0xff: No bonding
- Other: Bonding handle
|
uint8 |
advertiser |
The local advertising set that this connection was opened to. Values:
- 0xff: Invalid value or not applicable. Ignore this field
- Other: The advertising set handle
|
le_connection_closed
Indicates that a connection was closed.
C API
/* event id*/
gecko_evt_le_connection_closed_id
/* event structure*/
struct gecko_msg_le_connection_closed_evt_t
{
uint16 reason;
uint8 connection;
}
Event Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint16 |
reason |
Result code
- 0: success
- Non-zero: an error has occurred
For other values see Error codes
|
uint8 |
connection |
Handle of the closed connection |
le_connection_parameters
Triggered whenever the connection parameters are changed and at any time a connection is established.
C API
/* event id*/
gecko_evt_le_connection_parameters_id
/* event structure*/
struct gecko_msg_le_connection_parameters_evt_t
{
uint8 connection;
uint16 interval;
uint16 latency;
uint16 timeout;
uint8 security_mode;
uint16 txsize;
}
Event Parameters (for BGAPI headers refer to link)
Type |
Name |
Description |
uint8 |
connection |
Connection handle |
uint16 |
interval |
Connection interval. Time = Value x 1.25 ms |
uint16 |
latency |
Slave latency (how many connection intervals the slave can skip) |
uint16 |
timeout |
Supervision timeout. Time = Value x 10 ms |
uint8 |
security_mode |
Connection security mode |
uint16 |
txsize |
Maximum Data Channel PDU Payload size that the controller can send in an air packet |
le_connection_phy_status
Indicates that PHY update procedure is completed.
C API
/* event id*/
gecko_evt_le_connection_phy_status_id
/* event structure*/
struct gecko_msg_le_connection_phy_status_evt_t
{
uint8 connection;
uint8 phy;
}
Event Parameters (for BGAPI headers refer to link)
le_connection enumerations
le_connection_security
Indicate the Bluetooth Security Mode.
Enumerations
Value |
Name |
Description |
0 |
le_connection_mode1_level1 |
No security |
1 |
le_connection_mode1_level2 |
Unauthenticated pairing with encryption |
2 |
le_connection_mode1_level3 |
Authenticated pairing with encryption |
3 |
le_connection_mode1_level4 |
Authenticated Secure Connections pairing with encryption using a 128-bit strength encryption key |