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

This command can be used to 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.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x01 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x04 method Message ID
4 uint8 connection Handle of the connection to be closed

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x04 method Message ID
4-5 uint16 result Result code
  • 0: success
  • Non-zero: an error occurred
For other values refer to the Error codes

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
}

Events generated

Event Description
le_connection_closed

le_connection_disable_slave_latency

This command temporarily enables or disables slave latency. Used only when Bluetooth device is in slave role.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x02 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x02 method Message ID
4 uint8 connection Connection Handle
5 uint8 disable 0 enable, 1 disable slave latency

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x02 method Message ID
4-5 uint16 result Result code
  • 0: success
  • Non-zero: an error occurred
For other values refer to the Error codes

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
}

le_connection_get_rssi

This command can be used to get the latest RSSI value of a Bluetooth connection.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x01 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x01 method Message ID
4 uint8 connection Connection handle

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x01 method Message ID
4-5 uint16 result Result code
  • 0: success
  • Non-zero: an error occurred
For other values refer to the Error codes

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
}

Events generated

Event Description
le_connection_rssi Triggered when this command has completed.

le_connection_set_parameters

Deprecated. Replacement is le_connection_set_timing_parameters command for setting timing parameters.

This command can be used to request a change in the connection parameters of a Bluetooth connection.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x09 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x00 method Message ID
4 uint8 connection Connection Handle
5-6 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
7-8 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
9-10 uint16 latency Slave latency. This parameter 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
11-12 uint16 timeout Supervision timeout. The supervision timeout defines for how long the connection is maintained despite the devices being unable to 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
It is recommended that the supervision timeout is set at a value which allows communication attempts over at least a few connection intervals.

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x00 method Message ID
4-5 uint16 result Result code
  • 0: success
  • Non-zero: an error occurred
For other values refer to the Error codes

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
}

Events generated

Event Description
le_connection_parameters This event is triggered after new connection parameters has been applied on the connection.

le_connection_set_phy

Deprecated. Replacement is le_connection_set_preferred_phy command.

This command can be used to set preferred PHYs for connection. Preferred PHYs are connection specific. Event le_connection_phy_status is received when PHY update procedure has been completed. Other than 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.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x02 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x03 method Message ID
4 uint8 connection
5 uint8 phy Preferred PHYs for connection. This parameter is bitfield and multiple PHYs can be preferred by setting multiple bits.
  • 0x01: 1M PHY
  • 0x02: 2M PHY
  • 0x04: 125 kbit Coded PHY (S=8)
  • 0x08: 500 kbit Coded PHY (S=2)

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x03 method Message ID
4-5 uint16 result Result code
  • 0: success
  • Non-zero: an error occurred
For other values refer to the Error codes

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
}

Events generated

Event Description
le_connection_phy_status

le_connection_set_preferred_phy

This command can be used to set preferred and accepted PHYs for the given connection. Event le_connection_phy_status is received when PHY update procedure has been completed. Other than preferred PHY can also be set if remote device does not accept any of the preferred PHYs.

Parameter accepted_phy is used for specifying the PHYs the stack can accept in a remote initiated PHY update request. No PHY update will happen if none of the accepted PHYs presents in the request.

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

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x03 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x07 method Message ID
4 uint8 connection Connection handle
5 uint8 preferred_phy Preferred PHYs. This parameter is bitfield and multiple PHYs can be set.
  • 0x01: 1M PHY
  • 0x02: 2M PHY
  • 0x04: 125 kbit Coded PHY (S=8)
  • 0x08: 500 kbit Coded PHY (S=2)
6 uint8 accepted_phy Accepted PHYs in remote initiated PHY update requests. This parameter is bitfield and multiple PHYs can be set.
  • 0x01: 1M PHY
  • 0x02: 2M PHY
  • 0x04: Coded PHY
  • 0x04: 125 kbit Coded PHY (S=8)
  • 0x08: 500 kbit Coded PHY (S=2)
  • 0xff: Any PHYs

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x07 method Message ID
4-5 uint16 result Result code
  • 0: success
  • Non-zero: an error occurred
For other values refer to the Error codes

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
}

Events generated

Event Description
le_connection_phy_status

le_connection_set_timing_parameters

This command can be used to request a change in the connection parameters of a Bluetooth connection.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x0d lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x05 method Message ID
4 uint8 connection Connection Handle
5-6 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
7-8 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
9-10 uint16 latency Slave latency. This parameter 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
11-12 uint16 timeout Supervision timeout. The supervision timeout defines for how long the connection is maintained despite the devices being unable to 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
It is recommended that the supervision timeout is set at a value which allows communication attempts over at least a few connection intervals.
13-14 uint16 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
Value is not currently used and is reserved for future. It should be set to 0.
15-16 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

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x05 method Message ID
4-5 uint16 result Result code
  • 0: success
  • Non-zero: an error occurred
For other values refer to the Error codes

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
}

Events generated

Event Description
le_connection_parameters This event is triggered after new connection parameters has been applied on the connection.

le_connection events

le_connection_opened

This event indicates that a new connection was opened, whether the devices are already bonded, and what is the role of the Bluetooth device (Slave or Master). An open connection can be closed with the le_connection_close command by giving the connection handle ID obtained from this event.

Event

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x0b lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x00 method Message ID
4-9 bd_addr address Remote device address
10 uint8 address_type Remote device address type
11 uint8 master Device role in connection. Values:
  • 0: Slave
  • 1: Master
12 uint8 connection Handle for new connection
13 uint8 bonding Bonding handle. Values:
  • 0xff: No bonding
  • Other: Bonding handle
14 uint8 advertiser The local advertising set this connection was opened to. Values:
  • 0xff: Invalid value or not applicable, and this field should be ignored
  • Other: The advertising set handle

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
}

le_connection_closed

This event indicates that a connection was closed.

Event

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x03 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x01 method Message ID
4-5 uint16 reason Result code
  • 0: success
  • Non-zero: an error occurred
For other values refer to the Error codes
6 uint8 connection Handle of the closed connection

API

/* event id*/
gecko_evt_le_connection_closed_id

/* event structure*/
struct gecko_msg_le_connection_closed_evt_t
{
  uint16 reason,
  uint8 connection
}

le_connection_parameters

This event is triggered whenever the connection parameters are changed and at any time a connection is established.

Event

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x0a lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x02 method Message ID
4 uint8 connection Connection handle
5-6 uint16 interval Connection interval
7-8 uint16 latency Slave latency
9-10 uint16 timeout Supervision timeout
11 uint8 security_mode Connection security mode
12-13 uint16 txsize Maximum Data Channel PDU Payload size the controller can send in an air packet

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
}

le_connection_rssi

This event is triggered when an le_connection_get_rssi command has completed.

Event

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x03 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x03 method Message ID
4 uint8 connection Connection handle
5 uint8 status Command complete status:
  • 0x00: The command succeeded
  • 0x01-0xFF: The command failed. See Bluetooth Core specification v5.0 [Vol 2] Part D, Error Codes
6 int8 rssi RSSI in the latest received packet of the connection. Units: dBm. Range: -127 to +20. This parameter should be ignored if the command failed.

API

/* event id*/
gecko_evt_le_connection_rssi_id

/* event structure*/
struct gecko_msg_le_connection_rssi_evt_t
{
  uint8 connection,
  uint8 status,
  int8 rssi
}

le_connection_phy_status

This event indicates that PHY update procedure has been completed.

Event

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x02 lolen Minimum payload length
2 0x08 class Message class:Connection management
3 0x04 method Message ID
4 uint8 connection Connection handle
5 uint8 phy Current active PHY. See values from le_connection_set_phy command.

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
}

le_connection enumerations

le_connection_security

These values 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