设备管理

本文介绍设备信息的获取和管理能力等安卓版接口信息。包含设备初始化、设备监听、设备控制、查询设备信息、修改设备名称、移除设备、设备恢复出厂设置、查询 Wi-Fi 信号强度、回收设备资源等。

功能说明

• 设备相关的返回数据都采用异步消息的方式通知接收者。

• 同时，也提供了控制指令下发，设备固件升级的接口。

• IThingDevice 类提供了设备状态通知能力，通过注册回调函数，您可以方便的获取设备数据接受、设备移除、设备上下线、手机网络变化的通知。

• IThingGateway 类提供了 Zigbee 网关相关的操作，包括控制、查询和监听子设备状态的能力。

• DeviceBean 数据类型：

  属性	类型	说明
  devId	String	设备 ID。
  name	String	设备名称。
  iconUrl	String	图标地址。
  schema	String	设备控制数据点的类型信息。
  productId	String	产品 ID，同一个产品 ID 的设备的 schema 信息一致。
  timezoneId	String	设备所在的时区。
  category	String	设备类型。
  pv	String	网关协议版本。
  bv	String	网关通用固件版本。
  time	Long	设备激活时间。
  schemaMap	Map	schema 的缓存数据。
  dps	Map	设备功能点数据信息。key 是 DP ID，value 是取值。详情请参考 设备功能点 章节。
  getIsOnline	Boolean	设备是否在线，指局域网或者云端在线。
  isLocalOnline	Boolean	设备的局域网在线状态。
  supportGroup	Boolean	设备是否支持群组，如果不支持请到 涂鸦开发者平台 开启此功能。
  isShare	Boolean	是否是分享的设备。
  virtual	Boolean	是否是虚拟设备。
  isZigBeeWifi	Boolean	是否是 Zigbee 网关设备。
  hasZigBee	Boolean	是否有 Zigbee 设备。
  nodeId	String	用于网关和子设备类型的设备。属于子设备的一个属性，标识其短地址 ID，一个网关的子设备的 nodeId 都是唯一的。
  meshId	String	用于网关和子设备类型的设备。属于子设备的一个属性，标识其网关 ID。
  lon	String	设备所在经度信息。
  lat	String	设备所在纬度信息。

  注意：设备控制时，如果涉及到经纬度 lon 和 lat，请在配网前调用 setLatAndLong 设置经纬度：

  ThingSdk.setLatAndLong(String latitude, String longitude)
  

初始化设备

初始化设备控制类

根据设备 ID 初始化设备控制类 IThingDevice。

ThingOSDevice.newDeviceInstance(String devId);

参数说明

参数	说明
devId	设备 ID。

Java 示例

IThingDevice mDevice = ThingOSDevice.newDeviceInstance(deviceBean.getDevId());

监听设备

注册设备监听

IThingDevice 提供设备相关信息的监听，包含：

• DP 数据
• 设备名称
• 设备在线状态和设备移除

void IThingDevice.registerDevListener(IDevListener listener);

参数说明

参数	说明
listener	设备状态监听

IDevListener 接口

public interface IDevListener {

    /**
     * DP 数据更新
     *
     * @param devId 设备 ID
     * @param dpStr 设备发生变动的功能点，为 JSON 字符串，数据格式：{"101": true}
     */
    void onDpUpdate(String devId, String dpStr);

    /**
     * 设备移除回调
     *
     * @param devId 设备id
     */
    void onRemoved(String devId);

    /**
     * 设备上下线回调。如果设备断电或断网，服务端将会在3分钟后回调到此方法。
     *
     * @param devId  设备 ID
     * @param online 是否在线，在线为 true
     */
    void onStatusChanged(String devId, boolean online);

    /**
     * 网络状态发生变动时的回调
     *
     * @param devId  设备 ID
     * @param status 网络状态是否可用，可用为 true
     */
    void onNetworkStatusChanged(String devId, boolean status);

    /**
     * 设备信息更新回调
     *
     * @param devId 设备 ID
     */
    void onDevInfoUpdate(String devId);
}

说明：其中，设备功能点说明请参考 设备功能点 章节。

Java 示例

mDevice.registerDevListener(new IDevListener() {
    @Override
    public void onDpUpdate(String devId, String dpStr) {

    }

    @Override
    public void onRemoved(String devId) {

    }

    @Override
    public void onStatusChanged(String devId, boolean online) {

    }

    @Override
    public void onNetworkStatusChanged(String devId, boolean status) {

    }

    @Override
    public void onDevInfoUpdate(String devId) {

    }
});

注意：请勿使用 void registerDeviceListener(IDeviceListener listener) 方法，此方法需要配合标准设备使用，该 API 暂未开放使用。

取消设备监听

当不需要监听设备时，取消设备监听。

接口说明

void IThingDevice.unRegisterDevListener();

Java 示例

mDevice.unRegisterDevListener();

查询设备信息

查询单个 DP 数据，查询后的数据会通过 IDevListener.onDpUpdate() 接口进行异步回调。

注意：该接口主要是针对不主动发送数据的设备 DP，例如倒计时信息查询。常规查询 DP 数据值时，可通过 DeviceBean 中的 getDps() 获取。

void IThingDevice.getDp(String dpId, IResultCallback callback);

Java 示例

mDevice.getDp(dpId, new IResultCallback() {
    @Override
    public void onError(String code, String error) {

    }

    @Override
    public void onSuccess() {

    }
});

修改设备名称

重命名设备，并支持多设备同步。

// 修改设备名称
void IThingDevice.renameDevice(String name,IResultCallback callback);

Java 示例

mDevice.renameDevice("设备名称", new IResultCallback() {
    @Override
    public void onError(String code, String error) {
        // 修改设备名称失败
    }

    @Override
    public void onSuccess() {
        // 修改设备名称成功
    }
});

后续步骤

重命名成功后，IDevListener.onDevInfoUpdate() 会收到通知。调用以下方法可以获取最新数据，然后刷新设备信息即可。

ThingOSDevice.getDataInstance().getDeviceBean(String devId);

移除设备

从用户设备列表中移除设备。

void IThingDevice.removeDevice(IResultCallback callback);

Java 示例

mDevice.removeDevice(new IResultCallback() {
    @Override
    public void onError(String errorCode, String errorMsg) {
    }

    @Override
    public void onSuccess() {
    }
});

恢复出厂设置

设备恢复出厂设置后，设备的相关数据会被清除掉，并重新进入待配网状态。如果是 Wi-Fi 设备，默认进入 Wi-Fi 快连模式。

void IThingDevice.resetFactory(IResultCallback callback)；

Java 示例

mDevice.resetFactory(new IResultCallback() {
    @Override
    public void onError(String errorCode, String errorMsg) {
    }

    @Override
    public void onSuccess() {
    }
});

查询 Wi-Fi 信号强度

查询设备 Wi-Fi 的信号强度。

void IThingDevice.requestWifiSignal(WifiSignalListener listener);

Java 示例

mDevice.requestWifiSignal(new WifiSignalListener() {
    @Override
    public void onSignalValueFind(String signal) {

    }

    @Override
    public void onError(String errorCode, String errorMsg) {

    }
});

回收设备资源

应用或者 Activity 关闭时，可以调用此接口，回收设备占用的资源。

void IThingDevice.onDestroy();

Java 示例

mDevice.onDestroy();

初始化网关设备

初始化网关控制类

根据设备 ID 初始化网关设备控制类 IThingGateway。

ThingOSDevice.newGatewayInstance(String devId);

参数说明

参数	说明
devId	设备 ID。

Java 示例

IThingGateway mGateway = ThingOSDevice.newGatewayInstance(deviceBean.getDevId());

监听子设备

注册子设备监听

IThingGateway 提供设备相关信息的监听，包含：

• DP 数据
• 子设备名称
• 子设备在线状态和设备移除

void IThingGateway.registerSubDevListener(ISubDevListener listener);

参数说明

参数	说明
listener	设备状态监听

IDevListener 接口

public interface ISubDevListener {

    /**
     * 子设备DP 数据更新
     *
     * @param nodeId 子设备 ID
     * @param dps    设备发生变动的功能点，为 JSON 字符串，数据格式：{"101": true}
     */
    void onSubDevDpUpdate(String nodeId, String dps);

    /**
     * 子设备移除回调
     *
     * @param devId 子设备id
     */
    void onSubDevRemoved(String devId);

    /**
     * 子设备添加回调
     *
     * @param devId 子设备id
     */
    void onSubDevAdded(String devId);

    /**
     * 子设备上下线回调。如果设备断电或断网，服务端将会在3分钟后回调到此方法。
     *
     * @param onlineDeviceIds  在线子设备 ID
     * @param offlineDeviceIds 离线子设备 ID
     */
    void onSubDevStatusChanged(List<String> onlineDeviceIds, List<String> offlineDeviceIds);

    /**
     * 子设备信息更新回调
     *
     * @param devId 子设备 ID
     */
    void onSubDevInfoUpdate(String devId);
}

说明：其中，设备功能点说明请参考 设备功能点 章节。

Java 示例

mGateway.registerSubDevListener(
        new ISubDevListener() {
            void onSubDevDpUpdate(String nodeId, String dps) {

            }

            void onSubDevRemoved(String devId) {

            }

            void onSubDevAdded(String devId) {

            }

            void onSubDevInfoUpdate(String devId) {

            }

            void onSubDevStatusChanged(List<String> onlineDeviceIds, List<String> offlineDeviceIds) {

            }
        });

取消子设备监听

当不需要监听子设备时，取消子设备监听。

接口说明

void IThingGateway.unRegisterSubDevListener();

Java 示例

mGateway.unRegisterSubDevListener();

查询网关子设备列表

可以获取网关下子设备的列表。

接口说明

void IThingGateway.getSubDevList(IThingDataCallback<List<DeviceBean>> callback);

Java 示例

mGateway.getSubDevList(new IThingDataCallback<List<DeviceBean>>() {
    @Override
    public void onSuccess(List<DeviceBean> result) {

    }

    @Override
    public void onError(String errorCode, String errorMessage) {

    }
});

回收网关资源

应用或者 Activity 关闭时，可以调用此接口，回收网关设备占用的资源。

void IThingGateway.onDestroy();

Java 示例

mGateway.onDestroy();