Throughput Test Receiver (Central) Role API#

Throughput Test Receiver (Central) Role API opens connection to Throughput Test Transmitter (Peripheral) Role nodes, registers to notifications or indications. Throughput parameters can be managed using the API calls or via CLI. The API provides interface for configuring, starting and stopping transmission. Status and result callbacks can be also registered using the API.

Modules#

throughput_central_characteristic_t

throughput_central_characteristic_found_t

Functions#

bool
sl_status_t
throughput_central_set_mode(throughput_mode_t mode, uint32_t amount)
sl_status_t
sl_status_t
throughput_central_set_tx_power(throughput_tx_power_t tx_power, bool power_control, bool deep_sleep)
sl_status_t
throughput_central_set_connection_parameters(throughput_time_t min_interval, throughput_time_t max_interval, throughput_time_t latency, throughput_time_t timeout)
sl_status_t
throughput_central_set_type(throughput_notification_t type)
sl_status_t
sl_status_t
sl_status_t
throughput_central_set_scan_phy(throughput_scan_phy_t phy)
sl_status_t
void
bt_on_event_central(sl_bt_msg_t *evt)
void
throughput_central_on_role_set(throughput_role_t role)
void
throughput_central_on_state_change(throughput_state_t state)
void
throughput_central_on_mode_change(throughput_mode_t mode)
void
throughput_central_on_finish(throughput_value_t throughput, throughput_count_t count, throughput_count_t lost, throughput_count_t error, throughput_time_t time)
void
throughput_central_on_transmit_power_change(throughput_tx_power_t power)
void
throughput_central_on_rssi_change(throughput_rssi_t rssi)
void
throughput_central_on_phy_change(throughput_phy_t phy)
void
throughput_central_on_notification_change(throughput_notification_t notification)
void
throughput_central_on_indication_change(throughput_notification_t indication)
void
throughput_central_on_result_indication_change(throughput_notification_t result)
void
throughput_central_on_data_size_change(throughput_pdu_size_t data_size)
void
throughput_central_on_connection_settings_change(throughput_pdu_size_t pdu, throughput_mtu_size_t mtu)
void
throughput_central_on_connection_timings_change(throughput_time_t interval, throughput_time_t latency, throughput_time_t timeout)
void
throughput_central_on_characteristics_found(throughput_central_characteristic_found_t characteristics)
void
throughput_central_on_discovery_state_change(throughput_discovery_state_t state)
float
throughput_central_calculate(throughput_value_t *throughput)
bool
throughput_central_decode_address(char *addess_str, uint8_t *address)
float

Function Documentation#

throughput_central_allowlist_add#

bool throughput_central_allowlist_add (uint8_t * address)
Parameters
[in]address

BT address in 6 byte format

Add an address to the allowlist. Returns

  • true if adding the address was successful


Definition at line 81 of file common/throughput_central/throughput_central.h

throughput_central_allowlist_clear#

bool throughput_central_allowlist_clear (void )
Parameters
N/A

Clear the allowlist Returns

  • true if adding the clear was succesful


Definition at line 87 of file common/throughput_central/throughput_central.h

throughput_central_enable#

void throughput_central_enable (void )
Parameters
N/A

Enable receiver.


Definition at line 92 of file common/throughput_central/throughput_central.h

throughput_central_disable#

sl_status_t throughput_central_disable (void )
Parameters
N/A

Disable receiver.


Definition at line 97 of file common/throughput_central/throughput_central.h

throughput_central_set_mode#

sl_status_t throughput_central_set_mode (throughput_mode_t mode, uint32_t amount)
Parameters
[in]mode

the transmission mode is either of:

  • THROUGHPUT_MODE_CONTINUOUS: transfer until stop

  • THROUGHPUT_MODE_FIXED_TIME: transfer data for a fixed time

  • THROUGHPUT_MODE_FIXED_LENGTH: a fixed amount of data to transfer

[in]amount

the time in ms or data in bytes to transfer

Set receiver mode. Returns

  • status of the operation


Definition at line 108 of file common/throughput_central/throughput_central.h

throughput_central_set_mtu_size#

sl_status_t throughput_central_set_mtu_size (uint8_t mtu)
Parameters
[in]mtu

MTU size in bytes

Set data sizes for reception. Returns

  • status of the operation


Definition at line 116 of file common/throughput_central/throughput_central.h

throughput_central_set_tx_power#

sl_status_t throughput_central_set_tx_power (throughput_tx_power_t tx_power, bool power_control, bool deep_sleep)
Parameters
[in]tx_power

requested tx power in dBm

[in]power_control

enable adaptive power control

[in]deep_sleep

enable deep sleep during test

Set transmission power. Returns

  • status of the operation


Definition at line 125 of file common/throughput_central/throughput_central.h

throughput_central_set_connection_parameters#

sl_status_t throughput_central_set_connection_parameters (throughput_time_t min_interval, throughput_time_t max_interval, throughput_time_t latency, throughput_time_t timeout)
Parameters
[in]min_interval

Minimum connection interval (in 1.25 ms steps)

[in]max_interval

Maximum connection interval (in 1.25 ms steps)

[in]latency

Responder latency (in connection intervals)

[in]timeout

Supervision timeout (in 10 ms steps)

Set connection parameters. Returns

  • status of the operation


Definition at line 137 of file common/throughput_central/throughput_central.h

throughput_central_set_type#

sl_status_t throughput_central_set_type (throughput_notification_t type)
Parameters
[in]type

type of the test (notification or indication)

Set type of transmission. Returns

  • status of the operation


Definition at line 147 of file common/throughput_central/throughput_central.h

throughput_central_start#

sl_status_t throughput_central_start (void )
Parameters
N/A

Start transmission on remote side. Returns

  • status of the operation


Definition at line 153 of file common/throughput_central/throughput_central.h

throughput_central_stop#

sl_status_t throughput_central_stop (void )
Parameters
N/A

Stop transmission on remote side. Returns

  • status of the operation


Definition at line 159 of file common/throughput_central/throughput_central.h

throughput_central_set_scan_phy#

sl_status_t throughput_central_set_scan_phy (throughput_scan_phy_t phy)
Parameters
[in]phy

PHY used for scanning

Set PHY used for scanning. Returns

  • status of the operation


Definition at line 166 of file common/throughput_central/throughput_central.h

throughput_central_set_connection_phy#

sl_status_t throughput_central_set_connection_phy (throughput_phy_t phy)
Parameters
[in]phy

PHY used for the connection

Set PHY used for connection. Returns

  • status of the operation


Definition at line 173 of file common/throughput_central/throughput_central.h

throughput_central_change_phy#

sl_status_t throughput_central_change_phy (void )
Parameters
N/A

Change PHY to next one.

  • In case of scanning, it is used for changing between CODED and 1M PHY

  • In a connection, it is used to change between 1M, 2M and CODED PHYs Returns

    • status of the operation


Definition at line 181 of file common/throughput_central/throughput_central.h

throughput_central_step#

void throughput_central_step (void )
Parameters
N/A

Process step for throughput central.


Definition at line 186 of file common/throughput_central/throughput_central.h

bt_on_event_central#

void bt_on_event_central (sl_bt_msg_t * evt)
Parameters
[in]evt

Event coming from the Bluetooth stack.

Bluetooth stack event handler.


Definition at line 192 of file common/throughput_central/throughput_central.h

throughput_central_on_role_set#

void throughput_central_on_role_set (throughput_role_t role)
Parameters
[in]role

the role can be only THROUGHPUT_ROLE_PERIPHERAL

Callback to handle role settings. Note

  • To be implemented in user code.


Definition at line 219 of file common/throughput_central/throughput_central.h

throughput_central_on_state_change#

void throughput_central_on_state_change (throughput_state_t state)
Parameters
[in]state

current state

Callback to handle state change. Note

  • To be implemented in user code.


Definition at line 226 of file common/throughput_central/throughput_central.h

throughput_central_on_mode_change#

void throughput_central_on_mode_change (throughput_mode_t mode)
Parameters
[in]mode

current mode

Callback to handle mode change. Note

  • To be implemented in user code.


Definition at line 233 of file common/throughput_central/throughput_central.h

throughput_central_on_start#

void throughput_central_on_start (void )
Parameters
N/A

Callback to handle transmission start event. Note

  • To be implemented in user code.


Definition at line 239 of file common/throughput_central/throughput_central.h

throughput_central_on_finish#

void throughput_central_on_finish (throughput_value_t throughput, throughput_count_t count, throughput_count_t lost, throughput_count_t error, throughput_time_t time)
Parameters
[in]throughput

throughput value in bits/second (bps)

[in]count

data volume transmitted, in bytes

[in]lost

number of packets lost

[in]error

number of wrong packets

[in]time

total measurement time

Callback to handle transmission finished event. Note

  • To be implemented in user code.


Definition at line 250 of file common/throughput_central/throughput_central.h

throughput_central_on_transmit_power_change#

void throughput_central_on_transmit_power_change (throughput_tx_power_t power)
Parameters
[in]power

tx power in dBm

Callback to handle tx power changed event. Note

  • To be implemented in user code.


Definition at line 261 of file common/throughput_central/throughput_central.h

throughput_central_on_rssi_change#

void throughput_central_on_rssi_change (throughput_rssi_t rssi)
Parameters
[in]rssi

RSSI value

Callback to handle RSSI changed event. Note

  • To be implemented in user code.


Definition at line 268 of file common/throughput_central/throughput_central.h

throughput_central_on_phy_change#

void throughput_central_on_phy_change (throughput_phy_t phy)
Parameters
[in]phy

PHY that is in use

Callback to handle phy changed event. Note

  • To be implemented in user code.


Definition at line 275 of file common/throughput_central/throughput_central.h

throughput_central_on_notification_change#

void throughput_central_on_notification_change (throughput_notification_t notification)
Parameters
[in]notification

notification status

Callback to handle notification changed event. Note

  • To be implemented in user code.


Definition at line 282 of file common/throughput_central/throughput_central.h

throughput_central_on_indication_change#

void throughput_central_on_indication_change (throughput_notification_t indication)
Parameters
[in]indication

indication status

Callback to handle indication changed event. Note

  • To be implemented in user code.


Definition at line 289 of file common/throughput_central/throughput_central.h

throughput_central_on_result_indication_change#

void throughput_central_on_result_indication_change (throughput_notification_t result)
Parameters
[in]result

result indication status

Callback to handle result indication changed event. Note

  • To be implemented in user code.


Definition at line 296 of file common/throughput_central/throughput_central.h

throughput_central_on_data_size_change#

void throughput_central_on_data_size_change (throughput_pdu_size_t data_size)
Parameters
[in]data_size

Data size in bytes

Callback to handle data size change when receiving data. Note

  • To be implemented in user code.


Definition at line 303 of file common/throughput_central/throughput_central.h

throughput_central_on_connection_settings_change#

void throughput_central_on_connection_settings_change (throughput_pdu_size_t pdu, throughput_mtu_size_t mtu)
Parameters
[in]pdu

PDU size in bytes

[in]mtu

MTU size in bytes

Callback to handle connection parameter changes. Note

  • To be implemented in user code.


Definition at line 311 of file common/throughput_central/throughput_central.h

throughput_central_on_connection_timings_change#

void throughput_central_on_connection_timings_change (throughput_time_t interval, throughput_time_t latency, throughput_time_t timeout)
Parameters
[in]interval

Connection interval (in 1.25 ms steps)

[in]latency

Responder latency (in connection intervals)

[in]timeout

Supervision timeout (in 10 ms steps)

Callback to handle connection timing changes. Note

  • To be implemented in user code.


Definition at line 321 of file common/throughput_central/throughput_central.h

throughput_central_on_characteristics_found#

void throughput_central_on_characteristics_found (throughput_central_characteristic_found_t characteristics)
Parameters
[in]characteristics

Found characteristics

Callback to handle characteristic found event. Note

  • To be implemented in user code.


Definition at line 330 of file common/throughput_central/throughput_central.h

throughput_central_on_discovery_state_change#

void throughput_central_on_discovery_state_change (throughput_discovery_state_t state)
Parameters
[in]state

State of the discovery

Callback to handle discovery state change. Note

  • To be implemented in user code.


Definition at line 338 of file common/throughput_central/throughput_central.h

throughput_central_calculate#

float throughput_central_calculate (throughput_value_t * throughput)
Parameters
[out]throughput

calculated throughput value

Calculate throughput. Returns

  • the elapsed time in seconds since measurement started


Definition at line 346 of file common/throughput_central/throughput_central.h

throughput_central_decode_address#

bool throughput_central_decode_address (char * addess_str, uint8_t * address)
Parameters
[in]addess_str

Address string

[out]address

address byte array

Convert address string to address data bytes. Returns

  • true if operation was successful


Definition at line 354 of file common/throughput_central/throughput_central.h

waiting_indication#

void waiting_indication (void )
Parameters
N/A

ASCII graphics for indicating wait status


Definition at line 45 of file common/throughput_central/throughput_central_interface.h

timer_start#

void timer_start ()

Start timer


Definition at line 50 of file common/throughput_central/throughput_central_interface.h

timer_end#

float timer_end ()

Timer end. The return value of this function shall be the time passed form the timer_start() call in seconds.


Definition at line 56 of file common/throughput_central/throughput_central_interface.h

timer_refresh_rssi_start#

void timer_refresh_rssi_start (void )
Parameters
N/A

Start RSSI refresh timer


Definition at line 61 of file common/throughput_central/throughput_central_interface.h

timer_refresh_rssi_stop#

void timer_refresh_rssi_stop (void )
Parameters
N/A

Stop RSSI refresh timer


Definition at line 66 of file common/throughput_central/throughput_central_interface.h

timer_on_refresh_rssi#

void timer_on_refresh_rssi (void )
Parameters
N/A

Event handler


Definition at line 71 of file common/throughput_central/throughput_central_interface.h

Macro Definition Documentation#

THROUGHPUT_CENTRAL_TEST_TYPE#

#define THROUGHPUT_CENTRAL_TEST_TYPE
Value:
sl_bt_gatt_notification

Definition at line 19 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_MODE_DEFAULT#

#define THROUGHPUT_CENTRAL_MODE_DEFAULT
Value:
THROUGHPUT_MODE_CONTINUOUS

Definition at line 26 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_FIXED_DATA_SIZE#

#define THROUGHPUT_CENTRAL_FIXED_DATA_SIZE
Value:
100000

Definition at line 30 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_FIXED_TIME#

#define THROUGHPUT_CENTRAL_FIXED_TIME
Value:
10000

Definition at line 34 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_MTU_SIZE#

#define THROUGHPUT_CENTRAL_MTU_SIZE
Value:
247

Definition at line 42 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_DEFAULT_SCAN_PHY#

#define THROUGHPUT_DEFAULT_SCAN_PHY
Value:
sl_bt_scanner_scan_phy_1m

Definition at line 48 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_DEFAULT_PHY#

#define THROUGHPUT_DEFAULT_PHY
Value:
sl_bt_gap_phy_coding_1m_uncoded

Definition at line 56 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_CONNECTION_INTERVAL_MIN#

#define THROUGHPUT_CENTRAL_CONNECTION_INTERVAL_MIN
Value:
32

Definition at line 64 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_CONNECTION_INTERVAL_MAX#

#define THROUGHPUT_CENTRAL_CONNECTION_INTERVAL_MAX
Value:
32

Definition at line 68 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_CONNECTION_RESPONDER_LATENCY#

#define THROUGHPUT_CENTRAL_CONNECTION_RESPONDER_LATENCY
Value:
0

Definition at line 72 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_CONNECTION_TIMEOUT#

#define THROUGHPUT_CENTRAL_CONNECTION_TIMEOUT
Value:
1000

Definition at line 76 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_TX_POWER#

#define THROUGHPUT_CENTRAL_TX_POWER
Value:
10

Definition at line 84 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_POWER_CONTROL_ENABLE#

#define THROUGHPUT_CENTRAL_POWER_CONTROL_ENABLE
Value:
0

Definition at line 88 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_SLEEP_ENABLE#

#define THROUGHPUT_CENTRAL_SLEEP_ENABLE
Value:
0

Definition at line 92 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_ALLOWLIST_ENABLE#

#define THROUGHPUT_CENTRAL_ALLOWLIST_ENABLE
Value:
0

Definition at line 98 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_1_ENABLE#

#define THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_1_ENABLE
Value:
0

Definition at line 102 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_1#

#define THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_1
Value:
"00:00:00:00:00:00"

Definition at line 106 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_2_ENABLE#

#define THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_2_ENABLE
Value:
0

Definition at line 112 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_2#

#define THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_2
Value:
"00:00:00:00:00:00"

Definition at line 116 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_3_ENABLE#

#define THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_3_ENABLE
Value:
0

Definition at line 122 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_3#

#define THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_3
Value:
"00:00:00:00:00:00"

Definition at line 126 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_4_ENABLE#

#define THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_4_ENABLE
Value:
0

Definition at line 132 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_4#

#define THROUGHPUT_CENTRAL_ALLOWLIST_SLOT_4
Value:
"00:00:00:00:00:00"

Definition at line 136 of file common/throughput_central/config/throughput_central_config.h

THROUGHPUT_CENTRAL_CHARACTERISTICS_ALL#

#define THROUGHPUT_CENTRAL_CHARACTERISTICS_ALL
Value:
0x0F

Definition at line 51 of file common/throughput_central/throughput_central.h

ADR_LEN#

#define ADR_LEN
Value:
6

Definition at line 52 of file common/throughput_central/throughput_central.h

THROUGHPUT_CENTRAL_REFRESH_TIMER_PERIOD#

#define THROUGHPUT_CENTRAL_REFRESH_TIMER_PERIOD
Value:
1000

Definition at line 40 of file common/throughput_central/throughput_central_interface.h