1API for btshell app 2------------------- 3 4"btshell" is one of the sample applications that come with Mynewt. It is a shell application which provides a basic 5interface to the host-side of the BLE stack. "btshell" includes all the possible roles (Central/Peripheral) and they may 6be run simultaneously. You can run btshell on a board and issue commands that make it behave as a central or a peripheral 7with different peers. 8 9**btshell** is a new application that uses shell subsystem introduced in Mynewt 1.1 and has updated commands and 10parameters names. Thanks to support for tab completion commands names are more descriptive and self-explanatory 11without requiring extensive typing. 12 13Highlighted below are some of the ways you can use the API to establish connections and discover services and 14characteristics from peer devices. For descriptions of the full API, go to the next sections on 15:doc:`btshell_GAP` and :doc:`btshell_GATT`. 16 17.. contents:: 18 :local: 19 :depth: 2 20 21.. toctree:: 22 :hidden: 23 :titlesonly: 24 25 GAP <btshell_GAP> 26 GATT <btshell_GATT> 27 btshell_advdata 28 29Set device address. 30~~~~~~~~~~~~~~~~~~~ 31 32On startup, btshell has the following identity address configuration: 33 34- Public address: None 35- Random address: None 36 37The below ``set`` commands can be used to change the address configuration: 38 39:: 40 41 set addr_type=public addr=<device-address> 42 set addr_type=random addr=<device-address> 43 44For example: 45 46:: 47 48 set addr_type=public addr=01:02:03:04:05:06 49 set addr_type=random addr=c1:aa:bb:cc:dd:ee 50 51The address configuration can be viewed with the ``gatt-show-addr`` command, as follows: 52 53:: 54 55 gatt-show-addr 56 public_id_addr=01:02:03:04:05:06 random_id_addr=c1:aa:bb:cc:dd:ee 57 58Initiate a direct connection to a device 59~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 60 61In this case, your board is acting as a central and initiating a connection with another BLE device. The example 62assumes you know the address of the peer, either by scanning for available peers or because you have set up the peer 63yourself. 64 65.. code-block:: none 66 :emphasize-lines: 1 67 68 connect peer_addr=d4:f5:13:53:d2:43 69 connection established; handle=1 our_ota_addr_type=0 our_ota_addr=0a:0b:0c:0d:0e:0f out_id_addr_type=0 our_id_addr=0a:0b:0c:0d:0e:0f peer_addr_type=0 peer_addr=43:d2:53:13:f5:d4 conn_itvl=40 conn_latency=0 supervision_timeout=256 encrypted=0 authenticated=0 bonded=0 70 71The ``handle=1`` in the output indicates that it is connection-1. 72 73Configure advertisements to include device name 74~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 75 76In this case, your board is acting as a peripheral. 77 78With Extended Advertising enabled (should be executed after advertise-configure): 79 80:: 81 82 advertise-set-adv-data name=<your-device-name> 83 84With Extended Advertising disabled: 85 86:: 87 88 set-adv-data name=<your-device-name> 89 90Begin sending undirected general advertisements 91~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 92 93In this case, your board is acting as a peripheral. 94 95With Extended Advertising enabled: 96 97:: 98 99 advertise-configure connectable=1 legacy=1 scannable=1 100 advertise-start 101 102With Extended Advertising disabled: 103 104:: 105 106 advertise conn=und discov=gen 107 108Show established connections. 109~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 110 111:: 112 113 gatt-show-conn 114 115Discover and display peer's services, characteristics, and descriptors. 116~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 117 118This is how you discover and then display the services of the peer you established earlier across connection-1. 119 120.. code-block:: none 121 :emphasize-lines: 1,2 122 123 gatt-discover-full conn=1 124 gatt-show 125 [ts=132425ssb, mod=64 level=2] CONNECTION: handle=1 addr=d4:f5:13:53:d2:43 126 [ts=132428ssb, mod=64 level=2] start=1 end=5 uuid=0x1800 127 [ts=132433ssb, mod=64 level=2] start=6 end=16 uuid=0x1808 128 [ts=132437ssb, mod=64 level=2] start=17 end=31 uuid=0x180a 129 [ts=132441ssb, mod=64 level=2] start=32 end=65535 uuid=00000000-0000-1000-1000000000000000 130 131 132Read an attribute belonging to the peer 133~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 134 135:: 136 137 gatt-read conn=1 attr=21 138 139Write to an attribute belonging to the peer 140~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 141 142:: 143 144 gatt-write conn=1 attr=3 value=0x01:0x02:0x03 145 146Perform a passive scan 147~~~~~~~~~~~~~~~~~~~~~~ 148 149This is how you tell your board to listen to all advertisements around it. The duration is specified in ms. 150 151:: 152 153 scan duration=1000 passive=1 filter=no_wl 154