使用 GenTL Interface#
GenTL Producer 是实现 GenICam GenTL 传输层接口的库。GenTL Consumer 是通过该接口加载一个或多个 Producer 的任何应用程序或库，例如 pylon、HALCON 或您自己的软件。实现的 Producer 符合 GenICam GenTL Standard 1.5。
使用 GenTL Producer，您可以执行以下操作：
- 通过相同的接口 (GenApi) 配置兼容 GenICam 的 Camera Link 和 CoaXPress 相机。
- 查看图像采集系统的层次结构。
- 开发通用应用程序 (GenTL Consumer)，而无需考虑所使用的相机标准。
打开 GenTL Producer#
目录 <Framegrabber SDK installation directory>/bin 包含两个 GenTL Producer 文件：
| Producer | 传输技术 |
|---|---|
| ProducerCL.cti | Camera Link |
| ProducerCXP.cti | CoaXPress |
.cti 文件用于标识 GenTL Producer。该扩展名代表 Common Transport Interface（通用传输接口）。
请勿直接打开 GenTL Producer。请打开一个 GenTL consumer，例如 pylon。当 GENICAM_GENTL64_PATH 或 GENICAM_GENTL32_PATH 环境变量正确设置后，consumer 会加载 GenTL Producer。每个变量包含一个或多个 producer 目录。Framegrabber SDK 会添加 <Framegrabber SDK installation directory>/bin 更改为 GENICAM_GENTL64_PATH 或 GENICAM_GENTL32_PATH。在安装或卸载软件包后，请验证 GENICAM_GENTL64_PATH 或 GENICAM_GENTL32_PATH 环境变量是否仅包含一个 Basler producer 路径。有关如何在 GENICAM_GENTL64_PATH 当并行安装 pylon 和 Framegrabber SDK 时，请参见 并行安装 pylon 和 Framegrabber SDK.
GenTL 配置文件#
GenTL Producer 会在以下目录中为每个发现的采集卡保存一个配置文件：
- Windows：%AppData%\basler
- Linux：~/.config/basler
.config 文件存储该图像采集卡的 Producer 设置，例如所选的 Applet、发现方法以及相机协议配置。如果删除该文件，Producer 会将该图像采集卡的配置重置为默认值。在删除文件之前请关闭 Consumer，并在操作完成后再次打开 Consumer。
此配置是持久的，且属于图像采集卡。在一个应用程序会话中进行的设置在下一个会话以及不同的 GenTL Consumer 中仍然处于活动状态。请将存储的设置视为图像采集卡的活动配置文件。这些设置不是设置它们的应用程序的临时选项。有关更改后的设置何时生效的更多信息，请参见应用和持久化更改。
GenTL 模块层级#
GenTL 将采集系统以模块层级结构的形式呈现给 consumer：
| 模块 | 在 Framegrabber SDK 中的表示形式 |
|---|---|
System | Producer 本身。此模块是层级结构的入口点。 |
Interface | 一块采集卡。 |
Device | 一台相机，或者代表采集通道的伪设备。 |
Data Stream | 设备的一个采集流。 |
Buffer | 为图像采集预分配的内存。 |
Consumer 可以用不同的方式显示此层级结构。本主题中的 GenApi 特性名称在每个 consumer 中都是相同的。以下部分中的大部分配置都属于 Interface 模块。它属于采集卡，而不属于相机。
Interface Applets#
即： Interface 模块列出了 InterfaceApplets 类别中可用的 applet。在 InterfaceApplets > InterfaceApplet，您可以选择 Applet 或 .hap 除当前加载的文件之外的其他文件。
Producer 将 applet 更改保存在持久的 GenTL 配置文件中。只有在关闭所有设备并更新设备列表之后，或者在关闭并重新打开 Interface之后，更改才会生效。选择 applet 并更新设备后，请等待几秒钟。然后检查 InterfaceAppletStatus 以查看 Applet 是否已加载。
采集卡类型决定了哪些 Applet 可用：
| 采集卡 | Applet 可用条件… |
|---|---|
| imaWorx、imaFlex | 该小程序位于文件系统中的 Framegrabber SDK 安装目录下的 DLL 或 Hardware Applets 子目录中。运行包含该小程序的安装程序，或者将 VisualApplets 的 .hap 文件复制到 Hardware Applets 文件夹中（例如 …\Basler\FramegrabberSDK5.x.x\Hardware Applets）。 |
| marathon | 该小程序已烧录到采集卡上。如果尚未烧录，请先进行烧录。有关更多信息，请参见 将小程序烧录到 marathon 采集卡上。 |
有关在 microDiagnostics 中管理小程序的更多信息，请参见 管理小程序 (microDiagnostics)。
通过 User Sets 进行 Applet 配置#
MCF 文件用于存储小程序配置。MCF 代表 microEnable Configuration File（microEnable 配置文件）。文件扩展名为 .mcf。有关更多信息，请参见 MCF 文件。
在 UserSetControl 类别中的 Interface 模块，您可以保存和加载当前所选小程序的配置。要保存或加载该配置，请输入现有或新建的路径 *.mcf 文件中提供现有或不存在的 UserSetFile 参数中输入现有或新建的 *.mcf 文件路径。然后执行 UserSetSave 或 UserSetLoad。如果路径为空，或者文件扩展名不是 .mcf，则这两个命令不可用。
其中涉及两个不同的配置文件。它们具有不同的作用域和生命周期：
| 文件 | 包含 | 生存期 |
|---|---|---|
| *.mcf | 单个小程序的参数值。 | Producer 按需加载这些值，使用 UserSetLoad。非持久化：在更改小程序或关闭系统后，Producer 不会保留这些值。 |
| *.config | 单个采集卡的 GenTL Producer 配置。 | 持久化：每当 Producer 初始化时，都会自动重新加载此文件 Interface. |
如果当前加载的小程序与加载的 .mcf 文件引用的程序不匹配，Producer 会首先尝试设置 InterfaceApplet 设置为配置文件中的 Applet。请关闭设备并更新设备列表。切勿关闭 System。随后配置将生效。
设备发现与伪设备#
即： DiscoveryMethod 功能（Interface.DiscoveryMethod in Interface > TransportLayerControl）时，Producer 都会自动重新加载此文件，该功能定义了更新设备列表时 Producer 所创建的设备。
发现模式概述#
DiscoveryMethod | 暴露的设备 | 的默认值 |
|---|---|---|
EmulationDiscovery | 为小程序的每个采集通道分配一个伪设备。不搜索真实的相机。 | Camera Link |
MixedDiscovery | 搜索真实相机。在 Camera Link 上，搜索使用 GenCP 或 CLP。未发现相机的采集通道将用伪设备填充。 | — |
CameraDiscovery | 仅搜索并暴露真实相机。不创建伪设备。 | CoaXPress |
在无法发现相机时，伪设备（仿真设备）可使 Applet 及其采集通道保持可用状态。对于每个伪设备，Producer 会生成一个基本的远程设备 XML 文件。如果 Applet 包含图像生成器，Producer 默认会激活该图像生成器。若要接收来自已连接的 Camera Link 相机的图像，请禁用远程设备节点中的图像生成器。
根据预期的用途选择发现模式：
EmulationDiscovery：当您开发或检查 Applet、未连接相机，或者必须在没有相机控制的情况下访问 Applet 参数和采集通道参数时，请使用此模式。真实相机发现功能将被禁用，且不使用相机协议配置。MixedDiscovery：当必须找到真实相机且空的采集通道必须作为伪设备保持可访问状态时，请使用此模式。在 Camera Link 上，通过 GenCP 或 CLP 搜索真实相机。对于 VisualApplets 也可以使用此模式 .hap 文件，包括在 CXP 采集卡上。有关更多信息，请参见 结合 GenTL 使用 VisualApplets Applet.CameraDiscovery：当应用程序必须仅列出真实相机时，请使用此模式。
对于 Camera Link，发现真实相机还需要相机协议。有关更多信息，请参见 访问 Camera Link 相机。
兼容性状态#
即： CompatibilityStatus 类别报告当前采集卡、Applet 和相机的组合是否能够协同工作。
接口模块（图像采集卡）#
| 功能 | 回报值 |
|---|---|
InterfaceDriverVersion | 此驱动程序的版本号 Interface. |
InterfaceProducerVersion | GenTL Producer 的版本号。 |
InterfacePCIeStatus | 如果 PCIe 速度达到或超过所需速度，该功能将显示检测到的 PCIe 速度（例如 Gen3x8）。否则，该功能会显示诸如 Warning: Gen2x1 detected, but Gen3x8 possible之类的警告。降级链路会限制可用的带宽。 |
InterfacePowerSupplyStatus | 如果采集卡的电源连接器已连接，该功能将显示 Connected 。如果电源连接器未连接，该功能将显示 Warning: PCI-Power connector missing 。 |
在 pylon Viewer 中， 兼容性状态 小节了解 Interface 模块的兼容性状态如下：
设备模块（相机）#
| 功能 | 回报值 |
|---|---|
DevicePixelformatStatus | 如果采集卡的电源连接器已连接，该功能将显示 Supported 如果相机支持配置的 Pixel Format。否则，该功能默认显示 Warning: Not supported. |
DeviceAutomaticROIControlStatus | 如果采集卡的电源连接器已连接，该功能将显示 Activated ，或者在禁用 Automatic ROI 时显示 Deactivated 。在 pylon Viewer 中，禁用 Automatic ROI 下的 Device Transport Layer > Image Format Control。当相机的步长与 Applet 的步长不同且 ROI 被调整为下一个较低的匹配值时，该功能显示 Warning: ROI truncated according to stepping 。 |
DeviceTapGeometryStatus | 如果采集卡的电源连接器已连接，该功能将显示 Supported 如果找到了匹配的 tap geometry。否则，该功能显示 Warning: Driver does not support tap geometry setting 或 Warning: Requested geometry not supported in applet. |
Tap geometry 描述了传感器数据的传输方式。对于 1X_1Y（这是大多数相机的默认设置），整个图像作为一个数据流进行传输。大型、高速的传感器可能需要 1X_2YE。在该模式下，传感器同时以两个子帧进行读出。请仅在相机要求且 Applet 支持时设置 1X_2YE 。
在 pylon Viewer 中， 兼容性状态 小节了解 Device 模块的兼容性状态如下：
自动 ROI 与格式#
在 ImageFormatControl 类别中的 Device 模块中，您可以找到 AutomaticFormatControl, AutomaticROIControl, AutomaticTapGeometryControl和 OutputPacketFormats 节点。当 AutomaticFormatControl, AutomaticROIControl和 AutomaticTapGeometryControl 处于活动状态时，GenTL Producer 会配置 Applet 的格式、ROI 和 tap geometry，使其与相机设置相匹配，并且您只需配置一次相机和 Applet。此行为适用于 microEnable 6 frame grabber 的 Applet。
当 Applet 必须保留其自己的配置时，请禁用这些功能。这特别适用于使用 VisualApplets 设计的 Applet。有关更多信息，请参阅 Using VisualApplets Applets with GenTL。
访问 Camera Link 相机#
ProducerCL.cti 可以发现 Camera Link 相机并为其提供完整的 GenApi 访问权限，包括相机的 XML 描述文件。这种访问对于第三方 Camera Link 相机非常有用，因为大多数 GenTL Producer 不为这些相机提供 XML 访问权限。以下部分介绍了两种支持的相机协议以及如何配置它们。
为什么 Camera Link 需要配置协议#
在 Camera Link 上，您可以配置相机协议。协议不会被自动检测。Camera Link 标准化了图像传输和串行连接。它并未标准化如何通过该串行线路控制相机。每个厂商都实现了自己的命令协议。由于没有首先尝试的标准协议，因此无法进行自动检测。使用任意协议变体进行探测需要耗费太长时间，并且可能会使某些相机模型进入未定义状态。
GenApi 需要面向寄存器的访问：读取此地址，写入彼地址。相机的 XML 文件描述了该访问权限。两条标准化的路径将串行线路与此寄存器模型连接起来：
| 路由 | 如何弥合差距 | 相机特定部分驻留在何处 |
|---|---|---|
| GenCP | 相机本身在串行线上实现了一个标准化的、基于数据包的寄存器访问协议。 | 相机固件。主机上不需要供应商软件。 |
| CLP (CLProtocol) | 来自相机供应商的协议库将 GenApi 寄存器访问转换为供应商的专有串行协议。 | 安装在主机上的 CLProtocol 库（.dll 文件）。 |
这两条路径不可互换。拥有厂商 CLP 库的相机无法理解 GenCP。GenCP 相机不需要 CLP 库。
信息
Basler Camera Link 相机不兼容 GenCP，但它们支持 CLP。安装了 Basler CLProtocol 库后，ProducerCL 可以直接访问相机的 XML 文件以及完整的相机配置。
GenCP (Generic Control Protocol) 是针对基于寄存器的设备的 GenICam 标准。相机在串行线上响应标准化的读写命令。这些命令从 9600 波特的 Camera Link 唤醒速率开始。相机通过引导寄存器映射公开其身份，并通过该寄存器空间中的清单提供其 GenICam XML 文件。与相机相关的一切都在固件中，因此 GenCP 相机无需主机上的供应商特定软件即可工作。
CLP (CLProtocol) 是所有其他 Camera Link 相机的 GenICam 标准。供应商的 CLProtocol 库为 GenApi 提供寄存器接口，并将该接口转换为相机自己的串行协议。对于基于 ASCII 的相机，该库提供伪寄存器空间和匹配的 XML 描述。为每个供应商安装 CLProtocol 库并通过 GENICAM_CLPROTOCOL 环境变量进行注册。在每个注册目录下方，64 位 Windows 应用程序的库位于 Win64_x64 子目录中。对于 Basler 库，该文件为
Basler CLP 自动配置#
即： ConfigurationForBaslerCLP 功能为 Basler Camera Link 相机提供自动配置。该功能默认启用。在 Interface 初始化，Producer 检查是否 BaslerClProtocol.dll 可以通过 GENICAM_CLPROTOCOL。如果 Producer 找到该库，它将进行以下更改：
- 将
DiscoveryMethod更改为MixedDiscovery. - 将
ClpSharedLibraryPath找到 BaslerClProtocol.dll.
只读 Property BaslerCLPAutoConfigActive 表示自动配置正在生效。更新设备列表后，请在 LoadedClpSharedLibraryPath.
在自动配置处于活动状态时，它会控制 DiscoveryMethod 和 ClpSharedLibraryPath。若要手动设置其中任一 Property，请首先设置 ConfigurationForBaslerCLP 更改为 false.
手动协议选择#
配置的协议（GenCP 或 CLP）取决于相机。请在配置协议之前设置 ConfigurationForBaslerCLP 更改为 false 。
对于 GenCP（当未配置 CLP 库时，用于实际相机发现的默认协议）：
| 步骤 | 功能 | 值 |
|---|---|---|
| 1 | ConfigurationForBaslerCLP | false |
| 2 | ClpSharedLibraryPath | 空 |
| 3 | DiscoveryMethod | MixedDiscovery 或 CameraDiscovery |
对于带有厂商库的 CLP：
| 步骤 | 功能 | 值 |
|---|---|---|
| 1 | ConfigurationForBaslerCLP | false |
| 2 | ClpSharedLibraryPath | 厂商 CLProtocol 库（.dll 或 .so 文件）的完整路径，通常位于在以下位置注册的目录中： GENICAM_CLPROTOCOL |
| 3 | DiscoveryMethod | MixedDiscovery 或 CameraDiscovery |
更新设备列表后，请在 LoadedClpSharedLibraryPath. ClpSharedLibraryPath 仅存储请求的路径。 LoadedClpSharedLibraryPath 报告实际加载的库。
Camera Link 特性参考#
所有 Property 都位于 Interface > TransportLayerControl:
| 功能 | 目的 |
|---|---|
ConfigurationForBaslerCLP | 启用自动 Basler 配置。该 Property 默认处于启用状态。在手动配置协议之前，请将其禁用。 |
BaslerCLPAutoConfigActive | 只读。表示自动配置处于活动状态且已找到 Basler CLProtocol 库。 |
DiscoveryMethod | 选择实际相机、伪设备或两者。有关更多信息，请参见 设备发现和伪设备。 |
ClpSharedLibraryPath | 请求的 CLProtocol 库的完整路径。路径为空时，选择 GenCP 用于发现真实相机。 |
LoadedClpSharedLibraryPath | 只读。实际加载的 CLProtocol 库。 |
下表显示了典型配置：
| 预期用途 | ConfigurationForBaslerCLP | DiscoveryMethod | ClpSharedLibraryPath |
|---|---|---|---|
| 仅 Applet 或采集通道，无真实相机 | false | EmulationDiscovery | 未使用 |
| Basler Camera Link 相机 | true | 自动控制 (MixedDiscovery) | 自动控制（BaslerClProtocol.dll） |
| 兼容 GenCP 的相机 | false | MixedDiscovery 或 CameraDiscovery | 空 |
| 带有厂商 CLP 库的相机 | false | MixedDiscovery 或 CameraDiscovery | 供应商库的完整路径 |
串行连接的建立方式#
CLProtocol 库不直接与图像采集卡通信。该库接收来自加载该库的软件的串行接口 (ISerial)。当该库在 ProducerCL 内部运行时，Producer 会提供其自己的内部 ISerial 实现。对图像采集卡的访问保留在 Producer 内部，不涉及其他串行组件。
诸如 pylon 等独立的 CLProtocol 客户端不在 GenTL 内部运行。这些客户端通过以下方式获取串行接口： CLAllSerial. CLAllSerial 在注册表值下注册的目录中发现 Camera Link Serial 库（clser*.dll）。通常，该目录为 HKEY_LOCAL_MACHINE\SOFTWARE\CameraLink\CLSERIALPATH。在该目录中， C:\Program Files\CameraLink\Serial为 Basler 图像采集卡实现 Camera Link Serial。 clsersis.dll 。在
两条路径通向相同的硬件。无法同时通过两条路径初始化图像采集卡。此限制主要在安装 pylon 时尤为重要。本主题未介绍将 ProducerCL.cti 用作 pylon 传输层的使用方法。有关更多信息，请参见 并行安装 pylon 和 Framegrabber SDK。
应用并保存更改#
对 DiscoveryMethod，Applet 选择以及 GenCP 或 CLP 设置仅在您更新设备列表后生效。在某些情况下，更改仅在您关闭并重新打开 Interface 或重新启动 Consumer 后生效。请在应用配置之前完成完整配置。应用配置后，请评估结果。
该配置针对每个图像采集卡保存，并且在各个会话之间保持有效，即使在关闭 producer 后也是如此。有关更多信息，请参见 GenTL 配置。当预期用途发生变化时，请记住以下几点：
- 持久化的
EmulationDiscovery设置会阻止发现真实相机。这是有意设计的。 - 持久化的
CameraDiscovery当所选协议无法识别相机时，设置不会创建任何伪设备。 - 更换相机后，持久化的 CLP 路径将继续选择该供应商库。
- 启用 Basler 自动配置后，它会在每次
MixedDiscovery和 Basler CLP 路径时恢复Interface初始化。
Interface 某些 Consumer 中的节点访问
在某些 Consumer（例如 HALCON）中， Interface node map 仅在检测到至少一个设备时可用。如果 DiscoveryMethod 设为 CameraDiscovery 且协议与相机不匹配，则 producer 不会创建任何设备。这样，您将无法在该 consumer 中访问发现设置。请找到与图像采集卡的序列号关联的配置文件。在 Windows 上，该文件位于 %AppData%\basler。在 Linux 上，该文件位于 ~/.config/basler。修改该文件中的发现设置，或者删除该文件以重置配置。对于纯 applet 设置，请使用 EmulationDiscovery 以避免这种情况。该模式始终会创建伪设备。
结合 GenTL 使用 VisualApplets Applet#
设计考量#
Applet 文件名： applet 的文件名将直接用作 Name 中相应条目的 InterfaceApplets 枚举属性。因此，文件名必须符合 GenICam 命名要求。GenICam 2.1.1 标准指定了以下要求：
Each node has a Name attribute. The Name must be unique within the camera description
file. Names can be composed of alphanumeric characters [A-Za-z0-9]. The schema also
allows the use of the underscore '_', but not as a leading character.
算子和层级名称：applet 的参数名称由 VisualApplets 设计的算子层级构成。生产商会更改这些名称以使其符合 GenICam 要求。如果您从一开始就按照 GenApi 规则命名算子实例和层级元素，所生成的节点名称将更容易理解。
运行时配置#
当您使用通过 VisualApplets 设计的 applet 时，通常的相机发现机制是不够的。producer 也不会自动将相机参数同步到 applet。请进行以下设置：
- 设置
DiscoveryMethod更改为MixedDiscovery在枚举设备之前。此设置可启用所有DmaToPc模块。 - 打开设备后，将设备 XML 中的
AutomaticFormatControl,AutomaticROIControl和AutomaticTapGeometryControl设为false.
故障排除#
| 观察到的行为 | 解释与操作 |
|---|---|
DiscoveryMethod 或 ClpSharedLibraryPath 无法针对 Camera Link Interface. | 自动 Basler 配置处于活动状态。请先设置 ConfigurationForBaslerCLP 更改为 false 。 |
对于 Camera Link，仅列出了伪设备 Interface. | EmulationDiscovery 处于活动状态，或者 MixedDiscovery 未找到真实的相机，并用伪设备填充了通道。请检查协议配置。 |
| 未发现 Basler Camera Link 相机。 | 保持 ConfigurationForBaslerCLP 启用。确保 GENICAM_CLPROTOCOL 指向 Basler CLProtocol 安装。更新设备列表并确认 BaslerClProtocol.dll in LoadedClpSharedLibraryPath. |
| 配置 CLP 后未发现兼容 GenCP 的相机。 | 设置 ConfigurationForBaslerCLP 更改为 false配置 CLP 后未发现兼容 GenCP 的相机。请设置 ClpSharedLibraryPath，请选择 MixedDiscovery 或 CameraDiscovery，并更新设备列表。 |
| 未发现带有厂商 CLP 库的相机。 | 设置 ConfigurationForBaslerCLP 更改为 false，并更新设备列表。未发现带有供应商 CLP 库的相机。请设置 ClpSharedLibraryPath。在 LoadedClpSharedLibraryPath. |
| 伪设备输出 Test Images 而非相机图像。 | applet 的图像生成器处于活动状态。请在伪设备的远程设备节点中禁用图像生成器。 |
Interface 或采集卡初始化报告资源正在使用中。 | 另一个进程已占用采集卡。每个采集卡一次只能由一个进程初始化。对于 |
| Camera Link，这包括使用 clsersis.dll 的独立 CLProtocol 客户端（如 pylon）。有关详细信息，请参阅并行安装 pylon 和 Framegrabber SDK。 | |
| 生产商在初始化时报告另一个 Framegrabber SDK 版本已处于活动状态。 | 生产商从其他安装中加载了受保护的 Framegrabber SDK 模块，例如 fglib5.dll。有关详细信息，请参阅并行安装 pylon 和 Framegrabber SDK。 |
您无法访问 Interface 发现更改后的消费者设置。 | 未创建设备，且 consumer 仅在至少存在一个设备时显示 Interface node map。请重置或编辑采集卡的 .config 文件。有关详细信息，请参阅 应用并保存更改. |