Experimental: BLE Interactive Command Line Interface Example

nRF5 SDK v17.0.2
This example requires one of the following SoftDevices: S132, S140

Important: Before you run this example, make sure to program the SoftDevice .

The BLE Interactive Command Line Interface Example demonstrates how to control a BLE application using a command line interface. A set of generic BLE commands is provided. The application can be connected to several peripheral and central devices and interact with them. Dynamic subcommands are used to select a peer to interact with based on its BLE device address.

Main application features:

  • Scanning and advertising.
  • Private advertising.
  • Multiple central and peripheral connections.
  • Connecting with a private peer.
  • Connection parameter negotiation.
  • Other Link Layer parameter negotiation: Data Length and PHY.
  • ATT MTU length negotiation.
  • Requesting security (pairing, bonding).
  • OOB pairing using NFC as a BLE central or peripheral device.
  • GATT Client commands.
  • Device Name change.

The BLE Interactive Command Line Interface Example can be used with multiple nRF5 Development Kits as well as any other BLE devices. Use console BLE commands to interact with other BLE devices.

Additionally, the application includes the Battery Service to demonstrate GATT Server behavior.

This example demonstrates the use of Low Energy Secure Connections (LESC). The default cryptographic backend used for LESC is CC310 (when run on nRF52840) or Oberon (for other SoCs). To use micro-ecc instead, follow the steps in Enabling micro-ecc support in selected examples .

Note
This application is not power optimized!

Setup

Testing the example application requires other BLE devices such as a second nRF5 Development Kit, a smartphone, or other devices. If you want to use the NFC tag reader functionality, enable the sdk_config setting ADAFRUIT_SHIELD. Additional hardware is required for reading NFC tags: Adafruit NFC Shield library .

You can find the source code and the project file of the example in the following folder: <InstallFolder>\examples\ble_central_and_peripheral\experimental\ble_app_interactive

Button Assignment:

  • Button 1: If notification is on for Battery Service, pressing the button sends a notification with a fixed battery level value of 87.

LED assignments:

  • LED 1: On if the application is scanning.
  • LED 2: On if the application is connected to a BLE Peripheral device.
  • LED 3: On if the application is advertising.
  • LED 4: On if the application is connected to a BLE Central device.

BLE Commands

The application BLE commands are organized in a tree structure.

Root Commands

  • advertise           - Turn advertising on or off.
  • bonded_devices      - List bonded_devices.
  • connect             - <address/peer_id> Establish a connection with a device.
  • connected_devices   - Display connected devices and security information on each connection.
  • device_name         - <name> Set device name.
  • devices             - List available (advertising) devices.
  • disconnect          - <address> Disconnect from a device.
  • gatt                - GATT Client procedures.
  • key_reply           - <key> Enter passkey displayed by another device (for pairing mode: "Passkey Entry").
  • nfc_read            - <subcmd> Turn on NFC reader (requires additional hardware) <on/off>.
  • numeric             - Confirm or reject a numerical value (for pairing mode: "Numerical Comparison").
  • pair                - <subcmd> <address> <option> Initiate pairing with a connected device.
  • parameters          - <subcmd> Change or request new Link Layer or GATT parameters.
  • privacy             - Set privacy settings.
  • remove_bond         - <subcmd> Remove a bonded device.
  • scan                - Turn scanning on or off.

Subcommands tree

├── advertise
│   ├── on Start advertising and activate the on-chip NFC Tag.
│   └── off Stop advertising and deactivate the on-chip NFC Tag.
│
├── bonded_devices
│
├── connect <address/peer_id>
│
├── connected_devices
│
├── devices List advertising devices.
│
├── disconnect <address>
│
├── gatt
│   ├── characteristics <address> <service uuid> Discover service characteristics.
│   │
│   ├── indication Change indications state.
│   │   ├── on <address> <characteristic uuid> On indications.
│   │   └── off <address> <characteristic uuid> Off indications.
│   │
│   ├── notification> Change notifications state.
│   │   ├── on <address> <characteristic uuid> On notification.
│   │   └── off <address> <characteristic uuid> Off notification.
│   │
│   ├── read <address> <characteristic uuid> Read a characteristic value.
│   │
│   ├── services <address> Discover services.
│   │
│   └── write <sub_cmd> Write a characteristic value.
│       ├── command <address> <char uuid> <value> Use a Write Command.
│       └── request <address> <char uuid> <value> Use a Write Request.
│
├── key_reply <key> Type a passkey (in pairing mode: "Passkey Entry").
│
├── nfc_read
│   ├── on Turn on NFC tag reading (requires additional hardware), if an NDEF Message for BLE pairing is read, connecting and pairing are performed automatically.
│   └── off Turn off NFC tag reading.
│
├── numeric
│   ├── accept Accept a numerical value (in pairing mode: "Numerical Comparison")
│   └── reject Reject a numerical value (in pairing mode: "Numerical Comparison").
│
├── pair
│   ├── LEGACY <address> <option> Start pairing (use BLE Legacy pairing).
│   └── LESC <address> <option> Start pairing (use BLE Secure Connections pairing).
│
├── parameters
│   ├── apply <address> Apply the currently set connection parameters (start negotiation, or change parameters - depending on the BLE role).
│   ├── data_length <address> <value> Request Data Length change.
│   ├── max_conn_interval <value> Set maximum connection interval.
│   ├── min_conn_interval <value> Set minimum connection interval.
│   ├── mtu <value> Request Ab MTU length change.
│   ├── phy <subcmd> <address> PHY change.
│   ├── slave_latency <value> Set slave latency.
│   └── sup_timeout <value> Set connection supervision timeout.
│
├── privacy Set privacy settings for advertising.
│   ├── on Turn on privacy.
│   └── off Turn off privacy.
│
├── remove_bond
│   ├── all Remove all bonded devices.
│   └── device <address> Remove a selected bonded device.
│
└── scan
├── on Start scanning.
└── off Stop scanning.

Testing

Test the BLE Interactive Command Line Interface Example application by performing the following steps:

Note
Because of the large number command permutations, there is no quick way to test the entire application. Instead we have suggest a simple test path.

Test the BLE Interactive Command Line Interface Example application, for example by performing the following steps:

  1. If you are using the software backend of the Cryptography library - nrf_crypto , ensure that you have installed and enabled the micro-ecc library .
  2. Compile and program the application on test board.
  3. Start a terminal emulator like PuTTY (recommended) with the following Terminal settings and UART and USB settings or RTT settings .
  4. Open a serial connection to the COM port used by the tester board. A command prompt is displayed.
  5. Type scan on in the terminal to start scanning BLE devices.
  6. Type devices to display list of available (advertising) devices. The list is periodically refreshed in the background.
  7. Type connect <address> to connect to a device. You can use the device addresses displayed earlier. The addresses will display as dynamic subcommands (press 'Tab' for auto-fill).
  8. After establishing the connection, you can use other commands defined in the application. For example:
    • Type pair to initiate pairing with a device.
    • Type parameters to set new connection parameters or negotiate ATT MTU, PHY, or Data Length.
    • Type gatt to use GATT Client commands.
  9. You can also start scanning again and connect to another device, or start advertising to become connectable for other devices.
  10. The application supports multiple connections in both roles (central and peripheral). The commands can be directed to any connected device using its BLE device address.
  11. Type disconnect <address> to disconnect from a device.
  12. These steps can be repeated using two boards with the same application. Then, both boards work in different configurations, for example as a scanner or an advertiser, a central or a peripheral device etc.
Note
Use the Tab key to autocomplete and promt commands (or peers).