tools/hci_throughput: updated README.md file, help descriptions

tools/hci_throughput/README.md

@@ -13,9 +13,9 @@ sudo pip install -r requirements.txt
 
 ## Usage
 ### Prepare devices
-This tool may be used with existing controller or with any board with ```blehci``` app.
+This tool may be used with the existing controller or with any board with ```blehci``` app.
 
-  - If you want to use builtin PC controller, provide HCI index of the controller. Turn the Bluetooth ON on your device, run ```hciconfig``` in the terminal and get the HCI index. In the case below HCI index is equal to 0:
+  - If you want to use the builtin PC controller, provide HCI index of the controller. Turn the Bluetooth ON on your device, run ```hciconfig``` in the terminal and get the HCI index. In the case below HCI index is equal to 0:
 
 ```
 user@user:~$ hciconfig
@@ -27,21 +27,26 @@ hci0:	Type: Primary  Bus: USB
 ```
 
   - If you want to use the nimble controller, create the image and load the provided target (can be found under ```/targets``` for NRF52840 and NRF52832). 
-    - NRF52840 may use USB or UART transport. The target is configured for USB by default.
-    - NRF52832 uses UART as transport. This requires some additional configuration. Get the tty path and run in the terminal:
+    - NRF52840 may use USB or UART as HCI transport. The target is configured for USB by default.
+    - NRF52832 uses UART as HCI transport. This requires some additional configuration. Get the tty path and run in the terminal:
     ```
     sudo btattach -B /dev/ttyACM0 -S 1000000
     ```
     Then proceed with ```hciconfig``` as shown above.
 
 ### Run tests
-This tool opens a raw socket which requires running all scripts as ```sudo```. Copy the ```config.yaml.sample``` file, change the name to ```config.yaml``` and fill the parameters. Run ```main.py``` as shown below:
+
+
+This tool opens a raw socket which requires running all scripts as ```sudo```. Copy the ```config.yaml.sample``` file, change the name to ```config.yaml``` and fill the parameters. 
+Optionally pass the path to the custom transport directory if used. Run ```main.py``` as shown below:
 ```
-sudo python main.py -i <hci_idx_1> <hci_idx_2> -m rx tx -cf config.yaml
+sudo python main.py -i <hci_idx_1> <hci_idx_2> -m rx tx -t <path/to/custom_transport_directory> -cf config.yaml
 ```
-Switch ```<hci_idx_1>``` and ```<hci_idx_2>``` to corresponding hci indexes present in your computer. ```-m``` and ```-cf``` may be omitted if the defaults are correct. \
+Switch ```<hci_idx_1>``` and ```<hci_idx_2>``` to corresponding hci indexes present in your computer. ```-m```, ```-t``` and ```-cf``` may be omitted if the defaults are correct. \
 The output provides the plots of measured throughput in ```kb``` or ```kB``` as predefined in ```config.yaml```. In addition to the throughput plots, when the ```flag_plot_packets``` is turned on, the number of packets transmitted/received in time is visualized.
 
+**_When encountering issues with running tests, try to investigate the files in the log folder._**
+
 #### Set ```config.yaml``` file
 To run **once** the throughput measurement with given parameters, set the ```flag_testing``` to false.
 ```
@@ -93,9 +98,9 @@ sudo python hci_device.py -m tx -if init.yaml
 ```
 
 ### Check addr sub-tool
-When given hci indexes, ```check_addr.py``` returns devices' address types and addresses.
+When given hci indexes, ```check_addr.py``` returns devices' address types and addresses. Optionally pass the path to the custom transport directory if used.
 ```
-sudo python check_addr.py -i <hci_idx_1> <hci_idx_2> ... <hci_idx_N>
+sudo python check_addr.py -i <hci_idx_1> <hci_idx_2> ... <hci_idx_N> -t <path/to/custom_transport_directory>
 ```
 
 ### Throughput sub-tool

tools/hci_throughput/check_addr.py

@@ -32,16 +32,14 @@ def parse_arguments():
     parser = argparse.ArgumentParser(
         description='Check HCI device address type and address',
         epilog='How to run script: \
-                sudo python check_addr.py -i 0 1 2')
+                sudo python check_addr.py -i 0 1 2 \
+                -t path/to/custom_transport_dir')
     parser.add_argument('-i', '--indexes', type=str, nargs='*',
                         help='specify hci adapters indexes', default=0)
-    parser.add_argument(
-        '-t',
-        '--transport_directory',
-        type=str,
-        nargs='*',
-        help='specify hci transport directory path',
-        default="default")
+    parser.add_argument('-t', '--transport_directory', type=str, nargs='*',
+                        help='specify hci transport directory path. \
+                        Use for transport other than the default linux socket.',
+                        default=["default"])
     try:
         args = parser.parse_args()
         if (isinstance(args.transport_directory, list)):

tools/hci_throughput/config.yaml.sample

@@ -43,7 +43,7 @@ adv:
   peer_address: 00:00:00:00:00:00
   advertising_channel_map: 7
   advertising_filter_policy: 0
-enable_encryption: true
+enable_encryption: false
 conn:
   le_scan_interval: 2400
   le_scan_window: 2400

tools/hci_throughput/hci_device.py

@@ -44,13 +44,13 @@ class ParentCalledException(KeyboardInterrupt):
 
 def parse_arguments():
     parser = argparse.ArgumentParser(
-        description='HCI device with User Channel Socket',
-        epilog='Start a device according to predefined mode (receiver/transmitter). \
+        description='HCI device with User Channel Socket. \
+                Start a device according to predefined mode (receiver/transmitter). \
                 The initialization of the device is based on received parameters \
                 or predefined init.yaml and config.yaml files.\
                 The tx device will try to connect to rx device and send data. \
-                After completion the throughput plots will pop up. \
-                How to run the python scripts, first specifying all params: \
+                After completion the throughput plots will pop up. ',
+        epilog='How to run the python script: \
                     sudo python hci_device.py -m rx -oa 00:00:00:00:00:00 -oat 0 -di 0 \
                         -pa 00:00:00:00:00:00 -pat 0 -pdi 0 -cf config.yaml\
                 or, if present, specifying init.yaml file \

tools/hci_throughput/init.yaml.sample

@@ -32,3 +32,5 @@ tx:
   peer_address_type: 1
   peer_address: C0:0D:A5:1A:98:EF
 test_dir: /path/to/blehci_throughput/tests/Mon_May_23_12:29:10_2022
+transport_directory: default or /path/to/custom_transport.py
+ltk: '0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

tools/hci_throughput/main.py

@@ -36,10 +36,10 @@ PROCESS_TIMEOUT = 500  # seconds, adjust if necessary
 
 def parse_arguments():
     parser = argparse.ArgumentParser(
-        description='Measure throughput',
-        epilog='How to run python scripts: \
-                    sudo python main.py -i 0 1 -m rx tx -cf config.yaml\
-                then hci0 -> rx and hci1 -> tx')
+        description='App for measuring BLE throughput over ACL.',
+        epilog='How to run python script for hci0 -> rx and hci1 -> tx: \
+                sudo python main.py -i 0 1 -m rx tx \
+                -t path/to/custom_transport_directory -cf config.yaml')
     parser.add_argument('-i', '--indexes', type=str, nargs='*',
                         help='specify adapters indexes', default=[0, 1])
     parser.add_argument('-m', '--modes', type=str, nargs="*",
@@ -47,7 +47,8 @@ def parse_arguments():
                         choices=['rx', 'tx'], default=['rx', 'tx'])
     parser.add_argument('-t', '--transport_directory', type=str, nargs='*',
                         help='specify hci transport directory path. \
-                        The default is linux socket', default=["default"])
+                        Use for transport other than the default linux socket.',
+                        default=["default"])
     parser.add_argument('-cf', '--config_file', type=str, nargs="*",
                         help='configuration file for devices',
                         default=["config.yaml"])