# 系统相关
消息类型 | 名称 | 必须实现 |
---|---|---|
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 | 是否已实现软件更新相关的response 和request ,若该项未出现,云端默认为false | 否 |
power_controller | Boolean | 是否已实现power_off 的response ,若该项未出现,云端默认为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分钟检测是否有正常收到该响应
建议
- 当云端返回的时间与客户端本地时间误差超过60s时,请把设备本地时间更新为云端时间。
- 如果客户端超过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
。在接收到该返回后,你需要:
- 检查本地是否有已下载或正在下载的安装包。若有,则在下载完成后开始安装。
- 若本地没有安装包,调用你接入的OTA服务的检查更新接口(iFLYOS 有提供通用的OTA服务,点击了解)。若有新版本,下载安装包,并在下载完成后自动安装。
- 把设备更新的状态及时通过
update_software_state_sync
报告至云端。
建议
- 在更新过程中,我们建议设备不响应用户的唤醒或触控。
- 在更新过程中,若更新时间较长,我们建议你在适当的时候通过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
中的信息。
注意
- 若你的设备支持模式变更,请在
iflyos_header.device.flags
中告知云端。 - 该
response
中会包含所有你的设备支持的模式的开关信息(设备支持的模式可在设备控制台 (opens new window)中进行配置)。 - 如果你的支持模式开关,为了完整的用户体验,你需要实现这个
response
。
{
"iflyos_responses": [
...,
{
"header": {
"name": "system.update_device_modes"
},
"payload": {
"kid": true,
"continuous_interaction": true
}
}
]
}
参数 | 类型 | 说明 | 必有 |
---|---|---|---|
kid | Boolean | 儿童模式 | 否 |
continuous_interaction | Boolean | 持续交互模式 | 否 |
# 恢复出厂设置
当用户通过APP请求恢复设备出厂设置时,云端将会通过该response
通知设备。
设备收到该response
后,需要至少完成以下执行:
- 取消设备的账号授权绑定。
- 清除设备本地的闹钟列表和其他设置。
- 清除设备本地的网络相关信息。
{
"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
给云端,以便云端将检查更新结果反馈给用户。
- 开始更新。
- 更新成功
- 更新失败。
注意
若本次设备更新不是由云端返回的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 | 错误内容 | 否 |