map/docs/datacollect/README.md

# 数据采集

## 采集程序与系统交互通道

采集程序与系统间采用Websocket方式通讯， 访问系统服务器端口: 7790

报文格式为`json`, 字符集: `utf-8`。

### 通道建立

采集程序建立连接时，需要带上自身节点ID，连接URL如下所示:

`ws://127.0.0.1:7790/node/{nodeId}/{version}`

* `nodeId`: 采集节点ID
* `version`: 采集节点配置版本号,无配置时为0

建立连接后，当{version}为0时, 会主动推送配置更新命令。

PS: 同一节点只允许建立一条连接。

## 通讯报文

### 报文格式

```json
{
    //命令
    "cmd": "heartbeat",
    //命令ID
    "cmdId": "123123",
    //发送时间(毫秒)
    "time": 123123123123,
    //数据体
    "data": {}
}
```

### 配置更新

?> 方向: `系统` -> `采集程序`

**命令:** `configUpdate`

**数据体:**

```json
{
    //版本号
    "version": 101,
    //配置创建时间(毫秒值)
    "createTime": 1235235623433,
    //节点ID
    "nodeId": "nx10928234",
    //链路列表
    "links" : [
        {
            //链路ID
            "linkId": "1235123",
            //链路名称
            "linkName": "1#风机",
            //协议号
            "protocol": 1,
            //协议参数
            "params": {},
            "devices": [ {
            //设备ID
            "id": "11234131",
            //设备IOT地址
            "addr": "12341235",
            //属性列表
            "attrs":[
                {
                    //属性名
                    "name": "Ia",
                    //属性类型
                    "type": "yc",
                    //是否高频属性,  0 - 不是， 1 - 是
                    "highSpeed": 1,
                    //属性参数
                    "params": {
                        //上界
                        "upBound": 9999,
                        //下界
                        "lowBound": 0,
                        //基值, default: 0
                        "base": 0,
                        //系数, default: 1
                        "coef": 1,
                        //限值1, default: 0
                        "limit1Enable": 0,
                        //限值1下限
                        "limit1Low": 123.0,
                        //限值1上限
                        "limit1High": 999.0,
                        //限值2, default: 0
                        "limit2Enable": 0,
                        //限值2上限
                        "limit2High": 999.0,
                        //限值2下限
                        "limit2Low": 0.0
                    }
                },
                {
                    "name": "Switch01",
                    "type": "yx",
                    "params": {
                        //是否取反,default: 0
                        "invert": 0
                    }
                }
            ],
            //服务列表
            "services": [
                {
                    //服务名
                    "name": "start",
                    //服务类型
                    "type": "yk",
                    //服务参数
                    "params": {
                    
                    }
                }
            ]
        }, {
            //设备ID
            "id": "11234131",
            //设备IOT地址
            "addr": "12341235",
            //属性列表
            "attrs":[
                {
                    //属性名
                    "name": "Ia",
                    //属性类型
                    "type": "yc",
                    //是否高频属性,  0 - 不是， 1 - 是
                    "highSpeed": 1,
                    //属性参数
                    "params": {
                        //上界
                        "upBound": 9999,
                        //下界
                        "lowBound": 0,
                        //基值, default: 0
                        "base": 0,
                        //系数, default: 1
                        "coef": 1,
                        //限值1, default: 0
                        "limit1Enable": 0,
                        //限值1下限
                        "limit1Low": 123.0,
                        //限值1上限
                        "limit1High": 999.0,
                        //限值2, default: 0
                        "limit2Enable": 0,
                        //限值2上限
                        "limit2High": 999.0,
                        //限值2下限
                        "limit2Low": 0.0
                    }
                },
                {
                    "name": "Switch01",
                    "type": "yx",
                    "params": {
                        //是否取反,default: 0
                        "invert": 0
                    }
                }
            ],
            //服务列表
            "services": [
                {
                    //服务名
                    "name": "start",
                    //服务类型
                    "type": "yk",
                    //服务参数
                    "params": {
                    
                    }
                }
            ]
        }]
        },
        {
            //链路ID
            "linkId": "1235112",
            //链路名称
            "linkName": "2#风机",
            //协议号
            "protocol": 12,
            //协议参数
            "params": {},
            "devices": [ {
            //设备ID
            "id": "11234131",
            //设备IOT地址
            "addr": "12341235",
            //属性列表
            "attrs":[
                {
                    //属性名
                    "name": "Ia",
                    //属性类型
                    "type": "yc",
                    //是否高频属性,  0 - 不是， 1 - 是
                    "highSpeed": 1,
                    //属性参数
                    "params": {
                        //上界
                        "upBound": 9999,
                        //下界
                        "lowBound": 0,
                        //基值, default: 0
                        "base": 0,
                        //系数, default: 1
                        "coef": 1,
                        //限值1, default: 0
                        "limit1Enable": 0,
                        //限值1下限
                        "limit1Low": 123.0,
                        //限值1上限
                        "limit1High": 999.0,
                        //限值2, default: 0
                        "limit2Enable": 0,
                        //限值2上限
                        "limit2High": 999.0,
                        //限值2下限
                        "limit2Low": 0.0
                    }
                },
                {
                    "name": "Switch01",
                    "type": "yx",
                    "params": {
                        //是否取反,default: 0
                        "order": 0,
                        "invert": 0
                    }
                }
            ],
            //服务列表
            "services": [
                {
                    //服务名
                    "name": "start",
                    //服务类型
                    "type": "yk",
                    //服务参数
                    "params": {
                        "order": 0
                    }
                }
            ]
        }, {
            //设备ID
            "id": "11234131",
            //设备IOT地址
            "addr": "12341235",
            //属性列表
            "attrs":[
                {
                    //属性名
                    "name": "Ia",
                    //属性类型
                    "type": "yc",
                    //是否高频属性,  0 - 不是， 1 - 是
                    "highSpeed": 1,
                    //属性参数
                    "params": {
                        "order": 0
                        //上界
                        "upBound": 9999,
                        //下界
                        "lowBound": 0,
                        //基值, default: 0
                        "base": 0,
                        //系数, default: 1
                        "coef": 1,
                        //限值1, default: 0
                        "limit1Enable": 0,
                        //限值1下限
                        "limit1Low": 123.0,
                        //限值1上限
                        "limit1High": 999.0,
                        //限值2, default: 0
                        "limit2Enable": 0,
                        //限值2上限
                        "limit2High": 999.0,
                        //限值2下限
                        "limit2Low": 0.0
                    }
                },
                {
                    "name": "Switch01",
                    "type": "yx",
                    "params": {
                        //是否取反,default: 0
                        "invert": 0,
                        "order": 0
                    }
                }
            ],
            //服务列表
            "services": [
                {
                    //服务名
                    "name": "start",
                    //服务类型
                    "type": "yk",
                    //服务参数
                    "params": {
                        "order": 0
                    
                    }
                }
            ]
        }]
        }
    ]
}
```

### 节点心跳报文

?> 方向: `采集程序` -> `系统`

**命令:**  `heartbeat`

**数据体:**
```json
{
    //心跳生存时间(毫秒)
    "ttl": 30000,
    //终端状态, 0 - 离线, 1 - 在线
    "status": 0,
    //通讯链路监控信息
    "links": [
        {
            //通讯链路IRN
            "linkId": "3444",
            //通讯链路状态
            "online": true
        },
        {
            "linkId": "123",
            "online": false
        }
    ],
    //设备监控信息
    "devices": [
        {
            //设备ID
            "deviceId": "1123451235464",
            //设备状态
            "online": true
        }]
}
```

### 模拟量数据上报

采集程序向系统推送实时模拟量数据，此数据只刷新缓存，不归档。

?> 方向: `采集程序` -> `系统`

**命令：** `analogData`

**数据体:**
```json
{
    //数据时间(毫秒)
    "dataTime": 123123123123,
    //设备ID
    "deviceId": "1123451235464",
    "values": {
        //key为属性名
        "Ia": 123.1,
        "Ib": 122.1,
        "Ic": 123.1
    },
    //需要归档的数据
    "archiveValues":{
        "P": 1234.12,
        "Q": 12
    }
}
```

### 状态量数据上报

采集程序向系统推送实时状态量数据，此数据只刷新缓存，不归档。

?> 方向: `采集程序` -> `系统`

**命令：** `stateData`

**数据体:**
```json
{
    //数据时间(毫秒)
    "dataTime": 123123123123,
    //设备ID
    "deviceId": "1123451235464",
    "values": {
        //key为属性名
        "Switch01": 1
    },
    //需要归档的数据
    "archiveValues":{
        "Fault001": 0
    }
}
```

### 历史高频数据上报

采集程序推送高频历史数据

?> 方向: `采集程序` -> `系统`

**命令：** `historyHighSpeedData`

**数据体:**

```json
{
    //数据时间(毫秒)
    "dataTime": 123123123123,
    //设备ID
    "deviceId": "1123451235464",
    "values": {
        //key为属性名
        "Ia": 123.1,
        "Ib": 122.1,
        "Ic": 123.1
    }
}
```


### 历史低频数据上报

?> 方向: `采集程序` -> `系统`

**命令：** `historyLowSpeedData`

**数据体:**

```json
{
    //数据时间(毫秒)
    "dataTime": 123123123123,
    //设备ID
    "deviceId": "1123451235464",
    "values": {
        //key为属性名
        "Switch01": 1
    }
}
```

### 遥控/遥调命令请求

?> 方向: `系统` -> `采集程序`

**命令：** `deviceControl`

**数据体:**

```json
{
    //设备ID
    "deviceId": "1123451235464",
    //遥控服务名
    "serviceName": "start",
    //操作值
    "opValue": 1
}
```

### 遥控/遥调命令响应

?> 方向: `采集程序` -> `系统`

**命令：** `deviceControlResp`

**数据体:**

```json
{
    //操作结果
    "result": true,
    //设备ID
    "deviceId": "1123451235464",
    //遥控服务名
    "serviceName": "start",
    //操作值
    "opValue": 1
}
```

### 事件上报命令

采集程序向系统上报变位、越限事件

?> 方向: `采集程序` -> `系统`

**命令：** `deviceEvent`

**数据体:**

```json
[
    {
        //设备ID
        "deviceId": "112345123546",
        //设备属性编码
        "attrCode": "stop",
        //属性值
        "attrValue": 0,
        //事件类型 ( 0-遥信变位 1-越上限 2-越下限 3-越上上限  4-越下下限  5-越限复归)
        "eventType": 0, 
        //事件发生时刻
        "eventTime": 12321351235123,
        //限值
        "limitValue": null
    },
    {
        //设备ID
        "deviceId": "112345123546",
        //设备属性编码
        "attrCode": "Ia",
        //属性值
        "attrValue": 12350,
        //事件类型 ( 0-遥信变位 1-越上限 2-越下限)
        "eventType": 0, 
        //事件发生时刻
        "eventTime": 12321351235123,
        //限值
        "limitValue": 50
    }
]

```