安卓低功耗蓝牙（BLE）开发教程
翻译的官方文档，原文在这里：点击打开链接 ，本人对部分内容进行了微调，大意和原文一致。
蓝牙低功耗
Android 4.3（API级别18）为处于中心角色的低能耗蓝牙（BLE）引入了内置的平台支持，并为应用程序提供了可用于发现设备，查询服务和传输信息的API。
常见用例包括：
- 在附近设备之间传输少量数据。
- 与Google Beacons等距离传感器进行交互，可以根据用户的当前位置为用户提供个性化的体验。
与经典蓝牙相反，低功耗
蓝牙
（BLE）旨在提供显著的低功耗。 这将允许Android应用程序与具有更严格功率需求的BLE设备进行通信，例如距离传感器，心率监视器和健身设备。
关键术语和概念
以下是关键BLE术语和概念的摘要：
- 通用属性配置文件（GATT） - GATT配置文件是通过BLE链接发送和接收称为“属性”的短数据的通用规范。 所有当前的低能耗应用配置文件均基于GATT。
- Bluetooth SIG定义了低能耗设备的许多配置文件。 配置文件是设备在特定应用程序中如何工作的规范。 请注意，设备可以实现多个配置文件。 例如，设备可以包含心率监测器和电池电平检测器。
-
属性协议（ATT）-GATT建立在属性协议（ATT）之上。 这也被称为GATT / ATT。 ATT经过优化，可在BLE设备上运行。 为此，它使用尽可能少的字节。 每个属性由通用唯一标识符（UUID）唯一标识，该标识符是用于唯一标识信息的字符串ID的标准化128位格式。 由ATT传输的属性被格式化为特征和服务。
-
特征 - 特征包含描述特征值的单个值和0-n描述符。 一个特征可以被认为是一个类型，类似于一个类。
-
描述符 - 描述符是描述特征值的定义属性。 例如，描述符可以指定人类可读描述，特征值的可接受范围，或特定于特征值的特定度量单位。
-
服务 - 服务是特征的集合。 例如，您可以使用一个名为“心率监测器”的服务，其中包含“心率测量”等特征。 您可以在bluetooth.org上找到现有的基于GATT的配置文件和服务列表。
角色和责任
以下是Android设备与BLE设备进行交互的角色和职责：
- 中央与外围。 这适用于BLE连接本身。处于中央角色的设备扫描，寻找蓝牙设备，处于外围角色中的设备则成为可连接的设备。
- GATT服务器与GATT客户端。 这确定了两个设备在建立连接之后如何对话。
为了解这个区别，现在假设你有一个Android手机和一个BLE设备的活动跟踪器。 手机支持中心角色; 活动跟踪器支持外设角色（要建立一个BLE连接，您需要做下面两件事情之一 ——两个只支持外围设备的东西不能互相交谈，也不能两个只支持中心设备）。
一旦手机和活动跟踪器建立了连接，他们就开始
相互传送
GATT元数据。 根据传输的数据类型，一个或另一个可能充当服务器。 例如，如果活动跟踪器想要将传感器数据报告给手机，那么活动跟踪器可以用作服务器。 如果活动跟踪器想要从手机接收更新，则手机充当服务器可能是有意义的。
在本文档的使用的示例中，Android应用（在Android设备上运行）是GATT客户端。 该应用程序从GATT服务器获取数据，GATT服务器是支持心率谱的BLE心率监测器。 但您也可以设置您的Android应用来充当GATT服务器的角色。 有关详细信息请参阅BluetoothGattServer。
BLE权限
为了在您的应用程序中使用蓝牙功能，您必须声明蓝牙权限BLUETOOTH。 您需要此权限才能执行任何蓝牙通信，例如请求连接，接受连接和传输数据。
如果您希望应用程序启动设备发现或操作蓝牙设置，您还必须声明BLUETOOTH_ADMIN权限。 注意：如果您使用BLUETOOTH_ADMIN权限，则还必须具有BLUETOOTH权限。
声明您的应用程序清单文件中的蓝牙权限。如下：
1
<uses-permission android:name="android.permission.BLUETOOTH"/>
2
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
如果您要声明您的应用仅适用于支持BLE的设备，请在应用的清单中包含以下内容：
1
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>
但是，如果您希望将应用程序提供给不支持BLE的设备，则应将此元素包含在应用程序的清单中，但setrequired =“false”。 然后在运行时，您可以使用PackageManager.hasSystemFeature()来确定BLE的可用性：
1
// Use this check to determine whether BLE is supported on the device. Then
2
// you can selectively disable BLE-related features.
3
if (!getPackageManager().hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE))
4
{
5
Toast.makeText(this, R.string.ble_not_supported, Toast.LENGTH_SHORT).show();
6
finish();
7
}
请求用户权限
为了从NETWORK_PROVIDER或GPS_PROVIDER接收位置更新，您必须在Android清单文件中声明{@code ACCESS_COARSE_LOCATION}或{@code ACCESS_FINE_LOCATION}权限来请求用户权限。 没有这些权限，您的应用程序对位置更新的请求将失败，并将显示权限错误。
如果您使用的是NETWORK_PROVIDER和GPS_PROVIDER，那么您只需要请求{@code ACCESS_FINE_LOCATION}权限，因为它包含两个提供者的权限。 {@code ACCESS_COARSE_LOCATION}的权限仅允许访问NETWORK_PROVIDER。
注意：如果您的应用程序针对Android 5.0（API级别21）或更高版本，则必须声明您的应用程序在清单文件中使用android.hardware.location.network或者android.hardware.location.gps硬件功能，具体取决于您的应用程序是从NETWORK_PROVIDER还是从GPS_PROVIDER接收位置更新。 如果您的应用程序从这些位置提供商来源收到位置信息，则需要声明该应用程序在应用程序清单中使用这些硬件功能。 在Android 5.0（API 21）之前运行版本的设备上，请求{@code ACCESS_FINE_LOCATION}或{@code ACCESS_COARSE_LOCATION}权限包含对位置硬件功能的隐含请求。 但是，请求这些权限不会自动请求Android 5.0（API级别21）以上的位置硬件功能。
以下代码示例演示了如何在从设备的GPS读取数据的应用程序的清单文件中声明权限和硬件功能：
1
<manifest >
2
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
3
4
5
<uses-feature android:name="android.hardware.location.gps" />
6
7
</manifest>
设置BLE
在您的应用程序可以通过BLE进行通信之前，需要验证设备是否支持BLE，如果是，则确保已启用。 请注意，只有将
如果不支持BLE，则应优雅地禁用任何BLE功能。 如果支持BLE但禁用，那么您可以请求用户在不离开应用程序的情况下启用蓝牙。 使用BluetoothAdapter可以在两个步骤中完成此设置。
-
获取BluetoothAdapterBluetoothAdapter是所有蓝牙活动所必需的。 BluetoothAdapter表示设备自己的蓝牙适配器（蓝牙无线电）。 整个系统有一个蓝牙适配器，您的应用程序可以使用此对象进行交互。 下面的代码片段显示了如何获取适配器。 请注意，此方法使用getSystemService()返回一个BluetoothManager实例，然后用于获取适配器。 Android 4.3（API Level 18）介绍了BluetoothManager：1
private BluetoothAdapter mBluetoothAdapter;23// Initializes Bluetooth adapter.4final BluetoothManager bluetoothManager =5(BluetoothManager) getSystemService(Context.BLUETOOTH_SERVICE);6mBluetoothAdapter = bluetoothManager.getAdapter(); - 启用蓝牙
接下来，您需要确保启用蓝牙。 调用isEnabled()来检查蓝牙是否被启用。 如果此方法返回false，则蓝牙被禁用。 以下片段检查是否启用蓝牙。 如果不是，该片段会显示错误并提示用户进入设置以启用蓝牙：1// Ensures Bluetooth is available on the device and it is enabled. If not,2// displays a dialog requesting user permission to enable Bluetooth.3if (mBluetoothAdapter == null || !mBluetoothAdapter.isEnabled())4{5Intent enableBtIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE);6startActivityForResult(enableBtIntent, REQUEST_ENABLE_BT);7}注意：传递给startActivityForResult(android.content.Intent,int)的REQUEST_ENABLE_BT常量，是系统作为requestCode参数在您的onActivityResult(int,int,android.content.Intent) 实现 中，传回给您的本地定义的整数（必须大于0）。
查找BLE设备
To find BLE devices, you use the startLeScan() method. This method takes a BluetoothAdapter.LeScanCallback as a parameter. You must implement this callback, because that is how scan results are returned. Because scanning is battery-intensive, you should observe the following guidelines:
要查找BLE设备，可以使用startLeScan()方法。 此方法将使用BluetoothAdapter.LeScanCallback作为参数。 您必须实现此回调，因为这是用于定义如何返回扫描结果的方法。 因为扫描是非常消耗电量的，所以您应遵循以下准则：
- 一旦找到所需的设备，请停止扫描。
- 切勿循环扫描，并应该设置扫描时间限制。 以前可用的设备可能已经超出扫描范围，持续的扫描会耗光电池电量。
以下片段显示如何启动和停止扫描：
1
/**
2
* Activity for scanning and displaying available BLE devices.
3
*/
4
public class DeviceScanActivity extends ListActivity
5
{
6
private BluetoothAdapter mBluetoothAdapter;
7
private boolean mScanning;
8
private Handler mHandler;
9
10
// Stops scanning after 10 seconds.
11
private static final long SCAN_PERIOD = 10000;
12
13
private void scanLeDevice(final boolean enable)
14
{
15
if (enable)
16
{
17
// Stops scanning after a pre-defined scan period.
18
mHandler.postDelayed(new Runnable()
19
{
20
@Override
21
public void run()
22
{
23
mScanning = false;
24
mBluetoothAdapter.stopLeScan(mLeScanCallback);
25
}
26
}, SCAN_PERIOD);
27
28
mScanning = true;
29
mBluetoothAdapter.startLeScan(mLeScanCallback);
30
}
31
else
32
{
33
mScanning = false;
34
mBluetoothAdapter.stopLeScan(mLeScanCallback);
35
}
36
37
}
38
39
}
如果您只想扫描特定类型的外设，您可以调用startLeScan(UUID [],BluetoothAdapter.LeScanCallback)，提供一个指定应用程序支持的GATT服务的UUID对象数组。
以下是BluetoothAdapter.LeScanCallback的实现，它是用于传递BLE扫描结果的接口：
1
private LeDeviceListAdapter mLeDeviceListAdapter;
2
3
// Device scan callback.
4
private BluetoothAdapter.LeScanCallback mLeScanCallback =
5
new BluetoothAdapter.LeScanCallback()
6
{
7
@Override
8
public void onLeScan(final BluetoothDevice device, int rssi,
9
byte[] scanRecord)
10
{
11
runOnUiThread(new Runnable()
12
{
13
@Override
14
public void run()
15
{
16
mLeDeviceListAdapter.addDevice(device);
17
mLeDeviceListAdapter.notifyDataSetChanged();
18
}
19
});
20
}
21
};
注意：如蓝牙所述，您只能扫描蓝牙LE设备或扫描经典蓝牙设备。 您无法同时扫描BLE和经典设备。
连接到GATT服务器
与BLE设备交互的第一步是连接到它 - 更具体地说，是连接到设备上的GATT服务器。 要连接到BLE设备上的GATT服务器，可以使用connectGatt()方法。 此方法有三个参数：一个上下文对象，autoConnect（布尔值，指示是否在BLE设备可用时自动连接），以及对BluetoothGattCallback的引用：
1
mBluetoothGatt = device.connectGatt(this, false, mGattCallback);
这个到
GATT服务器的
连接
由BLE设备托管，并返回一个BluetoothGatt实例，然后您可以使用它来进行GATT客户端操作。 调用者（Android应用程式）是GATT客户端。 BluetoothGattCallback用于向客户端提供结果，例如连接状态以及任何进一步的GATT客户端操作。
在此示例中，BLE应用程序提供一个活动（DeviceControlActivity）来连接，显示数据，并显示GATT服务和设备支持的特性。 根据用户输入，此活动与名为BluetoothLeService的服务进行通信，该服务通过Android BLE API与BLE设备进行交互：
1
// A service that interacts with the BLE device via the Android BLE API.
2
public class BluetoothLeService extends Service
3
{
4
private final static String TAG = BluetoothLeService.class.getSimpleName();
5
6
private BluetoothManager mBluetoothManager;
7
private BluetoothAdapter mBluetoothAdapter;
8
private String mBluetoothDeviceAddress;
9
private BluetoothGatt mBluetoothGatt;
10
private int mConnectionState = STATE_DISCONNECTED;
11
12
private static final int STATE_DISCONNECTED = 0;
13
private static final int STATE_CONNECTING = 1;
14
private static final int STATE_CONNECTED = 2;
15
16
public final static String ACTION_GATT_CONNECTED =
17
"com.example.bluetooth.le.ACTION_GATT_CONNECTED";
18
public final static String ACTION_GATT_DISCONNECTED =
19
"com.example.bluetooth.le.ACTION_GATT_DISCONNECTED";
20
public final static String ACTION_GATT_SERVICES_DISCOVERED =
21
"com.example.bluetooth.le.ACTION_GATT_SERVICES_DISCOVERED";
22
public final static String ACTION_DATA_AVAILABLE =
23
"com.example.bluetooth.le.ACTION_DATA_AVAILABLE";
24
public final static String EXTRA_DATA =
25
"com.example.bluetooth.le.EXTRA_DATA";
26
27
public final static UUID UUID_HEART_RATE_MEASUREMENT =
28
UUID.fromString(SampleGattAttributes.HEART_RATE_MEASUREMENT);
29
30
// Various callback methods defined by the BLE API.
31
private final BluetoothGattCallback mGattCallback =
32
new BluetoothGattCallback()
33
{
34
@Override
35
public void onConnectionStateChange(BluetoothGatt gatt, int status,
36
int newState)
37
{
38
String intentAction;
39
if (newState == BluetoothProfile.STATE_CONNECTED)
40
{
41
intentAction = ACTION_GATT_CONNECTED;
42
mConnectionState = STATE_CONNECTED;
43
broadcastUpdate(intentAction);
44
Log.i(TAG, "Connected to GATT server.");
45
Log.i(TAG, "Attempting to start service discovery:" +
46
mBluetoothGatt.discoverServices());
47
48
}
49
else if (newState == BluetoothProfile.STATE_DISCONNECTED)
50
{
51
intentAction = ACTION_GATT_DISCONNECTED;
52
mConnectionState = STATE_DISCONNECTED;
53
Log.i(TAG, "Disconnected from GATT server.");
54
broadcastUpdate(intentAction);
55
}
56
}
57
58
@Override
59
// New services discovered
60
public void onServicesDiscovered(BluetoothGatt gatt, int status)
61
{
62
if (status == BluetoothGatt.GATT_SUCCESS)
63
{
64
broadcastUpdate(ACTION_GATT_SERVICES_DISCOVERED);
65
}
66
else
67
{
68
Log.w(TAG, "onServicesDiscovered received: " + status);
69
}
70
}
71
72
@Override
73
// Result of a characteristic read operation
74
public void onCharacteristicRead(BluetoothGatt gatt,
75
BluetoothGattCharacteristic characteristic,
76
int status)
77
{
78
if (status == BluetoothGatt.GATT_SUCCESS)
79
{
80
broadcastUpdate(ACTION_DATA_AVAILABLE, characteristic);
81
}
82
}
83
84
};
85
86
}
当一个特定的回调被触发时，它调用相应的broadcastUpdate（）辅助方法并传递一个动作。 请注意，本节中的数据解析是根据蓝牙心率测量配置文件规范执行的：
1
private void broadcastUpdate(final String action)
2
{
3
final Intent intent = new Intent(action);
4
sendBroadcast(intent);
5
}
6
7
private void broadcastUpdate(final String action,
8
final BluetoothGattCharacteristic characteristic)
9
{
10
final Intent intent = new Intent(action);
11
12
//这是心率测量配置文件的特殊处理。 根据配置文件规范进行数据解析。
13
if (UUID_HEART_RATE_MEASUREMENT.equals(characteristic.getUuid()))
14
{
15
int flag = characteristic.getProperties();
16
int format = -1;
17
if ((flag & 0x01) != 0)
18
{
19
format = BluetoothGattCharacteristic.FORMAT_UINT16;
20
Log.d(TAG, "Heart rate format UINT16.");
21
}
22
else
23
{
24
format = BluetoothGattCharacteristic.FORMAT_UINT8;
25
Log.d(TAG, "Heart rate format UINT8.");
26
}
27
final int heartRate = characteristic.getIntValue(format, 1);
28
Log.d(TAG, String.format("Received heart rate: %d", heartRate));
29
intent.putExtra(EXTRA_DATA, String.valueOf(heartRate));
30
}
31
else
32
{
33
// 对于所有其他配置文件，写入以十六进制格式化的数据。
34
final byte[] data = characteristic.getValue();
35
if (data != null && data.length > 0)
36
{
37
final StringBuilder stringBuilder = new StringBuilder(data.length);
38
for(byte byteChar : data)
39
stringBuilder.append(String.format("%02X ", byteChar));
40
intent.putExtra(EXTRA_DATA, new String(data) + "\n" +
41
stringBuilder.toString());
42
}
43
}
44
sendBroadcast(intent);
45
}
回到设备控制活动，这些事件由BroadcastReceiver处理：
1
// Handles various events fired by the Service.
2
// ACTION_GATT_CONNECTED: connected to a GATT server.
3
// ACTION_GATT_DISCONNECTED: disconnected from a GATT server.
4
// ACTION_GATT_SERVICES_DISCOVERED: discovered GATT services.
5
// ACTION_DATA_AVAILABLE: received data from the device. This can be a
6
// result of read or notification operations.
7
private final BroadcastReceiver mGattUpdateReceiver = new BroadcastReceiver()
8
{
9
@Override
10
public void onReceive(Context context, Intent intent)
11
{
12
final String action = intent.getAction();
13
if (BluetoothLeService.ACTION_GATT_CONNECTED.equals(action))
14
{
15
mConnected = true;
16
updateConnectionState(R.string.connected);
17
invalidateOptionsMenu();
18
}
19
else if (BluetoothLeService.ACTION_GATT_DISCONNECTED.equals(action))
20
{
21
mConnected = false;
22
updateConnectionState(R.string.disconnected);
23
invalidateOptionsMenu();
24
clearUI();
25
}
26
else if (BluetoothLeService.
27
ACTION_GATT_SERVICES_DISCOVERED.equals(action))
28
{
29
// Show all the supported services and characteristics on the
30
// user interface.
31
displayGattServices(mBluetoothLeService.getSupportedGattServices());
32
}
33
else if (BluetoothLeService.ACTION_DATA_AVAILABLE.equals(action))
34
{
35
displayData(intent.getStringExtra(BluetoothLeService.EXTRA_DATA));
36
}
37
}
38
};
阅读BLE属性
一旦您的Android应用程序连接到GATT服务器并发现服务，它就可以在支持的情况下读取和写入属性。 例如，此代码段遍历服务器的服务和特征，并在UI中显示它们：
1
public class DeviceControlActivity extends Activity
2
{
3
4
//演示如何迭代支持的GATT服务/特性。
5
//在此示例中，我们填充绑定到UI上的ExpandableListView的数据结构。
6
private void displayGattServices(List<BluetoothGattService> gattServices)
7
{
8
if (gattServices == null) return;
9
String uuid = null;
10
String unknownServiceString = getResources().
11
getString(R.string.unknown_service);
12
String unknownCharaString = getResources().
13
getString(R.string.unknown_characteristic);
14
ArrayList<HashMap<String, String>> gattServiceData =
15
new ArrayList<HashMap<String, String>>();
16
ArrayList<ArrayList<HashMap<String, String>>> gattCharacteristicData
17
= new ArrayList<ArrayList<HashMap<String, String>>>();
18
mGattCharacteristics =
19
new ArrayList<ArrayList<BluetoothGattCharacteristic>>();
20
21
// 通过可用的GATT服务循环。
22
for (BluetoothGattService gattService : gattServices)
23
{
24
HashMap<String, String> currentServiceData =
25
new HashMap<String, String>();
26
uuid = gattService.getUuid().toString();
27
currentServiceData.put(
28
LIST_NAME, SampleGattAttributes.
29
lookup(uuid, unknownServiceString));
30
currentServiceData.put(LIST_UUID, uuid);
31
gattServiceData.add(currentServiceData);
32
33
ArrayList<HashMap<String, String>> gattCharacteristicGroupData =
34
new ArrayList<HashMap<String, String>>();
35
List<BluetoothGattCharacteristic> gattCharacteristics =
36
gattService.getCharacteristics();
37
ArrayList<BluetoothGattCharacteristic> charas =
38
new ArrayList<BluetoothGattCharacteristic>();
39
// 循环通过可用特性。
40
for (BluetoothGattCharacteristic gattCharacteristic :
41
gattCharacteristics)
42
{
43
charas.add(gattCharacteristic);
44
HashMap<String, String> currentCharaData =
45
new HashMap<String, String>();
46
uuid = gattCharacteristic.getUuid().toString();
47
currentCharaData.put(
48
LIST_NAME, SampleGattAttributes.lookup(uuid,
49
unknownCharaString));
50
currentCharaData.put(LIST_UUID, uuid);
51
gattCharacteristicGroupData.add(currentCharaData);
52
}
53
mGattCharacteristics.add(charas);
54
gattCharacteristicData.add(gattCharacteristicGroupData);
55
}
56
57
}
58
59
}
接收GATT通知
BLE应用程序通常会在设备上的特定特性发生变化时要求收到通知。 此代码段显示了如何使用setCharacteristicNotification()方法设置特征的通知：
1
private BluetoothGatt mBluetoothGatt;
2
BluetoothGattCharacteristic characteristic;
3
boolean enabled;
4
5
mBluetoothGatt.setCharacteristicNotification(characteristic, enabled);
6
7
BluetoothGattDescriptor descriptor = characteristic.getDescriptor(
8
UUID.fromString(SampleGattAttributes.CLIENT_CHARACTERISTIC_CONFIG));
9
descriptor.setValue(BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE);
10
mBluetoothGatt.writeDescriptor(descriptor);
一旦为特征启用通知，如果远程设备上的特性发生变化，则会触发onCharacteristicChanged()回调：
1
@Override
2
// Characteristic notification
3
public void onCharacteristicChanged(BluetoothGatt gatt,
4
BluetoothGattCharacteristic characteristic)
5
{
6
broadcastUpdate(ACTION_DATA_AVAILABLE, characteristic);
7
}
关闭客户端应用程序
一旦您的应用程序完成使用BLE设备，它应该调用close()，以便系统可以正确释放资源：
1
public void close()
2
{
3
if (mBluetoothGatt == null)
4
{
5
return;
6
}
7
mBluetoothGatt.close();
8
mBluetoothGatt = null;
9
}
另外推荐几篇有关低功耗蓝牙开发的好文章：
Android BLE学习笔记 :
Android BLE基础框架使用详解
蓝牙自动配对：
Android蓝牙自动配对Demo，亲测好使！！！