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
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235---
sidebar_label: 'BLE'
---
import DocsCard from '@components/global/DocsCard';
import DocsButton from '@components/page/native/DocsButton';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CodeBlock from '@theme/CodeBlock';
# BLE
This plugin enables communication between a phone and Bluetooth Low Energy (BLE) peripherals.
The plugin provides a simple JavaScript API for iOS and Android.
- Scan for peripherals
- Connect to a peripheral
- Read the value of a characteristic
- Write new value to a characteristic
- Get notified when characteristic's value changes
Advertising information is returned when scanning for peripherals. Service, characteristic, and property info is returned when connecting to a peripheral. All access is via service and characteristic UUIDs. The plugin manages handles internally.
Simultaneous connections to multiple peripherals are supported.
<p>
<a href="https://github.com/don/cordova-plugin-ble-central" target="_blank" rel="noopener" className="git-link">github.com/don/</a>
</p>
<h2>Stuck on a Cordova issue?</h2>
<DocsCard
className="cordova-ee-card"
header="Don't waste precious time on plugin issues."
href="https://ionicframework.com/sales?product_of_interest=Ionic%20Native"
>
<div>
<img src="/docs/icons/native-cordova-bot.png" className="cordova-ee-img" />
<p>If you're building a serious project, you can't afford to spend hours troubleshooting. Ionic’s experts offer premium advisory services for both community plugins and premier plugins.</p>
<DocsButton className="native-ee-detail">Contact Us Today!</DocsButton>
</div>
</DocsCard>
<h2 id="installation">
<a href="#installation">Installation</a>
</h2>
<Tabs
groupId="runtime"
defaultValue="Capacitor"
values={[
{ value: 'Capacitor', label: 'Capacitor' },
{ value: 'Cordova', label: 'Cordova' },
{ value: 'Enterprise', label: 'Enterprise' },
]}
>
<TabItem value="Capacitor">
<CodeBlock className="language-shell">
$ npm install cordova-plugin-ble-central {'\n'}$ npm install @awesome-cordova-plugins/ble {'\n'}$ ionic cap sync
</CodeBlock>
</TabItem>
<TabItem value="Cordova">
<CodeBlock className="language-shell">
$ ionic cordova plugin add cordova-plugin-ble-central {'\n'}$ npm install @awesome-cordova-plugins/ble {'\n'}
</CodeBlock>
</TabItem>
<TabItem value="Enterprise">
<blockquote>
Ionic Enterprise comes with fully supported and maintained plugins from the Ionic Team.
<a className="btn" href="https://ionic.io/docs/premier-plugins">Learn More</a> or if you're interested in an enterprise version of this plugin <a className="btn" href="https://ionicframework.com/sales?product_of_interest=Ionic%20Enterprise%20Engine">Contact Us</a>
</blockquote>
</TabItem>
</Tabs>
## Supported Platforms
- Android
- iOS
## Usage
### React
[Learn more about using Ionic Native components in React](../native-community.md#react)
### Angular
```tsx
import { BLE } from '@awesome-cordova-plugins/ble/ngx';
constructor(private ble: BLE) { }
```
## Peripheral Data
Peripheral Data is passed to the success callback when scanning and connecting. Limited data is passed when scanning.
```tsx
{
'name': 'Battery Demo',
'id': '20:FF:D0:FF:D1:C0',
'advertising': [2,1,6,3,3,15,24,8,9,66,97,116,116,101,114,121],
'rssi': -55
}
```
After connecting, the peripheral object also includes service, characteristic and descriptor information.
```tsx
{
'name': 'Battery Demo',
'id': '20:FF:D0:FF:D1:C0',
'advertising': [2,1,6,3,3,15,24,8,9,66,97,116,116,101,114,121],
'rssi': -55,
'services': [
'1800',
'1801',
'180f'
],
'characteristics': [
{
'service': '1800',
'characteristic': '2a00',
'properties': [
'Read'
]
},
{
'service': '1800',
'characteristic': '2a01',
'properties': [
'Read'
]
},
{
'service': '1801',
'characteristic': '2a05',
'properties': [
'Read'
]
},
{
'service': '180f',
'characteristic': '2a19',
'properties': [
'Read'
],
'descriptors': [
{
'uuid': '2901'
},
{
'uuid': '2904'
}
]
}
]
}
```
## Advertising Data
Bluetooth advertising data is returned in when scanning for devices. The format varies depending on your platform. On Android advertising data will be the raw advertising bytes. iOS does not allow access to raw advertising data, so a dictionary of data is returned.
The advertising information for both Android and iOS appears to be a combination of advertising data and scan response data.
### Android
```tsx
{
'name': 'demo',
'id': '00:1A:7D:DA:71:13',
'advertising': ArrayBuffer,
'rssi': -37
}
```
Convert the advertising info to a Uint8Array for processing. `var adData = new Uint8Array(peripheral.advertising)`
### iOS
Note that iOS uses the string value of the constants for the [Advertisement Data Retrieval Keys](https://developer.apple.com/library/ios/documentation/CoreBluetooth/Reference/CBCentralManagerDelegate_Protocol/index.html#//apple_ref/doc/constant_group/Advertisement_Data_Retrieval_Keys). This will likely change in the future.
```tsx
{
'name': 'demo',
'id': 'D8479A4F-7517-BCD3-91B5-3302B2F81802',
'advertising': {
'kCBAdvDataChannel': 37,
'kCBAdvDataServiceData': {
'FED8': {
'byteLength': 7 // data not shown
}
},
'kCBAdvDataLocalName': 'demo',
'kCBAdvDataServiceUUIDs': ['FED8'],
'kCBAdvDataManufacturerData': {
'byteLength': 7 // data not shown
},
'kCBAdvDataTxPowerLevel': 32,
'kCBAdvDataIsConnectable': true
},
'rssi': -53
}
```
## Typed Arrays
This plugin uses typed Arrays or ArrayBuffers for sending and receiving data.
This means that you need convert your data to ArrayBuffers before sending and from ArrayBuffers when receiving.
```tsx
// ASCII only
function stringToBytes(string) {
var array = new Uint8Array(string.length);
for (var i = 0, l = string.length; i < l; i++) {
array[i] = string.charCodeAt(i);
}
return array.buffer;
}
// ASCII only
function bytesToString(buffer) {
return String.fromCharCode.apply(null, new Uint8Array(buffer));
}
```
You can read more about typed arrays in these articles on [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays) and [HTML5 Rocks](http://www.html5rocks.com/en/tutorials/webgl/typed_arrays/).
## UUIDs
UUIDs are always strings and not numbers. Some 16-bit UUIDs, such as '2220' look like integers, but they're not. (The integer 2220 is 0x8AC in hex.) This isn't a problem with 128 bit UUIDs since they look like strings 82b9e6e1-593a-456f-be9b-9215160ebcac. All 16-bit UUIDs should also be passed to methods as strings.