泸州市智慧工地综合管理信息平台 塔式起重机监控系统数据接口标准 （版本1.0）

泸州市智慧工地综合管理信息平台

塔式起重机监控系统数据接口标准

（版本1.0）

泸州市住房和城乡建设局

2020年9月

目录

1 前言 7

2 编码规则 7

2.1 协议规范与名称解析 7

3 接口调用 7

3.1 接口说明 7

3.2 服务器地址 7

3.3 接口方式 7

3.3.1 接口概述 7

3.3.2 API基地址 8

3.3.3 POST方法 8

3.3.4 API响应格式 8

3.3.5 API的校验机制与编码规则 8

3.3.6 注意事项 9

3.4 接口列表 9

3.4.1 注册设备/设备上线 9

3.4.2 设备下线 11

3.4.3 设备心跳维持 11

3.4.4 实时数据 11

3.4.5 时间校对 14

3.4.6 工作数据 15

3.4.7 设备开机运行时间记录 17

3.4.8 报警上传 18

附录一 API响应状态码 22

1 前言

本标准描述了塔吊上报接口的规范，主要用于解决：

l 解决设备注册、设备上线、上报数据等问题。

l 完善APIKey（新增一些必要的数据）。

l 优化数据上报地址。

l 优化注释，便于上报者理解。

2 编码规则

2.1 协议规范与名称解析

(1) API地址（REST服务地址）全部小写。

(2) JSON数据内容是用Pascal命名规则。

(3) 协议中出现的时间隔，比如每隔60s发送一次运行数据等，根据具体设备而定（即由设备厂商确定）。

(4) JSON: 一种轻量级的数据交换格式

(5) REST API: 符合rest风格的应用程序接口。

(6) 心跳：设备为保持通讯链路，定时发送少量数据。

(7) 文档规范：一级标题使用三号黑体字，二级标题使用4号宋体字，正文使用小四字体。代码以及备注使用5号宋字体。

3 接口调用

3.1 接口说明

塔机数据上报接口上报设备上线信息、设备下线信息、设备心跳维持信息、设备实时数据信息、时间校对信息，设备工作数据信息、设备开机运行时间记录信息、设备报警上传信息实现数据的更新和存储。

3.2 服务器地址

服务器地址（API地址中api_root部分）：http://api.safe110.net:9991 

3.3 接口方式

3.3.1 接口概述

数据采集接口分为：设备主动上报REST API、设备参数获取设置API。

REST API使用HTTP拉取实现。传输数据格式约定为JSON。API允许有GET、POST、PUT、DELTE四中方法。其中GET、POST、PUT、DELETE为客户端调用API的方法。

3.3.2 API基地址

命令地址格式：http://apiurl /{monitortype}/v1.0 /{servicename}

API基地址包括三部分：域名，版本号，API服类型，服务名称。如上地址表示API服务器域名为：http://apiurl，版本号为：v1.0，服务名称：servicename。

起重机械类型：monitortype

3.3.3 POST方法

命令地址格式：http:// apiurl/{monitortype}/v1.0 /{serveicename}

3.3.4 API响应格式

API响应指调用API客户返回信息。API响应信息有如下格式

{"StatusCode":0,       --响应状态，具体状态码见附录一

"MonitorType":0,     --设备类型 0表示塔吊

"Result":{/*响应JSON格式数据域*/}

}

注：本文档中API调用返回中出现的“StatusCode”都指响应状态（见附录一）。

3.3.5 API的校验机制与编码规则

API服务器在每次收到数据后会根据http包头携带的ApiKey校验数据的有效性，并判断数据来源的设备厂商等相关信息。

用户设备的每次请求，均需要在HTTP请求的header中加入厂商唯一的Api Key。

简易的C#示例代码如下：

request.Headers.Add("ApiKeyValue: kL3HGhesgOY=");

request.Headers.Add("ApiUID: 3DEADFC6-9D60-4358-B845-9A6D646B303F");

request.Headers.Add("ApiKeyType: 0");

request.Headers.Add("DeviceSN: 010713030000 ");

编码规则：采用UTF8。

3.3.6 注意事项

本文档JSON数组定义格式为[{“Data”:”XX”},{/*第2-N个值*/}]，JSON数组可以为空,而不是指必须有一个元素。

本文档中代码部分时间均使用yyyy-MM-dd HH:mm:ss格式（时区为UTC+8）。

本文档中出现的“XXX设置的响应状态上报”均指网站参数设置的响应部分，参数设置请求由网站模拟Socket通信，这里不需要处理。

所有参数（包括设备主动与服务端主动）均通过API POST方法上报，其中服务端主动的参数获取，在本文档中都以API POST方法上报实现网站Socket获取的响应。

本文档中“是否必填”列中的值“M”表示必填。

3.4 接口列表

3.4.1 注册设备/设备上线

对此URL进行Post请求将为您注册一个新设备：

请求参数：

返回结果：

请求示例：

{

"SN":"B1080106",          --设备序列号  

"Type":"B",                 --设备类型简称

"DeviceType":1,            --设备类型代码

"DeviceIp":"127.0.0.1:8888",     --设备IP与端口信息 

"CollisionType":0,     --Int32 防碰撞类型：0无,1直角坐标系,2极坐标系

"RatationType":0,     --Int32 0无,1零度正北顺时针,2零度正东逆时针

"ParamsAppIP":”127.0.0.1:8001”  -- 参数设置应用程序IP与端口信息

}

返回示例：

{

"StatusCode":0,           --响应状态

"MonitorType":0,          --设备类型 0表示塔吊

"Result":{

"Id":1          --设备ID Int32

}

}

注意事项：如果其他命令返回数据时提示“设备未上线或已经下线，请重新注册/上线”需从新发送此注册/上线命令；

3.4.2 设备下线

终端设备主动将设备置为下线状态。

3.4.3 设备心跳维持

终端设备每隔一定时间（默认60S）发送一次心跳请求，保证设备在线。如果API服务端在三次心跳间隔时间内没有收到设备端发送的心跳包，那么认为设备已经下线。

附注：这里的ID指设备注册上线后返回的设备ID。 本文档后续章节中如无特别声明，出现的ID都指设备ID，在服务器注册时分配。

3.4.4 实时数据

设备正常工作时每隔60S生成并发送一条实时数据

请求参数：

返回结果：

请求示例：

{

"Id":1,             --设备ID（注册上线后返回的ID，后续章节相同含义）

"Index":index,             --流水号 表示当前发送数据的序号

"CollectionTime":”2012-10-27 01:12:24”, --采集时间 格式2012-10-27 01:12:24

" Angle":100.0,             --浮点数 回转角度 (°) 正北方向为正

" Radius":2.5,              --浮点数 幅度(m)

"Height":12.1,              --浮点数 吊钩高度 (m)

"Load":2.50,                --浮点数 吊重(t)

"Safeload":2.43,            --浮点数 安全吊重(t)

" MomentPer":95.0,         --浮点数 力矩百分比(%)

"WindSpeed":1.25,          --浮点数 风速(m/s)

"Obliquity":125.0,           --浮点数 塔机倾斜角度(°)

"ObliquityDirAnge":125.0,    --浮点数 塔机方向 (°)

"Fall":2,             --整数值 吊绳倍率

"ControlNo":0,           --Int32  系统输出控制状态编码

"PreAlarm":1,       -- Int32  系统预警状态编码

"Alarm":125,       -- Int32  系统报警状态编码

"BreakRuleNo":2,      -- Int32  违章操作状态编码表

"SensorAlarm":12      -- Int32  传感器报警状态编码  

}

返回示例：

{

   "StatusCode":0,           --响应状态，状态值见附录一

"MonitorType":0,          --设备类型 0表示塔吊

"Result":{

" Index ":1         --运行数据序号

}

}

3.4.5 时间校对

请求参数：

返回结果：

返回示例：

{

"StatusCode":0,               --响应状态，状态值见附录一

"Result":{

" ServerTime ":”2012-12-18 01:10:22”         --运行数据序号

}

}

注意事项：终端设备发送时间校对申请，API服务器收到请求，并返回服务器时间。时间格式：yyyy-MM-dd HH:mm:ss；

3.4.6 工作数据

上报塔吊工作数据

请求参数：

返回结果：

请求示例：

{

"Id":1,            --设备ID

"Index":index,              --流水号 表示当前发送数据的序号

" CollectionTime":”2012-10-27 01:12:24”, --采集时间 格式2012-10-27 01:12:24

" Angle":100.0,             --浮点数 回转角度 (°) 正北方向为正

" Radius":2.5,              --浮点数 幅度(m)

"Height":12.1,              --浮点数 吊钩高度 (m)

"Load":2.50,               --浮点数 吊重(t)

"Safeload":2.43,            --浮点数 安全吊重(t)

" MomentPer":95.0,         --浮点数 力矩百分比(%)

"WindSpeed":1.25,          --浮点数 风速(m/s)

"Obliquity":125.0,           --浮点数 塔机倾斜角度(°) 

"ObliquityDirAnge":125.0,    --浮点数 塔机方向 (°)

"Fall":2,             --整数值 吊绳倍率

"ControlNo":0,          --Int32  系统输出控制状态编码

"PreAlarm":1,      -- Int32  系统预警状态编码

"Alarm":125,      -- Int32  系统报警状态编码

"BreakRuleNo":2,     -- Int32  违章操作状态编码表

"SensorAlarm":12,     -- Int32  传感器报警状态编码     

}

返回示例：

{

"StatusCode":0,           --响应状态，状态值见附录一

"MonitorType":0,            --设备类型 0表示塔吊

"Result":{

" Index ":1           --运行数据序号

}

}

注意事项：工作数据每一次吊重会生成一条，为防止吊重波动生成数据，每一次吊重过程至少要经过30s，少于30s不予记录。报警违章以及控制状态编码见附录一。 

3.4.7 设备开机运行时间记录

设备正常工作时每隔60S生成并发送一条实时数据

请求参数：

返回结果：

请求示例：

{

"Id":1,                 -- Int32 设备ID

"Index":index,                 -- Int32 表示当前发送数据的序号

" StartTime":”2012-10-27 01:12:24”,     --设备开机时间 格式2012-10-27 01:12:24

" RunSecond":100             -- Int32 记录设备从开机到目前运行了多少秒

}

返回示例：

{

"StatusCode":0,           --响应状态，状态值见附录一

"MonitorType":0,       --设备类型 0表示塔吊

"Result":{/*扩展数据，暂时为空*/}

}

3.4.8 报警上传

报警从有到无时上报一次报警信息

请求参数：

返回结果：

请求示例：

{

"Id":1,                 -- Int32 设备ID  

"StartTime":”2012-10-27 01:12:24”, --报警开始时间 格式2012-10-27 01:12:24

"EndTime":”2012-10-27 01:12:24”,  --报警结束时间 格式2012-10-27 01:12:24

"ControlNo":0,           --Int32 系统输出控制状态编码

"PreAlarm":1,       -- Int32 系统预警状态编码

"Alarm":125,       -- Int32 系统报警状态编码

"BreakRuleNo":2,      -- Int32 违章操作状态编码表

"SensorAlarm":12,      -- Int32 传感器报警状态编码 

"LeftAlarm":true,      -- Bool 左转报警 false未报警，true报警

"RightAlarm": true,      -- Bool 右转报警 false未报警，true报警

"OutAlarm": true,      -- Bool 小车出报警 false未报警，true报警

"InAlarm":false,      -- Bool 小车进报警 false未报警，true报警

"LeftEnvironmentAlarm": false,  -- Bool 左转环境报警 false未报警，true报警

"RightEnvironmentAlarm": false,  -- Bool 右转环境报警 同上

"OutEnvironmentAlarm": false,   -- Bool 小车出环境报警

"InEnvironmentAlarm": false,    -- Bool 小车进环境报警  

"MaxRadiusAlarm": false,    -- Bool 最大幅度限位报警

"MinRadiusAlarm": false,     -- Bool 最小幅度限位报警

"HeightUpAlarm": false,     -- Bool 高度上限位报警

"HeightDownAlarm": false,    -- Bool 高度下限位报警

"AngleLeftAlarm": false,     -- Bool 回转左限位报警

"AngleRightAlarm": false,    -- Bool 回转右限位报警

"TorqueAlarm": false,     -- Bool 力矩报警

"WindAlarm": false,      -- Bool 风速报警

"ObliqueAlarm": false     -- Bool 防倾翻倾斜报警      

}

返回示例：

{

"StatusCode":0,           --响应状态，状态值见附录一

"MonitorType":0,       --设备类型 0表示塔吊

"Result":{/*扩展数据，暂时为空*/}

}

附录一 API响应状态码