TS-BUS家居控制软件KNX通讯协议模块详细设计说明书V1.00.docx

TIANSUTS-BUS家居控制软件KNX通讯协议模块详细设计说明书评审记录对"S-BUS家居控制软件KNX通讯协议模块详细设计说明书YL00的评审意见:上述问题修改验证后，由验证后，本文件即可发布。评审人员签字:问题修改验证结果:验证人签字：时间：年月一日变更日志编号版本修改内容修改人修改日期123451引言11.1 编写目的11.2 背景113定义11.4 参考资料12 系统设计总体说明22.1 系统结构23 模块详细设计33.1 外部接口模块33.1.1 功能描述33.1.2 性能要求33.1.3 接口定义33.1.4 类设计说明43.1.5 程序流程63.1.6 测试要点63.2 UDP通讯模块63.2.1 功能描述63.2.2 性能要求63.2.3 接口定义63.2.4 类设计说明63.2.5 程序流程83.2.6 测试要点83.3 KNX核心处理模块83.3.1 功能描述83.3.2 性能要求93.3.3 接口定义93.3.4 类设计说明93.3.5 程序流程103.3.6 测试要点113.4 数据类型处理模块123.4.1 功能描述123.4.2 性能要求123.4.3 接口定义123.4.4 类设计说明123.4.5 程序流程123.4.6 测试要点123.5 异常类模块123.5.1 功能描述123.5.2 性能要求133.5.3 接口定义133.5.4 类设计说明133.5.5 程序流程143.5.6 测试要点141引言1.l编写目的本文档是对TS-BUS家居控制软件通讯协议模块（以下称为TS-BUS通讯协议模块）的要求进行详细分析和讨论后得出的详细设计说明书，旨在明确软件对TS-BUS通讯协议模块的需求，并对模块的具体实施进行详细的计划、安排和设计。通过本详细设计说明书，可以了解到TS-BUS通讯协议模块的总体设计、各模块以及模块之间内部接口的详细设计。借助该文档，可指导TS-BUS通讯协议模块的开发人员开始软件的编码工作。本文档面向的读者是：TS-BUS家居控制软件项目开发负责人、评审人员。1.2 背景模块名称：TS-BUS家居控制软件通讯协议模块根据TS-BUS家居控制软件（简称为TS-BUS软件）的开发需求，TS-BUS通讯协议模块主要用于实现TS-BUS软件与EIB/IP网关之间的通讯，数据的请求和接收处理，数据类型的转换等功能。该模块主要为TS-BUS的Ul模块提供操作接口，以满足Ul模块所需要实现的数据通讯和处理需求。该模块功能的实现，使用户能方便的对ElB总线上的设备进行相应的读、写等相关操作，实现总线设备的自动化控制，从而达到家居智能化控制的目的。1.3 定义下表列出本报告中专门术语的定义、英文缩写词的原词组和意义、项目组内达成一致意见的专用词汇，同时继承全部的先前过程中定义过的词汇。词汇名称词汇含义备注1.4 参考资料编号资料名称说明1TS-BUS家居控制软件项目立项书2TS-BUS家居控制软件项目计划书3TS-BUS家居控制软件需求规格说明书4TS-BUS家居控制软件通讯协议模块概要设计说明书2系统设计总体说明2.1系统结构根据对TS-BUS通讯协议模块功能的分析，该模块划分为以下几个子功能模块，其类图如图21所示：1 .外部接口模块：主要包括向模块外部提供的接口，以及需要外部调用模块实现的回调方法。2 .UDP通讯模块：主要实现UDP报文收发逻辑处理。3 .KNX核心处理模块：主要实现KNX帧的处理，达到对EIB总线设备数据的读写操作。4 .数据类型处理模块：主要实现各种不同的KNX数据类型与字节数组之间的相互转换。图2-1TS-BUS通讯协议模块类图3模块详细设计3.1 外部接口模块3.1.1 功能描述主要包括向模块外部提供的接口，以及需要外部调用模块实现的回调方法。该模块主要为Ul模块提供通讯接口服务，以致UI模块可以很方便的操作EIB总线设备。3.1.2 性能要求无。3.1.3 接口定义本模块定义的回调方法，分别完成本模块对逻辑组数据类型的请求、调用模块(即UI模块)逻辑组数据的读/写响应等，这些方法均由TS-BUS通讯协议模块的调用者一Ul模块来实现，它们分别是：typedefint(CALLBACK*GetDPT)(intnMainAddr,intnMidAddr,intnGrpAddrtypedefvoid(CALLBACK*OnReadResponse)(GroupDatagrpData.intnStatus);typedefvoid(CALLBACK*OnWriteResponse)(intnMainAddr,intIiMidAddr,intnGrpAddr,intnResult);typedefvoid(CALLBACK*OnSearchResponse)(char*serverip,intservcrPort,intnStatus);typedefvoid(CALLBACK*OnDisconnect)();在TS-BUS通讯协议模块内部，为其调用者提供了以下接口，分别是设置回调方法指针、初始化UDP参数、处理逻辑组数据的读/写请求等，分别是：voidSetCallBacks(GetDPT*pGetDPT,OnReadResponse*pReadResponse,OnWriteResponse*pWriteResponse,OnSearchRcsponse*pSearchRcsponse,OnDisconncct*pDisconnect);intUDPSocketInit(char*serverip,intserverPort);intReadGrpVal(intnMainAddr,intnMidAddr,intnGrpAddr);intWriteGrpVal(GroupDatagrpData);UI模块与KNX协议模块接口的时序图如图3-1所示。3.1.4 类设计说明类名ICKNXKemel主要属性说明GetDPTvoid SetCallBacks（GetDPT *pGetDPT, OnReadResponse *pRcadResponse, OnWriteResponsepWriteResponse, OnSearchResponse *pSearchResponse, OnDisconnect *pDisconnect）;设置回调函数指针int UDPSocketInit（char * serverip, int serverPort）;初始化 UDP socketint ReadGrpVal （int nMainAddr, int nMidAddr, int nGrpAddr）;读逻辑组值int WriteGrpVal （GroupData grpData）;写逻辑组值m_PGetDPT;/回调方法的指针（获取逻辑组数据类型）OnReadResponse*m_pReadResponse;/回调方法的指针（逻辑组数据读响应处理）OnWriteResponse*m_pWriteResponse;/回调方法的指针（逻辑组数据写响应处理）OnSearchResponse*m_pSearchResponse;/回调方法的指针（自发现响应处理）OnDisconnect*m_pDisconnect;/回调方法的指针（断开连接的响应处理）主要方法说明建组播，自发现接收组播报文分析报文，结束组播初始化UDP模块KNX通道连接接收返回报文启动心跳监测发送读逻辑组UDP报文接收消息发送读逻辑组UDp报文接收消息接收到通道断开消息停止心跳监测UDPClose3.1.5 程序流程略。3.1.6 测试要点本模块为接口模块，其测试要点主要是检查与外部模块之间的接口方法是否能正常的相互调用。3.2 UDP通讯模块3.2.1 功能描述实现TS-BUS通讯协议模块与IP网关之间的UDP通讯，以UDP携带KNX帧的方式实现KNX请求与响应等相关功能帧的收发。其实现的功能包括组播和无连接点对点的通讯，它们各自的SoCke3接收线程的建立，以及线程的结束和SOCkel的关闭。UDP重发考虑：考虑不同KNX服务需要不同的重发机制，为减小UDP模块与KNX核心处理模块的藕合度，重发机制主要由KNX核心处理模块考虑，UDP模块仅实现循环3次重发而不做额外的延时。3.2.2 性能要求无。3.2.3 接口定义UDP通讯模块与KNX核心处理模块之间的接口类如下所示：classCKNXUdpIface(public:virtualintExecRecvMsgAction(BYTE*pRecvBuf)=0;)；KNX协议模块与UDP通讯模块接口的操作时序如图3-2所示。3.2.4 类设计说明类名CUDPManager主要属性说明CKNXUdpIface*m_pKnxPtr;charm-serverlp32;intm_serverPort;主要方法说明intUDPInit(char*serverip,intserverPort);voidSelKnxPtr(CKNXUdpIface*pInterClassPtr);intUDPSend(BYTE*pSendBuf);intUDPRecv(BYTE*pRecvBuf);intUDPClose();/UDP通讯初始化设置接口类对象指针发送UDP报文接收UDP报文关闭UDP通讯建组播启动组播接收线程发送UDP报文接收组播报文结束组播控制端点、数据端点SOCket初始化建立控制端点接收线程发送TUnnel连接请求控制端点接收报文建立数据端点接收线程发送UDP报文接收返回报文停止接收报文关闭SoCkeI3.2.5 程序流程UDP通讯模块主要包括UDP报文的收发逻辑，其中，发送报文功能由UDPSend()方法实现，由KNXKemel模块调用触发；接收报文功能由UDPReCV()方法实现，通讯初始化完成时启动一循环逻辑不断调用该方法接收UDP报文，接收到UDP报文后调用相应的CKNXUdPIfaCe接口类方法，做出相应的处理。1.UDP通讯模块是否能与KNX核心处理模块实现正确的相互调用；2 .发送正确格式的UDP报文，是否能正常发出并接收到来自IP网关的回复:3 .是否能被动接收到来自IP网关的主动UDP报文。3.3KNX核心处理模块3.3.1 功能描述主要功能是对KNX帧进行组装、拆分和分析。即，对其调用者(Ul模块)的请求组装KNX帧，通过UDP模块发送，并接收UDP回复报文进行处理和分析，调用Ul回调方法执行相应的动作。考虑要点：(1)组播请求(用于发现服务)：不重发，超时时间为3秒；(2)控制点请求：连接请求：运行于主线程，阻塞，不重发，超时时间10s；连接状态请求：单独线程，每隔60秒发送一次，每次请求超时时间为10s,连接两次超时则断开连接通道。断开连接：运行于主线程，阻塞，不重发，超时时间1s,超时未收到回复则强行断开。(3)数据点请求：用于数据请求服务。偿试发送两次，失败则断开通道连接。332性能要求无。333接口定义KNX核心处理模块与UDP通讯模块的公共接口类CKNXUdpIface类的定义请参见本文3.2.3节。KNX核心处理模块相应的类CKNXKemel需要继承于该公共接口类，并实现类中的ExecRecvMsgActionO方法。该方法是UDP通讯模块回应KNX核心处理模块的接口，CKNXKemel类中ExecRecvMsgActionO方法实现KNX帧的解析工作。对KNX帧进行解析后，需要调用UI模块的Response回调方法，以将KNX回更结果反映至Ul模块，以执行相应动作。3.3.4类设计说明关于CKNXKernel与UI模块接口相关的部分请参见本文3.1.4节。此处仅对UDP通讯模块回应KNX核心处理模块的接口EXeCReCvMSgAClion()方法做相应的说明。类名ICKNXKemel主要属性说明无主要方屈明intExecRecvMsgAction(BYTE*pRecvBuf);对缓冲区pRecvBuf进行KNX帧的解析3.3.5程序流程图3-4(a)KNX核心处理模块帧发送流程图图3-4(a)KNX核心处理模块帧解析流程图3.3.6测试要点1 .UDP模块对CKNXUdPIfaCe接口方法的调用；2 .能否组装正确的KNX帧；3 .能否正确处理回复的KNX帧。3.4 数据类型处理模块3.4.1 功能描述实现BYTE字节数组与KNX各种不同数据类型(主要是十七种大数据类型)之间的转换，包括：当KNX核心处理模块接到写数据请求时，将调用数据处理模块CDPTManager类的DPT2Byte(),将某一KNX数据类型数据转换为字节数组，并填入KNX帧中，作为一个写逻辑组值请求KNX帧发出；当KNX核心处理模块接到来自UDP模块的读逻辑组值回应时(由IP网关发出，UDP通讯模块接收)，在KNX核心处理模解析KNX帧时，它将调用数据处理模块CDPTManager类的Byle2DPT()方法，将BYTE字节数组所携带的值转换为相应的KNX数据类型值。3.4.2 性能要求无。3.4.3 接口定义无。3.4.4 类设计说明类名CDPTManager主要属性说明无主要方法说明intGetVarTypeFromDPT(intnDPT);从KNX数据类型(17种)获取程序变量类型(5种)BYTE*DPT2Byte(GroupDatagrpData,BYTE*PBUf);将KNX数据转为BYTE字节数组intByte2DPT(BYTE*pBuf,GroupData&grpData);将BYTE字节数组转为KNX数据类型值3.4.5 程序流程略。3.4.6 测试要点1 .在KNX核心处理模块中能否正确调用该类的方法；2 .能否正确地将KNX数据转为BYTE字节数组；3 .能否正确地将BYTE字节数组转为KNX数据类型值。3.5 异常类模块3.5.1 功能描述为KNX协议模块，以及所有使用KNX协议模块的模块，提供KNX错误描述。由一个虚基类CKNXException派生多个异常子类，每次出现的异常是其中的一种，对应一个子类。其它模块可通过lry.CalCh结构来捕获，其使用方法的源码示例在TS-BUS家居控制软件KNX协议模块概要设计说明书已给出。3.5.2 性能要求无。3.5.3 接口定义typedefenum(KNX_ERR_UNKNOWN=O,KNX_ERR_INPUT,KNX_ERR_NETWORK,KNX_ERR_UDP,KNX_ERR_CALLBACK,KNX_ERR_DPTCONVERTIONKNX_EXCEPTIONJD;classCKNXException(public:virtualKNX_EXCEPTION_IDGetExceptionIdO=O)；3.5.4 类设计说明由CKNXException派生出的异常类有CKNXUnknownException、CKNxinputException、CKNxNetworkException、CKNxUdpExceptionCKNXCallbackException、CKNxDPTConversion-EXCePtion等，分别为KNX异常提供相应的错误码，各子类的实现如下所示：classCKNXUnknownException:publicCKNXException(public:virtualKNX_EXCEPTIONJDGetExceptionIdO(returnKNX_ERR_UNKNOWN;)；classCKNxinputException:publicCKNXException(public:virtualKNX_EXCEPTION_IDGetExceptionIdOreturnKNX.ERRJNPUT;);classCKNxNetworkException:publicCKNXException(public:virtualKNX_EXCEPTION_IDGetExceptionIdO(returnKNX_ERR_NETWORK;)；classCKNxUdpException:publicCKNXException(public:virtualKNX_EXCEPTIONJDGetExceptionIdO(returnKNX_ERR_UDP;)I；classCKNXCallbackException:publicCKNXException(public:virtualKNX_EXCEPTION_IDGetExceptionIdO(returnKNX_ERR_CALLBACK;I；classCKNXDPTConvertException:publicCKNXException(public:virtualKNX_EXCEPT1ON_IDGetExceptionIdO(returnKNX_ERR_DPTCONVERSION;)；3.5.5程序流程略。3.5.6测试要点1 .其它模块是否可正常调用CKNXException的GeIEXCePlionld()方法。2 .调用KNX协议模块并发生错误时，通过CEXCePtiorlld()获取的错误码与实际错误是否相符。