@tanglibo/node-red-contrib-pnet 0.1.1

Node-RED process-data nodes for a local p-net C bridge over Unix sockets

npm install @tanglibo/node-red-contrib-pnet

@tanglibo/node-red-contrib-pnet

Node-RED nodes for reading and writing the process-data buffers of a local p-net IO device application, through a persistent Unix-domain socket. Zero third-party runtime dependencies.

A separately installed compatible C bridge is required. This npm package is the Node-RED client. It does not contain a PROFINET stack, GSDML files, a PLC driver, or the C bridge executable. An unmodified p-net installation does not expose this interface. See BRIDGE.md for the integration contract and protocol.

This is a community project, independent of RT-Labs, Siemens, and the Node-RED project.

Requirements and installation

• Node.js 18 or later; Node-RED 3 or later. Tested with Node.js 20 and Node-RED 4.1.1 on Linux.
• A local C bridge implementing PN IO socket protocol version 1, normally at /run/pnet-bridge/io.sock.
• The Node-RED runtime user must have permission to access that socket.
• A p-net application and PLC hardware configuration with matching module IDs, directions, and lengths.

From the Node-RED user directory:

npm install @tanglibo/node-red-contrib-pnet

Restart your Node-RED runtime. On an existing installation of the unscoped node-red-contrib-pnet package, remove that package before installing this scoped package; both register the same node types. Keep a backup of your flows when migrating. This package does not install or restart p-net or import any example flow automatically.

Nodes and directions

Directions are from the PLC perspective: write -> PLC I; PLC Q -> read. Node configuration uses slot/subslot and a byte offset within the module, not absolute PLC I/Q addresses.

1. Create a pnet connection with the path of the local bridge socket.
2. Configure a read or write node with the actual slot, subslot, byte offset, and data type. The provided CM4 application uses IO subslot 1.
3. Connect a manual Inject node to a write node, or a read node to Debug.
4. Add Catch and Status nodes for error and connection monitoring.

For example, a DI INT16 module in slot 1 is written with pnet write, slot 1, subslot 1, offset 0, type INT16, and a numeric payload such as -1234. A DO REAL32 module in slot 8 is read with pnet read, slot 8, subslot 1, offset 0, type REAL32. These examples require those modules to be configured; the node does not create modules.

The bundled example flows demonstrate BYTE and BOOL mappings for a separate four-slot example configuration. Adapt their slot mappings to your application before using them. Their Inject nodes are manual.

Data mapping

All multi-byte numbers use big-endian encoding. Offsets are bytes, starting at zero.

Module lengths and directions are discovered from the bridge. Out-of-range mappings are rejected. The client has no fixed four-slot limit; the actual capacity is set by the C application and stack. BOOL bit 0 is the least significant bit of its selected byte. Atomic masked writes preserve other bits; a full-byte write replaces all bits in that byte. Overlapping writes apply in acceptance order.

Messages and validity

Read nodes place the value in msg.payload and attach msg.pnet metadata including slot, subslot, offset, type, validity, snapshot sequence, timestamps, and dropped/coalesced snapshot counts. Read on change is the default; cyclic publishing supports configured periods from 4 ms.

Sequence numbers and monotonic nanosecond timestamps are decimal strings to preserve precision. Monotonic timestamps are comparable only within the same host boot. timestamp is Unix milliseconds. outputNs is the C application's buffer-read timestamp, not a PLC or Ethernet hardware timestamp.

Disconnected, STOP, invalid, or stale data does not produce normal read messages. A healthy connection emits the current value again after recovery. Messages already queued elsewhere in Node-RED cannot be recalled.

Write nodes preserve the incoming message and add msg.pnet.accepted, writeSequence, acceptedNs, and mapping information. Accepted means the C buffer accepted the write; it does not mean the PLC acknowledged it. Multiple writes can merge into the last value before a PN frame is transmitted. Errors are reported through Catch.

Ownership and recovery

• Write ownership is per input slot. Writers sharing one connection configuration share ownership; read-only nodes do not claim slots.
• Other connections cannot write an owned slot. The companion HTTP API, if installed, returns 409 for such conflicts.
• Heartbeats are sent every 250 ms. The compatible bridge clears values and releases ownership after 1 second without a heartbeat, and on socket close or normal release.
• While a connection is healthy, values remain at their last written value even when no new flow messages arrive.
• Reconnection does not replay previous write commands. New messages are required. Late module discovery and expired ownership trigger claim retries.
• The bridge may accept input-buffer writes while the PLC is stopped or disconnected; acceptance is not a PN delivery guarantee.

The current companion sample caches installed module definitions during a process lifetime. When changing module types or data lengths in a PLC hardware configuration, restart that p-net application so it rebuilds the module configuration. The plugin cannot perform this restart.

Timing, tests, and license

4 ms is an optimization target. Node-RED and general-purpose Linux do not provide a hard real-time maximum latency guarantee. See PERFORMANCE.md for historical measurements and their limits.

Run npm test for the included unit tests. C integration tests additionally require PNET_HARNESS=/path/to/test_harness. Real Node-RED runtime tests also require PNET_NODE_RED=/path/to/node-red. Those optional tests are skipped when their environment is absent.

The JavaScript node package is MIT licensed. RT-Labs p-net and derived C applications retain their own licensing; this package does not change their terms or redistribute their binaries.

中文说明

本包仅提供 Node-RED 读写节点，必须另外部署匹配的 p-net C 桥接程序。单独安装 npm 包不能建立 PN 从站。使用实际模块的槽位、子槽位和字节偏移；pnet write 写入 PLC 的 I 区，pnet read 读取 PLC 的 Q 区。支持 BOOL、BYTE、16/32 位整数、REAL32、Buffer，数值均为大端。

当前配套 CM4 程序支持八个用户槽；更换模块类型或长度并下载 PLC 组态后，需要重启 p-net 服务以刷新原模块定义。重启后发送新的写入消息。4 ms 不代表 Node-RED 的硬实时保证。