Apache PLC4X 1.0.0 配置参数详解

目标：讲清 Apache PLC4X 1.0.0（plc4j）作为 Java SDK 的全部可配置项：连接字符串与标签地址两大核心语法层、JVM 堆参数、SLF4J 日志参数、Maven 依赖版本参数，并给出每个参数的查看方式、取值规则、错误回显与生产配置模板。所有命令与回显均在 Ubuntu 22.04.5 + JDK 21 环境实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS
• Java：OpenJDK 21.0.12.1
• 构建工具：Apache Maven 3.6.3
• PLC4X 版本：1.0.0（plc4j-api、plc4j-driver-simulated）
• 驱动：simulated（协议码 simulated，协议名 Simulated PLC4X Datasource）
• 示例工程目录：/root/plc4x-demo/
• 演示账号：root

💡 说明：plc4j 是进程内 SDK，没有独立服务端配置文件；全部参数分布在「连接字符串、标签地址、JVM、日志、依赖版本」五个层面，逐层配置即可。

二、前置条件

• 已按《Ubuntu 22.04 安装 Apache PLC4X 1.0.0 指南》装好 JDK 21、Maven 并引入 plc4j 1.0.0 依赖；

• 示例工程 /root/plc4x-demo/ 已按《Apache PLC4X 1.0.0 构建并运行示例应用指南》编译通过（mvn clean compile 返回 BUILD SUCCESS）；

• 运行示例时统一使用：

  export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
  export MAVEN_OPTS="-Xms256m -Xmx512m"
  

三、参数查看与修改方式

反编译驱动类示例（确认协议码与 URL 形态）：

cd /root/.m2/repository/org/apache/plc4x
javap -cp plc4j-api/1.0.0/plc4j-api-1.0.0.jar org.apache.plc4x.java.DefaultPlcDriverManager | head -6

实测回显：

public class org.apache.plc4x.java.DefaultPlcDriverManager
  implements org.apache.plc4x.java.api.PlcDriverManager,org.apache.plc4x.java.api.PlcConnectionFactory
  public org.apache.plc4x.java.DefaultPlcDriverManager();
  public org.apache.plc4x.java.DefaultPlcDriverManager(java.lang.ClassLoader);
  public org.apache.plc4x.java.api.PlcConnection getConnection(java.lang.String) throws org.apache.plc4x.java.api.exceptions.PlcConnectionException;

下载驱动源码包核对地址语法：

curl -s -o /tmp/sim-src.jar https://repo1.maven.org/maven2/org/apache/plc4x/plc4j-driver-simulated/1.0.0/plc4j-driver-simulated-1.0.0-sources.jar
unzip -p /tmp/sim-src.jar org/apache/plc4x/java/simulated/SimulatedDriver.java | grep -A2 "URL schema"

实测回显：

 * URL schema: simulated:<device_name>. Each call creates a fresh
 * in-memory device; values written through one connection do not survive its
 * close, and devices are not shared between connections.

四、参数总览

五、核心参数详解

5.1 连接字符串参数

语法：simulated:<device_name>，设备名可含字母、数字、下划线。DefaultPlcDriverManager.getConnection(url) 按协议码路由驱动，内部自动完成 connect()。

错误取值实测：

连接串缺设备名：

org.apache.plc4x.java.api.exceptions.PlcConnectionException: Invalid plc4j connection string 'simulated:'

协议码未注册（classpath 只有 simulated 驱动时）：

org.apache.plc4x.java.api.exceptions.PlcConnectionException: Unable to find driver for protocol 's7'

认证参数：模拟驱动不支持认证，传入认证对象直接拒绝。实测程序片段：

driverManager.getConnection("simulated:device1",
    new PlcUsernamePasswordAuthentication("root", "q1w2e3r4"));

实测回显：

org.apache.plc4x.java.api.exceptions.PlcConnectionException: Simulated driver does not support authentication.

⚠️ 注意：真实设备（如 S7、Modbus TCP）的连接串为 协议码:传输层:主机:端口?参数=值 形态，具体参数由对应驱动定义；接入真实设备前，先以同版本驱动 jar 的 sources 核对该驱动的连接参数表。

5.2 标签地址参数

三段语法：<TYPE>/<name>:<值类型>[<数量>]（数量可省略，缺省 1）。

PlcValueType 全部 33 个取值（javap 枚举常量实测）：NULL、BOOL、BYTE、WORD、DWORD、LWORD、USINT、UINT、UDINT、ULINT、SINT、INT、DINT、LINT、REAL、LREAL、CHAR、WCHAR、STRING、WSTRING、TIME、LTIME、DATE、LDATE、TIME_OF_DAY、LTIME_OF_DAY、DATE_AND_TIME、DATE_AND_LTIME、LDATE_AND_TIME、Struct、List、RAW_BYTE_ARRAY。

错误取值实测（三类典型错误）：

缺值类型段（地址 RANDOM/foo）：

org.apache.plc4x.java.api.exceptions.PlcInvalidTagException: RANDOM/foo invalid

值类型不存在（地址 RANDOM/foo:NOTATYPE）：

org.apache.plc4x.java.api.exceptions.PlcInvalidTagException: Invalid data type: NOTATYPE invalid

类型段不是枚举值（地址 FOO/foo:INT），build() 阶段仅 WARN 不抛异常，堆栈打印 No enum constant：

[main] WARN org.apache.plc4x.java.spi.drivers.messages.DefaultPlcReadRequest - Invalid address 'FOO/foo:INT' for tag 'x': No enum constant org.apache.plc4x.java.simulated.types.SimulatedTagType.FOO

⚠️ 注意：地址非法时 build() 只打 WARN 不抛异常，execute() 返回的响应码为 INVALID_ADDRESS（实测），服务返回后必须检查 getResponseCode。

5.3 JVM 堆参数

plc4j 是客户端库，建议把示例与边缘采集进程的堆限制在 256M 至 512M：

java -Xms256m -Xmx512m -cp "target/classes:$(cat /tmp/cp.txt)" demo.HelloPlc4x

参数是否生效的两步验证：

java -Xms256m -Xmx512m -XX:+PrintFlagsFinal -version 2>&1 | grep -E "size_t InitialHeapSize|size_t MaxHeapSize"

实测回显：

   size_t InitialHeapSize                          = 268435456                                 {product} {command line}
   size_t MaxHeapSize                              = 536870912                                 {product} {command line}

进程运行期复核（另开终端）：

jps -v
6321 demo.HelloPlc4x -Xms256m -Xmx512m

Maven 构建进程同理，用环境变量限定：

export MAVEN_OPTS="-Xms256m -Xmx512m"

5.4 日志参数

plc4j 经 SLF4J 输出日志，演示环境用 slf4j-simple（2.0.18）作为绑定。常用系统属性：

实测：追加 -Dorg.slf4j.simpleLogger.defaultLogLevel=off 后运行 HelloPlc4x，所有 INFO 行消失，仅保留程序自身输出：

[1] Registered protocol codes: [simulated]
[2] isConnected = true
[2] protocol    = unknown / unknown
[3] ping response = OK

⚠️ 注意：STDOUT 标签的回显走的就是 INFO 日志（TEST PLC STDOUT [log]: written by HelloPlc4x），把级别调成 off 会连带关闭该回显。

5.5 依赖版本参数

<dependencyManagement> 中把四个构件统一锁定 1.0.0（plc4j-api、plc4j-driver-simulated、plc4j-tools-connection-cache、plc4j-tools-opm）。可用版本由 Maven Central metadata 决定，实测 <latest>、<release> 均为 1.0.0，历史版本含 0.12.0、0.13.0、0.13.1。升级/降级只改版本号一处并全量回归 mvn clean compile 与示例运行。

六、生产配置模板

适用场景：边缘网关进程（16G 内存、SSD 磁盘、单进程采集多路 PLC，模拟驱动先联调再切换真实协议驱动）。关键配置要点如下：

# 启动命令模板（真实路径与主类按项目替换）
java -Xms256m -Xmx512m \
  -Dorg.slf4j.simpleLogger.defaultLogLevel=warn \
  -cp "/opt/app/classes:/opt/app/lib/*" \
  com.example.GatewayApplication

配置清单：

⚠️ 注意：-cp "/opt/app/lib/*" 需引号；模拟驱动的 STATE 数据在进程内存，重启即失，不能作为持久化存储。

七、常见问题

Q1：连接串写错为什么报 Invalid plc4j connection string 而不是驱动自己的提示？ 协议码路由失败发生在驱动选择阶段（实测 simulated: 缺设备名即报此错）。先核对「协议码:设备名」整体格式，再核对协议码是否已在 classpath 注册。

Q2：标签地址错了为什么 build() 不报错？ 1.0.0 的 builder 对非法地址只打 WARN 日志（地址原样回显在日志中），错误推迟到响应码 INVALID_ADDRESS。生产代码必须检查每个标签名的响应码。

Q3：JVM 堆参数为什么不生效？ 先确认进程确实以新参数启动（jps -v），再确认没有 -XX:MaxHeapSize 等冲突参数覆盖；PrintFlagsFinal 输出里 {command line} 标记表示参数来自命令行（实测回显见 5.3）。

Q4：改了 pom 版本后驱动行为变了？ 0.x 与 1.0.0 的包名有变化（消息类从 api.message 移到 api.messages，驱动管理器为 org.apache.plc4x.java.DefaultPlcDriverManager），降级到 0.x 需要同步改代码，不能只改版本号。

八、参考链接

• Apache PLC4X 官网：https://plc4x.apache.org/
• plc4j javadoc（1.0.0）：https://plc4x.apache.org/plc4x/latest/users/plc4j/
• Maven Central 构件目录：https://repo1.maven.org/maven2/org/apache/plc4x/
• simulated 驱动源码：https://github.com/apache/plc4x/tree/rel/1.0.0/plc4j/drivers/simulated