Fixing node-red-contrib-modbus Install Errors on SIMATIC IoT2000

Problem Description

When running npm install node-red-contrib-modbus on a SIMATIC IoT2000 (IoT2020 or IoT2040) gateway, the installation fails during the serialport postinstall phase. The build chain invokes node-pre-gyp, which first attempts to fetch a pre-compiled binary from GitHub. When no IA-32 / ARM binary is available for the running Node.js ABI (node-v48), it falls back to building from source via node-gyp. That source build then aborts with a TLS error returned by OpenSSL.

The failure surfaces in two distinct TLS variants depending on the embedded node-serialport release pulled transitively:

npm then prints npm ERR! code ELIFECYCLE and the install script exits with status 1. The node-red-contrib-modbus node never lands in /usr/lib/node_modules/, and Node-RED cannot load the modbus palette.

Environment Analysis

The problem originates in the SIMATIC IoT2000 firmware image shipped with older Example Image releases. Capture the baseline first so you can compare against expected values:

Reference the SIMATIC IoT2020 / IoT2040 Operating Instructions on the Siemens Industry Online Support portal for image partitioning and update procedures.

Root Cause Analysis

The error chains together three independent defects. Each must be resolved to reach a successful install.

Cause 1 - Expired CA Store on the Yocto Image

The bundled OpenSSL trust anchors expired in 2017. When node-gyp downloads process.h or invokes a Python helper that hits an HTTPS endpoint, OpenSSL validates the chain and rejects it. The stack frame at TLSSocket._finishInit (_tls_wrap.js:603:8) confirms the verification happens inside the Node 6.x TLS wrapper, not inside the application layer.

Cause 2 - Outdated Node.js / node-gyp / node-pre-gyp Trio

Node 6.9.2 (ABI v48) has been unsupported since 2019. The node-serialport project dropped IA-32 binary builds in release 9.x and later. With no prebuilt matching node-v48-linux-ia32, node-pre-gyp falls back to source compilation. node-gyp 3.4.0 does not understand the build requirements of modern nan, bindings, and cmake-js packages, so configure fails before any C++ file is touched.

Cause 3 - Clock Skew in IoT2000 Field Deployments

SIMATIC IoT2000 units without internet or NTP keep the RTC at the factory burn-in date (commonly 2017). The TLS variant certificate is not yet valid surfaces when the local date is earlier than the notBefore field on the certificate. This is a clock problem, not a trust problem.

Diagnostic Verification

Run these commands from the IoT2000 shell (ssh root@iot2000 or via the serial console) and record the output before applying fixes:

1. uname -a - confirm kernel 4.4.18-yocto-standard and IA-32 / ARM build.
2. node -v and npm -v - capture ABI generation.
3. date - verify RTC; compare with NTP source.
4. openssl version - check the bundled library version.
5. curl -vI https://nodejs.org/dist/index.json 2>&1 | grep -E 'expire|expired|date' - verify TLS handshake behavior.
6. npm config get registry and npm config get strict-ssl.
7. cat /usr/lib/node_modules/node-red/package.json | grep version - capture Node-RED version in the image.

Solution 1 - Bring the System Clock Forward and Refresh Trust Anchors

The fastest zero-touch path when you cannot replace the Node.js runtime (locked firmware image, regulatory re-qualification). Apply both clock and certificate patches because they reinforce each other.

1. Set the clock manually if NTP is unavailable:
   date -s "$(wget -qO- http://worldtimeapi.org/api/timezone/Etc/UTC | grep -oE '\\d{4}-\\d{2}-\\d{2}T[0-9:]+' | head -c 16)Z"
2. Enable NTP persistence so the unit survives power cycles:
   /usr/sbin/ntpd -q -g
3. Refresh the system CA bundle by replacing /etc/ssl/certs/ca-certificates.crt with a current Mozilla bundle:
   curl -L https://curl.se/ca/cacert.pem -o /etc/ssl/certs/ca-certificates.crt
4. Symptom-only escape hatch: tell npm to skip peer and TLS verification for the modbus package only:
   npm config set strict-ssl false

Solution 2 - Upgrade Node.js on the SIMATIC IoT2000

Long-term fix. Node.js 6.x cannot build current native modules. Use a maintained LTS line that still ships IA-32 binaries.

1. Download a prebuilt tarball that matches the architecture:
   wget https://nodejs.org/dist/v14.21.3/node-v14.21.3-linux-ia32.tar.xz
2. Extract into a non-removable mount and link:
   tar -xJf node-v14.21.3-linux-ia32.tar.xz -C /opt/
ln -sf /opt/node-v14.21.3-linux-ia32/bin/node /usr/bin/node
ln -sf /opt/node-v14.21.3-linux-ia32/bin/npm /usr/bin/npm
3. Verify:
   node -v should report v14.21.3.
   npm -v should report 6.14.18.
4. Re-run the install:
   cd /usr/lib/node_modules
npm install node-red-contrib-modbus

For ARM-based IoT2040 units, substitute node-v14.21.3-linux-armv7l.tar.xz and confirm with uname -m. Refer to the Node.js Previous Releases index for the latest 14.x IA-32 / ARMv7 tarballs.

Solution 3 - Build serialport from a Vendored Source

When the runtime upgrade is blocked by another application, download a pre-vetted node-serialport tarball and build offline.

1. Install the build toolchain shipped on the SDK image:
   opkg install gcc g++ make python3-native nodejs-native
2. Fetch the exact serialport version required by node-red-contrib-modbus at the time:
   npm view node-red-contrib-modbus dependencies
3. Pre-stage the archive in the npm cache or pass --offline after manually copying the tarball:
   npm install --offline --build-from-source=false node-red-contrib-modbus
4. If configure still fails, force a source build of just serialport:
   npm install [email protected] --build-from-source
npm_config_build_from_source=true npm install node-red-contrib-modbus

Solution 4 - Skip the Serial Dependency with Modbus TCP-Only

For installations that never use RTU, replace the heavyweight palette with a Modbus TCP-only package. This removes the serialport chain entirely.

1. Remove any partial install:
   rm -rf /usr/lib/node_modules/node-red-contrib-modbus
2. Install the TCP-only modbus server:
   cd ~/.node-red
npm install node-red-contrib-modbustcp
3. Configure the Modbus-Get/Modbus-Read nodes to point at the PLC IP:port (default 502).
4. Test with:
   curl http://127.0.0.1:1880/red and confirm the modbus palette loads without errors.

Solution 5 - Patch npm Build Recipes on Locked Firmware

When the firmware is locked but you can edit the Image SDK recipe (typical during development on the Yocto Poky BSP), pin the dependencies so the next image build resolves cleanly.

DEPENDS += "nodejs-native"
RDEPENDS_${PN} += "ca-certificates"
SRC_URI += "file://ca-certificates.pem"
do_install_append() {
    install -m 0644 ${WORKDIR}/ca-certificates.pem ${D}${sysconfdir}/ssl/certs/
}

This ships a known-good CA set inside the read-only image, eliminating the certificate has expired TLS failure forever.

Verification Procedures

After applying any of the above solutions, verify with a checklist of observable signals.

Troubleshooting Matrix

Hardware-Specific Caveats for SIMATIC IoT2000

• Quark CPU, IA-32 only: Node 17+ removed IA-32 support. IoT2020 owners are limited to Node 14 LTS as the most recent line that still ships IA-32 binaries.
• Read-only rootfs: If the firmware is locked, install into ~/.node-red/node_modules instead of /usr/lib/node_modules. This is the user-local install path that survives firmware updates.
• Limited RAM (256 MiB on IoT2020 Rev A): Native builds consume up to 180 MiB of resident memory. Close other Node-RED instances or stop services before compiling.
• RS232/485 buffer: The serialport native binding depends on libc.so.6 from the image. Verify with ldd /usr/lib/node_modules/node-red-contrib-modbus/node_modules/serialport/build/Release/serialport.node.
• Yocto Opkg: Some SDK images ship python3-native only. Force npm config set python /usr/bin/python3 when node-gyp rejects Python 2.

Architectural Constraints

The failure mode highlights a deeper constraint: the SIMATIC IoT2000 was qualified at a software bill-of-materials that included Node 6.9.2 and a 2017-era CA store. Modern modbus palettes pull dozens of nested dependencies, most of which assume Node 12+ tooling and a fresh trust anchor set. Engineering teams should treat the palette install as a controlled change rather than a routine npm install. Document the resulting dependency tree with npm ls --json > audit.json so future audits have a baseline to diff against.

Alternative Forks

When the upstream node-red-contrib-modbus chain remains unworkable on legacy Node 6, an actively maintained alternative is the mikakaraila/node-red-contrib-modbus mirror, which preserves a compatible manifest for older Node releases. Verify any fork against your corporate supply-chain controls before deploying.

FAQ