Using Bluetooth Shell

Purpose

The purpose of this guide is to demonstrate the use of Bluetooth Shell.  Bluetooth Shell (BT Shell) is a command-line shell application that runs over the UART.  It allows one to manually type in a UNIX-like shell to establish and manipulate Bluetooth connections.  In this guide, we shall show how to compile, run, and establish a BT connection with a device running the nRF Connect application.

Hardware

1 x nRF5340-DK
1 x Android or iOS device (Android used in this example)

Software

nRF Connect mobile application
nRF Connect SDK (v1.8.0, at time of publishing)

Procedure

1. Please install the latest nRF Connect SDK using the Toolchain Manager applet in the nRF Connect Desktop PC application.
   
   
2. Launch the Git Bash shell from within the Toolchain Manager.
   
   
3. Change to the zephyr/test/bluetooth/shell directory.
   
   
4. Open the prj.conf file in your favorite text editor and add the following line at the end:
   

   CONFIG_SHELL_BACKEND_SERIAL=y

   
   
5. Build the project using the following command:
   

   west build -b nrf5340dk_nrf5340_cpuapp_ns -p auto

   This will build the code for the BT Shell app as a non-secure application for the nRF5340-DK.
   
   
6. Plug in the nRF5340-DK to your PC and flash the board using the following command:
   

   west flash

   
   
7. Connect a terminal emulation software (such as TeraTerm or Putty on Windows) to one of the serial ports of the DK.  You want the port which will display the following upon reset:
   
   
   
8. Press the <Tab> key to see the possible commands available:
   
   
   
9. Type the following command to display the listing of the available bluetooth commands:
   

   bt --help

   
   
10. Observe the commands available as well as their parameters:
    
    
    
11. Issue the following command to initialize the BT subsystem and observe output:
    

    bt init

    
    
    
12. Now let's exercise the BT subsystem; type in the following command to turn on BT advertising:
    

    bt advertise on

    
    
13. Launch the nRF Connect app on your device and tap on the "test shell" advertising beacon's Connect button:
    
    
    
14. Now the DK is the peripheral device while the device is the central device.  Tap on the Heart Rate to show the Heart Rate Measurement characteristics and tap on the notify icon to enable heart rate monitor notifications:
    
    
    
15. Observe the message on the terminal window that indicates that notifications have been successfully enabled:
    
    
    
16. Type the following commands in the terminal window to enable Heart Rate simulation:
    

    bt advertise off
    hrs simulate on

    
    
    
17. Observe the simulated changing Heart Rate Measurements in the nRF Connect app:
    
    

Conclusion

As shown, BT Shell is a very powerful tool to enable the manipulation of Bluetooth connections.  It can be modified via its prj.conf file to enable customizations. There are many options that enables one to modify the connection such as PHY choices, advertising types, etc.  Furthermore, BT Shell can act as a peripheral and a central device simultaneously which allows for testing and development of Bluetooth-enabled products.  Make sure to use the built-in help text to learn the various functions.  Also note that there may be experimental features in the shell that are not yet implemented (such as the iso command at the time of this publishing).