最新版拓展下载:
edu.mit.appinventor.ble-20240822.aix
低功耗蓝牙,也称为蓝牙LE 或简称 BLE,是一种类似于经典蓝牙的新通信协议,不同之处在于它旨在消耗更少的功耗和成本,同时保持同等的功能。
因此,低功耗蓝牙是与耗电资源有限的物联网设备进行通信的首选。BluetoothLE 扩展需要 Android 5.0 或更高版本。
2种通信方式:扫描和广播
扫描
详细接入步骤:
开始扫描 -> 获取BLE设备列表 -> 连接指定设备(也可指定MAC地址连接)-> 设备指定服务uuid和特征uuid 发送 / 接收 数据。
广播
现在常规便宜芯片并无蓝牙协议栈,只能通过人工拼包用最简单的蓝牙广播方式通信,可以做到手机与设备进行简单的交互。
- 无连接的
- 是单向的,可以向任何人或者接收器发送数据。
- 使用广播方式通信没有任何安全措施,任何监听设备都能收到,因此它可能不适合于敏感数据,除非在广播数据中采用某种加密方法。
详细接入步骤:
设置广播扫描周期 -> 广播扫描 -> 获取广播设备列表 -> 获取设备服务uuids列表 -> 设备指定服务uuid 发送 / 接收 广播数据。
更深入的通信原理请参考:《BLE协议—广播和扫描》。
属性
-
AutoReconnect
– 如果为真
,App将尝试重连已断开的设备(比如:距离过大导致的连接断开等)。注意:这不适用于通过调用Disconnect
方法断开的连接,这类断开连接需要通过调用Connect
或ConnectWithAddress
进行重新连接。 -
ConnectedDeviceName
– 已连接设备的广播名称。如果没有连接任何设备或不支持低功耗蓝牙,则返回空字符串。 -
ConnectedDeviceRssi
– 返回连接设备的 RSSI(Received Signal Strength Indicator:接收信号强度指示)。 -
ConnectionTimeout
– 建立连接的超时时间(单位:秒):调用Connect
或ConnectWithAddress
后,BluetoothLE 组件等待与设备建立连接的时间(以秒为单位),如果在给定的时间内未建立连接,则将中止尝试并触发ConnectionFailed
事件。 -
DeviceCharacteristics
– 已连接设备所广播的每个特征对应的三元组列表,包含服务UUID、特征UUID 和特征名称(如果有)。列表格式为 ((服务 1 特征 1 名称 1) (服务 2 特征 2 名称 2) …)。如果未连接任何设备或不支持低功耗蓝牙,则将返回空列表。 -
DeviceServices
– 键值对列表,每个广播服务对应一个键值对:服务UUID 及 服务名称(如果有)。列表的格式为 ((uuid1 name1) (uuid2 name2) …)。如果没有连接任何设备或不支持低功耗蓝牙,则将返回一个空列表。 -
NoLocationNeeded
– 启用此选项用以申明你的App不使用蓝牙来获取位置信息。如果启用,编译后的App将不需要请求ACCESS_FINE_LOCATION
权限,扩展程序也不会尝试请求这个权限。(此属性仅“界面设计”视图可用)
-
NullTerminateStrings
– 指示 BluetoothLE 组件在向连接的设备发送字符串数据时,是否以\0
空字节(真
)或不以\0
空字节(假
)结束字符串。
方法
-
AdvertisementData
– 返回指定地址设备相关的广播数据。参数:
-
AdvertiserAddress
– 返回指定名称的设备MAC地址。参数:
deviceName
(text) — 目标BLE设备的广播名称。
-
AdvertiserServiceUuids
– 返回广播设备上可用的服务列表。参数:
deviceAddress
(text) — 目标BLE设备的MAC地址。
-
CanReadCharacteristic
– 测试指定的特征是否可以读取。参数:
-
CanRegisterForCharacteristic
– 测试指定的特征是否可用于注册通知。参数:
-
CanWriteCharacteristic
– 测试指定的特征是否可以写入。参数:
-
CanWriteCharacteristicWithResponse
– 测试指定的特征是否可以通过设备确认进行写入。参数:
-
CharacteristicByIndex
– 从已连接设备支持的特征列表中返回指定索引的特征UUID,索引从 1 开始。参数:
index
(number) — 特征的索引,必须介于 1 和特征列表的长度之间。
-
Connect
– 使用Connect
方法连接到设备列表中指定索引处的BLE设备。参数:
index
(number) — 目标设备的索引,必须介于 1 和列表长度之间。
-
ConnectToDeviceType
– 连接到使用name
和device
指定的已发现的正在广播的第一个设备。参数:
-
ConnectToDeviceWithServiceAndName
– 连接到使用name
和serviceUuid
指定的已发现的正在广播的第一个设备。参数:
-
ConnectWithAddress
– 如果已知BLE设备的MAC地址(如:已存储并从微数据库中读取),则使用ConnectWithAddress
方法连接到该设备。如果设备列表中没有任何设备与给定MAC地址匹配,则将触发ConnectionFailed
事件。否则,如果连接成功,则将触发Connected
事件。参数:
address
(text) — 目标设备的 MAC 地址,格式为12:34:56:78:90:ab
-
DisconnectWithAddress
– 断开指定MAC地址的已连接的BLE设备。参数:
address
(text) — 要断开连接的设备MAC地址,格式为12:34:56:78:90:ab
-
FoundDeviceAddress
– 获取设备列表中指定索引处设备的MAC地址。索引为BLE设备列表中的位置,从 1 开始。参数:
index
(number) — 已发现设备索引,必须介于 1 和设备列表的长度之间。
-
FoundDeviceName
– 获取设备列表中指定索引处设备的名称。参数:
index
(number) — 已发现设备索引,必须介于 1 和设备列表的长度之间。
-
FoundDeviceRssi
–获取设备列表中指定索引处设备的接收信号强度指示 (RSSI)。返回值将介于 -100 和 0 之间,表示连接强度。参数:
index
(number) — 已发现设备索引,必须介于 1 和设备列表的长度之间。
-
GetCharacteristicsForService
– 返回指定服务所支持的特征列表。该列表包含服务UUID 提供的每个特征的 (UUID, 名称) 键值对。参数:
serviceUuid
(text) — 在读取或注册调用中传递的服务UUID。
-
ReadBytes
– 从连接的BLE设备中读取一个或多个 8-bit (1 字节)整型值。服务UUID和特征UUID是必需的。signed
参数指示在转换为 App Inventor数字 时是否应将字节解释为有符号值。读取字节后,将触发BytesReceived
事件。参数:
-
ReadConnectedRssi
– 启动对已连接设备的接收信号强度指示 (RSSI) 的读取。结果值将通过RssiChanged
事件中参数给出。 -
ReadFloats
– 从连接的BLE设备读取一个或多个 IEEE 754 浮点数。服务UUID和特征UUID是必需的。shortFloat
参数指示浮点数是 16 位半精度浮点数还是 32 位单精度浮点数。读取浮点数后,将触发FloatsReceived
事件。参数:
-
ReadIntegers
– 从连接的BLE设备读取一个或多个 32-bit (4 字节)整型值。服务UUID和特征UUID是必需的。signed
参数指示在转换为 App Inventor数字 时是否应将整数解释为有符号值。读取整数后,将触发IntegersReceived
事件。参数:
-
ReadShorts
– 从连接的BLE设备读取一个或多个 16-bit (2 字节)短整型值。服务UUID和特征UUID是必需的。signed
参数指示在转换为 App Inventor数字 时是否应将 short短整型值 解释为有符号值。读取 short短整型值 后,将触发ShortsReceived
事件。参数:
-
ReadStrings
– 从连接的BLE设备读取一个或多个 以\0
空字节结尾的字符串。服务UUID和特征UUID是必需的。utf16
参数指示在转换为 App Inventor字符串 时是否应将内容解码为 UTF-16(真
)或 UTF-8(假
)编码格式。读取字符串后,将触发StringsReceived
事件。参数:
-
RegisterForBytes
– 注册用以在已连接BLE设备的一个或多个 8-bit(单字节)整型值发生变化时接收更新。服务UID 和特性UUID 是必需的。signed
参数指示在转换为 App Inventor数字 时是否应将字节解释为有符号值。每当收到更改时,将触发BytesReceived
事件。参数:
-
RegisterForFloats
– 注册用以在已连接BLE设备的一个或多个 IEEE 754 浮点数发生变化时接收更新。服务UID 和特性UUID 是必需的。shortFloat
参数指示浮点数是 16 位半精度浮点数还是 32 位单精度浮点数。每当收到更改时,就会触发FloatsReceived
事件。参数:
-
RegisterForIntegers
– 注册用以在已连接BLE设备的一个或多个 32-bit (4 字节)整型值发生变化时接收更新。服务UID 和特性UUID 是必需的。signed
参数指示在将整数转换为 App Inventor数字 时是否应将其解释为有符号值。每当收到更改时,都会触发IntegersReceived
事件。参数:
-
RegisterForShorts
– 注册用以在已连接BLE设备的一个或多个 16-bit (2 字节)短整型值发生变化时接收更新。服务UID 和特性UUID 是必需的。signed
参数指示在转换为 App Inventor数字 时是否应将 short短整型值 解释为有符号值。每当收到更改时,就会触发ShortsReceived
事件。参数:
-
RegisterForStrings
– 注册用以在已连接BLE设备的一个或多个 以\0
空字节结尾的字符串 发生更改时接收更新。服务UID 和特性UUID 是必需的。utf16
参数指示在转换为 App Inventor字符串 时是否应将内容解码为 UTF-16(真
)或 UTF-8(假
)编码格式。每当收到更改时,都会触发StringsReceived
事件。参数:
-
RequestMTU
– 为 BluetoothLE 连接请求新的最大传输单元 (MTU)。此功能仅在两个设备都支持蓝牙 4.2 或更高版本时才受支持。如果 MTU 更改成功,则 MTUChanged 事件将被触发。默认 MTU 为 20。此块适用于需要更改 BLE 设备之间发送的消息大小的高级应用。大多数开发人员不需要调整此值。
- MTU: 最大传输单元(MAXIMUM TRANSMISSION UNIT) , 指在一个PDU (Protocol Data Unit: 协议数据单元,在一个传输单元中的有效传输数据)能够传输的最大数据量(多少字节可以一次性传输到对方)。
- MTU 交换是为了在主从双方设置一个PDU中最大能够交换的数据量,通过MTU的交换和双方确认(注意这个MTU是不可以协商的,只是通知对方,双方在知道对方的极限后会选择一个较小的值作为以后的MTU,比如说,主设备发出一个150个字节的MTU请求,但是从设备回应MTU是23字节,那么今后双方要以较小的值23字节作为以后的MTU),主从双方约定每次在做数据传输时不超过这个最大数据单元。
- 更多MTU技术内幕请参考《一分钟读懂低功耗蓝牙(BLE) MTU交换数据包》。
参数:
bytes
(number) — 期望的 MTU 大小(单位:字节)。
-
ScanAdvertisements
– 扫描广播BLE设备。参数:
scanPeriod
(number) — 扫描所需的时间(单位:毫秒 ms)。
-
ScanForDevice
– 扫描特定类型的设备。设备组件必须实现 BLEDevice 接口才能使此方法正常工作。参数:
param
(component) — 需要特定服务的组件块。
-
ScanForService
– 通过服务UUID扫描 广播特定BLE服务 的设备。参数:
serviceUuid
(text) — 目标BLE设备的广播服务UUID。
-
ServiceByIndex
– 返回服务列表中给定索引处的服务UUID。参数:
index
(number) — 所需服务的索引,必须介于 1 和服务列表的长度之间。
-
StartAdvertising
– 创建并发布蓝牙低功耗广播。参数:
-
StopAdvertising
– 停止蓝牙低功耗广播(之前调用StartAdvertising
的广播)。 -
UnregisterForValues
– 取消注册指定的服务和特征的更新。参数:
-
WriteBytes
– 将一个或多个 8-bit 整数值写入已连接的BLE设备。服务UID 和特性UUID 是必需的。参数可以是 单个数值 或 数值列表。如果signed
为真
,则可接受的值介于 -128 和 127 之间。如果signed
为假
,则可接受的值介于 0 和 255 之间。参数:
-
WriteBytesWithResponse
– 将一个或多个 8-bit 整数值写入已连接的BLE设备,并等待通过BytesWritten
事件确认。服务UID 和特性UUID 是必需的。参数可以是 单个数值 或 数值列表。如果signed
为真
,则可接受的值介于 -128 和 127 之间。如果signed
为假
,则可接受的值介于 0 和 255 之间。参数:
-
WriteFloats
– 将一个或多个 IEEE 754 浮点数写入已连接的BLE设备。服务UID 和特性UUID 是必需的。参数可以是 单个浮点值 或 浮点值列表。如果shortFloat
为真
,则每个数值将被压缩以适合 16 位半精度浮点值。如果shortFloat
为假
,则每个数值将作为 32 位单精度浮点值发送。参数:
-
WriteFloatsWithResponse
– 将一个或多个 IEEE 754 浮点值写入已连接的BLE设备,并等待通过FloatsWritten
事件确认。服务UID 和特性UUID 是必需的。参数可以是 单个浮点值 或 浮点值列表。如果shortFloat
为假
,则每个数值将作为 32 位单精度浮点值发送。参数:
-
WriteIntegers
– 将一个或多个 32 位整型值写入已连接的BLE设备。服务UID 和特性UUID 是必需的。参数可以是 单个数值 或 数值列表。如果signed
为真
,则可接受的值介于 -2147483648 和 2147483647 之间。如果signed
为假
,则可接受的值介于 0 和 4294967295 之间。参数:
-
WriteIntegersWithResponse
– 将一个或多个 32 位整型值写入连接的BLE设备,并等待通过IntegersWritten
事件确认。服务UID 和特性UUID 是必需的。参数可以是 单个数值 或 数值列表。如果signed
为真
,则可接受的值介于 -2147483648 和 2147483647 之间。如果signed
为假
,则可接受的值介于 0 和 4294967295 之间。参数:
-
WriteShorts
– 将一个或多个 16 位短整型值写入已连接的BLE设备。服务UID 和特性UUID 是必需的。参数可以是 单个数值 或 数值列表。如果signed
为真
,则可接受的值介于 -32768 和 32767 之间。如果signed
为假
,则可接受的值介于 0 和 65535 之间。参数:
-
WriteShortsWithResponse
– 将一个或多个 16 位短整型值写入连接的BLE设备,并等待通过ShortsWritten
事件确认。服务UID 和特性UUID 是必需的。参数可以是 单个数值 或 数值列表。如果signed
为真
,则可接受的值介于 -32768 和 32767 之间。如果signed
为假
,则可接受的值介于 0 和 65535 之间。参数:
-
WriteStrings
– 将一个或多个字符串写入已连接的BLE设备。服务UID 和特性UUID 是必需的。参数可以是 单个字符串 或 字符串列表。如果utf16
为真
,则将使用 UTF-16 小端序(little endian)编码发送字符串。如果utf16
为假
,则将使用 UTF-8 编码发送字符串。参数:
-
WriteStringsWithResponse
– 将一个或多个字符串写入已连接的BLE设备,并等待通过StringsWritten
事件确认。服务UID 和特性UUID 是必需的。参数可以是 单个字符串 或 字符串列表。如果utf16
为真
,则将使用 UTF-16 小端序(little endian)编码发送字符串。如果utf16
为假
,则将使用 UTF-8 编码发送字符串。参数:
事件
-
BytesReceived
– 当从连接的蓝牙BLE设备接收到一个或多个字节值时,将触发该事件。根据上次调用ReadBytes
或RegisterForBytes
时给定的serviceUuid
和characteristicUuid
的sign
参数,byteValues
列表将包含从 -128 到 127 (signed = true
) 或 0 到 255 (signed = false
) 的数字。参数:
-
BytesWritten
– 当将一个或多个字节值写入连接的蓝牙设备时,将触发该事件。byteValues
将是实际写入设备的值列表。如果原始输入太长而无法放入单个传输单元(通常为 23 个字节),则情况可能会有所不同。参数:
-
Connected
– App成功连接到BLE设备后,将触发该事件。这可能是调用Connect
或ConnectWithAddress
的结果,或者如果在请求连接时AutoReconnect
属性为真
,则可能是自动重新连接的结果。 -
ConnectionFailed
– 当尝试连接设备失败时,将触发该事件。如果提供了具体的失败原因,则会通过reason
参数给出。参数:
reason
(text) — 连接失败的原因(如果有)。
-
Disconnected
– 当BLE设备断开连接时,将触发该事件。这可能是由于调用Disconnect
或DisconnectWithAddress
引起的,或者在设备移开或重置以致发生连接丢失后引起的。 -
FloatsReceived
– 当从连接的蓝牙设备接收到一个或多个 IEEE 754 浮点值时,将触发该事件。根据上次调用ReadFloats
或RegisterForFloats
的shortFloat
参数(对于给定的serviceUuid
和characteristicUuid
),floatValues
列表 将包含从 -65504.0 到 65504.0(shortFloat = true
)或 -3.402823466E38 到 3.402823466E38(shortFloat = false
)的数字。参数:
-
FloatsWritten
– 当将一个或多个 IEEE 754 浮点值写入连接的蓝牙设备时,将触发该事件。floatValues
将是实际写入设备的值列表。如果原始输入太长而无法放入单个传输单元(通常为 11 个短浮点数或 5 个常规浮点数),则情况可能会有所不同。参数:
-
IntegersReceived
– 当从连接的蓝牙设备接收到一个或多个 32-bit 整型数值时,将触发该事件。根据上次调用ReadIntegers
或RegisterForIntegers
时给定serviceUuid
和characteristicUuid
的sign
参数,intValues
列表将包含从 -2147483648 到 2147483647 (signed = true
) 或 0 到 4294967296 (signed = false
) 的数字。参数:
-
IntegersWritten
– 当将一个或多个 32-bit 整型数值写入连接的蓝牙设备时,将触发该事件。intValues
将是实际写入设备的值列表。如果原始输入太长而无法放入单个传输单元(通常为 5 个整数),则情况可能会有所不同。参数:
-
MTUChanged
– 当BLE设备将其最大传输单元 (MTU) 成功更改为不同的值时,将触发该事件。此事件为RequestMTU
方法块调用时的响应。参数:
bytes
(number) — 新的 MTU 的大小(以字节为单位)。
-
ShortsReceived
– 当从连接的蓝牙设备接收到一个或多个短整型值时,将触发该事件。根据上次调用ReadShorts
或RegisterForShorts
时给定的serviceUuid
和characteristicUuid
的sign
参数,shortValues
列表将包含从 -32768 到 32767 (signed = true
) 或 0 到 65535 (signed = false
) 的数字。参数:
-
ShortsWritten
– 当将一个或多个短整数值写入连接的蓝牙设备时,将触发该事件。shortValues
将是实际写入设备的值列表。如果原始输入太长而无法放入单个传输单元(通常为 11 个短整数),则情况可能会有所不同。参数:
-
StringsReceived
– 当从连接的蓝牙设备接收到一个或多个字符串时,将触发该事件。根据上次调用ReadStrings
或RegisterForStrings
时给定的serviceUuid
和characteristicUuid
的utf16
参数,stringValues
列表将包含 UTF-16 小端序 (utf16 = true
) 或 UTF-8 解码 (utf16 = false
) 字符串。字符串长度受蓝牙设备的最大传输单元 (MTU) 限制,通常为 23 个字节。参数:
-
StringsWritten
– 当将一个或多个字符串写入连接的蓝牙设备时,将触发该事件。stringValues
将是实际写入设备的值列表。如果原始输入太长而无法放入单个传输单元(通常为 22 个字节),则情况可能会有所不同。参数: