可扩展连接协议

版本：1.0

时间	修改者	描述
2018.2.3	jxfengzi@gmail.com	初始化文档

一、概念

XCP 可扩展连接协议(eXtensible Connectivity Protocol)
DEVICE 设备
AP

设备接入点，即：AccessPoint
CP

设备控制点，即：ControlPoint
Stanza

一段完整的报文数据，称之为节（Stanza）
AccessKey

访问秘钥，AP服务用不上，但是在CP服务用来做设备控制的校验，本协议用不上。
DID

设备ID，字符串，即：Device ID
IID

实例ID, 自然数，即：Instance ID，分为4种实例ID

类型说明
SIID 服务实例ID，即：Service Instance ID
AIID 方法实例ID，即：Action Instance ID
EIID 事件实例ID，即：Event Instance ID
PIID 属性实例ID，即：Property Instance ID
PID

属性ID，即：Property ID，字符串，唯一标识某个具体设备的某个属性

PID = {DID}.{SIID}.{PIID}

如：abc.1.2
AID

方法ID，即：Action ID，字符串，唯一标识某个具体设备的某个方法

AID = {DID}.{SIID}.{AIID}

如：abcdefg.3.4
EID

事件ID，即：Event ID，字符串，唯一标识某个具体设备的某个事件

EID = {DID}.{SIID}.{EIID}

如：xyz.10.17

类型	说明
SIID	服务实例ID，即：Service Instance ID
AIID	方法实例ID，即：Action Instance ID
EIID	事件实例ID，即：Event Instance ID
PIID	属性实例ID，即：Property Instance ID

二、承载协议

本协议使用 websocket 作为传输层，只使用 text frame 承载报文：

可以和标准HTTP服务一样，使用负载均衡组件。
安全方面可以使用wss协议（可选）。

2.1 连接

连接到AP服务，将did和type放在URI种（type = DeviceType），如：

/v1/{did}/{type}

2. 2 设备证书

使用wss协议时，设备可以携带设备证书，证书里有一个 CN 字段，记录了 did。AP服务会校验此字段。

2.3 证书体系

使用3级证书体系：根证书 > 开发组证书 > 设备证书

三、报文格式

异步双工整个通信过程采用异步双工方式，即：

设备和服务器之间可以互相同时发送请求和应答. 不用等待对方的应答就可以继续发送N个请求.

3.1 报文类型

包括两种报文

报文类型含义备注
IQ 请求/应答 Info/Query的缩写
Message 纯消息，不需要应答

报文类型	含义	备注
IQ	请求/应答	Info/Query的缩写
Message	纯消息，不需要应答

3.2 IQ

请求/应答 IQ消息采用请求/应答模型，即发送方发送一条请求消息，接收方必须回复一条应答。
字段

字段含义备注
id 报文ID 此字段必须存在
type IQ报文类型此字段必须存在
method 方法在query和result中必须存在
content 方法需要的内容根据具体的方法定义
IQ报文类型

IQ Type 含义
query 请求
result 执行成功的应答
error 执行失败的应答
方法请求或应答的方法，必须是urn格式：
```
urn:namespace:name
```
- namespace 名字空间，由应用指定．
- name 方法名称，由应用指定．
- content 如果是error，必须包含content．标识出错的原因．如果是query和result，content由method自己定义．

IQ Type	含义
query	请求
result	执行成功的应答
error	执行失败的应答

Query 这是一个请求消息，type为query, content得看具体的方法定义．如：

{
    "iq": {
        "id": "1",
        "type": "query",
        "method": "urn:xiot:set-version",
        "content": {
            "version": "1.0"
        }
    }
}

Result 这是一个应答消息，type为result, id必须和请求中的id保持一直．content得看具体的方法定义．如：

{
    "iq": {
        "id": "1",
        "type": "result",
        "method": "urn:xiot:set-version"
    }
}

Error 这是一个应答消息, type为error，id必须和请求中的id保持一直. 必须包含content，指定出错的原因．如：

{
    "iq": {
        "id": 1,
        "type": "error",
        "content": {
            "status": -100,
            "description": "method not supported"
        }
    }
}

3.3 Message

这是一个不需要应答的消息．

字段

字段	含义	备注
id	报文ID	此字段必须存在
topic	消息主题	此字段必须存在
type	消息数据的类型	此字段必须存在
payload	消息数据	此字段必须存在

如：

{
    "message": {
        "id": "1001",
        "topic": "urn:xiot:notification",
        "content": {
            "message": "hello"
        }
    }
}

四、基础报文

4.1 心跳报文

说明：设备保证60秒内向AP发送一个数据报文，如果没有数据报文，可以发送一个心跳报文。

请求: Device > AP

{
    "iq": {
        "type": "query",
        "method": "urn:xiot:ping",
        "id": "5003"
    }
}

应答: AP > Device

{
    "iq": {
        "type": "result",
        "method": "urn:xiot:ping",
        "id": "5003"
    }
}

4.2 关闭报文（可选）

说明：客户端可以先发送一个关闭报文，然后再关闭连接。

请求: Device > AP

{
    "iq": {
        "type": "query",
        "method": "urn:xiot:bye-bye",
        "id": "5009"
    }
}

应答: AP > Device

{
    "iq": {
        "type": "result",
        "method": "urn:xiot:bye-bye",
        "id": "5003"
    }
}

五、控制报文

5.1 读属性

请求: AP > Device

{
    "iq": {
        "type": "query",
        "method": "urn:xiot:get-properties",
        "id": "5004",
        "content": {
            "properties": [
                "abc.1.1",
                "abc.1.2",
                "abc.1.3"
            ]
        }
    }
}

字段说明

字段说明
properties 属性ID列表

字段	说明
properties	属性ID列表

应答: Device > AP

{
    "iq": {
        "type": "result",
        "method": "urn:xiot:get-properties",
        "id": "5004",
        "content": {
            "properties": [
                {
                    "pid": "abc.1.1",
                    "value": 26
                },
                {
                    "pid": "abc.1.2",
                    "status": -1,
                    "description": "xxx"
                },
                {
                    "pid": "abc.1.3",
                    "status": -3,
                    "description": "xxx"
                }
            ]
        }
    }
}

5.2 写属性

请求: AP > Device

{
    "iq": {
        "type": "query",
        "method": "urn:xiot:set-properties",
        "id": "5005",
        "content": {
            "properties": [
                {
                    "pid": "abc.2.3",
                    "value": 37
                },
                {
                    "pid": "abc.2.4",
                    "value": 3600
                },
                {
                    "pid": "abc.2.5",
                    "value": 10.7
                }
            ]
        }
    }
}

应答: AP > Device

{
    "iq": {
        "type": "result",
        "method": "urn:xiot:set-properties",
        "id": "5004",
        "content": {
            "properties": [
                {
                    "pid": "abc.2.3",
                    "status": 0
                },
                {
                    "pid": "abc.2.4",
                    "status": -2,
                    "description": "xxx"
                },
                {
                    "pid": "abc.2.5",
                    "status": -3,
                    "description": "xxx"
                }
            ]
        }
    }
}

5.3 调用方法

请求

{
    "iq": {
        "type": "query",
        "method": "urn:xiot:invoke-action",
        "id": "5006",
        "content": {
            "action": {
                "aid": "abc.1.9",
                "in": [
                    {
                        "piid": 2,
                        "values": [
                            37
                        ]
                    },
                    {
                        "piid": 3,
                        "values": [
                            3600,
                            1800
                        ]
                    }
                ]
            }
        }
    }
}

应答（成功）

{
    "iq": {
        "type": "result",
        "method": "urn:xiot:invoke-action",
        "id": "5006",
        "content": {
            "action": {
                "aid": "abc.1.9",
                "status": 0,
                "out": [
                    {
                        "piid": 5,
                        "values": [
                            2700
                        ]
                    }
                ]
            }

        }
    }
}

应答（失败）

{
    "iq": {
        "type": "error",
        "id": "5006",
        "content": {
            "status": -3,
            "description": "action not found"
        }
    }
}

六、通知报文

所有通知报文均使用 IQ，因为请求有应答，设备端通过应答，就可以看到自己通知报文是否发正确了没有。

6.1 属性已变化

请求: Device > AP

{
    "iq": {
        "type": "query",
        "method": "urn:xiot:properties-changed",
        "id": "1",
        "content": {
            "properties": [
                {
                    "pid": "abc.2.3",
                    "value": 37
                },
                {
                    "pid": "abc.2.4",
                    "value": 3600
                },
                {
                    "pid": "abc.2.5",
                    "value": 10.7
                }
            ]
        }
    }
}

应答: AP > Device

{
    "iq": {
        "type": "result",
        "method": "urn:xiot:properties-changed",
        "id": "1",
        "content": {
            "properties": [
                {
                    "pid": "abc.2.3",
                    "status": 0
                },
                {
                    "pid": "abc.2.4",
                    "status": -2,
                    "description": "xxx"
                },
                {
                    "pid": "abc.2.5",
                    "status": -3,
                    "description": "xxx"
                }
            ]
        }
    }
}

6.2 事件已发生

请求: Device > AP

{
  "iq": {
    "type": "query",
    "method": "urn:xiot:event-occurred",
    "id": "1",
    "content": {
      "eid": "abc.1.1",
      "arguments": [
        {
          "piid": 1,
          "values": [
            "hello"
          ]
        },
        {
          "piid": 2,
          "values": [
            1
          ]
        },
        {
          "piid": 3,
          "values": [
            100,
            200,
            300
          ]
        },
        {
          "piid": 4,
          "values": [
            10.7,
            10.9
          ]
        }
      ]
    }
  }
}

应答: AP > Device

{
  "iq": {
    "type": "result",
    "method": "urn:xiot:event-occurred",
    "id": "1"
  }
}

七、其他

7.1 修改AccessKey

请求: Device > AP

{
    "iq": {
        "type": "query",
        "method": "urn:xiot:set-access-key",
        "id": "5014",
        "content": {
            "key": "abcdef1234567890"
        }
    }
}

应答

{
    "iq": {
        "type": "result",
        "method": "urn:xiot:set-access-key",
        "id": "5014"
    }
}

7.2 查询AccessKey

请求

{
    "iq": {
        "type": "query",
        "method": "urn:xiot:get-access-key",
        "id": "5013"
    }
}

应答

{
    "iq": {
        "type": "result",
        "method": "urn:xiot:get-access-key",
        "id": "5013",
        "content": {
            "key": "abcdef1234567890"
        }
    }
}

八、错误码

status	description
0	成功
1	接收到请求，但操作没有完成
-1	不可读
-2	不可写
-3	不存在
-4	内部错误
-5	Value错误
-6	Action参数错误
-7	验证错误

字段	含义	备注
id	报文ID	此字段必须存在
type	IQ报文类型	此字段必须存在
method	方法	在query和result中必须存在
content	方法需要的内容	根据具体的方法定义

一、概念​

二、承载协议​

2.1 连接​

2. 2 设备证书​

2.3 证书体系​

三、报文格式​

3.1 报文类型​

3.2 IQ​

3.3 Message​

四、基础报文​

4.1 心跳报文​

4.2 关闭报文（可选）​

五、控制报文​

5.1 读属性​

5.2 写属性​

5.3 调用方法​

六、通知报文​

6.1 属性已变化​

6.2 事件已发生​

七、其他​

7.1 修改AccessKey​

7.2 查询AccessKey​

八、错误码​

一、概念

二、承载协议

2.1 连接

2. 2 设备证书

2.3 证书体系

三、报文格式

3.1 报文类型

3.2 IQ

3.3 Message

四、基础报文

4.1 心跳报文

4.2 关闭报文（可选）

五、控制报文

5.1 读属性

5.2 写属性

5.3 调用方法

六、通知报文

6.1 属性已变化

6.2 事件已发生

七、其他

7.1 修改AccessKey

7.2 查询AccessKey

八、错误码