跳到主要内容

Java API 参考

Darra Profinet Slave Java SDK（Maven 包 com.darra.pns）。单一入口是 PnSService。配置由 GUI / 服务完成，SDK 负责连接、启停、写 I、读 Q。周期自由配置，最低 1 ms。

connect() → start() → write / read / pdo() → stop()。不要把 Q 抄回 I。

运行前提：服务已启动，驱动已就绪。

import com.darra.pns.PDO;
import com.darra.pns.service.PnSService;

概览​

类包职责
PnSServicecom.darra.pns.service单一入口：无主机连接 / 启停 / 写 I / 读 Q / 地址化
PDOcom.darra.pnsETH 式过程数据：in() 读 Q，out() 写 I
PnSServiceExceptioncom.darra.pns.service服务模式异常（Q 区只读、未连接、越界等）

连接与生命周期​

try (PnSService svc = new PnSService()) {
    svc.connect();
    svc.start();
    // ... 写 I / 读 Q ...
    svc.stop();
}
成员类型类别读写说明
PnSService()PnSService设备构造未连接会话（AutoCloseable）
connect()void设备写本机会话
connect(String host)void设备写"127.0.0.1" = 指定本机服务
connect(host, port, apiKey)void设备写完整形。只应填本机回环
DEFAULT_PORTint设备只读本机服务默认端口
start()void设备写启动会话。已启动则成功返回
stop()void设备写停止本会话。主站在连时不要拆应用关系。停止路径不抛
close()void设备写释放会话。空会话 / 重复调用安全
isConnected() / isStarted()boolean设备只读会话是否已 connect / 本地是否已 start
host() / port()String / int设备只读服务主机 / 端口

生命周期：new → connect() → start() → 写 I / 读 Q → stop() → close()。

过程数据（写 I / 读 Q）​

方向以控制器视角：

  • I 区（设备 → 控制器）：SDK 写。write 允许短写。
  • Q 区（控制器 → 设备）：SDK 读。写 Q 抛 PnSServiceException。
svc.write(new byte[]{0x01, 0x02, 0x03, 0x04});   // 写 I（允许短写）
byte[] q = svc.read();                             // 读 Q
svc.setByte(4, 0x11);                              // 按偏移写 I
byte b = svc.getByte(0);                           // 按偏移读 Q
成员类型类别读写说明
write(byte[] data)voidIO写写 I 区前缀（设备 → 控制器）。空数组不写；超长 / 未启动抛异常
read()byte[]IO只读读 Q 区副本（控制器 → 设备）。空数组 = 尚无过程数据
setByte(offset, v)voidIO写按绝对地址写 I 区单字节
getByte(offset)byteIO只读按绝对地址读 Q 区单字节
getIo()byte[][]IO只读过程映像快照：[0] = I 区，[1] = Q 区
writeArea(area, offset, data)voidIO写整区部分覆盖写。仅 INPUT / MEMORY；OUTPUT（Q）只读抛异常
readArea(area, offset, length)byte[]IO只读整区按偏移读取

PDO（pdo().in() / pdo().out()）​

学 ETH Slave.PDO()：in() 只读 Q，out() 可写 I。与 read() / write() 同区。无 live 指针，每次读写新拷。Java 无索引器：in().get(i) ≡ C# In[i]。

PDO pdo = svc.pdo();
byte q0 = pdo.in().get(0).getContent();     // 读 Q[0]
pdo.out().get(0).setContent((byte) 0x11);   // 写 I[0]
short w = pdo.in().get(2).asInt16();        // 大端字
pdo.out().get(2).asInt16((short) -2);

byte[] q = new byte[16];
pdo.copyInputsTo(q);                        // 整段拷 Q
pdo.copyToOutputs(new byte[]{0x01, 0x02});  // 短写 I
成员类型类别读写说明
pdo() / getPdo()PDOPDO只读同一会话上的 PDO 单例（懒初始化）
in()PdoArrayInstancePDO只读输入数组：读 Q（控制器 → 设备）。写抛 UnsupportedOperationException
out()PdoArrayInstancePDO写输出数组：写 I（设备 → 控制器）
in().get(offset) / out().get(offset)PdoDataItemPDO只读 / 写按字节偏移取项。偏移即过程映像地址
getContent() / setContent(byte)byte / voidPDO只读 / 写单字节。setContent 仅 out()
asInt16() / asInt32() / asFloat()数值PDO读写大端（PROFINET 网络序）。写仅 out()
getBit(bit) / setBit(bit, value)boolean / voidPDO读写本字节第 0–7 位。写仅 out()
copyInputsTo(dest)intPDO只读整段拷 Q 到调用方缓冲（允许短拷）
copyToOutputs(src)intPDO写整段 / 短写 I
readStruct / writeStruct结构 / voidPDO只读 / 写packed 大端结构 ↔ Q / I（PdoStruct 或 byte[]）

地址化读写​

西门子 / HSL 式地址，解析与 C# PnSAddress.Parse 对齐。字 / 双字大端，偏移即字节偏移，不强制 2 / 4 对齐（IW3 合法）。单一线性过程区，DB 仅槽位 1 有效（DB2 及以上抛 PnSServiceException）。

区域地址格式方向写
I 区I0.0 / IB0 / IW2 / ID4设备 → 控制器允许
Q 区Q0.0 / QB0 / QW2 / QD4控制器 → 设备只读，写抛 PnSServiceException
M 区M0.0 / MB0 / MW100 / MD0映射 I 面允许
DB 区DB1.DBX0.0 / DB1.DBB2 / DB1.DBW0 / DB1.DBD4槽位 1写走 I 面；仅 DB1
svc.writeBool("I0.0", true);          // 写输入位
svc.writeInt16("IW2", (short) 0x1234); // 写输入字（大端）
boolean start = svc.readBool("Q0.0"); // 读输出位
short cmd = svc.readInt16("QW2");     // 读输出字
// svc.writeBool("Q0.0", true);       // 抛 PnSServiceException：Q 区只读
成员类型类别读写说明
readBool(address)booleanIO只读位：I0.0 / Q0.0 / M1.6 / DB1.DBX0.0
writeBool(address, value)voidIO写写位（I / M / DB）。Q 区只读，抛 PnSServiceException
readInt16(address)shortIO只读字：IW2 / QW2 / MW0 / DB1.DBW0，大端
writeInt16(address, value)voidIO写写字（I / M / DB）。Q 区只读抛异常
readInt32(address)intIO只读双字：ID4 / QD4 / MD0 / DB1.DBD4，大端
writeInt32(address, value)voidIO写写双字（I / M / DB）。Q 区只读抛异常
parseAddress(text)AddressIO静态解析地址。非法格式 / 位号越界抛异常

状态​

状态来自运行态。

成员类型类别读写说明
status() / getState()PnSState设备只读运行态枚举
statusEx()ServiceStatus设备只读一次取回 state / connected / errorCode
getErrorCode()PnSRuntimeErrorCode设备只读最近错误码枚举。未识别 = UNKNOWN
getErrorCodeRaw()int设备只读错误码原值（0 = 无错误）

ServiceStatus：getState() / connected() / getErrorCode() / getErrorCodeRaw()。connected() = 是否已与 IO 控制器建立周期数据交换。

PnSRuntimeErrorCode：OK=0 / ERR_INIT=-1 / ERR_CFG=-2 / ERR_THREAD=-3 / ERR_RUNNING=-4 / ERR_PDI=-5 / UNKNOWN=-10000。

完整示例​

与仓库 examples/ServiceBasicExample.java 同口径。

import com.darra.pns.PDO;
import com.darra.pns.service.PnSService;
import com.darra.pns.service.PnSServiceException;

public class ServiceBasicExample {
    public static void main(String[] args) {
        PnSService svc = new PnSService();
        try {
            svc.connect();
            svc.start();

            byte[] q = svc.read();                  // 读 Q
            System.out.println("Q 长度 " + q.length);

            svc.write(new byte[]{0x01, 0x02, 0x03, 0x04});  // 写 I
            svc.writeBool("I0.0", true);

            PDO pdo = svc.pdo();
            System.out.printf("PDO In[0]=0x%02X%n", pdo.in().get(0).getContent() & 0xFF);
            pdo.out().get(0).setContent((byte) 0x11);

            svc.stop();
        } catch (PnSServiceException e) {
            System.err.println("错误: " + e.getMessage());
        } finally {
            svc.close();
        }
    }
}

Maven 依赖​

<dependency>
    <groupId>xyz.darra</groupId>
    <artifactId>darra-pns-slave</artifactId>
    <version>1.0.0</version>
</dependency>

相关​