# ***IOT采集与控制的TCP/UDP报文*** 版本说明 | 版本 | 日期 | 变更内容 | 备注 | | ---- | ------------- | ---------------------------------------------------------- | -------------------------- | | 1.0 | | | | | 1.1 | 2022年2月16日 | 1.增加数据上传有效时间的说明2.通过有效时间判断数据的在离线 | 编写：罗广毅 审核：韩艳辉 | ## 通讯说明： - 本协议使用范围是Iot-project,Iot-client,iot-collect 3个服务的通讯数据的规范，为了有效使用本协议建议首先了解TCP和UDP的基础通讯方式。 - **所有报文同时支持TCP和UDP报文方式，并且使用TCP和UDP等价，仅仅是通讯方式的区别，其他没有区别；本文档只是TCP/UDP通讯的报文格式及约定** - **数据上传包可以一次传多个，分隔符使用&,回包的时候&分割的包可能分成多个小包进行回包** 示例: 1101070037;1;report;20010203040506;123;1001;2;11;3.1;12;3.2**&**1101070038;1;report;20010203040506;123;1001;2;11;3.1;12;3.2 - **注：TCP通信为解决半包粘包问题，在包头和包围需要增加左括号和有括号。** **TCP示例 (1101070037;1;connect)** **UDP示例 1101070037;1;connect** - **为避免理解偏差，通信双方均使用目前的服务名称**；涉及服务iot-collect,iot-project,iot-client3个服务之间通讯使用；iot-control服务作废，功能合并到iot-collect; IBMS业务： iot-client<--->iot-project<--->iot-collect 资管业务: iot-client<--->iot-collect 有控制业务必须有iot-project服务,没有控制业务的可以省略iot-project服务; - **时间格式统一采用yyyyMMddHHmmss;** - **历史原因,iot服务的文档以及tcp/udp/http通讯中提到的建筑一律为10位的不带Pj的项目id,不再另行说明**; - iot-collect与iot-project/iot-client是一对多的关系，iot-project与iot-client是一对多的关系，一个项目只能启动一份iot-project; - **服务列表** | 服务名称 | 服务说明 | 说明 | | ----------- | ------------------------------------------------------------ | ---- | | iot-client | iot采集集成，一般对接子系统数据的程序或直接隐身为4-6代采集器或第三方应用等;负责集成各种IOT数据，对接各种二方、三方系统，各种协议的数据 | | | iot-project | 可理解为处理边缘数据到云端数据的中间转发程序;边缘端IOT数据，上传下达的转发服务，所有iot数据都是传输到iot-project,然后再转发到iot-collect，只是上传下达的搬运工，不生产数据，也不处理数据。iot-project也可以提供边缘端的一些实时数据查询和websocket推送能力; | | | iot-collect | 云端采集控制程序，云端处理动态数据到Hbase数据库的应用模块或应用程序;这个服务是几个服务中唯一对业务方提供接口的服务，iot-collec提供主要接口：查询采集实时数据、查询分精度数据、采集值统计下发控制指令、查询指令结果,实时websocket推送数据等。 | | ## **通讯流程** ![](http://assets.processon.com/chart_image/620e13207d9c0807ec9462bf.png) ## 1 心跳类报文 心跳类的报文有3种类，connect/heart/buildingheart。 connect和heart等价，无本质上区别,作为iot-client与 北向服务心跳报文； connect包目前默认5分钟1次，heart包1分钟1次； **心跳包作用：** - 心跳报文作为服务连接正常的判断依据，心跳响应成功后才可以继续各种数据传输； - 通过不断发送心跳防止服务长时间不通讯后断开； - 通过相应回包时间进行时间校准对比； buildingheart是iot-project和iot-collect服务的心跳报文，作为云端控制指令的下发使用,判断被控制信息点的项目是否存在的,控制指令会下发到对应项目的iot-project,一个项目只能部署一份iot-project； ### ***1.1 连接*** Iot-client向Iot-project或Iot-collect通过TCP或UDP的主动发起的。 **连接包** iot-client --> iot-project/iot-collect | 建筑 | 网关 | 类型 | | ---- | ---- | ------- | | 字符 | 整数 | connect | 示例 1101070037;1;connect **应答包** iot-project/iot-collect -> iot-client | 建筑 | 网关 | 类型 | 时间 | | ---- | ---- | ---------- | ---- | | 字符 | 整数 | connectack | 时间 | 示例 1101070037;1;connectack;20010203040506 ### ***1.2 心跳*** Iot-client定时向iot-project/collect发送客户端的存活信息，iot-project/collect如果代表回应说明服务端收到了客户端的信息，心跳周期没有严格定义，根据项目可随便改。 **心跳包** iot-client --> iot-project/iot-collect | 建筑 | 网关 | 类型 | | ---- | ---- | ----- | | 字符 | 整数 | heart | 示例 1101070037;1;heart **应答包** iot-project/iot-collect --> iot-client | 建筑 | 网关 | 类型 | 时间 | | ---- | ---- | -------- | ---- | | 字符 | 整数 | heartack | 时间 | 示例 1101070037;1;heartack;20010203040506 ### ***1.3 项目心跳*** 此心跳是Iot-project到Iot-collect的心跳，如果做开发iot-client可忽略。 ***项目心跳***包 iot-project -> iot-collect | 建筑 | 网关 | 类型 | | ---- | ---- | ------------- | | 字符 | 整数 | buildingheart | 示例 1101070037;0;buildingheart **应答包** iot-collect --> iot-project | 建筑 | 网关 | 类型 | 时间 | | ---- | ---- | ---------------- | ---- | | 字符 | 整数 | buildingheartack | 时间 | 示例 1101070037;0;buildingheartack;20211227110548 ### ***1.4 点位清单及其有效期*** 控制使用点位清单，判断点位离线使用点位有效期 数据有效期全部为秒,有效期为负1(-1)代表长期有效,没有过期时间 有效期只支持下面几个-1,120,600,1800,7200,172800,如果设置的不是上述值,会向上取整找到对应的值,比如设置180,会向上取整到600; ``` SECOND_DEFAULT(-1, "默认值,长期有效"), SECOND_120(120, "2分钟"), SECOND_600(600, "10分钟"), SECOND_1800(1800, "30分钟"), SECOND_7200(7200, "2小时"), SECOND_172800(172800, "48小时"); ``` **点位清单包** iot-client --> iot-project | 建筑 | 网关 | 类型 | 时间 | 有效期(秒) | 序号 | 页容量 | 总页数 | 页编号 | 总条数 | 表号1 | 功能1 | 。。。 | | ---- | ---- | ------------- | ---- | ---------- | ---- | ------ | ------ | ------ | ------ | ----- | ----- | ------ | | 字符 | 整数 | pointValidity | 时间 | 整数 | 整数 | 整数 | 整数 | 整数 | 整数 | 字符 | 整数 | 。。。 | UDP示例 1101070037;1;pointValidity;20010203040506;600;123;123;50;55;2;1001;11;1001;12 TCP示例 (1101070037;1;pointValidity;20010203040506;600;123;123;50;55;2;1001;11;1001;12) **应答包** iot-project --> iot-client | 建筑 | 网关 | 类型 | 时间 | 有效期(秒) | 序号 | 页容量 | 总页数 | 页编号 | 总条数 | 表号1 | 功能1 | 。。。 | | ---- | ---- | ---------------- | ---- | ---------- | ---- | ------ | ------ | ------ | ------ | ----- | ----- | ------ | | 字符 | 整数 | pointValidityAck | 时间 | 整数 | 整数 | 整数 | 整数 | 整数 | 整数 | 字符 | 整数 | 。。。 | UDP示例 1101070037;1;pointValidityAck;20010203040506;600;123;123;50;55;2;1001;11;1001;12 TCP示例 (1101070037;1;pointValidityAck;20010203040506;600;123;123;50;55;2;1001;11;1001;12) ## 2 采集通讯报文 ### ***2.1 数值数据上传*** 数值类型的iot数据上报采用 **数据上报包** iot-client -> iot-project-->iot-collect | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 数量 | 功能号1 | 数据1 | 功能号2 | 数据2 | 。。。 | | ---- | ---- | ------ | ---- | ---- | ---- | ---- | ------- | ----- | ------- | ----- | ------ | | 字符 | 整数 | report | 时间 | 整数 | 字符 | 整数 | 整数 | 字符 | 整数 | 字符 | 。。。 | UDP示例 1101070037;1;report;20010203040506;123;1001;2;11;3.1;12;3.2 TCP示例 (1101070037;1;report;20010203040506;123;1001;2;11;3.1;12;3.2) **应答包** iot-collect -> iot-project --> iot-client | 建筑 | 网关 | 类型 | 时间 | 序号 | | ---- | ---- | --------- | ---- | ---- | | 字符 | 整数 | reportack | 空 | 整数 | UDP示例 1101070037;1;reportack;;123 TCP示例 (1101070037;1;reportack;;123) 数据上传包可以一次传多个，分隔符使用& ### ***2.2 文本数据上传*** 文本类型的iot数据上报采用 **数据上报包** iot-client -> iot-project-->iot-collect | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 数量 | 功能号1 | 数据1 | 。。。 | | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ------- | ----- | ------ | | 字符 | 整数 | text | 时间 | 整数 | 字符 | 整数 | 整数 | 字符 | 。。。 | UDP示例 1101070037;1;text;20010203040506;123;1001;2;11;hello;12;world TCP示例 (1101070037;1;text;20010203040506;123;1001;2;11;hello;12;world) **应答包** iot-collect -> iot-project --> iot-client | 建筑 | 网关 | 类型 | 时间 | 序号 | | ---- | ------- | ---- | ---- | ---- | | 字符 | textack | 字符 | 空 | 整数 | UDP示例 1101070037;1;textack;;123 TCP示例 (1101070037;1;textack;;123) 数据上传包可以一次传多个，分隔符使用&; ### ***2.3 事件消息上传*** 事件消息类型的iot数据上报采用，没有表号和功能号 香港置地火警使用过,目前应该已经没有使用场景了;时间类型的数据不具有表号-功能号标识,无法映射到物理世界物模型. 数据上报包 iot-client -> iot-project-->iot-collect | 建筑 | 网关 | 类型 | 时间 | 序号 | 消息类型 | 消息内容 | | ---- | ---- | --------- | ---- | ---- | -------- | -------- | | 字符 | 整数 | happening | 时间 | 整数 | 字符 | 字符 | UDP示例 1101070037;1;happening;20010203040506;123;firealarm;{"id":"abc"} TCP示例 (1101070037;1;happening;20010203040506;123;firealarm;{"id":"abc"}) 应答包 | 建筑 | 网关 | 类型 | 时间 | 序号 | | ---- | ---- | ------------ | ---- | ---- | | 字符 | 整数 | happeningack | 空 | 整数 | UDP示例 1101070037;1;happeningack;20010203040506;123;firealarm;{"id":"abc"} ## 3 控制通讯报文 ### ***3.1 点位设置*** iot-collect-->iot-project 控制下发的指令格式 **点位设置包** iot-collect-->iot-project | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | 数据 | | ---- | ---- | -------- | ---- | ---- | ---- | ---- | ---- | | 字符 | 整数 | pointset | 空 | 整数 | 字符 | 整数 | 字符 | UDP示例 1101070037;1;pointset;20010203040506;123;1001;11;3.1 TCP示例 (1101070037;1;pointset;20010203040506;123;1001;11;3.1) UDP示例 1101070037;1;pointset;20010203040506;123;1001;11;[3.1,3.2,3.3] **应答包** iot-project --> iot-collect | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | 数据 | 结束时间 | 状态 | | ---- | ---- | ----------- | ---- | ---- | ---- | ---- | ---- | -------- | ---- | | 字符 | 整数 | pointsetack | 时间 | 整数 | 字符 | 整数 | 字符 | 字符 | 字符 | UDP示例 1101070037;1;pointsetack;20010203040506;123;1001;11;3.1;20010203040507;success TCP示例 (1101070037;1;pointsetack;20010203040506;123;1001;11;3.1;20010203040507;success) ### 3.2 点位设置下发协议 ot-project --> iot-client 控制下发的指令格式 **下发包** iot-project --> iot-client | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | 数据 | | ---- | ---- | ----------- | ---- | ---- | ---- | ---- | ---- | | 字符 | 整数 | senddownset | 空 | 整数 | 字符 | 整数 | 字符 | UDP示例 1101070037;1;senddownset;20010203040506;123;1001;11;3.1 TCP示例 (1101070037;1;senddownset;20010203040506;123;1001;11;3.1) UDP示例 1101070037;1;senddownset;20010203040506;123;1001;11;[3.1,3.2,3.3] **应答包** iot-client -> iot-project | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | 数据 | 结束时间 | 状态 | | ---- | ---- | -------------- | ---- | ---- | ---- | ---- | ---- | -------- | ---- | | 字符 | 整数 | senddownsetack | 时间 | 整数 | 字符 | 整数 | 字符 | 字符 | 字符 | **提示：控制和回包使用下面的字面进行唯一标识和对应，所以回包内容中下列字段不可以变更；** | 建筑 | 时间 | 序号 | 表号 | 功能 | 数据 | | ---- | ---- | ---- | ---- | ---- | ---- | UDP示例 1101070037;1;senddownsetack;20010203040506;123;1001;11;3.1;20010203040507;success TCP示例 (1101070037;1;senddownsetack;20010203040506;123;1001;11;3.1;20010203040507;success) ### ***3.3 点位设置通知同步*** 直接通过iot-project进行的控制设定,通过点位设置通知同步到iot-collect,然后保存到数据库中; **点位设置包** iot-project --> iot-collect | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | 数据 | 结束时间 | 状态 | | ---- | ---- | -------------- | ---- | ---- | ---- | ---- | ---- | -------- | ---- | | 字符 | 整数 | reportpointset | 时间 | 整数 | 字符 | 整数 | 字符 | 字符 | 字符 | UDP示例 1101070037;1;reportpointset;20010203040506;123;1001;11;3.1;; UDP示例 1101070037;1;reportpointset;20010203040506;123;1001;11;3.1; 20010203040506;failure_point_not_exist TCP示例 (1101070037;1;reportpointset;20010203040506;123;1001;11;3.1; 20010203040506;failure_point_not_exist) **应答包** iot-collect --> iot-project | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | 数据 | 结束时间 | 状态 | | ---- | ---- | ----------------- | ---- | ---- | ---- | ---- | ---- | -------- | ---- | | 字符 | 整数 | reportpointsetack | 时间 | 整数 | 字符 | 整数 | 字符 | 字符 | 字符 | UDP示例 1101070037;1;reportpointsetack;20010203040506;123;1001;11;3.1; 20010203040506;failure_point_not_exist TCP示例 (1101070037;1;reportpointsetack;20010203040506;123;1001;11;3.1; 20010203040506;failure_point_not_exist) ## 4 作废报文 作废报文都是历史曾经设计支持过的,但是基于以下原因,以后不再支持的报文类型: - 该功能已经删除,pointupload - 该功能没有场景在继续使用,考虑作废, - 已有更好的提供方式,不再推荐使用的功能如presentset,presentreportack,pointupload,virtualpointset - 功能适用场景太有限,考虑不再支持,如pointread 作废的报文以后不再继续提供支持,也不再文档中做过多介绍; ### ***4.1 点位清单上传***(已作废) 点位清单包 采集器 -> 本网关 | 建筑 | 网关 | 类型 | 时间 | 序号 | 页容量 | 总页数 | 页编号 | 总条数 | 表号1 | 功能1 | 。。。 | | -------- | -------- | -------- | -------- | -------- | ---------- | ---------- | ---------- | ---------- | --------- | --------- | ---------- | | 字符 | 整数 | 字符 | 空 | 整数 | 整数 | 整数 | 整数 | 整数 | 字符 | 整数 | 。。。 | UDP示例 1101070037;1;pointupload;;123;50;5;5;2;1001;11;1001;12 应答包 | 建筑 | 网关 | 类型 | 时间 | 序号 | 页容量 | 总页数 | 页编号 | | -------- | -------- | -------- | -------- | -------- | ---------- | ---------- | ---------- | | 字符 | 整数 | 字符 | 空 | 整数 | 整数 | 整数 | 整数 | UDP示例 1101070037;1;pointuploadack;;123;50;5;5 ### ***4.2 点位读取***(已作废) 点位读取包 应用软件 -> 采集软件 | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | | ---- | ---- | ---- | ---- | ---- | ---- | ---- | | 字符 | 整数 | 字符 | 空 | 整数 | 字符 | 整数 | UDP示例 1101070037;1;pointread;;123;1001;11 应答包 | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | 结束时间 | 状态 | 数据 | | ---- | ---- | ---- | ---- | ---- | ---- | ---- | -------- | ---- | ---- | | 字符 | 整数 | 字符 | 时间 | 整数 | 字符 | 整数 | 字符 | 字符 | 字符 | UDP示例 1101070037;1;pointreadack;20010203040506;123;1001;11;20010203040507;success;3.1 1101070037;1;pointreadack;20010203040506;123;1001;11;20010203040507;failure_rrr ### **4.3 读取下发协议(已作废)** 下发包 采集软件 -> 采集器 | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | | ---- | ---- | ---- | ---- | ---- | ---- | ---- | | 字符 | 整数 | 字符 | 空 | 整数 | 字符 | 整数 | UDP示例 1101070037;1;senddownread;;123;1001;11 应答包 | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | 结束时间 | 状态 | 数据 | | ---- | ---- | ---- | ---- | ---- | ---- | ---- | -------- | ---- | ---- | | 字符 | 整数 | 字符 | 时间 | 整数 | 字符 | 整数 | 字符 | 字符 | 字符 | UDP示例 1101070037;1;senddownreadack;20010203040506;123;1001;11;20010203040507;success;3.1 1101070037;1;senddownreadack;20010203040506;123;1001;11;20010203040507;failure_rrr ### ***4.4 虚拟点位设置下发***(已作废) 点位设置包 上级程序->本网关 | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | 数据 | | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | | 字符 | 整数 | 字符 | 空 | 整数 | 字符 | 整数 | 字符 | UDP示例 1101070037;0;virtualpointset;20010203040506;123;1001;11;3.1 应答包 | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | 数据 | | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | | 字符 | 整数 | 字符 | 时间 | 整数 | 字符 | 整数 | 字符 | UDP示例 1101070037;0;virtualpointsetack;20010203040506;123;1001;11;3.1 ### ***4.5 查询当前上传值***(已作废) 点位读取包 上级程序 ->本网关 | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | | ---- | ---- | ---- | ---- | ---- | ---- | ---- | | 字符 | 整数 | 字符 | 空 | 整数 | 字符 | 整数 | UDP示例 1101070037;1;presentreport;20010203040506;123;1001;11 应答包 | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | 数据时间 | 数据 | | ---- | ---- | ---- | ---- | ---- | ---- | ---- | -------- | ---- | | 字符 | 整数 | 字符 | 时间 | 整数 | 字符 | 整数 | 字符 | 字符 | UDP示例 1101070037;1;presentreportack;20010203040506;123;1001;11;20010203040506;3.1 ### ***4.6 查询当前设置值(已作废)*** 点位读取包 上级程序 ->本网关 | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | | ---- | ---- | ---- | ---- | ---- | ---- | ---- | | 字符 | 整数 | 字符 | 空 | 整数 | 字符 | 整数 | UDP示例 1101070037;1;presentset;20010203040506;123;1001;11 应答包 | 建筑 | 网关 | 类型 | 时间 | 序号 | 表号 | 功能 | 数据时间 | 数据 | 结束时间 | 状态 | | ---- | ---- | ---- | ---- | ---- | ---- | ---- | -------- | ---- | -------- | ---- | | 字符 | 整数 | 字符 | 时间 | 整数 | 字符 | 整数 | 字符 | 字符 | 字符 | 字符 | UDP示例 1101070037;1;presentsetack;20010203040506;123;1001;11;20010203040506;3.1; 20010203040506; failure_point_not_exist