SimpliciTIAPI使用指南英文翻译

SimpliciTI应用程序接口文档编号:SWRA221美国加利福尼亚州圣迭哥德州仪器有限公司版本号说明日期1.0最初版本2008/08/011.1更新到1.1.0版本2009/01/141.2最新的修改记录2009/03/241绪论1.1目的本文档描述了SimpliciTI软件的应用程序接口。应用程序接口给SimpliciTI协议栈工作提供了一个接口。1.2参考书目1．SimpliciTI1.1.0版本说明书。2．SimpliciTI开发者注意事项。1.3字体使用一些专用的字体：字体用法常规字体用于文件名、代码段、符号和代码示例。带下划线的蓝色正文文件交叉引用链接1.4缩略语和定义API应用程序编程接口。BSP板级支持包CCA清除信道评估GPIO通用输入输出ISR中断服务例程LED发光二极管LQI链接情况指示LRU最近应用MAC介质访问控制。PHY物理层。RSSI接收信号强度指示器2应用程序接口概述2.1接口机制下面的接口机制应用于SimpliciTI的应用程序接口。2.1.1直接执行函数调用这些应用程序接口函数直接执行代码进行工作，函数在执行时联系前后调用，这些函数可能有鉴定识别的部分。2.1.2回调函数在SimpliciTI协议中又一次随意回调的机会，这样的函数必须在应用中定义和执行，并且在初始化时要声明。在运行中断程序时,函数回调的实现应避免CPU强制操作，这一函数将在第7部分做详细的描述。2.2数据接口这些接口支持SimpliciTI协议栈和应用程序之间的发送和接收数据,并最终支持点对点通讯。2.3普通常量和结构体2.3.1公共数据类型下面定义：typedefsignedcharint8_t；typedefsignedshortint16_t；typedefsignedlongint32_t；typedefunsignedcharuint8_t;typedefunsignedshortuint16_t；typedefunsignedlonguint32_t；typedefunsignedcharlinkID_t；typedefenumsmplStatussmplStatus_t；另外一些类型和结构体用于IOCTL接口，这些将在第6部分中详细说明。2.3.2状态下列状态值用于各种API函数。这些都是Status_t类型的值。每个API象征的相应的返回代码将会在后续章节中详细说明。名称描述SMPL_SUCCESS操作成功SMPL_TIMEOUT同步调用超时SMPL_BAD_PARAM在调用错误的参数值SMPL_NOMEM无可用内存。依赖于对象的APISMPL_NO_FRAME在输入帧队列中没有可用帧SMPL_NO_LINK没有收到答复的链接帧发送SMPL_NO_JOIN没有收到答复加入帧发送SMPL_NO_CHANNEL频道扫描没有1个通道响应SMPL_NO_PEER_UNLINK同行无法删除连接。在答复信息返回到中断请求（不正式支持）SMPL_TX_CCA_FAIL帧传输失败，因为清除信道评估失败SMPL_NO_PAYLOAD收到帧但没有得到有效载荷应用SMPL_NO_AP_ADDRESS我们没有收到一个接入点的地址2.3.3专用链接标识SimpliciTI协议支持由应用程序默认的专用链接标识，下面的值表示的专用链接标识。名称描述SMPL_LINKID_USER_UUD未连接的用户数据链路标识。这是一个专用的，无连接链路的编号，它默认被所有用户应用程序所支持。3初始化接口3.1简介SimpliciTI初始化涉及三个初始化阶段：板级、无线和堆栈初始化，并特意把板级初始化（BSP）与无线和堆栈初始化分开：无线和堆栈的初始化作为SimpliciTI初始化调用的结果同时发生；板级初始化可以单独地调用。我们可以不考虑SimpliciTIAPI部分，但还是要注意到初始化的完整性。把板级的初始化分离开来，这样做是为了客户可以使用自己的目标设备的BSP。使板级的初始化明确与SimpliciTI初始化分开，可以更容易地移植到另一个目标设备。3.1.1板级初始化SimpliciTI支持最小板级特定的板级初始化，板级初始化包括LED的GPIO引脚配置、开关配置和一个服务协议事务的计数器/定时器，它还包括双核射频设计需要的SPI初始化。3.1.2无线初始化无线寄存器的改写和无线模块的设置都发生在供电、空闲状态。大部分无线寄存器都是基于SmartRFStudio输出代码，并且默认的通道设置在频道表的第一项。3.1.3堆栈初始化初始化所有的数据结构和网络应用程序，此外，该堆栈产生一个代表该设备的加入请求，在没有中心处理节点的拓扑结构中加入请求将失败，这是提前在拓扑结构中设置的，而不是一种错误情况。这种技术在有中心处理节点时，连接失败是一种错误，在应用程序中就应该尝试重新加入或者是采取其它措施。3.2BSP_Init()3.2.1函数说明它虽然不严格属于SimpliciTI应用程序接口，但调用这个初始化函数可以初始化目标板硬件。该函数应在调用SMPL_Init()前执行。3.2.2函数原型voidBSP_init(void)3.2.3详细参数无。3.2.4返回值无。3.3SMPL_Init()3.3.1函数说明这个函数初始化无线和SimpliciTI协议栈，并且必须在软件运行和调用任何SimpliciTI应用程序接口函数前调用一次。3.2.2函数原型smplStatus_tSMPLInit(uint8_t(*callback)(linkID_t))3.3.3详细参数参数描述callback指针的功能，可以对应一个linkID_t参数返回一个uint8_t参数非空的声明回事的被调用的函数成为回调函数并被注册。由于该函数只被调用一次，该回调函数服务与平台上的所有逻辑终端设备。3.3.4返回值可能的状态如下：状况描述SMPL_SUCCESS初始化成功SMPL_NO_JOIN没有连接回应，可能是没有中心处理节点，在拓扑中无中心处理节点时不是错误。SMPL_NO_CHANNEL1、只有当频率变换时；2、如果没有AP；3、频率通道扫描会失败。4连接接口4.1简介此接口提供了建立两个对等节点之间连接的机制。4.2SMPL_Link()4.2.1函数说明这个函数的调用发送了一个广播连接帧后等待应答，一接到应答，两节点之间的连接就被建立，一个链接ID作为应用层对连接的处理结果被指定使用。这个调用等待一个应答，如果在一定时间内没有接收到应答也会返回，所以他不是一个严格的模块化调用，等待时间的缩放是基于帧的长度和数据传输速度并且在自动初始化过程中确定。这个函数可以多次调用来建立多个逻辑连接，在同级节点中可能连接相同或不同的设备。4.2.2函数原型smplStatus_tSMPL_Link(linkID_t*lid)4.2.3详细参数参数描述lid这个参数是一个指向LinkID指针，如果调用成功，指针指向的变量将有效，并将在随后的具体节点应用程序接口中使用，用来指向特定的设备。4.2.4函数返回可能的状况如下：状况描述SMPL_SUCCESS连接成功。SMPL_NO_LINK在等待其间没有连接应答。SMPL_NOMEM没有空间分配给当地的接收端口，没有更多的连接表空间，或没有在输出帧队列空间。SMPL_TX_CCA_FAIL无法发送链接帧。4.3SMPL_LinkListen()4.3.1函数说明这个函数侦听一个广播的连接帧，当收到一个连接帧时，他会直接向发送节点返回一个应答。这个函数调用是一个修改后的模块调用，他将把“forawhile”模块化成下面这个设置在nwk_api.c源文件中的常量所描述的那样。常数描述LINKLISTEN_MILLISECONDS_2_WAIT数毫秒阻止听取链接帧。默认值为5000（5秒）如果侦听超时，应用程序可以实现恢复策略。这包括建立另一个侦听窗口。注意存在这样一种间隙情况，侦听调用在超时后被调用时，有可能一个链接帧在其不侦听的这一小段时间内到达。4.3.2函数原型smplStatus_tSMPL_LinkListen(linkID_T*lid)4.3.3详细参数参数描述lid这个参数是一个指向LinkID指针，如果调用成功，指针指向的变量将有效，并将在随后的具体节点应用程序接口中使用。4.3.4函数返回可能的状况如下：状况描述SMPL_SUCCESS连接成功。SMPL_TIMEOUT在侦听时间内没有接收到连接，Link_ID无效。5数据接口5.1简介应用程序接口提供了发送和接收端之间的数据接口。5.2SMPL_SendOpt()5.2.1函数说明此函数利用能指定传输选项的能力，把应用数据发送到指定节点。该网络的代码需要适当地为无线服务做调整，在完成调用之前无线将处于同一状态，应用将一直不做任何处理直到无线达到一定要求。默认情况下，一直试图强制发送CCA。5.2.2函数原型smplStatus_tSMPL_SendOpt(linkID_tlid,uint8_t*msg,uint8_tlen.txOpt_topts)5.2.3详细参数参数描述lid用来发送信息目标节点的连接IDmsg消息指针寄存器。len消息的长度。这可以是0。在没有应用情况下发送消息负载是合法的。opts被选择的有效传输选项的位图。‘lid’参数必须在先前一个成功链接时确定，除了未连接用户自带寻址信息的LINKID（参见2.3.3节），这个linkID总是有效。由于这种连接不是基于连接的，使用这一ID的信息可以作为有效的数据表发送到所有应用节点。有效的传输选项是:选项描述SMPL_TXOPTION_NONE没有选择。Nooptionsselected.SMPL_TXOPTION_ACKREQ来自目标节点的请求确认。同步调用。5.2.4返回值状况描述SMPL_SUCCESS传送成功。SMPL_BAD_PARAM无效的入口连接ID；入口连接数据不合适；无消息或者消息太长。SMPL_NOMEM输出数据针队列没有空间。SMPL_TX_CCA_FAIL通信配置失败，发送数据不成功。SMPL_NO_ACK未接收到确认。5.3SMPL_Send()5.3.1函数说明这个函数是把应用数据发送到一个节点。除了传送选择项，应用编程接口和SimpliciTI早期的版本保持一致。这个应用编程接口相当于以指定的SMPL_TXOPTION_NONE参数调用SMPL_SendOpt()。该网络的代码需要适当地为无线服务做调整，在完成调用之前无线将处于同一状态，应用将一直不做任何处理直到无线达到一定要求。默认情况下，一直试图强制发送CCA。5.3.2函数原型smplStatus_tSMPL_Send(linkID_tlid,uint8_t*msg,uint8_tlen)5.3.3详细参数参数描述lid目标节点的连接ID。msg指向消息存储空间的指针。len消息的长度。这可以是0。在没有应用情况下发送消息负载是合法的。用负荷负载是合法的。‘lid’参数必须在先前一个成功链接时确定，除了未连接用户自带寻址信息的LINKID（参见2.3.3节），这个linkID总是有效。由于这种连接不是基于连接的，使用这一ID的信息可以作为有效的数据表发送到所有应用节点。5.3.4函数返回值可能的状况如下：状况描述SMPL_SUCCESS传输成功。SMPL_BAD_PARAM没有有效的链接入口的ID；链接入口数据不合适；没有信息或者是信息太长。SMPL_NOMEM输出数据针对列没有空间。SMPL_TX_CCA_FAIL通信配置失败，未能发送消息。5.4SMPL_Receive()5.4.1函数说明这个函数的功能就是核对从任何节点收到的数据帧数组。除非设备是轮流检测设备，否则他将不会激活无线或者不会将无线的状态转换为接收模式，他所做的只是去核对接收到的数据帧是否为指定的连接。如果设备是在配置文件中指定了的设备（参见theDevelopersNotes中的9.2节），网络层将要使能无线发送轮流检测的申请，并接受