node-red-contrib-s7-suite 0.0.3

Node-RED nodes for Siemens S7 PLC communication with dual backend support (nodes7 + node-snap7)

npm install node-red-contrib-s7-suite

node-red-contrib-s7-suite

Node-RED nodes for Siemens S7 PLC communication with dual backend support.

Overview

s7-suite is a TypeScript-based Node-RED package for communicating with Siemens S7 PLCs. It supports multiple communication backends and is designed for both production deployments and hardware-free development.

Highlights

Multiple backends — Pick the backend that fits your environment per connection:

• nodes7 — pure JavaScript, no native compilation required
• node-snap7 — native Snap7 library, enables advanced features like block listing, SZL reads, and CPU control
• sim — built-in simulator generating dynamic values (sine waves, counters, sawtooth signals) for development without a physical PLC

Flexible address formats — Write addresses in the style you prefer: nodes7-style (DB1,REAL0), IEC-style (DB1.DBD0), or area-style (MW4, I0.1, QD8). The address parser handles conversion transparently.

Smart polling — The trigger node supports edge detection (rising, falling, any) for booleans and configurable deadband for numeric values, reducing unnecessary messages in flows.

PLC browsing — Discover data blocks directly from Node-RED. With snap7 this uses native block listing; with nodes7 a probe-based approach with rate limiting explores the PLC address space safely.

Robust connections — Connection manager with request queuing (max 100), automatic reconnection with exponential backoff, and structured error codes (S7Error with error code and cause chain).

Flexible read/write modes — Single values, combined objects, raw buffers, structured schemas, or unpacked bit arrays.

Bulk tag import — Import full PLC tag lists from TIA Portal (.xlsx) or Step 7 symbol exports (.csv/.tsv) into the read node with one click. Auto-detects column names (name/symbol/tag and address) and separators (tab/semicolon/comma). Imported tags get human-readable labels used as object keys in the output.

Features

• s7-config — Connection configuration with backend selection and auto-reconnect
• s7-read — Read PLC data in multiple output modes: single value, combined object, raw buffer, struct, or bit array
• s7-write — Write data to PLC memory areas with dynamic address via msg.topic
• s7-trigger — Polling with edge detection and deadband filtering
• s7-browse — Discover PLC data blocks with category filtering and search
• s7-control — CPU control actions: Start, Stop, Cold Start (snap7 backend only)

Supported PLCs

S7-200, S7-300, S7-400, S7-1200, S7-1500, LOGO!

Backends

Node API

s7-read

Output modes:

• single — msg.payload = single value (or object if multiple addresses)
• object — msg.payload = { "DB1,REAL0": 23.5, "DB1,INT4": 100 }
• buffer — msg.payload = raw Buffer of the requested memory area
• struct — msg.payload = { fieldName: value, ... } based on schema definition
• bits — msg.payload = boolean[] with each bit unpacked (LSB first per byte)

s7-write

On success, the input message is passed through to the output.

s7-trigger

s7-browse

Send any message to trigger. Output msg.payload contains { blocks, areas, addresses, cpuInfo? }.

s7-control

Requires the snap7 backend. Send a message to execute the configured action, or override via msg.payload.

Troubleshooting

node-snap7 not installed — The snap7 backend requires the native node-snap7 package. Install it with npm install node-snap7. If compilation fails, ensure build tools are installed (build-essential on Debian/Ubuntu, Xcode CLI tools on macOS).

Connection timeout — Verify the PLC IP is reachable (ping <ip>). Check that rack/slot values match your hardware. For S7-1200/1500, ensure "Permit access with PUT/GET" is enabled in the PLC settings.

LOGO connection — LOGO PLCs require TSAP-based connections. Set PLC Type to "LOGO" and configure Local TSAP (e.g. 0x0100) and Remote TSAP (e.g. 0x0200).

Address parse errors — Verify address format. Examples: DB1,REAL0, DB1.DBD0, MW4, I0.1, QB0. See the address format table above.

Excel import does nothing — XLSX parsing requires the SheetJS library, which is loaded on demand from a public CDN. If your Node-RED editor runs in an air-gapped environment, export your tag list as .csv from Excel/TIA Portal instead.

Remote I/O via Profibus/Profinet not browsable — The browse node scans local rack I/O (areas I/Q, M, DB, C, T) and PLC blocks. Distributed I/O addresses on remote stations (Profibus DP couplers, Profinet IO) are reachable for read/write using the standard IB/IW/ID/QB/QW/QD syntax with the absolute peripheral address, but they will not appear in the browse results since they are not enumerable through the standard S7 protocol.

Installation

Node-RED Palette

Search for node-red-contrib-s7-suite in the Node-RED palette manager.

npm

cd ~/.node-red
npm install node-red-contrib-s7-suite

Docker

docker compose up -d

Node-RED is then available at http://localhost:1885 with the S7 nodes pre-installed.

Development Setup

Prerequisites

• Node.js >= 18
• npm

Getting Started

git clone https://github.com/lagramm/node-red-contrib-s7-suite.git
cd node-red-contrib-s7-suite
npm install
npm run build

Scripts

Project Structure

src/
├── backend/        # PLC communication backends (nodes7, snap7, sim)
├── core/           # Address parser, connection manager, poller, rate limiter
├── nodes/          # Node-RED node definitions (HTML + TypeScript)
│   ├── s7-config/
│   ├── s7-read/
│   ├── s7-write/
│   ├── s7-trigger/
│   ├── s7-browse/
│   ├── s7-control/
│   └── shared/      # Shared helpers (status updater)
├── types/          # TypeScript type definitions
├── utils/          # Error codes and helpers
└── icons/          # Node icons
test/
├── helpers/        # Test utilities and mocks
└── unit/           # Unit tests (backend + core)

Contributing

Contributions are welcome! Please follow these steps:

1. Fork & Branch

git checkout -b feature/my-feature

Use a descriptive branch name with a prefix:

• feature/ for new features
• fix/ for bug fixes
• docs/ for documentation changes
• refactor/ for code refactoring

2. Code Style

This project uses ESLint and Prettier. Make sure your code passes linting before committing:

npm run lint
npm run format

3. Tests

All new features and bug fixes must include tests. The project enforces a minimum coverage threshold of 80% on branches, functions, lines, and statements.

npm test

4. Commit Messages

Use clear, concise commit messages:

feat: add support for S7-1500 optimized blocks
fix: handle connection timeout on slow networks
docs: add Docker deployment instructions

5. Pull Request

• Make sure all tests pass and linting is clean
• Provide a clear description of what your PR does and why
• Reference any related issues

Development Tips

• Use the sim backend for development — no physical PLC required
• Import examples/test-flows.json into Node-RED for a ready-made test setup
• Run the project in Docker for a quick local environment: docker compose up -d

Changelog

See CHANGELOG.md for release notes.

License

MIT