通用概念

本页将简要介绍帮助您更好理解 Apache PLC4X 的最重要概念。

从用户角度来看，最重要的概念通常包括：

• 连接 — 协议 — 传输 — 配置
• 地址

在 PLC4X API 中，我们从现实世界抽象出来的两部分是 connection strings 和 tag address strings。

这两者都很大程度上取决于您计划通信的设备类型。不过，它们都可以在外置配置中轻松配置，或者作为参数传入。

如果您熟悉 JDBC 或 ODBC，那么您将很容易理解 PLC4X 中的概念，因为它们是创建 Apache PLC4X 的重要灵感来源。

连接

一般来说，连接是两个端点之间的物理或逻辑连接。

这种连接使用某种技术性的传输机制，并按照给定的协议逻辑传递数据。因此，我们对这两个方面分别进行了建模。

先从 Transports 开始：

目前可用的传输方式如下，不久之后可能还会有更多：

• CAN
• PCAP 回放
• 原始套接字（Raw Socket）
• 串口（RS232 和 RS485）
• TCP
• UDP
• 测试

虽然 TCP、UDP 基于操作系统的标准 TCP 和 UDP 协议栈，但原始套接字可直接提供对 Ethernet Frames 的底层访问。这使得它们不仅可以用于我们所说的 passive-mode drivers——简单地读取所有网络流量，还可以与基于以太网但不使用 TCP 或 UDP 的协议进行通信。这通常是 Fieldbus 协议的情况，例如 PROFINET 或 EtherCAT，这类协议通常要求比 TCP 和 UDP 更低的延迟。

串口传输只是向指定的串口读写数据。

目前最特殊的两种传输形式是 PCAP replay 和 Test 传输。

PCAP replay 传输允许回放使用 WireShark 等工具录制的网络流量数据包。这对于编写新驱动（尤其是被动模式驱动）非常有帮助，因为它无需连接到真实设备。

从驱动的角度来看，Raw Socket 和 PCAP replay 传输实际上没有区别。

Test 传输通常是为在 PLC4X 测试框架中使用而构建的，因为它允许对驱动的输入和输出进行细粒度访问。通过测试传输，我们可以显式地控制传入驱动以及从驱动获取的数据，并在单元测试和集成测试中对其加以验证。

连接字符串

一个完整的 PLC4X 连接字符串如下所示：

{driver code}:{transport code}://{transport config}?{options}

driver code 通常用于选择我们想要使用的协议，而 transport code 现在用于选择应使用的传输类型。

根据所选的传输机制，transport config 会告诉传输层应使用哪个资源。

例如，对于 TCP 和 UDP 传输，这将是 IP address 或 hostname，其后可选择跟上 Port。

对于 Serial 传输，这将是 name of the serial interface。Raw Sockets 将需要 device name 或 MAC address，依此类推。

有关所有传输及其选项的完整说明，请查阅 Transport Documentation 此处。

最后一部分 —— options —— 可用于将某些协议或传输选项微调为非默认值。通常这些选项因协议而异。有关这些选项的详情，请查看 Protocol Documentation 此处。即使大多数传输也有一些通用选项，它们的默认值也会因所使用的协议而有很大差异。因此，除了查看通用的 Transport Documentation 此处 之外，每个协议的文档还包含所有支持的传输列表，以及传输配置选项及其默认值。

这部分的通用结构始终是相同的：

?{option-1-name}={option-1-value}&{option-2-name}={option-2-value}&{option-3-name}={option-3-value}

因此，选项以 ? 开头，其后跟随若干 name-value 键值对，各键值对之间用和号字符 & 分隔。

不过，特定协议的驱动程序通常只有一个 default transport，因此有时可以省略传输代码。此外，大多数驱动程序会为各种配置选项定义默认值，所以通常只有在使用非默认设置时才需要使用配置选项。

完整限定连接字符串的最简形式大致如下：

{driver code}://{transport config}

有关给定协议或传输层的默认设置的更多信息，请查阅相应驱动程序的文档。

单个资源地址（标签）

PLC 上单个标签的地址与所使用的协议高度相关。由于我们通常决定沿用这些特定环境中所使用的地址格式，请在此处查阅 Protocol Documentation] 以了解这些地址格式的详细信息。

标签语法相当通用，可以概括为 type:address。某些协议可能支持标签属性，这些属性以键值对的形式指定在主标签地址之后。例如 coil:1{unit-id: 10}。标签属性是取决于具体协议的附加元素。

标签元数据

从 Apache PLC4X 0.13 版本开始，plc4j 提供了实验性的结果集元数据支持。该元数据用于提供可能在协议层（采样时间戳）或驱动层（例如数据包接收时间）可用的附加信息。同样请参阅协议文档以了解此功能的具体细节。

目前定义的常用元数据键包括：

• timestamp — 由通信对端提供的标签值时间戳。
• timestamp_source — 时间戳或 receive_timestamp 字段的来源（如果提供了其中任意一个）。
• receive_timestamp — 假定在接收到携带数据的数据包时的时间戳。

入站消息的限制

驱动程序读取设备发送给它的内容，而某些协议允许一个值包含同类的更多值——BACnet 构造数据可以包含更多构造数据，OPC UA 变体可以包含更多变体，ADS 数据类型表条目可以包含更多条目。此类消息的嵌套深度由发送方决定，而每多一层嵌套在传输线上可能仅增加一个字节的成本。

因此，PLC4X 最多读取 1024 层深度，超出该深度的内容将作为解析错误报告，其方式与报告其他任何无法理解的消息相同。项目自身测试套件中最深的消息嵌套了 36 层，因此这一限制远远超出了任何真实设备可能发送的范围。

如果你遇到消息确实嵌套更深的设备，请将 PLC4X_MAX_NESTING_DEPTH 环境变量设置为所需的深度：

export PLC4X_MAX_NESTING_DEPTH=4096

该变量在所有语言绑定中的含义相同，因此通过多个绑定与设备通信的进程只需设置一次即可。若传入的值不是正数，则会被忽略，保留默认值，并在日志中予以说明。

应将其提升到设备实际需要的值，而不是远高于该值的整数上限。设置此限制的原因在于，除了报告解析错误之外，另一种结果就是栈空间耗尽，而其代价各不相同：在 plc4j 和 plc4py 中，会抛出一个驱动仍可报告的错误；而在 plc4go 和 plc4c 中，栈耗尽会导致进程终止，而不是终止当前消息。