Harmony Ble蓝牙App（四）描述符

前言

  上一篇中了解了特性和属性，同时显示设备蓝牙服务下的特性和属性，本文中就需要来使用这些特性和属性来完成一些功能。

正文

  上一篇完成了特性，这一篇中我们增加描述符的处理，以及一些简单的优化。

一、优化

  这样看起来主页面在没有设备信息的时候不会显得单调，那么还有一个小细节就是，当设备的蓝牙服务和特性不属于SIG定义的，是厂商自定义时，我们最好就显示完整的UUID，为了方便使用，在BleUtils类中增加如下代码：

	public static final String APP_NAME = "GoodBle";public static final String UNKNOWN_DEVICE = "Unknown device";public static final String UNKNOWN_SERVICE = "Unknown Service";public static final String UNKNOWN_CHARACTERISTICS = "Unknown Characteristics";public static final String UNKNOWN_DESCRIPTOR = "Unknown Descriptor";public static final String BROADCAST = "Broadcast";public static final String READ = "Read";public static final String WRITE_NO_RESPONSE = "Write No Response";public static final String WRITE = "Write";public static final String NOTIFY = "Notify";public static final String INDICATE = "Indicate";public static final String AUTHENTICATED_SIGNED_WRITES = "Authenticated Signed Writes";public static final String EXTENDED_PROPERTIES = "Extended Properties";

  这里定义了一些常量，包括未知服务、未知特性，和一些其他的属性，这样做在修改的时候修改一个常量就可以了。下面我们分别修改一下BleUtils中的getServiceName()和getCharacteristicsName()方法的else的值为UNKNOWN_SERVICE和UNKNOWN_CHARACTERISTICS，剩下的就可以在服务适配器和特性适配器中去修改了，首先是服务适配器，修改

    @Overridepublic Component getComponent(int position, Component component, ComponentContainer componentContainer) {...String serviceName = BleUtils.getServiceName(service.getUuid());holder.txServiceName.setText(serviceName);holder.txUuid.setText(serviceName.equals(BleUtils.UNKNOWN_SERVICE) ? service.getUuid().toString() : BleUtils.getShortUUID(service.getUuid()));return cpt;}

在设置uuid的时候根据服务的名称进行判断，如果是标准的SIG服务则使用短UUID，不是则使用完整的UUID。默认是小写的，你也可以改成大写。

那么同样特性适配器也改一下：

    @Overridepublic Component getComponent(int position, Component component, ComponentContainer componentContainer) {...String characteristicsName = BleUtils.getCharacteristicsName(characteristic.getUuid());holder.txCharacterName.setText(characteristicsName);holder.txUuid.setText(BleUtils.getShortUUID(characteristic.getUuid()));holder.txUuid.setText(characteristicsName.equals(BleUtils.UNKNOWN_CHARACTERISTICS) ? characteristic.getUuid().toString() : BleUtils.getShortUUID(characteristic.getUuid()));return cpt;}

再运行一下，对于未知设备服务和特性的UUID就会显示完整的值。

二、描述

  在上一篇中提到了特性和属性，特性有那些功能是属性决定的，那么描述又是做什么的呢？

① 概念

在蓝牙低功耗（BLE）中，Descriptor（描述符）是用于提供有关特征值的额外信息的数据结构。Descriptor 提供了特定特征的更详细描述和配置选项。Descriptor 是特征（Characteristics）的子项，用于描述特征的特定属性或行为。每个特征可以有一个或多个 Descriptor。

以下是一些常见的 BLE Descriptor 类型及其含义：

1. 声明 Descriptor：这个 Descriptor 用于描述特征的声明信息，包括特征的唯一标识符、权限、值的格式和其他标志。它提供了特征的基本信息供其他设备了解。

2. 用户描述（User Description）Descriptor：用于提供特征的人类可读描述信息。这个描述可以是特征的名称、标签或其他有关特征的说明性文字。

3. 配置 Descriptor：用于描述特征的配置选项。这个 Descriptor 可以包含特征的可选设置，例如采样率、测量单位或阈值等。

4. 通知 Descriptor：用于配置特征是否支持通知功能。这个 Descriptor 可以用于使设备可以接收特征值变化的通知。

5. 线性区间 Descriptor：用于描述特征值的线性关系，例如数值范围和步长等。

6. 客户端配置 Descriptor：用于允许远程设备（例如中心设备）订阅特征值的变化通知，这个很重要。
   这些只是一些常见的 BLE Descriptor 类型和其含义的示例，实际上可以根据应用需求定义自定义的 Descriptor。

   Descriptor 提供了对特征更详细的描述和配置，它们可以通过蓝牙协议进行传输和访问。在 BLE 应用中，Descriptor 充当了配置和元数据信息的重要角色，帮助设备之间准确地交换和理解数据。

那么现在你已经了解了描述符的作用了，而我们目前的特性下还没有描述符的，注意不是每一个特性都有描述符，下面我们就来把描述符写出来了。首先我们在item_characteristic.xml中增加一个描述的列表控件，代码如下所示：

<?xml version="1.0" encoding="utf-8"?>
<DependentLayoutxmlns:ohos="http://schemas.huawei.com/res/ohos"ohos:height="match_content"ohos:width="match_parent"ohos:background_element="#FFFFFF"ohos:bottom_margin="2vp"ohos:bottom_padding="8vp"ohos:end_padding="16vp"ohos:start_padding="16vp"ohos:top_padding="8vp"><Textohos:id="$+id:tx_character_name"ohos:height="match_content"ohos:width="match_content"ohos:background_element="$color:black"ohos:text="服务"ohos:text_size="16fp"/><Textohos:id="$+id:tx_uuid_title"ohos:height="match_content"ohos:width="match_content"ohos:below="$id:tx_character_name"ohos:text="UUID："ohos:text_color="$color:gray"ohos:text_size="16fp"ohos:top_margin="2vp"/><Textohos:id="$+id:tx_uuid"ohos:height="match_content"ohos:width="match_content"ohos:background_element="$color:black"ohos:below="$id:tx_character_name"ohos:end_of="$id:tx_uuid_title"ohos:text="UUID"ohos:text_size="16fp"ohos:top_margin="2vp"/><Textohos:id="$+id:tx_property_title"ohos:height="match_content"ohos:width="match_content"ohos:below="$id:tx_uuid_title"ohos:text="Properties："ohos:text_color="$color:gray"ohos:text_size="16fp"ohos:top_margin="2vp"/><ListContainerohos:id="$+id:lc_property"ohos:height="match_content"ohos:width="match_parent"ohos:align_bottom="$id:tx_property_title"ohos:align_top="$id:tx_property_title"ohos:end_of="$id:tx_property_title"ohos:orientation="horizontal"/><DirectionalLayoutohos:id="$+id:lay_descriptors"ohos:height="match_content"ohos:width="match_parent"ohos:below="$id:tx_property_title"ohos:orientation="vertical"><Textohos:height="match_content"ohos:width="match_content"ohos:text="Descriptors:"ohos:text_color="#000000"ohos:text_size="16fp"ohos:top_margin="2vp"/><ListContainerohos:id="$+id:lc_descriptor"ohos:height="match_content"ohos:width="match_parent"/></DirectionalLayout></DependentLayout>

下面我们就可以正式去写描述符的提供者了。

② 描述提供者

  首先在layout下增加一个item_descriptor.xml，代码如下所示：

<?xml version="1.0" encoding="utf-8"?>
<DependentLayoutxmlns:ohos="http://schemas.huawei.com/res/ohos"ohos:height="match_content"ohos:width="match_parent"ohos:background_element="#FFFFFF"ohos:bottom_margin="2vp"ohos:bottom_padding="4vp"ohos:top_padding="4vp"><Textohos:id="$+id:tx_descriptor_name"ohos:height="match_content"ohos:width="match_content"ohos:background_element="$color:black"ohos:text="描述"ohos:text_size="16fp"/><Textohos:id="$+id:tx_uuid_title"ohos:height="match_content"ohos:width="match_content"ohos:below="$id:tx_descriptor_name"ohos:text="UUID："ohos:text_color="$color:gray"ohos:text_size="16fp"ohos:top_margin="2vp"/><Textohos:id="$+id:tx_uuid"ohos:height="match_content"ohos:width="match_content"ohos:background_element="$color:black"ohos:below="$id:tx_descriptor_name"ohos:end_of="$id:tx_uuid_title"ohos:text="UUID"ohos:text_size="16fp"ohos:top_margin="2vp"/></DependentLayout>

然后关于描述符的名称，我们可以在BleUtils中写一个函数，代码如下所示：

    public static String getDescriptorName(UUID uuid) {String targetUuid = getShortUUID(uuid);switch (targetUuid) {case "0x2900":return "Characteristic Extended Properties";case "0x2901":return "Characteristic User Description";case "0x2902":return "Client Characteristic Configuration";case "0x2903":return "Server Characteristic Configuration";case "0x2904":return "Characteristic Presentation Format";case "0x2905":return "Characteristic Aggregate Format";case "0x2906":return "Valid Range";case "0x2907":return "External Report Reference";case "0x2908":return "Report Reference";case "0x2909":return "Number of Digitals";case "0x290A":return "Value Trigger Setting";case "0x290B":return "Environmental Sensing Configuration";case "0x290C":return "Environmental Sensing Measurement";case "0x290D":return "Environmental Sensing Trigger Setting";case "0x290E":return "Time Trigger Setting";case "0x290F":return "Complete BR-EDR Transport Block Data";case "0x2910":return "Observation Schedule";case "0x2911":return "Valid Range and Accuracy";default:return UNKNOWN_DESCRIPTOR;}}

  下面我们写描述符适配器，在provider包下新建一个DescriptorProvider类，代码如下所示：

public class DescriptorProvider extends BaseItemProvider {private final List<GattDescriptor> descriptorList;private final AbilitySlice slice;public DescriptorProvider(List<GattDescriptor> list, AbilitySlice slice) {this.descriptorList = list;this.slice = slice;}@Overridepublic int getCount() {return descriptorList == null ? 0 : descriptorList.size();}@Overridepublic Object getItem(int position) {if (descriptorList != null && position >= 0 && position < descriptorList.size()) {return descriptorList.get(position);}return null;}@Overridepublic long getItemId(int position) {return position;}@Overridepublic Component getComponent(int position, Component component, ComponentContainer componentContainer) {final Component cpt;DescriptorHolder holder;GattDescriptor descriptor = descriptorList.get(position);if (component == null) {cpt = LayoutScatter.getInstance(slice).parse(ResourceTable.Layout_item_descriptor, null, false);holder = new DescriptorHolder(cpt);//将获取到的子组件信息绑定到列表项的实例中cpt.setTag(holder);} else {cpt = component;// 从缓存中获取到列表项实例后，直接使用绑定的子组件信息进行数据填充。holder = (DescriptorHolder) cpt.getTag();}String descriptorName = BleUtils.getDescriptorName(descriptor.getUuid());holder.txDescriptorName.setText(descriptorName);holder.txUuid.setText(descriptorName.equals(BleUtils.UNKNOWN_DESCRIPTOR) ? descriptor.getUuid().toString() : BleUtils.getShortUUID(descriptor.getUuid()));return cpt;}/*** 用于保存列表项的子组件信息*/public static class DescriptorHolder {Text txDescriptorName;Text txUuid;ListContainer lcProperty;public DescriptorHolder(Component component) {txDescriptorName = (Text) component.findComponentById(ResourceTable.Id_tx_descriptor_name);txUuid = (Text) component.findComponentById(ResourceTable.Id_tx_uuid);lcProperty = (ListContainer) component.findComponentById(ResourceTable.Id_lc_property);}}
}

可以看这里的代码同样对于自定义UUID展示完整数据，对于SIG的展示短UUID。

③ 显示描述符

  接下来就是在特性适配器中去加载显示描述符数据，修改CharacteristicProvider中代码，所示代码：

public class CharacteristicProvider extends BaseItemProvider {private final List<GattCharacteristic> characteristicList;private final AbilitySlice slice;private final OperateCallback operateCallback;public CharacteristicProvider(List<GattCharacteristic> list, AbilitySlice slice, OperateCallback operateCallback) {this.characteristicList = list;this.slice = slice;this.operateCallback = operateCallback;}@Overridepublic int getCount() {return characteristicList == null ? 0 : characteristicList.size();}@Overridepublic Object getItem(int position) {if (characteristicList != null && position >= 0 && position < characteristicList.size()) {return characteristicList.get(position);}return null;}@Overridepublic long getItemId(int position) {return position;}@Overridepublic Component getComponent(int position, Component component, ComponentContainer componentContainer) {final Component cpt;CharacteristicHolder holder;GattCharacteristic characteristic = characteristicList.get(position);if (component == null) {cpt = LayoutScatter.getInstance(slice).parse(ResourceTable.Layout_item_characteristic, null, false);holder = new CharacteristicHolder(cpt);//将获取到的子组件信息绑定到列表项的实例中cpt.setTag(holder);} else {cpt = component;// 从缓存中获取到列表项实例后，直接使用绑定的子组件信息进行数据填充。holder = (CharacteristicHolder) cpt.getTag();}String characteristicsName = BleUtils.getCharacteristicsName(characteristic.getUuid());holder.txCharacterName.setText(characteristicsName);holder.txUuid.setText(BleUtils.getShortUUID(characteristic.getUuid()));holder.txUuid.setText(characteristicsName.equals(BleUtils.UNKNOWN_CHARACTERISTICS) ? characteristic.getUuid().toString() : BleUtils.getShortUUID(characteristic.getUuid()));List<String> properties = BleUtils.getProperties(characteristic.getProperties());//加载属性holder.lcProperty.setItemProvider(new PropertyProvider(properties, slice));//属性列表点击holder.lcProperty.setItemClickedListener((listContainer, component1, propertyPosition, l) -> {if (operateCallback != null) {//属性操作回调operateCallback.onPropertyOperate(characteristic, properties.get(propertyPosition));}});//加载特性下的描述if (characteristic.getDescriptors().size() > 0) {holder.lcDescriptor.setItemProvider(new DescriptorProvider(characteristic.getDescriptors(), slice));} else {holder.layDescriptor.setVisibility(Component.HIDE);}return cpt;}/*** 用于保存列表项的子组件信息*/public static class CharacteristicHolder {Text txCharacterName;Text txUuid;ListContainer lcProperty;DirectionalLayout layDescriptor;ListContainer lcDescriptor;public CharacteristicHolder(Component component) {txCharacterName = (Text) component.findComponentById(ResourceTable.Id_tx_character_name);txUuid = (Text) component.findComponentById(ResourceTable.Id_tx_uuid);lcProperty = (ListContainer) component.findComponentById(ResourceTable.Id_lc_property);layDescriptor = (DirectionalLayout) component.findComponentById(ResourceTable.Id_lay_descriptors);lcDescriptor = (ListContainer) component.findComponentById(ResourceTable.Id_lc_descriptor);}}
}

请注意这一段代码：

        //加载特性下的描述if (characteristic.getDescriptors().size() > 0) {holder.lcDescriptor.setItemProvider(new DescriptorProvider(characteristic.getDescriptors(), slice));} else {holder.layDescriptor.setVisibility(Component.HIDE);}

  这个判断和重要，因为不是每一个特性都有描述符，这个前面已经说过了，没有的我们就直接隐藏对应的描述符布局，否则就加载描述符数据，同时我们还需要修改一下服务UUID和特性UUID的Text控件的属性，因为UUID过长的话可能一行无法显示出来。

改动如下：

服务uuid：

        <Textohos:id="$+id:tx_uuid"ohos:height="match_content"ohos:width="match_content"ohos:background_element="$color:black"ohos:below="$id:tx_service_name"ohos:truncation_mode="ellipsis_at_middle"ohos:end_margin="24vp"ohos:text="UUID"ohos:end_of="$id:tx_uuid_title"ohos:align_end="$id:iv_state"ohos:text_size="16fp"ohos:top_margin="2vp"/>

特性uuid：

    <Textohos:id="$+id:tx_uuid"ohos:height="match_content"ohos:width="match_content"ohos:background_element="$color:black"ohos:below="$id:tx_character_name"ohos:end_of="$id:tx_uuid_title"ohos:truncation_mode="ellipsis_at_middle"ohos:text="UUID"ohos:text_size="16fp"ohos:top_margin="2vp"/>

下面运行看一下。

通过这个图就可以清晰的的看到特性下的描述符，本文就到这里了。

三、源码

如果对你有所帮助的话，不妨 Star 或 Fork，山高水长，后会有期~

源码地址：HarmonyBle-Java