diff --git a/tools/hci_throughput/README.md b/tools/hci_throughput/README.md index aa6652f1f..1e153928a 100644 --- a/tools/hci_throughput/README.md +++ b/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 -m rx tx -cf config.yaml +sudo python main.py -i -m rx tx -t -cf config.yaml ``` -Switch `````` and `````` to corresponding hci indexes present in your computer. ```-m``` and ```-cf``` may be omitted if the defaults are correct. \ +Switch `````` and `````` 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 ... +sudo python check_addr.py -i ... -t ``` ### Throughput sub-tool diff --git a/tools/hci_throughput/check_addr.py b/tools/hci_throughput/check_addr.py index 456913188..ce2a94465 100644 --- a/tools/hci_throughput/check_addr.py +++ b/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)): diff --git a/tools/hci_throughput/config.yaml.sample b/tools/hci_throughput/config.yaml.sample index 68068e3e7..6d5dcbcf8 100644 --- a/tools/hci_throughput/config.yaml.sample +++ b/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 diff --git a/tools/hci_throughput/hci_device.py b/tools/hci_throughput/hci_device.py index b054b7050..b634d5493 100644 --- a/tools/hci_throughput/hci_device.py +++ b/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 \ diff --git a/tools/hci_throughput/init.yaml.sample b/tools/hci_throughput/init.yaml.sample index ec1752276..f097d9cf2 100644 --- a/tools/hci_throughput/init.yaml.sample +++ b/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' \ No newline at end of file diff --git a/tools/hci_throughput/main.py b/tools/hci_throughput/main.py index 565cce426..1f9d6e151 100644 --- a/tools/hci_throughput/main.py +++ b/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"])