# 系统相关

消息类型 名称 必须实现
response ping
error
check_software_update
update_software
power_off
update_device_modes
factory_reset
reboot
revoke_response
update_cloud_alarm_list
request state_sync
exception
check_software_update_result
update_software_state_sync
update_message_board

# context

"iflyos_context": {
  ...
  "system": {
    "version": "1.3",
    "software_updater": true,
    "power_controller": true,
    "device_modes": true,
    "factory_reset": true,
    "reboot": true
  }
  ...
}
参数 类型 说明 必填
version String 模块版本,现在是1.3
software_updater Boolean 是否已实现软件更新相关的responserequest,若该项未出现,云端默认为false
power_controller Boolean 是否已实现power_offresponse,若该项未出现,云端默认为false
device_modes Boolean 是否已实现update_device_modes,若设备支持儿童模式和持续交互模式,该项必须出现。若该项未出现,云端默认为false
factory_reset Boolean 是否已实现factory_reset。若设备支持恢复出厂设置,该项必须出现。若该项未出现,云端默认为false
reboot Boolean 是否已实现reboot。若设备支持重启,该项必须出现。若该项未出现,云端默认为false

版本说明

版本 说明 更新日期
1.0 基础实现 2019-07-01
1.1 新增对关机、检查更新的支持 2019-08-28
1.2 新增更新设备模式 2019-09-12
1.3 新增恢复出厂模式,重启和解除授权绑定 2019-12-12

# response

# 健康检查

在 iFLYOS 中,我们认为网络是不可靠的,所以我们提供了健康检查的机制。根据我们的经验,目前许多芯片的时间钟不可信,所以客户端必须做好时间同步,该响应会返回一个服务器时间戳,可用来当作系统时间的参考。当设备连接着iFLYOS时,我们每隔2分钟会下发一次该响应,建议客户端每隔2分钟检测是否有正常收到该响应

建议

  1. 当云端返回的时间与客户端本地时间误差超过60s时,请把设备本地时间更新为云端时间。
  2. 如果客户端超过2分钟还没有收到过这个指令,请必须重新连接 websocket。

回复示例


{
  "iflyos_responses": [
   ...,
    {
      "header": {
        "name": "system.ping"
      },
      "payload": {
        "timestamp": 1558598737
      }
    }
  ]
}

参数 类型 说明 必有
timestamp Long 服务器时间的unix时间戳,如果你本地的ntp服务器不可信,请使用这个时间来同步本地的时间,推荐在linux和rtos中使用

# 请求出错

设备发送请求给 iFLYOS 中,你可能会得到以下的错误信息,如果发生了这些情况,设备可以选择缓存识别结果,在必要的时候进行重试。

回复示例


{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "system.error"
      },
      "payload": {
        "code": 400,
        "message": "参数出错"
      }
    }
  ]
}

参数 类型 说明 必有
code Int 错误状态码,见下表
message String 描述信息

可能出现的错误

错码码 说明 建议操作
400 参数错误 仔细检查参数是否有误
401 认证失败 断开链接,刷新授权后,再重新建立链接
403 没有权限操作 检查请求是否有误 / 检查是否有权限发送对应请求操作
500 服务端异常 断开链接,重新建立新链接。重连间隔建议为5~120秒随机,而非固定间隔
503 服务端异常 断开链接,重新建立新链接。重连间隔建议为5~120秒随机,而非固定间隔

# 检查更新

当用户在APP中点击【检查更新】后,你会收到云端返回的check_software_update,在接收到该返回后,你需要调用你接入的OTA服务的检查更新接口(iFLYOS 有提供通用的OTA服务,点击了解),并将检查结果通过check_software_update_result发送给云端。

建议

我们建议你的设备在调用检查更新接口,发现有新版本时,设备自动下载更新包,并在适当的时候提示用户通过APP或语音请求“立即升级”来进行设备软件的更新。

回复示例

{
  "iflyos_responses": [
    ...,
   {
      "header": {
        "name": "system.check_software_update"
     },
      "payload": {
     }
   }
 ]
}

# 设备更新

当用户在APP中点击【立即更新】,或用户语音请求“立即升级”后,你会收到云端返回的update_software。在接收到该返回后,你需要:

  1. 检查本地是否有已下载或正在下载的安装包。若有,则在下载完成后开始安装。
  2. 若本地没有安装包,调用你接入的OTA服务的检查更新接口(iFLYOS 有提供通用的OTA服务,点击了解)。若有新版本,下载安装包,并在下载完成后自动安装。
  3. 把设备更新的状态及时通过update_software_state_sync报告至云端。

建议

  1. 在更新过程中,我们建议设备不响应用户的唤醒或触控。
  2. 在更新过程中,若更新时间较长,我们建议你在适当的时候通过TTS提示用户设备当前的状态。详情可参考EVS设备体验参考规范
{
  "iflyos_responses": [
    ...,
   {
      "header": {
        "name": "system.update_software"
     },
      "payload": {
     }
   }
 ]
}

# 关机

当你的设备支持关机时,若用户说“关机”,你会收到云端返回的power_off。当你收到这个返回时,你可以根据设备自身的情况和需求,执行关机/休眠等操作。

{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "system.power_off"
      },
      "payload": {
      }
    }
 ]
}

# 更新设备模式

当用户通过语音或者APP变更设备所处模式(如儿童模式持续交互模式等)时,云端将会通过该response通知设备,设备需要更新iflyos_header.device.flags中的信息。

注意

  1. 若你的设备支持模式变更,请在iflyos_header.device.flags中告知云端。
  2. response中会包含所有你的设备支持的模式的开关信息(设备支持的模式可在设备控制台 (opens new window)中进行配置)。
  3. 如果你的支持模式开关,为了完整的用户体验,你需要实现这个response
{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "system.update_device_modes"
      },
      "payload": {
        "kid": true,
        "continuous_interaction": true
      }
    }
 ]
}
参数 类型 说明 必有
kid Boolean 儿童模式
continuous_interaction Boolean 持续交互模式

# 恢复出厂设置

当用户通过APP请求恢复设备出厂设置时,云端将会通过该response通知设备。

设备收到该response后,需要至少完成以下执行:

  1. 取消设备的账号授权绑定。
  2. 清除设备本地的闹钟列表和其他设置。
  3. 清除设备本地的网络相关信息。
{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "system.factory_reset"
      },
      "payload": {
      }
    }
 ]
}

# 重启

当用户通过APP请求重启设备时,云端将会通过该response通知设备。设备收到该response后,需要对设备进行重启。

{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "system.reboot"
      },
      "payload": {
      }
    }
 ]
}

# 解除授权绑定

当用户通过APP解除设备绑定时,云端将会通过该response通知设备。设备收到该response后,需要清除设备本地的token信息。

{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "system.revoke_authorization"
      },
      "payload": {
      }
    }
 ]
}

# 更新云端闹钟列表

若你的设备使用的是云端闹钟,在闹钟列表发生变更后(可能是因为闹钟响铃、用户通过语音或关联APP增删查改闹钟),云端会下发该指令。在收到指令后,若你的设备本地需要显示闹钟列表,我们建议你立即调用GET /alerts,更新闹钟列表中的数据。

{
  "iflyos_responses": [
   ...,
    {
      "header": {
        "name": "system.update_cloud_alarm_list"
      },
      "payload": {
      }
    }
  ]
}

# 留言板更新通知

当设备收到新的留言板消息时,云端将会通过该response通知设备。设备收到该response后,可以进行留言板更新的相关业务操作。

{
  "iflyos_responses": [
   ...,
    {
      "header": {
        "name": "system.update_message_board"
      },
      "payload": {
      }
    }
  ]
}

# request

# 检查更新结果

在接收云端返回的check_software_update,调用检查更新接口后,你需要发送该request给云端,以便云端将检查更新结果反馈给用户。

{
  "iflyos_header": {...},
  "iflyos_context": {...},
  "iflyos_request": {
    "header": {
      "name": "system.check_software_update_result",
      "request_id": "xxxxxxxx"
    },
    "payload": {
      "result": "SUCCEED",//或"FAILED"
      "need_update": true,
      "version_name": "1.7.1",
      "update_description": "这里是一个版本描述"
    }
  }
}
参数 类型 说明 必填
iflyos_header Object 构建的通用 iflyos_header
iflyos_context Object 构建的通用 iflyos_context
result String 检查更新的结果,取值:
- SUCCEED:调用检查更新接口成功。
- FAILED:调用检查更新接口出现了问题。
need_update Bool 是否需要更新。当result取值为FAILED时,该项无需出现。
version_name String 版本的名称,建议在此处填写供用户查看的版本名称,如1.7.1新春特别版。当result取值为FAILED时,该项无需出现。
update_description String 版本的描述,简要说明该版本更新了什么内容。\n换行。当result取值为FAILED时,该项无需出现。

# 更新状态同步

在接收云端返回的update_software,开始更新时,你需要在以下时间节点发送该request给云端,以便云端将检查更新结果反馈给用户。

  1. 开始更新。
  2. 更新成功
  3. 更新失败。

注意

若本次设备更新不是由云端返回的update_software触发的,你可以不发送request


{
  "iflyos_header": {...},
  "iflyos_context": {...},
  "iflyos_request": {
    "header": {
      "name": "system.update_software_state_sync",
      "request_id": "xxxxxxxx"
    },
    "payload": {
      "state": "FINISHED",//或"FAILED","STARTED"
      "version_name": "1.7.1",//上报更新状态的版本号
      "update_description": "这里是一个版本描述",
      "error_type": "UP_TO_DATE",//取值:CHECK_ERROR, DOWNLOAD_ERROR, INSTALL_ERROR
      "error_message": "这是一个错误描述"
    }
  }
}
参数 类型 说明 必填
iflyos_header Object 构建的通用 iflyos_header
iflyos_context Object 构建的通用 iflyos_context
state String 更新状态,取值:
- FINISHED:更新成功。
- FAILED:更新失败。
- STARTED:开始更新。
version_name String 版本的名称,建议在此处填写供用户查看的版本名称,如1.7.1新春特别版。当state取值为FAILED时,该项无需出现。
update_description String 版本的描述,简要说明该版本更新了什么内容。\n换行。当state取值为FAILED时,该项无需出现。
error_type String 更新失败类型,取值见下表。只有当state取值为FAILED时,该项才出现。
error_message String 更新失败的信息,建议填写要提示用户的TTS文本。

# 本地状态同步

你需要在以下情况同步设备的状态:

  • 每15分钟
  • 网络状态变更
  • 本地闹钟列表发生:新增、删除、响铃
  • 设备音量发生变化

请求示例

{
  "iflyos_header": {...},
  "iflyos_context": {...},
  "iflyos_request": {
    "header": {
      "name": "system.state_sync",
      "request_id": "xxxxxxxx"
    },
    "payload": {
    }
  }
}
参数 类型 说明 必填
iflyos_header Object 构建的通用 iflyos_header
iflyos_context Object 构建的通用 iflyos_context

# 异常报告

如果你的设备需要把某些关键错误发送到 iFLYOS 控制台中,你可以使用本协议,这个接口日志单次最大10K,基础版存储1天,专业版30天;

请求示例


{
  "iflyos_header": {...},
  "iflyos_context": {...},
  "iflyos_request": {
    "header": {
      "name": "system.exception",
      "request_id": "xxxxxxxx"
    },
    "payload": {
      "type": "xxx",
      "code": "xxx",
      "message": "xxxx"
    }
  }
}

参数 类型 说明 必填
iflyos_header Object 构建的通用 iflyos_header
iflyos_context Object 构建的通用 iflyos_context
type String crash发生的地方,比如audio_player, recognizer, internal等, 你可以自定义
code String 错误代码,你可以自定义
message String 错误内容