SensorSDK使用说明书¶

概述¶

SensorSDK是EwayOS的Sensor部分的编程接口SDK，主要包含emake、文档、example部分。

Sensor结构介绍¶

Sensor是EwayOS中的感知层，Sensor接受HighLevelAI连接，开启机器人感知功能，根据机器人的传感器获取的数据运行算法进行运算，将计算结果通过HighLevelAI中转发送至Function，由Function进行处理。Sensor框架主要机制如下：

Element机制¶

Sensor将多个算法拆分成为多个Element，每一个Element负责处理一部分运算。每一个Element由多个输入引脚（InputPin）、多个输出引脚（OutputPin）及消息输出（FeatureCode）组成。一个Element至少拥有InputPin、OutPinPin及FeatureCode其中任意的一个。

InputPin负责接收输入数据，OutPinPin负责讲计算结果输出至下级Element。Feature负责生成发送至Function的消息数据。

每一个InputPin及OutPinPin均有个子的名称。Sensor框架在加载Element时根据每个Pin的名称自主进行拼接，拼接时一个InputPin只能连接一个OutPutPin，一个OutPutPin可连接多个InputPin。对应的Pin连接成功后，OutputPin输出的数据会立刻被InputPin收到。

Element定义Pin及Feature使用宏定义的方式。

Declare_Element_ID("2f1f7297-438d-4674-a8b4-a9982d521134")  定义Element ID，使用GUID，各Element不可重复
Declare_Feature_Code(51)    ：定义输出Feature 51,（具体宏定义请参见FuncSDK）
Declare_Feature_None ： 定义此Element无Feature输出

Declare_Input_Pin_Start ： InputPin定义开始
Declare_Input_Pin(1,"Example Element Input 1",false,EwayOS::CvMatBridge) ：定义1号输入引脚，1为InputPin ID（同一Element下的InputPin ID不可重复），Example Element Input 1为此InputPin 的名称，框架拼接Element的Pin完全根据Pin的名称，相同即为可连，名称大小写敏感。false说明此引脚不是必须引脚，最后声明此引脚输入的数据类名，（数据类必须继承CEwayData）。
Declare_Pin_End ： InputPin定义结束

Declare_Output_Pin_Start ： OutputPin定义开始
Declare_Output_Pin(1,"Example Element Output 1",EwayOS::CvMatBridge) ： ：定义1号输出引脚，1为OutputPin ID（同一Element下的OutputPin ID不可重复），Example Element Output 1为此Output Pin 的名称，最后声明此引脚输出的数据类名。
Declare_Pin_End： OutputPin定义结束

Declare_Feedback_Start ： 保留功能
Declare_FeedBack_End： 保留功能
Declare_Element_Implement(CExampleElement) ： 框架代码

以上代码定义了一个Element，其拥有一个输入Pin，名称为Example Element Input 1，输入数据为EwayOS::CvMatBridge；一个输出Pin，名称为Example Element Output 1，输出数据为EwayOS::CvMatBridge。一个Feature，Code为51，对应CMarkerMessage

Element连接机制¶

Sensor框架运行后，根据-t参数传入的文件名遍历此文件夹下的所有可用Element。当Sensor收到ActiveFeature指令后检测本地是否存在拥有此FeatureCode的Element，若存在则开始连接流程。连接时以一个Element开始，遍历其所有InputPin，根据名称查找本地或网络内是否存在与其名称相同的OutputPin，若存在则加载该Element并将此InputPin及OutputPin进行连接。之后继续遍历，直至所有激活的Element的InputPin均配对成功，则该Feature激活成功。

对于不必须InputPin，连接是框架会检测此引脚对应的输出引脚是否已激活，若已激活，则将此对引脚连接，若未激活，则不进行连接。

若待连接的Element不在本机，框架会自动使用TCP/IP远程调用Element，传输数据。

数据传输机制¶

Sensor框架运行自带智能指针功能，当Element调用OutPutData时，框架会自动将数据复制装入数据仓库，并将智能指针使用回调机制传输至连接的InputPin，对应Element的ProcInputData接口会被自动调用，Element使用GetDataFromPinData获取数据对象指针。（注意，所有Element获得的输入均为同一数据实体，更改其中内容会同时影响所有输入数据。）

所有通过Sensor Pin传递的数据均应继承自CEwayData基类。

PinData中数据中dOrigDataStamp为原始数据生成时的时间戳，此时间戳被框架使用作为帧数据同步的依据，在Element间传递是请勿修改。

当一个PinData在跨机传输过程中，框架会自动调用Serilize接口对数据进行序列化，之后传输到接收PC之后调用Deserilize函数反序列化，之后在依据本机PinData传递机制继续传递。

自定义Message¶

SensorSDK为自定义Message提供一种临时解决方案。用户可以根据需求自定义Feature和Message，自定义的Message必须继承CBaseMessage类，并实现其中的Serilize，Deserilize，opreator ＝，clear和copy函数, 详情请参看自定义Message示例。在EwayOS中Sensor产生的数据最终会流入到Function模块中，如果想在Function中接收sensor中自定义的Message需要在Function中注册这个Message，两个模块引用相同的自定义Message头文件，详请请参阅FunctionSDK中的自定义Messgae。

在自定义的Message的编写过程中存在bug会引起程序崩溃，所以这种方式要求用户有较高的编码和调试能力，EwayOS会在近期提供一种更高效安全的方式来解决这个问题。

输入端口绑定机制¶

对于某些Element，仅有某一输入输入引脚数据无法进行处理，必须多个引脚同一帧数据到齐才可进行处理（如引脚1输入图像数据，引脚2输入深度数据），为此Sensor框架提供绑定机制（binder）。Element中可调用BindInputPinForNotify函数讲某几个InputPin绑定在一起。让某一引脚数据到达后，框架不调用ProcInputData通知Element进行处理，而是暂存入数据仓库等待。当在Binder内的所有引脚同一帧数据都到达后，系统调用ProcInputData接口一次性将此帧所有数据发送给Element。

若不使用ProcInputData回调机制，Element调用CreatePinWaiter创建一个异步Binder，之后在线程内调用WaitPinGetInput函数等待数据到达。若使用等待机制，则在waiter内的数据到达后框架不会调用ProcInputData通知Element处理。

错误处理机制¶

Element在运行过程中发声错误时可调用PostErrorMessage方法，该方法会向框架发送一个错误信息，框架会在全网内广播。若某一Feature数据经过此Element，则框架会自动调用Deactive Feature方法，关闭此Feature，受影响的连接均会被断开。

若Element分布在不同PC上，当某一PC连接出现错误时（进程退出或网络连接断开），受影响连接会发送连接错误消息至框架，框架会自动断开此连接；当某一个Element所有输出连接均被断开后，此Element被判定为无效Element，其所有输入连接将被断开，Element实体将被销毁。同时此连接影响到的Feature会被Deactive。Function可收到Feature Deactived消息。