Kithara常用功能模块使用

Kithara除了构建了一个与windows并行运行的实时子系统，还在其构建的实时子系统中搭建了很多功能模块，如EtherCAT主站，实时视觉等。这些功能模块全部以API函数接口的形式提供给用户使用。本章将对Kithara最经常使用的功能模块的功能，及其用法进行介绍。

EtherCAT主站使用

EtherCAT主站是Kithara提供的最重要功能模块之一。通过Kithara提供的EtherCAT主站软件模块，用户可以使用任何一个带Kithara支持的Intel或Realtek网卡的工控机，然后按安装上包含EtherCAT模块的Kithara软件，就可以搭建一个EtherCAT主控制器.学习Kithara EtherCAT主站可以参考的官方资料如下:

  1. API和结构体定义说明
  2. EtherCAT基本使用教程
  3. EtherCAT状态机
  4. EtherCAT重新分配和映射PDO方法
  5. EtherCAT热插拔的使用
  6. EtherCAT DC分布使用使用
  7. 提高EtherCAT主站初始化速度方法
  8. EtherCAT从站相关功能
  9. EAP使用 官方例程: Kithara安装目录/smp/EtherCATBridge Kithara安装目录/smp/EtherCATBridgeConfig Kithara安装目录/smp/EtherCATConfigPdo Kithara安装目录/smp/EtherCATDataExchange Kithara安装目录/smp/EtherCATDcOverSampling Kithara安装目录/smp/EtherCATDcTimeStamp Kithara安装目录/smp/EtherCATDrive Kithara安装目录/smp/EtherCATEapNode Kithara安装目录/smp/EtherCATEoeWindowsConnection Kithara安装目录/smp/EtherCATLoadFirmware Kithara安装目录/smp/EtherCATRedundancy Kithara安装目录/smp/EtherCATSafety Kithara安装目录/smp/EtherCATScanTopology Kithara安装目录/smp/EtherCATSimple Kithara安装目录/smp/EtherCATSimpleDc Kithara安装目录/smp/EtherCATSlaveDevice Kithara安装目录/smp/EtherCATSlaveDevicePrepare 说明：默认安装目录在C:\Program Files\Kithara[Kithara Driver Name]\

EtherCAT主站基本介绍

EtherCAT总线是目前使用最广泛的工业实时以太网总线之一。其具有拓扑结构灵活，通信效率高，速度快，应用层支持CANopen等特点，在近几年得到广泛的应用。各大工控厂商也都纷纷推出了相关的EtherCAT从站设备（IO，伺服）产品，因此用户可以非常方便的根据需要，选择相应的EtherCAT从站设备，搭配Kithara EtherCAT主站构建一个设备的运动控制系统.

Kithara EtherCAT主站程序架构

使用Kithara 提供的EtherCAT主站功能的控制系统中，一般至少都要创建三个任务：周期性定时器回调任务，网卡中断回调任务，用户应用相关任务(可以把用户任务放在一个普通函数里，在中断回调函数里调用).周期性定时器回调任务根据配置的主站通信周期，周期性的把从站控制信息组成下发数据包,然后发送给各个从站.网卡中断回调任务则是接收EtherCAT总线反馈回来的数据包，并解析各个从站的状态信息.而用户应用相关任务主要是处理与具体应用相关的逻辑，以及规划各轴运动等. 1709472948299 在Kithara中，每个任务的主函数都对应到Kithara内核中的回调函数。如上图所示，与定时器任务绑定的回调函数TimerCallBack中，通过 KS_postEcatDataSet，把从站控制数据组装成EtherCAT总线数据包，并下发到EtherCAT总线中。EtherCAT数据包是集总帧形式的，下发的数据包经过每个从站的时候，每个从站从该数据包中取出各自从站的控制数据，并把各自的状态数据插入到该数据包中，数据包下行到最后一个从站后，由最后一个从站把更新后的数据包返回到主控制器中。主控制器接收到从站反馈回来的数据包后，会触发与网卡中断处理任务绑定的DataSetCallBack回调函数执行，其通过 KS_readEcatDataSet读取并更新从站状态信息。在这之后，与用户应用任务绑定的AppTaskCallBack回调函数将被触发执行。至此一个完整的控制周期就结束了,系统将再次等待定时器触发下一个周期的任务的执行.

Kithara EtherCAT主站一般建立流程

一般情况下，一个完整的基于Kithara EtherCAT主站的应用从建立到结束的流程如下表:

步骤 功能 使用API 说明
1 打开Kithara驱动 KS_openDriver() 这是所有基于Kithara应用程序
第一步
2 枚举系统所有网卡，
并打开EtherCAT
使用的网卡		 KS_enumDevices()
KS_openNetworkAdapter ()		 Kithara EtherCAT主站使用PC
标准以太网口硬件作为总线接口
,由于EtherCAT数据包收发有实
时性要求,因此需要安装Kithara
网卡驱动,替代原先的默认以太网
卡驱动
3 创建用户层和内核层
共享内存		 KS_createSharedMem() 对于一般的Kithara应用程序，
为了实现windows内核层数据
和应用层数据共享，一般都需要
创建共享内存
4 加载EtherCAT内核
dll模块到Kithara内核		 KS_loadKernel() 由于EtherCAT相关任务有实时
性要求，因此需要以dll的形式
载入到windows内核空间中
执行
5 创建EtherCAT主站，
并查询EtherCAT主站
状态		 KS_createEcatMaster()
KS_queryEcatMasterState()		 创建主站的时候，需要选择
主站使用的网卡句柄，以及
从站xml文件路径。通过查询
主站状态，可以知道主站是否
连接从站，以及从站的个数
信息等
6 创建EtherCAT主站
数据集合		 KS_createEcatDataSet() 主站数据集相当于一个数据
收发的容器，Kithara驱动内部
将把所有从站PDO数据放到
该容器中
7 创建并安装主站
相关的回调函数		 KS_createKernelCallBack()
KS_installEcatHandler()		 主站回调函数用于当与主站
相关的特定事件发生时调用，
其主要有，主站发生错误时的
回调函数、主站拓扑结构发生
变化时的回调函数以及主站
网卡接收到数据的回调函数
8 创建并配置
EtherCAT从站		 KS_createEcatSlave()
KS_assignEcatDataSet()
KS_lookupEcatDcOpMode()
KS_configEcatDcOpMode()		 在创建EtherCAT通信过程中,
需要根据实际连接的硬件,
创建与之对应的从站，并获得
从站句柄.另外还需要配置从站
DC同步参数,以及把从站PDO
数据分配到创建的数据集中
9 得到从站PDO
数据接口		 KS_getEcatDataObjAddress() 在EtherCAT从站进入周期通信
的时候,从站PDO数据将
周期性的刷新,因此通过获得
从站PDO数据指针,就能获得
上传的PDO信息以及刷新
下发的PDO信息
10 创建定时器任务,
并启动定时器任务		 KS_createKernelCallBack()
KS_createTask()
KS_createTimer()
KS_activateEcatDcMode()		 定时器任务用于周期性的下发
EtherCAT数据包,EtherCAT有
两种运行模式,FreeRun和DC
同步模式.当使用DC同步模式
的时候,需要使用
KS_activateEcatDcMode来启动
定时器
11 切换EtherCAT通信
到运行状态		 KS_changeEcatState() EtherCAT通信过程有：
INIT、PreOP、SaveOP、
OP这几个状态，正常运行
时应该处于OP状态
12 正常运行 EtherCAT主站进入正常的周期
通信
13 停止EtherCAT通信,
销毁Kithara资源		 KS_changeEcatState()
KS_stopTimer()
KS_killTask()
KS_execKernelFunction()
KS_removeTask()
KS_removeCallBack()
KS_deleteEcatSlave()
KS_deleteEcatDataSet()
KS_closeEcatMaster()
KS_freeKernel()
KS_freeSharedMem()
KS_closeAdapter()
KS_closeDriver()		 当程序接收的时候,需要停止
EtherCAT通信,即切换EtherCAT
通信状态到INIT,而后按照资源
创建顺序的倒叙,即先创建的后
销毁,销毁Kithara资源,并关闭
网卡驱动以及Kithara驱动

除了上述比较通用的流程，在基于Kithara EtherCAT主站编写应用的时候，还可能用到一些其他的功能如SDO读写，使用环形拓扑等。对于初学者，Kithara在安装目录下的smp文件夹下提供的EtherCAT相关例子是一个不错的学习资料。此外您也可以联系我们，我们会给您提供更加实用的Kithara EtherCAT主站使用示例

Kithara EtherCAT主站其他相关问题说明

PDO数据接口的重新分配

在某些情况下，默认激活的PDO通道映射数据不能满足用户使用需求。如用户需要伺服的力矩前馈和速度前馈数据接口，在这种情况下就需要重新分配PDO通道到相应的同步管理器，或者重新映射激活的PDO通道内的对象。为了实现这一功能Kithara提供了相关的API，能够实现用户重新映射PDO通道数据，并重新分配PDO通道到同步管理器。以0x1600通道（0x1600分配到输出同步管理器）为例，流程如下所示: 1.复位输出同步管理器分配的通道信息

ksError = KS_setEcatPdoAssign(pAppPtr->hSlave[index], KS_ECAT_SYNC_OUTPUT, -1, 0);
if (ksError != KS_OK) {
    Demo_OutputKrtsError("KS_setEcatPdoAssign error", ksError);
    return;
}

2.分配0x1600 PDO通道到输出同步管理器

ksError = Ks_setEcatPdoAssign(pAppPtr->hSlave[index], KS_ECAT_SYNC_OUTPUT, 0x1600, 0);
if (ksError != KS_OK) {
    Demo_OutputKrtsError("KS_setEcatPdoAssign error", ksError);
    return;
}

3.复位0x1600 PDO通道映射数据对象信息

ksError = KS_setEcatPdoMapping(pAppPtr->hSlave[index],0x1600, -1, 0, 0, 0);
if (ksError != KS_OK) {
    Demo_OutputKrtsError("KS_setEcatPdoMapping error", ksError);
    return;
}

4.添加0x1600 PDO通道映射的数据对象信息 如下所示，把控制模式0x6060，控制字0x6040，目标位置0x607A这些数据对象，分别添加到0x1600 PDO通道中，这些对象的subIndex 对应0、1、2.

ksError =KS_setEcatPdoMapping(pAppPtr->hSlave[index].0x1600, 0x6060, 0, 8, 0);
if (ksError != KS_OK) {
    Demo_OutputKrtsError("KS_setEcatPdoMapping error", ksError);
    return;
}
ksError =KS_setEcatPdoMapping(pAppPtr->hSlave[index].0x1600, 0x6040, 0, 16, 0);
if (ksError != KS_OK) {
    Demo_OutputKrtsError("KS_setEcatPdoMapping error", ksError);
    return;
}
ksError =KS_setEcatPdoMapping(pAppPtr->hSlave[index].0x1600, 0x607A, 0, 32, 0);
if (ksError != KS_OK) {
    Demo_OutputKrtsError("KS_setEcatPdoMapping error", ksError);
    return;
}

<mark>注意 </mark>:

  1. 在重新映射PDO通道对象，重新分配PDO通道到同步管理器时，总线的状态必须是PreOP前
  2. 映射到PDO通道的数据对象，其读写属性必须和相应的PDO通道对应
  3. 映射到PDO通道的数据对象，其伺服必须支持 <mark>PDO通道映射时的注意事项 </mark>： 以清能德创伺服为例，在进行0x6060映射时需要再改PDO对象后面进行假字节对齐PDO映射，才不会出现OutPutMapping Error 0x25，Codesys平台下不对假字节进行映射也会出现类似问题 1709476757442 Kithara支持的数据发送形式为LRW形式发送数据帧 1709476973182

DC同步模式

每个EtherCAT从站伺服设备对应的DC同步模式的名字可以在其设备描述文件中的Dc一节中找到。如下所示，伺服支持两种运行模式，FreeRUN和DC运行模式，DC运行模式的操作模式的名称就是“DC”。需要注意的是，每个不同厂商的伺服，该名称可能都不同。 1709477035258

环形拓扑功能

EtherCAT各个从站之间通过网线互联，这些网线若是松动导致断开，将会导致EtherCAT通信出现异常。在一些应用场合，这种通信的中断将会导致一些危险。为了减少因为网线断开，而导致通信故障，可以采用环形拓扑的方法。如下图所示，环形拓扑是通过把总线的最后一个从站设备和主控制器的另一个网口相连实现硬件的冗余。当系统中的一跟网线断开时，由于所有的从站设备依旧和主站有着物理连接，这样通过EtherCAT主站的环形拓扑功能，就能保证在一根网线断开的情况下，总线通信还能正常工作。Kithara EtherCAT主站支持环形拓扑功能，并且用户能检测到任何拓扑结构的变化。 1709477091230

实时视觉模块使用

Kithara提供的实时视觉模块包含两大部分：图像的实时获取和图像的实时处理。对于图像的实时获取，Kithara支持USB3.0和GiGe两种接口相机。对于图像的处理，Kithara支持在内核层采用OpenCV或Halcon库进行图像处理，此外用户也可以自己编写图像处理算法进行图像处理学习Kithara实时视觉模块可以参考一下官网资料:

  1. 文档资料如何在Kithara内核控制相机如何在Kithara内核使用OpenCV如何在Kithara内核使用Halcon库
  2. 使用例程 Kithara安装目录/smp/CameraImageAcquisition Kithara安装目录/smp/CameraSimple Kithara安装目录/smp/CameraWithLinkAggregation Kithara安装目录/smp/VisionHalcon Kithara安装目录/smp/VisionHalconWithCamera Kithara安装目录/smp/VisionOpenCV Kithara安装目录/smp/VisionOpenCVDisplay Kithara安装目录/smp/VisionOpenCVWithCamera

实时视觉模块基本介绍

传统的视觉系统一般都不具备实时性能，其一般直接采用相机厂商提供的驱动，实现相机的配置和控制，以及图像的获取，并直接采用现有的图像处理库，对采集到的图像进行处理。由于相机驱动以及图像处理的环境（大部分是在Windows或linux操作系统下），不具备实时性，因此整个视觉系统是非实时的。也就是说无法保证，从图像的获取到图像处理完毕，并输出处理结果时间的准确性。例如，在某个应用中，可能一个大部分一个处理周期都在100ms左右，但是偶尔出现几次一个周期大于200ms，甚至更大如500ms，1s。

对于一般的应用，由于视觉处理周期不需要很短，如1秒甚至更长时间采集并处理一次即可，且如果在特点的时间没有处理过来，也不会对整个系统造成太大的影响，这个时候用实时视觉意义就不是那么大，然而当系统对图像的采集和处理周期要求很严格，如视觉处理的周期必须在50ms，甚至更低如10ms，这个时候，不管是用纯软件的方案，还是硬件的方案，视觉系统必须是实时的。

此外实时视觉，对于降低视觉系统对硬件处理能力的要求，以及提高系统的稳定性也具有一定的意义。

实时视觉模块程序一般结构

1709477928403 如图所示，对于实时视觉应用任务，用户一般至少需要两个任务，图像接收任务和图像处理任务。

对于图像接收任务，其为一个中断回调任务，其默认的优先级为192/193（Kithara任务的优先级为0~255），当有图片信息到来时，就会触发相应的图片接收中断回调函数执行。图像处理任务可以是Kithara的一个具有较高优先级的任务（如优先级为250），当图片接收完成后，图片接收任务可以通过事件触发图像处理任务的执行。当图像处理完毕后，可以通过共享内存或其他方式，把处理得到的信息传给其他任务，如EtherCAT用户主任务，从而可以实现视觉和运动控制的结合。

实时视觉模块一般建立流程

这里以使用GiGe接口相机，和OpenCV图像处理库为例说明，一般情况下，一个实时视觉应用从建立到结束的流程

步骤 功能 使用API 说明
1 打开Kithara驱动 KS_openDriver() 这是所有基于Kithara应用程序
第一步
2 创建用户层和内核层
共享内存		 KS_createSharedMem() 对于Kithara应用程序，为了实现
windows内核层数据和应用层数据
共享，一般都需要创建共享内存
3 加载实时视觉内核
dll模块		 KS_loadVisionKernel() 为了实现图像接收和处理的实时，
其相应任务的执行主体都需要
以动态连接块的形式，加载到
Kithara内核中
4 创建内核资源，如事件 KS_createEvent() 一般都需要创建事件，用于图像
接收任务，和图像处理任务的同步
5 查询硬件系统的信息 KS_getSystemInformation()
KS_enumDevices()		 为了打开系统的网卡，配置任务
独占CPU核，一般都要查询系统
的基本信息，如支持的网卡，
可独占的CPU核序列
6 创建图像处理任务 KS_setTargetProcessor()
KS_createKernelCallBack()
KS_setTaskStackSize()
KS_createTask()		 Kithara内核任务默认栈大小为
3KB，对于调用OpenCV库的
图像处理任务，由于OpenCV
代码把内核线程当做普通
windows线程，因此需要设置成
Windows线程默认的栈大小1MB。
此外可以设置任务独占某个特定的
CPU核，提高处理任务的实时性能
7 建立与相机的连接，
配置相机，并创建图
像流		 KS_openNetworkAdapter()
KS_execAdapterCommand()
KS_enumCameras()
KS_openCameraEx()
KS_configCamera()
KS_createKernelCallBack()
KS_createCameraStream()
KS_installCameraHandler()		 GiGe接口相机是采用标准的
以太网口，因此为配置相机，
需要打开连接到相机的网卡，
设置其IP地址和相机在统一网段，
查找并打开连接的相机，而后
为获取相机图像信息，需要建立
一个流，并创建一个相机接收
回调函数，与创建的流接收
图像信号绑定
8 启动相机接收图像 KS_startCameraAcquisition() 至此相机就进入正常的工作状态
9 系统正常工作状态
10 停止相机收图 KS_stopCameraAcquisition()
11 释放所有相机使用的
资源		 KS_installCameraHandler()
KS_closeCameraStream()
KS_removeCallBack()
KS_closeCamera()
KS_closeNetwork()
12 释放OpenCV处理
任务使用的资源		 KS_removeTask()
KS_removeCallBack()
13 释放其他Kithara资源，
关闭Kithara驱动		 KS_closeEvent()
KS_freeKernel()
KS_freeSharedMem()
KS_closeDriver()

对于初学者，Kithara在安装目录下的smp文件夹下提供的实时视觉相关例子，如“VisionOpenCVWithCamera”是一个不错的学习资料。此外您也可以联系我们，我们会给您提供更加实用的实时视觉模块使用示例

实时视觉模块其他相关说明

Task与Timer

用户需要创建实时任务时，可以调用 KS_createTask函数进行Task创建，创建成功后，需要指定对应的回调函数，KS_createKernelCallBack，两个函数之家按的关联是通过回调函数的句柄传递的

// 插补数据更新任务，任务回调函数
ksError = KS_createKernelcallBack(
                &m_hGcodeDataUpdateKernelTaskcallback[i],  // Address of callback handle
                m_hGCodeIpoModule,  // Kernel handle
                m_callbackName_GcodeDataUpdateKernelTask,  // callback function
                NULL,  // Parameter to the callback
                m_funcExecFlag,  // Flags
                0);  // Priority
if (ksError != KS_OK) {
    return;
}
// 创建任务
ksError = Ks createTask(&m_hGcodeDataUpdateKernelTask[i],  // Address of task handle
                        m_hGcodeDataUpdatekernelTaskcallback[i],  //Callback object to be executed
                        GCodeEngine_KernelTaskPriority_GCodeDataUpdate,  // Priority of the task
                        0);  // Flags,here enable the customized stack size

在Task任务中可以调用KS_sleepTask进行延时处理，在timer中不可以调用KS_sleepTask进行延时处理

SSD文件实时读写模块使用

  • [ ] 待完善

实时通信模块的使用

  • [ ] 待完善

Base Module模块使用说明

Base Module是基础模块、必须模块

ID 名称 备注
1 KS_openDriver 打开驱动
2 KS_openDriverEx 根据版本号打开对应驱动
3 KS_CloseDriver 关闭驱动，当设备驱动不用时，需要调用该API接口关闭驱动
4 KS_getDriverVersion 获取驱动版本
5 KS_getDriverVersionAsString
6 KS_getErrorString 获取错误代码
7 Ks_getSystemInformation 获取操作系统信息，包括硬件信息
8 Ks_getProcessorInformation 获取处理器相关信息
9
10
11
12

Kernel Module模块使用说明

内核模式采用dll的形式将API接口加载内核模式下，用户模式核内核模式的系统层区别在于内存寻址区域，使用KS_loadKernal函数加载内核dll，通过配置flag来选择将函数加载到内核模式还是用户模式 1709480362037