InfiniTime.git

ref: 0.12.0

src/libs/mynewt-nimble/docs/btshell/btshell_api.rst


  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
API for btshell app
-------------------

"btshell" is one of the sample applications that come with Mynewt. It is a shell application which provides a basic
interface to the host-side of the BLE stack. "btshell" includes all the possible roles (Central/Peripheral) and they may
be run simultaneously. You can run btshell on a board and issue commands that make it behave as a central or a peripheral
with different peers.

**btshell** is a new application that uses shell subsystem introduced in Mynewt 1.1 and has updated commands and
parameters names. Thanks to support for tab completion commands names are more descriptive and self-explanatory
without requiring extensive typing.

Highlighted below are some of the ways you can use the API to establish connections and discover services and
characteristics from peer devices. For descriptions of the full API, go to the next sections on
:doc:`btshell_GAP` and :doc:`btshell_GATT`.

.. contents::
   :local:
   :depth: 2

.. toctree::
   :hidden:
   :titlesonly:

   GAP <btshell_GAP>
   GATT <btshell_GATT>
   btshell_advdata

Set device address.
~~~~~~~~~~~~~~~~~~~

On startup, btshell has the following identity address configuration:

-  Public address: None
-  Random address: None

The below ``set`` commands can be used to change the address configuration:

::

    set addr_type=public addr=<device-address>
    set addr_type=random addr=<device-address>

For example:

::

    set addr_type=public addr=01:02:03:04:05:06
    set addr_type=random addr=c1:aa:bb:cc:dd:ee

The address configuration can be viewed with the ``gatt-show-addr`` command, as follows:

::

    gatt-show-addr
    public_id_addr=01:02:03:04:05:06 random_id_addr=c1:aa:bb:cc:dd:ee

Initiate a direct connection to a device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In this case, your board is acting as a central and initiating a connection with another BLE device. The example
assumes you know the address of the peer, either by scanning for available peers or because you have set up the peer
yourself.

.. code-block:: none
    :emphasize-lines: 1

    connect peer_addr=d4:f5:13:53:d2:43
    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

The ``handle=1`` in the output indicates that it is connection-1.

Configure advertisements to include device name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In this case, your board is acting as a peripheral.

With Extended Advertising enabled (should be executed after advertise-configure):

::

    advertise-set-adv-data name=<your-device-name>

With Extended Advertising disabled:

::

    set-adv-data name=<your-device-name>

Begin sending undirected general advertisements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In this case, your board is acting as a peripheral.

With Extended Advertising enabled:

::

    advertise-configure connectable=1 legacy=1 scannable=1
    advertise-start

With Extended Advertising disabled:

::

    advertise conn=und discov=gen

Show established connections.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    gatt-show-conn

Discover and display peer's services, characteristics, and descriptors.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is how you discover and then display the services of the peer you established earlier across connection-1.

.. code-block:: none
    :emphasize-lines: 1,2

    gatt-discover-full conn=1
    gatt-show
    [ts=132425ssb, mod=64 level=2] CONNECTION: handle=1 addr=d4:f5:13:53:d2:43
    [ts=132428ssb, mod=64 level=2]     start=1 end=5 uuid=0x1800
    [ts=132433ssb, mod=64 level=2]     start=6 end=16 uuid=0x1808
    [ts=132437ssb, mod=64 level=2]     start=17 end=31 uuid=0x180a
    [ts=132441ssb, mod=64 level=2]     start=32 end=65535 uuid=00000000-0000-1000-1000000000000000


Read an attribute belonging to the peer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    gatt-read conn=1 attr=21

Write to an attribute belonging to the peer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    gatt-write conn=1 attr=3 value=0x01:0x02:0x03

Perform a passive scan
~~~~~~~~~~~~~~~~~~~~~~

This is how you tell your board to listen to all advertisements around it. The duration is specified in ms.

::

    scan duration=1000 passive=1 filter=no_wl