Android sdk开发文档

概述

    本文档适用于接入科大讯飞iFLYIoT平台的开发者,重点描述Android平台的开发接口和接入流程。iFLYIoT Android客户端是科大讯飞iFLYIoT基于Android客户端的SDK实现,本文档描述SDK的组成,mqtt和设备影子的集成步骤。详细的实现流程也可阅读附带的demo源文件和对应的文档。

一.术语

1.IoT

Internet Of Things的缩写,也称为物联网。让所有的物品都与网络连接在一起,方便识别和管理。

2.IFLYIoT平台

科大讯飞的物联网平台。

3.MQTT

Message Queuing Telemetry Transport的缩写,是IBM开发的一个即时通讯开源协议。采用发布/订阅(Publish/Subscribe)模式。

二.sdk调用说明

1.创建client实例


/**
 * 实例化client对象
 * @param context
 *         上下文信息
 * @param params
 *         传入参数,包含productKey,productName,deviceSecret,apiKey,apiSercret
 *
 */
XIotMqttClient createInstance(Context context, HashParam params)

2.注册消息监听器


/**
 * 注册callback,用于接收服务端下发消息
 * @param userCallback
 *             本地消息监听器
 */
@Override
public void registerMsgListener(XIotTopicCallback userCallback) {
      super.registerMsgListener(userCallback);
}

3.与服务端建立连接

一.阻塞式连接:


  /**
   * 建立客户端sdk与服务端的连接。
   * 这是阻塞式的连接,因此线程会被阻塞,直到该连接操作成功/失败或者超时。
   * 
   * 阻塞API在不指定超时时调用,在非常罕见的情况下,如果服务器响应接收失败或者丢失,能够立即阻断当前线程。
   * 
   *
   * @throws XIotException
   *             连接操作失败时抛出的异常
   */
   @Override
   public void connect() throws XIotException {
        super.connect();
   }
 

二.可设置超时时间的阻塞式连接:


   /**
    * 建立客户端sdk与服务端的连接。
    * 这是阻塞式的连接,因此线程会被阻塞,直到该连接操作成功/失败或者超时。
    *
    * @param timeout
    *             建立连接时,线程等待时间
    * @throws XIotException
    *             连接操作失败向外抛出的异常
    * @throws XIotTimeoutException
    *             连接操作超时抛出的异常
    */
   @Override
   public void connect(long timeout) throws XIotException, XIotTimeoutException {
        super.connect(timeout);
    }

三.自由选择连接方式(阻塞or非阻塞)

 
  /**
   * 建立客户端sdk与服务端的连接。
   * 该请求既可以是阻塞式也可以是非阻塞式。
   *
   * @param timeout
   *             线程等待时间
   * @param blocking
   *            设置是否为阻塞式
   * @throws XIotException
   *             连接操作失败抛出异常
   * @throws XIotTimeoutException
   *            连接超时抛出异常
   */
  @Override
  public void connect(long timeout, boolean blocking) throws XIotException, XIotTimeoutException {
        super.connect(timeout, blocking);
   }

4.发布消息

一.发布设备属性消息



/**
 * 发布属性消息到服务端,用于更新设备属性。
 * 该函数为非阻塞式调用,因此一旦在消息队列中会理解返回。
 * 因此该操作结果会通过{@link XIotMessage#onSuccess},
 * {@link XIotMessage#onFailure}以及{@link XIotMessage#onTimeout}等回调接口进行回馈。
 * 
 * @param attributeMsg
 *            要发布的消息载体
 * @param params
 *            设备属性组装而成的HashParam结构参数
 * @throws XIotException
 *             操作失败抛出异常
 */
@Override
public String publishProperty(XIotMessage attributeMsg, HashParam params) throws XIotException {
    return super.publishProperty(attributeMsg, params);
}

二.发布事件消息


/**
 * 发布事件消息到服务端,用于设置事件操作。
 * 该函数为非阻塞式调用,因此一旦在消息队列中会理解返回。
 * 因此该操作结果会通过{@link XIotMessage#onSuccess},{@link XIotMessage#onFailure}以及{@link XIotMessage#onTimeout}等回调接口进行回馈。
 * @param eventMsg
 *             要发布的消息体
 * @param params
 *             事件消息附带参数
 *     @param eventName
 *          定义的事件名称
 * @throws XIotException
 *             操作失败抛出异常
 */
@Override
public String publishEvent(XIotMessage eventMsg, HashParam params,String                             eventName) throws XIotException {
       return super.publishEvent(eventMsg, params,eventName);
}

三.客户端反馈属性消息


/**
 * 发布属性回馈消息到服务端,该接口在收到{@XIotTopicCallback#onPropertyRequest} 
 * 时,进行调用,根据该下行消息中带入的message中payload信息,针对指定属性值进行反馈。
 *  @param message
 *             要发布的消息体
 * @param params
 *             属性参数
 * @throws XIotException
 *             操作失败抛出异常
 * 
 */
 @Override
 public void publishProReqReply(XIotMessage message, HashParam params ) throws XIotException {
        super.publishProReqReply(message, params);
  }

四.属性设置回应消息


/** 
 * 服务端设置属性后,发送属性设置消息,客户端接收后,立即发送回应消息。
 * 该接口在收到{@XIotTopicCallback#onPropertySet}时,进行调用。
 * @param message
 *             要发布的消息体
 * @throws XIotException
 *             操作失败抛出异常
 *
 */
 @Override
 public void publishProSetReply(XIotMessage message) throws XIotException {
        super.publishProSetReply(message);
  }

五.服务消息响应


/**
 * 接收到服务端设置的服务消息后,客户端立即响应。
 * 该接口在收到{@XIotTopicCallback#onServiceSet}时,进行调用。
 * @param message
 *             要发布的消息体
 * @param params
 *             服务消息参数
 * @param identifer
 *             服务名称,从{@XIotTopicCallback#onServiceSet}接口消息体中获取
 * @throws XIotException
 *             操作失败抛出异常
 *             
 */
@Override
public void publishServiceReply(XIotMessage message, HashParam params,String identifer) throws XIotException {
       super.publishServiceReply(message, params, identifer);
}


5.OTA模块

一.设置版本号

在connect之前,设置当前固件版本,sdk在connect成功后,直接将版本号上传至服务。


    //connect 之前设置
    XIotMqttClient.getInstance().setFirmwareVer("1.0.0");//设置当前固件版本,用于ota升级业务
    
    XIotMqttClient.getInstance().registerMsgListener(new TestTopicListener());
    XIotMqttClient.getInstance().connect();ota升级业务

二.接收固件更新信息

通过在connect前设置当前固件版本信息后,sdk在connect成功后,上报版本信息,此时服务端会判断,如果有待升级版本,则下发致客户端,客户端通过onFireWareDownloaded回调接口进行监听。


    /**
     * 固件版本下载监听
     * @param errCode 错误码,取值范围{0,-1},0表示成功,-1表示失败
     * @param firewareInfo 在错误码为0时,下载固件的本机位置;错误码为-1 时,具体错误信息
     */
    @Override
    public void onFireWareDownloaded(int errCode, String firewareInfo) {
        Log.d(TAG,"onFireWareDownloaded :"+errCode);
    }

三.更新固件安装状态


    HashParam param = new HashParam();
    //-3:烧写失败,0:待升级,2:升级成功
    param.putParam("status",-3);
    param.putParam("desc","test 0");
    XIotMessage message = new NonBlockingPublishListener();
    try {
          if (XIotClient.getConnectionStatus() == XIotConnectionStatus.CONNECTED) {
              XIotClient.publishEvent(message,param, XIotMqttConstants.OTA_STATUS_UPLOAD);
           }
         } catch (XIotException e) {
           System.out.println(System.currentTimeMillis() + ": publish failed for " );
         }catch (NullPointerException e) {
           showTip("请先创建连接");
         }

6.更多API

更多api调用,请参考XIot-Android-API文档com.iflytek.xiot.client.XIotMqttClient

results matching ""

    No results matching ""