Examples — MAX BLE HCI 0.1.0 documentation

# Examples

Three examples are provided to demonstrate the basic functionality of the MAX BLE HCI library. The source code for these examples can be found in the `examples` directory.

## Example 1: Hello HCI

    #! /usr/bin/env python3
    ###############################################################################
    #
    #
    # Copyright (C) 2023 Maxim Integrated Products, Inc., All Rights Reserved.
    #
    # Permission is hereby granted, free of charge, to any person obtaining a
    # copy of this software and associated documentation files (the "Software"),
    # to deal in the Software without restriction, including without limitation
    # the rights to use, copy, modify, merge, publish, distribute, sublicense,
    # and/or sell copies of the Software, and to permit persons to whom the
    # Software is furnished to do so, subject to the following conditions:
    #
    # The above copyright notice and this permission notice shall be included
    # in all copies or substantial portions of the Software.
    #
    # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
    # OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    # IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
    # OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
    # ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
    # OTHER DEALINGS IN THE SOFTWARE.
    #
    # Except as contained in this notice, the name of Maxim Integrated
    # Products, Inc. shall not be used except as stated in the Maxim Integrated
    # Products, Inc. Branding Policy.
    #
    # The mere transfer of this software does not imply any licenses
    # of trade secrets, proprietary technology, copyrights, patents,
    # trademarks, maskwork rights, or any other form of intellectual
    # property whatsoever. Maxim Integrated Products, Inc. retains all
    # ownership rights.
    #
    ##############################################################################
    #
    # Copyright 2023 Analog Devices, Inc.
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.
    #
    ##############################################################################
    """
    hello_hci.py

    Description: Bare minimum example of using the BleHci class

    """
    from ble_hci import BleHci

    # Path to serial port used for HCI
    PORT = ""

    controller = BleHci(PORT)
    event = controller.reset()

    print(event)

## Example 2: Direct-Test Mode

    #! /usr/bin/env python3
    ###############################################################################
    #
    #
    # Copyright (C) 2023 Maxim Integrated Products, Inc., All Rights Reserved.
    #
    # Permission is hereby granted, free of charge, to any person obtaining a
    # copy of this software and associated documentation files (the "Software"),
    # to deal in the Software without restriction, including without limitation
    # the rights to use, copy, modify, merge, publish, distribute, sublicense,
    # and/or sell copies of the Software, and to permit persons to whom the
    # Software is furnished to do so, subject to the following conditions:
    #
    # The above copyright notice and this permission notice shall be included
    # in all copies or substantial portions of the Software.
    #
    # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
    # OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    # IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
    # OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
    # ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
    # OTHER DEALINGS IN THE SOFTWARE.
    #
    # Except as contained in this notice, the name of Maxim Integrated
    # Products, Inc. shall not be used except as stated in the Maxim Integrated
    # Products, Inc. Branding Policy.
    #
    # The mere transfer of this software does not imply any licenses
    # of trade secrets, proprietary technology, copyrights, patents,
    # trademarks, maskwork rights, or any other form of intellectual
    # property whatsoever. Maxim Integrated Products, Inc. retains all
    # ownership rights.
    #
    ##############################################################################
    #
    # Copyright 2023 Analog Devices, Inc.
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.
    #
    ##############################################################################
    """
    dtm.py

    Description: Simple example showing direct test mode between two devices
                 and printing the packet error rate
    """
    import time

    from ble_hci import BleHci

    # Switch out for serial port used to connect over HCI
    RX_HCI_PORT = ""
    TX_HCI_PORT = ""

    def main():
        """MAIN"""
        tx_power = -10
        num_packets = 100

        rx_hci = BleHci(RX_HCI_PORT)
        tx_hci = BleHci(RX_HCI_PORT)

        tx_hci.set_adv_tx_power(tx_power)
        tx_hci.reset_test_stats()
        rx_hci.reset_test_stats()

        rx_hci.rx_test()

        tx_hci.tx_test_vs(num_packets=num_packets)

        time.sleep(0.1)

        tx_hci.end_test()
        rx_hci.end_test()

        tx_stats, _ = tx_hci.get_test_stats()
        rx_stats, _ = rx_hci.get_test_stats()

        per = rx_stats.per(tx_stats)

        print(per)

    if __name__ == "__main__":
        main()

## Example 3: Connection Mode

    #! /usr/bin/env python3
    ###############################################################################
    #
    #
    # Copyright (C) 2023 Maxim Integrated Products, Inc., All Rights Reserved.
    #
    # Permission is hereby granted, free of charge, to any person obtaining a
    # copy of this software and associated documentation files (the "Software"),
    # to deal in the Software without restriction, including without limitation
    # the rights to use, copy, modify, merge, publish, distribute, sublicense,
    # and/or sell copies of the Software, and to permit persons to whom the
    # Software is furnished to do so, subject to the following conditions:
    #
    # The above copyright notice and this permission notice shall be included
    # in all copies or substantial portions of the Software.
    #
    # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
    # OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    # IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
    # OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
    # ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
    # OTHER DEALINGS IN THE SOFTWARE.
    #
    # Except as contained in this notice, the name of Maxim Integrated
    # Products, Inc. shall not be used except as stated in the Maxim Integrated
    # Products, Inc. Branding Policy.
    #
    # The mere transfer of this software does not imply any licenses
    # of trade secrets, proprietary technology, copyrights, patents,
    # trademarks, maskwork rights, or any other form of intellectual
    # property whatsoever. Maxim Integrated Products, Inc. retains all
    # ownership rights.
    #
    ##############################################################################
    #
    # Copyright 2023 Analog Devices, Inc.
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.
    #
    ##############################################################################
    """
    connection.py

    Description: Simple example showing creation of a connection and getting packet error metrics

    """

    import time

    from ble_hci import BleHci

    # Switch out for serial port used to connect over HCI
    MASTER_HCI_PORT = ""
    SLAVE_HCI_PORT = ""

    def main():
        """MAIN"""
        master = BleHci(MASTER_HCI_PORT)
        slave = BleHci(SLAVE_HCI_PORT)

        master.reset()
        slave.reset()

        master_addr = 0x001234887733
        slave_addr = 0x111234887733

        master.set_adv_tx_power(-10)
        slave.set_adv_tx_power(-10)

        slave.set_address(slave_addr)
        master.set_address(master_addr)

        slave.start_advertising(connect=True)
        master.init_connection(addr=slave_addr)

        while True:
            slave_stats, _ = slave.get_conn_stats()
            master_stats, _ = master.get_conn_stats()

            if slave_stats.rx_data and master_stats.rx_data:
                print(f"Slave PER {slave_stats.per()}")
                print(f"Master PER {master_stats.per()}")
                break

            time.sleep(0.5)

        master.disconnect()
        slave.disconnect()

        master.reset()
        slave.reset()