# 系统相关

消息类型	名称	必须实现
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	错误内容	否

← 音频播放器本地闹钟 →