1.1.1. 目录

• 若琪智能家居协议
  • 请求消息类型
  • 回复消息类型
  • 消息体
• 示例
  • 一个控制请求
  • 一个控制成功的返回
  • 当发生了错误时的一个返回

1.1.2. 若琪智能家居协议

请求消息类型

命令 Directives

由若琪主动向 Skill 发起的请求，可以是 Skill 开放的 HTTP 服务，或者是 JSON RPC over TCP 等

• Rokid.Discovery: 搜索终端
• Rokid.Control: 终端控制，如"帮我打开客厅灯"
• Rokid.Query: 终端状态查询，如"现在家里门锁了吗"（暂不支持）

Skill 对于若琪命令的回复需要使用 Responses所定义的消息类型，否则若琪会认为本次消息发送失败；

当前版本尚不支持向若琪问询终端状态

事件 Events

由 Skill 主动向若琪发起的请求，只能通过 Rokid EventGateway 开放的 HTTP服务使用

• Rokid.AsyncResponse: 当 Skill 认为终端控制、终端发现可能需要超过 3秒的时间来完成时，可以推迟回复
• Rokid.ChangeReport: 终端状态变更，如灯被手动打开了

当前版本尚不支持事件推送

回复消息类型

回复 Responses

Skill 回复若琪发起的命令

所有回复应该在 3 秒内返回，如果 Skill认为本次操作需要更长的时间，应该考虑使用 DeferredResponse来向若琪告知会在一定时间内使用 AsyncResponse 回复若琪

• Response: 普通的命令回复，包含终端的最新状态
• DiscoveryResponse: 终端发现命名空间的回复，需要包含终端所有应有的信息
• ErrorResponse: 发生错误时的回复，包含一个错误码和一条描述错误的消息
• DeferredResponse（(规划中)）: 表示这个操作会超过2秒，需要在指定时间内使用 AsyncResponse 事件通知 Rokid EventGateway

消息体

Header Object

通用的必需字段

Authorization Object

Endpoint Object

本次消息的目标终端描述信息如 endpointId 和 additionalInfo

Payload Object

可选。根据消息类型决定内容，像控制请求的期望值等

1.1.3. 示例

一个搜索设备请求

{
  "header": {
    "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
    "namespace": "Rokid.Discovery",
    "name": "Discover",
    "payloadVersion": "v1",
    "authorization": {
      "type": "BearerToken",
      "token": "a-token-from-skill"
    }
  }
}

一个搜索设备成功的返回

{
  "header": {
    "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
    "namespace": "Rokid",
    "name": "DiscoveryResponse",
    "payloadVersion": "v1"
  },
  "payload": {
    "endpoints": [
      {
        "endpointId": "开发者自己定义的终端Id",
        "displayName": "大米台灯",
        "displayType": "light",
        "recommendRoomName": "厨房",
        "recommendHomeName": "我的家",
        "additionalInfo": {
          "key1": "value"
        },
        "capabilities": [
          {
            "interface": "Switch",
            "supportedOperations": [ "On", "Off" ],
            "proactivelyReported": true,
            "retrievable": true
          },
          {
            "interface": "Color",
            "supportedOperations": [ "Set" ],
            "proactivelyReported": true,
            "retrievable": true
          }
        ],
        "states": [
          {
            "interface": "Switch",
            "value": "On",
            "timeOfSample": "2018-03-15T18:00:00.000Z"
          },
          {
            "interface": "Color",
            "value": 12345,
            "timeOfSample": "2018-03-15T18:00:00.000Z"
          }
        ]
      }
    ],
  }
}

一个控制请求

{
  "header": {
    "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
    "namespace": "Rokid.Control",
    "name": "Color.Set",
    "payloadVersion": "v1",
    "authorization": {
      "type": "BearerToken",
      "token": "a-token-from-skill"
    }
  },
  "endpoint": {
    "endpointId": "开发者自己定义的终端Id",
    "additionalInfo": {
      "key1": "value1"
    },
    "states": [
      {
        "interface": "Color",
        "value": 12345,
        "timeOfSample": "20180320T00:00:00.000Z"
      }
    ]
  },
  "payload": {
    "value": 65280
  }
}

一个控制成功的返回

{
  "header": {
    "messageId": "123-456",
    "namespace": "Rokid",
    "name": "Response",
    "payloadVersion": "v1",
  },
  "endpoint": {
    "endpointId": "开发者自己定义的终端Id",
    "states": [
      {
        "interface": "Color",
        "value": 12345,
        "timeOfSample": "20180320T00:00:00.000Z"
      }
    ]
  },
  "payload": {}
}

当发生了错误时的一个返回

若琪会使用 Skill的错误消息告知用户发生了什么错误，并如何解决该错误；如果 Skill没有返回标准的错误格式，若琪将无法告知用户如何解决问题。

{
  "header": {
    "messageId": "789-123",
    "namespace": "Rokid",
    "name": "ErrorResponse",
    "payloadVersion": "v1",
  },
  "payload": {
    "name": "E_DRIVER_ERROR",
    "message": "发生了一些不可告人的错误"
  }
}

关于错误的更多信息请查阅 当发生了错误。