You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<spanclass="notes">**Note:** Some functions, variables or types have been deprecated. Please see the class reference linked below for details.</span>
3
+
Bluetooth low energy (BLE) is a low power wireless technology standard for building personal area networks. Typical
4
+
applications of BLE are health care, fitness trackers, beacons, smart home, security, entertainment, proximity sensors,
5
+
industrial and automotive.
4
6
5
-
Bluetooth low energy (BLE) is a low power wireless technology standard for building personal area networks. Typical applications of BLE are health care, fitness trackers, beacons, smart home, security, entertainment, proximity sensors, industrial and automotive.
7
+
Arm Mbed BLE is the Bluetooth Low Energy software solution for Mbed. Many Mbed
8
+
[targets and components](https://os.mbed.com/platforms/?mbed-enabled=15&connectivity=3) support Mbed BLE. Developers can
9
+
use it to create new BLE enabled applications.
6
10
7
-
Arm Mbed BLE, also called `BLE_API`, is the Bluetooth Low Energy software solution for Mbed. Many Mbed [targets and components](https://os.mbed.com/platforms/?mbed-enabled=15&connectivity=3) support Mbed BLE. Developers can use it to create new BLE enabled applications.
11
+
## BLE API
8
12
9
-
Mbed’s `BLE_API` interfaces with the BLE controller on the board. It hides the BLE stack’s complexity behind C++ abstractions and is compatible with all BLE-enabled Mbed board. The Mbed OS `BLE_API` automatically configuring the clocks, timers and other hardware peripherals to work at their lowest power consumption.
13
+
Mbed's BLE API is available through C++ classes. It hides the BLE stack’s complexity and is compatible with all
14
+
BLE-enabled Mbed board. It automatically configures the clocks, timers and other hardware peripherals to work at their
BLE API is accessible through several header files:
14
20
15
-
You can build a BLE application using Mbed OS, `BLE_API` and a controller-specific Bluetooth stack together with some bridge software to adapt it to `BLE_API`:
21
+
-[BLE.h](https://github.com/ARMmbed/mbed-os/blob/master/connectivity/FEATURE_BLE/include/ble/BLE.h) - acquire the BLE
- The bridge software is specific to each vendor’s board. It provides the instantiations for the interfaces `BLE_API` offers and helps drive the underlying controller and Bluetooth stack.
19
-
- The Bluetooth stack implements the Bluetooth protocol and is specific to the controller, so a vendor using different controllers may provide different stacks.
32
+
Specific documentation for each component is available inside each of these headers.
BLE implementation does not provide thread safety and assumes single thread execution. Event processing and API calls
37
+
must be dispatched from the same thread.
24
38
25
-
`BLE_API` offers building blocks to help construct applications. These fall into two broad categories:
39
+
### Asynchronous calls
26
40
27
-
1. Interfaces under **`ble/`** to express BLE constructs, such as GAP, GATT, services and characteristics.
41
+
Many API calls are asynchronous and provide results through callbacks. These are implemented as events. To receive these
42
+
events register an EventHandler that is specific to that component. For example to receive events from Gap, use
43
+
`Gap::setEventHandler()` passing in your implementation that inherits from `Gap::EventHandler`. Your class will override
44
+
the events (methods) you are interested in, the others will inherit the do-nothing implementations provided by the parent.
28
45
29
-
1. Classes under `ble/services` to offer reference implementations for many of the commonly used GATT profiles. The code under 'services/' isn't essential, but it’s a useful starting point for prototyping. We continue to implement the standard GATT profiles.
46
+
### Instancing a BLE device
30
47
31
-
## The BLEDevice class and header
48
+
All BLE operations are executed on an instance of BLE accessible through a function in the header`ble/BLE.h`.
32
49
33
-
The entry point of Mbed's `BLE_API` is the BLE class accessible using the header `ble/BLE.h`. This class allows you to obtain a BLE object that includes the basic attributes of a spec-compatible BLE device and can work with any BLE radio:
34
-
35
-
```c TODO
50
+
```c
36
51
#include"ble/BLE.h"
37
52
38
53
BLE& mydevicename = BLE::Instance();
39
54
```
40
55
41
-
The class's member functions can be divided by purpose:
56
+
### BLE stacks
57
+
58
+
To build and application using BLE you will be using the Mbed OS BLE API and an implementation of the BLE stack
59
+
appropriate for your board. The implementation is split into Host and Controller part. They can both run on the same
60
+
chip or two separate ones. They will be both communicating through HCI (Host Controller Interface, a well defined
61
+
protocol that is part of the Bluetooth specification). Read more about the HCI interface in Mbed OS
1. Basic BLE operations, such as initializing the controller.
69
+
## Debugging
44
70
45
-
1. Accessor to Bluetooth Modules that manage GAP, GATT or the security.
71
+
To learn about debugging with mbed go to:
46
72
47
-
## Usage
73
+
[Debugging Mbed OS](../debug-test/index.html)
48
74
49
-
1. Set up advertising and connection modes.
50
-
1. Assign UUIDs to the service and its characteristic.
51
-
1. Create an input characteristic.
52
-
1. Construct a service class and add it to the BLE stack.
53
-
1. Push notifications when the characteristic's value changes.
75
+
However, keep in mind when trying to debug connectivity issues that if more than one device is involved it might
76
+
not be possible to stop your target without the communication breaking down. A less invasive way to help you understand
77
+
what is happening might be to use tracing.
54
78
55
79
## Tracing
56
80
57
81
To debug issues (or to understand what the stack is doing) it may be helpful to enable tracing.
58
82
59
-
Traces can be turned on by overriding configuration options in you mbed_app.json:
83
+
To enable traces override configuration options in you mbed_app.json:
60
84
61
85
```
62
86
"target_overrides": {
63
87
"*": {
64
88
"mbed-trace.enable": true,
65
89
"mbed-trace.max-level": "TRACE_LEVEL_DEBUG",
66
-
"cordio.trace-hci-packets": true,
67
-
"cordio.trace-cordio-wsf-traces": true,
90
+
"cordio.trace-hci-packets": false,
91
+
"cordio.trace-cordio-wsf-traces": false,
68
92
"ble.trace-human-readable-enums": true
69
93
}
70
94
}
71
95
```
72
96
73
-
and compiling your application with `--profile debug`. Please note that with all options enabled your application may become too big - disable some options or lower the `mbed-trace.max-level`. Detailed documentation is available in the tracing [README.md](https://github.com/ARMmbed/mbed-os/blob/master/platform/mbed-trace/README.md).
97
+
Compile your application with `--profile debug`. Please note that with all options enabled your application may become
98
+
too big - disable some options or lower the `mbed-trace.max-level`. Detailed documentation is available in the tracing
Copy file name to clipboardExpand all lines: docs/api/connectivity/bluetooth/Gap.md
-2Lines changed: 0 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,5 @@
1
1
# GAP
2
2
3
-
<spanclass="notes">**Note:** Some functions, variables or types have been deprecated. Please see the class reference linked below for details.</span>
4
-
5
3
The Generic Access Profile is the layer of the stack that handles connectivity tasks. This includes link establishment and termination, advertising and scanning.
6
4
7
5
Devices with data to publish can use GAP to advertise. They can include the data in the advertisement itself, inside the scan response, or leave a peer device to query it after the connection has been established.
Copy file name to clipboardExpand all lines: docs/api/connectivity/bluetooth/GattClient.md
-2Lines changed: 0 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,5 @@
1
1
# GattClient
2
2
3
-
<spanclass="notes">**Note:** Some functions, variables or types have been deprecated. Please see the class reference linked below for details.</span>
4
-
5
3
You can use Generic Attribute Profile (GATT) to discover services, characteristics and descriptors and to perform operations on them. The interaction happens between two peers, one of which is the client (which initiates interactions) and the other is the server (which responds). You can use Attribute Protocol (ATT) to implement this interaction. `GattClient` defines procedures required for interacting with a remote `GattServer`.
Copy file name to clipboardExpand all lines: docs/api/connectivity/bluetooth/GattServer.md
+3-3Lines changed: 3 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,5 @@
1
1
# GattServer
2
2
3
-
<spanclass="notes">**Note:** Some functions, variables or types have been deprecated. Please see the class reference linked below for details.</span>
4
-
5
3
You can use Generic Attribute Profile (GATT) to discover services, characteristics and descriptors and to perform operations on them. The interaction happens between two peers, one of which is the client (which initiates interactions) and the other is the server (which responds). You can use Attribute Protocol (ATT) to implement this interaction.
6
4
7
5
`GattServer` is a collection of GattServices. These services contain characteristics that a `GattClient` on the peer connected to the device may read or write. These characteristics may also emit updates to subscribed clients when their values change.
@@ -24,7 +22,9 @@ The Attribute Protocol Maximum Transmission Unit (`ATT_MTU`) is the maximum size
24
22
25
23
## Events
26
24
27
-
You can register several event handlers with the GattServer that it will call to notify you of client (remote application connected to the server) and server activities:
25
+
You can register your implementation of `GattServer::EventHandler` with the GattServer using
26
+
`GattServer::setEventHandler()`. It will call your event handler methods to notify you of client (remote application
27
+
connected to the server) and server activity:
28
28
29
29
-`onDataSent`: Register an event handler with the GattServer that it will call to notify you when it sends a characteristic value update to a client.
30
30
-`onDataWriten`: Register an event handler with the GattServer that it will call to notify you when a client has written an attribute of the server.
0 commit comments