bartoszek/zephyr
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ff36d10333
zephyr/samples/bluetooth/iso_connected_benchmark
History
Rubin Gerritsen a4e43d013c Bluetooth: Samples: Use string printing functions for error codes 
When developing Bluetooth applications, you typically run into some errors.
If you are an experienced Bluetooth developer, you would typically know
how to translate the error codes into string representations.
Others might not.

This commit to adds string printing of error codes for all
samples to make them more user-friendly.

Several formatting alternatives were considered. The chosen alternative
balances code readability and FLASH size (with and without string
printing).

Example output from the peripheral_hids sample when the
peer rejects pairing:

```
Bluetooth initialized
Bluetooth authentication callbacks registered.
Advertising successfully started
Connected 5E:67:02:D3:1C:DB (random)
Security failed: 5E:67:02:D3:1C:DB (random) \
level 1 err 6 BT_SECURITY_ERR_PAIR_NOT_ALLOWED
Disconnected from 5E:67:02:D3:1C:DB (random), \
reason 0x13 BT_HCI_ERR_REMOTE_USER_TERM_CONN
```

Other alternatives that were considered:

- Use of parantheses:
```
// strings enabled
Security failed: 5E:67:02:D3:1C:DB (random) level 1 \
err BT_SECURITY_ERR_PAIR_NOT_ALLOWED(6)
Disconnected from 5E:67:02:D3:1C:DB (random), reason \
BT_HCI_ERR_REMOTE_USER_TERM_CONN(0x13)
// strings disabled
Security failed: 5E:67:02:D3:1C:DB (random) level 1 err (6)
Disconnected from 5E:67:02:D3:1C:DB (random), reason (0x13)
```

- Spaces and parantheses:
```
// strings enabled
Security failed: 5E:67:02:D3:1C:DB (random) level 1 \
err BT_SECURITY_ERR_PAIR_NOT_ALLOWED (6)
Disconnected from 5E:67:02:D3:1C:DB (random), \
reason BT_HCI_ERR_REMOTE_USER_TERM_CONN (0x13)
// strings disabled
Security failed: 5E:67:02:D3:1C:DB (random) level 1 err  (6)
Disconnected from 5E:67:02:D3:1C:DB (random), reason  (0x13)
```

- Parantheses around everything:
```
// strings enabled
Security failed: 5E:67:02:D3:1C:DB (random) level 1 \
err (BT_SECURITY_ERR_PAIR_NOT_ALLOWED(6))
Disconnected from 5E:67:02:D3:1C:DB (random), \
reason (BT_HCI_ERR_REMOTE_USER_TERM_CONN(0x13))
// strings disabled
Security failed: 5E:67:02:D3:1C:DB (random) level 1 err ((6))
Disconnected from 5E:67:02:D3:1C:DB (random), reason ((0x13))
```

- Error code first, then string representation:
```
// strings enabled
Security failed: 5E:67:02:D3:1C:DB (random) level 1 \
err 6 (BT_SECURITY_ERR_PAIR_NOT_ALLOWED)
Disconnected from 5E:67:02:D3:1C:DB (random), reason \
0x13 (BT_HCI_ERR_REMOTE_USER_TERM_CONN)
// strings disabled
Security failed: 5E:67:02:D3:1C:DB (random) level 1 err 6 ()
Disconnected from 5E:67:02:D3:1C:DB (random), reason 0x13 ()
```

- Apostrophes around error printing:
```
// strings enabled
Security failed: 5E:67:02:D3:1C:DB (random) level 1 \
err "BT_SECURITY_ERR_PAIR_NOT_ALLOWED (6)"
Disconnected from 5E:67:02:D3:1C:DB (random), reason \
"BT_HCI_ERR_REMOTE_USER_TERM_CONN (0x13)"
// strings disabled
Security failed: 5E:67:02:D3:1C:DB (random) level 1 err " (6)"
Disconnected from 5E:67:02:D3:1C:DB (random), reason " (0x13)"
```

Signed-off-by: Rubin Gerritsen <rubin.gerritsen@nordicsemi.no>
2024-07-31 12:56:11 +02:00
..
src Bluetooth: Samples: Use string printing functions for error codes 2024-07-31 12:56:11 +02:00
CMakeLists.txt
prj.conf Bluetooth: ISO: Add Kconfig for ISO central/peripheral 2022-05-13 12:44:47 -07:00
README.rst Bluetooth: Samples: Add controller Kconfig requirement for ISO samples 2022-01-26 13:29:45 +01:00
sample.yaml hwmv2: Introduce Hardware model version 2 and convert devices 2024-03-02 16:56:33 -05:00

README.rst 

.. _iso_connected_benchmark:

Bluetooth: Throughput
#####################

The ISO Connected Channels Benchmark sample measures and reports packet loss
and sync loss in connected ISO channels.


Overview
********

The sample transmits data between the *central* and the *peripheral*
and measures the quality of the ISO channels.

The application can be used as both a central and a peripheral, and the mode
can easily be changed.

Requirements
************

* BlueZ running on the host, or
* A board with Bluetooth Low Energy 5.2 support
* A Bluetooth Controller and board that supports setting
  CONFIG_BT_CTLR_CENTRAL_ISO=y
* A remote board running the same sample as the reversed role that supports
  setting CONFIG_BT_CTLR_PERIPHERAL_ISO=y

Building and running
********************

This sample can be found under
:zephyr_file:`samples/bluetooth/iso_connected_benchmark` in the Zephyr tree.

See :ref:`bluetooth samples section <bluetooth-samples>` for details.


Testing
=======

After programming the sample to both boards, test it by performing the following
steps:

1. Connect to both boards with a terminal emulator (for example, PuTTY or
   minicom).
#. Reset both boards.
#. In one of the terminal emulators, type "c" to start the application on the
   connected board in the central role.
#. In the other terminal emulator, type "p" to start the application in the
   peripheral role.
#. Optionally modify the central ISO settings using the console.
#. Observe that the central and the peripheral connects.
#. Observe the receive statistics on the devices (the connected ISO channels may
   by uni- or bidirectional).

Sample output
==============
The peripheral will output overall data (since boot),
current connection (since the CIG was connected) and latest 1000 received
packets::

  *** Booting Zephyr OS build zephyr-v2.5.0-4098-gdcaaee6db2f5  ***
   [00:00:00.392,333] <inf> iso_connected: Starting Bluetooth Throughput example
   [00:00:00.405,395] <inf> iso_connected: Bluetooth initialized
   Choose device role - type c (central role) or p (peripheral role), or q to quit: p
   Peripheral role
   [00:00:10.281,555] <inf> iso_connected: Registering ISO server
   [00:00:10.281,555] <inf> iso_connected: Starting advertising
   [00:00:10.282,684] <inf> iso_connected: Waiting for ACL connection
   [00:00:16.711,517] <inf> iso_connected: Connected: FA:4C:4B:DB:D3:89 (public)
   [00:00:16.711,669] <inf> iso_connected: Waiting for ISO connection
   [00:00:16.802,856] <inf> iso_connected: Incoming ISO request
   [00:00:16.802,856] <inf> iso_connected: Returning instance 0
   [00:00:17.016,845] <inf> iso_connected: ISO Channel 0x20002934 connected
   [00:00:17.769,439] <inf> iso_connected: Sending value 100
   [00:00:17.774,902] <inf> iso_connected: Overall     : Received 100/100 (100.00%) - Total packets lost 0
   [00:00:17.774,932] <inf> iso_connected: Current Conn: Received 100/100 (100.00%) - Total packets lost 0
   [00:00:17.774,963] <inf> iso_connected: Latest 1000 : Received 100/100 (100.00%) - Total packets lost 0
   [00:00:17.774,963] <inf> iso_connected:
   [00:00:18.529,510] <inf> iso_connected: Sending value 200
   [00:00:18.532,409] <inf> iso_connected: Overall     : Received 200/200 (100.00%) - Total packets lost 0
   [00:00:18.532,470] <inf> iso_connected: Current Conn: Received 200/200 (100.00%) - Total packets lost 0
   [00:00:18.532,501] <inf> iso_connected: Latest 1000 : Received 200/200 (100.00%) - Total packets lost 0


The central will ask if any changes to the current settings are wanted.
If y/Y is chosen, then it will create a prompt to changes the settings,
otherwise continue with the current settings. The central will then start
scanning for and connecting to a peer device running the sample as peripheral
role. Once connected, the central will output overall data (since boot),
current connection (since the CIG was connected) and latest 1000 received
packets::

   *** Booting Zephyr OS build zephyr-v2.5.0-4098-gdcaaee6db2f5  ***
   [00:00:00.459,869] <inf> iso_connected: Starting Bluetooth Throughput example
   [00:00:00.472,961] <inf> iso_connected: Bluetooth initialized
   Choose device role - type c (central role) or p (peripheral role), or q to quit: c
   Central role
   Change ISO settings (y/N)?
   [00:00:03.277,893] <inf> iso_connected: Scan started
   [00:00:03.277,893] <inf> iso_connected: Waiting for advertiser
   [00:00:03.899,963] <inf> iso_connected: Found peripheral with address F4:5A:12:BF:4F:2C (public) (RSSI -24)
   [00:00:03.900,024] <inf> iso_connected: Stopping scan
   [00:00:03.908,020] <inf> iso_connected: Scan stopped
   [00:00:03.908,020] <inf> iso_connected: Connecting
   [00:00:04.007,232] <inf> iso_connected: Connected: F4:5A:12:BF:4F:2C (public)
   [00:00:04.007,354] <inf> iso_connected: Binding ISO
   [00:00:04.007,812] <inf> iso_connected: Connecting ISO channels
   [00:00:04.312,744] <inf> iso_connected: ISO Channel 0x20002934 connected
   [00:00:05.065,368] <inf> iso_connected: Sending value 100
   [00:00:05.072,052] <inf> iso_connected: Overall     : Received 100/100 (100.00%) - Total packets lost 0
   [00:00:05.072,113] <inf> iso_connected: Current Conn: Received 100/100 (100.00%) - Total packets lost 0
   [00:00:05.072,143] <inf> iso_connected: Latest 1000 : Received 100/100 (100.00%) - Total packets lost 0
   [00:00:05.072,143] <inf> iso_connected:
   [00:00:05.825,439] <inf> iso_connected: Sending value 200
   [00:00:05.829,589] <inf> iso_connected: Overall     : Received 200/200 (100.00%) - Total packets lost 0
   [00:00:05.829,620] <inf> iso_connected: Current Conn: Received 200/200 (100.00%) - Total packets lost 0
   [00:00:05.829,650] <inf> iso_connected: Latest 1000 : Received 200/200 (100.00%) - Total packets lost 0