UniOS文档中心

# 系统相关

# 协议类型

消息类型 名称 必须实现
directive ping 是
error 是
check_software_update 是
update_software 是
power_off 否
factory_reset 否
reboot 否
revoke_authorization 是
event state_sync 是
check_software_update_result 是
update_software_state_sync 是

# context

"unios_context": {
  ...
  "system": {
    "version": "1.0",
    "software_updater": true,
    "device_modes": true,
    "factory_reset": true,
    "reboot": true
  }
  ...
}
1
2
3
4
5
6
7
8
9
10
11
参数 类型 说明 必填
version String 模块版本，现在是1.0 是
software_updater Boolean 是否已实现软件更新相关的directive和request，若该项未出现，云端默认为false 否
device_modes Boolean 是否已实现update_device_modes，若设备支持儿童模式和持续交互模式，该项必须出现。若该项未出现，云端默认为false 否
factory_reset Boolean 是否已实现factory_reset。若设备支持恢复出厂设置，该项必须出现。若该项未出现，云端默认为false 否
reboot Boolean 是否已实现reboot。若设备支持重启，该项必须出现。若该项未出现，云端默认为false 否

# directive

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

建议

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

回复示例

{
  "unios_directives": [
   ...,
    {
      "header": {
        "name": "system.ping"
      },
      "payload": {
        "timestamp": 1558598737,
        "device_state_sync_cycle": 300,
        "device_check_ping_cycle": 120
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
参数 类型 说明 必填
timestamp Long 服务器时间的unix时间戳，如果本地的ntp服务器不可信，请使用这个时间来同步本地的时间，推荐在linux和rtos中使用 是
device_state_sync_cycle Long 设备状态自动同步周期，单位：秒 是
device_check_ping_cycle Long 终端检测ping周期时间，单位：秒 是


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

{
  "unios_directives": [
    ...,
    {
      "header": {
        "name": "system.error"
      },
      "payload": {
        "code": 8410400,
        "message": "参数出错"
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
参数 类型 说明 必填
code Int 错误状态码，见下表 是
message String 描述信息 是

可能出现的错误

错误码 说明 建议操作
8410400 参数错误 仔细检查参数是否有误
8410401 认证失败 断开链接，刷新授权后，再重新建立链接
8410402 device_id或appkey不一致 建立链接的device_id、appkey与发送消息时的device_id、appkey不一致
8410403 没有权限操作 检查请求是否有误 / 检查是否有权限发送对应请求操作
8410500 服务端异常 断开链接，重新建立新链接。重连间隔建议为5～120秒随机，而非固定间隔

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

建议

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

回复示例

{
  "unios_directives": [
    ...,
   {
      "header": {
        "name": "system.check_software_update"
     },
      "payload": {
     }
   }
 ]
}
1
2
3
4
5
6
7
8
9
10
11
12

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

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

建议

  1. 在更新过程中，我们建议设备不响应用户的唤醒或触控
  2. 在更新过程中，若更新时间较长，我们建议在适当的时候通过TTS提示用户设备当前的状态
{
  "unios_directives": [
    ...,
   {
      "header": {
        "name": "system.update_software"
     },
      "payload": {
     }
   }
 ]
}
1
2
3
4
5
6
7
8
9
10
11
12

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

{
  "unios_directives": [
    ...,
    {
      "header": {
        "name": "system.power_off"
      },
      "payload": {
      }
    }
 ]
}
1
2
3
4
5
6
7
8
9
10
11
12

恢复出厂设置
当用户通过APP请求恢复设备出厂设置时，云端将会通过该directive通知设备。
设备收到该directive后，需要至少完成以下执行：

  1. 取消设备的账号授权绑定
  2. 清除设备本地的闹钟列表和其他设置
  3. 清除设备本地的网络相关信息
{
  "unios_directives": [
    ...,
    {
      "header": {
        "name": "system.factory_reset"
      },
      "payload": {
      }
    }
 ]
}
1
2
3
4
5
6
7
8
9
10
11
12

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

{
  "unios_directives": [
    ...,
    {
      "header": {
        "name": "system.reboot"
      },
      "payload": {
      }
    }
 ]
}
1
2
3
4
5
6
7
8
9
10
11
12

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

{
  "unios_directives": [
    ...,
    {
      "header": {
        "name": "system.revoke_authorization"
      },
      "payload": {
      }
    }
 ]
}
1
2
3
4
5
6
7
8
9
10
11
12

# event

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

{
  "unios_header": {...},
  "unios_context": {...},
  "unios_event": {
    "header": {
      "name": "system.check_software_update_result",
      "message_id": "xxxxxxxx"
    },
    "payload": {
      "result": "SUCCEED",//或"FAILED"
      "need_update": true,
      "version_name": "1.9.1",
      "update_description": "这里是一个版本描述"
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
参数 类型 说明 必填
unios_header Object 构建的通用 unios_header 是
unios_context Object 构建的通用 unios_context 是
result String 检查更新的结果，取值：
- SUCCEED：调用检查更新接口成功。
- FAILED：调用检查更新接口出现了问题。		 是
need_update Boolean 是否需要更新。当result取值为FAILED时，该项无需出现。 否
version_name String 版本的名称，建议在此处填写供用户查看的版本名称，如1.9.1国庆特别版。当result取值为FAILED时，该项无需出现。 否
update_description String 版本的描述，简要说明该版本更新了什么内容。\n换行。当result取值为FAILED时，该项无需出现。 否

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

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

注意

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

{
  "unios_header": {...},
  "unios_context": {...},
  "unios_event": {
    "header": {
      "name": "system.update_software_state_sync",
      "message_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": "这是一个错误描述"
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
参数 类型 说明 必填
unios_header Object 构建的通用 unios_header 是
unios_context Object 构建的通用 unios_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文本。 否

本地状态同步
需要在以下情况同步设备的状态：

  1. 每N分钟（间隔时间，通过system.ping指令下发到终端）
  2. 网络状态变更
  3. 本地闹钟列表发生：新增、删除、响铃
  4. 设备音量发生变化

请求示例

{
  "unios_header": {...},
  "unios_context": {...},
  "unios_event": {
    "header": {
      "name": "system.state_sync",
      "message_id": "xxxxxxxx"
    },
    "payload": {
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
参数 类型 说明 必填
unios_header Object 构建的通用 unios_header 是
unios_context Object 构建的通用 unios_context 是

← 视频播放器 →