Manche Nodes brauchen Binärmodule (native Module), z.B. node-red-node-serialport für serielle Schnittstellen und USB-Leseköpfe. RedMatic liefert keine vorkompilierten Binärmodule mit, und auf der CCU gibt es keinen Compiler (siehe Nodes mit Binärmodulen). Diese Seite zeigt, wie man so ein Modul auf einem PC baut und auf die CCU kopiert.

Viele Module bringen fertige Binaries für gängige Plattformen mit. Auf OpenCCU mit aarch64 oder x86_64 reicht deshalb oft die normale Installation über den Paletten-Manager – node-red-node-serialport lässt sich dort z.B. ohne Weiteres installieren. Selbst bauen muss man nur, wenn die Installation mit Meldungen wie gyp ERR! oder not found: make abbricht.

Auf der CCU3 ist Node.js in RedMatic eine musl-Variante, weil die CCU3-Firmware für aktuelle Node.js-Versionen zu alt ist. Dafür gibt es meist keine fertigen Binaries, hier ist Selbstbauen der Normalfall.

Architektur und Node.js-Version der CCU zeigen diese Befehle (per SSH auf der CCU):

uname -m
/usr/local/addons/redmatic/bin/node -v

Gebraucht wird ein Rechner mit Docker: ein Linux-PC, eine VM, ein Raspberry Pi oder Windows mit Docker Desktop. Gebaut wird in einem Container, der zur CCU passt.

Auf einem x86-PC muss Docker ARM-Container emulieren können. Das richtet dieser Befehl ein (nach einem Neustart des Rechners ggf. wiederholen):

docker run --privileged --rm tonistiigi/binfmt --install arm,arm64

In einem leeren Verzeichnis den passenden Container starten, dort landet später das fertige Modul:

Nur im CCU3-Container (Alpine) zusätzlich Node.js und die Build-Werkzeuge installieren:

apk add nodejs npm build-base python3 linux-headers

Die Hauptversion von node -v im Container muss zu der auf der CCU passen (RedMatic 9: Node.js 24). Alpine 3.23 und node:24-bookworm bringen beide Node.js 24 mit.

Im Container, Beispiel node-red-node-serialport (für einen anderen Node den Namen austauschen):

MODUL=node-red-node-serialport
mkdir /build && cd /build
echo '{"private":true}' > package.json
npm_config_build_from_source=true npm install --install-strategy=shallow --no-package-lock $MODUL
npm ls $MODUL
tar -czf /out/$MODUL.tgz -C node_modules $MODUL
exit

• --install-strategy=shallow legt alle Abhängigkeiten in das Verzeichnis des Nodes, so lässt es sich als Ganzes kopieren.
• npm_config_build_from_source=true sorgt dafür, dass die Binärmodule für diesen Container compiliert werden, statt womöglich unpassende fertige Binaries zu übernehmen.
• npm ls zeigt die Versionsnummer, die in Schritt 3 gebraucht wird.

SSH muss auf der CCU aktiviert sein. Vom Build-Host aus, im Verzeichnis mit der .tgz-Datei (<ccu> durch IP-Adresse oder Hostnamen der CCU ersetzen):

scp node-red-node-serialport.tgz root@<ccu>:/usr/local/tmp/
ssh root@<ccu>

Bricht scp mit „Connection closed“ ab, hilft scp -O ….

Dann auf der CCU:

source /usr/local/addons/redmatic/home/.profile
cd /usr/local/addons/redmatic/var
tar -xzf /usr/local/tmp/node-red-node-serialport.tgz -C node_modules
rm /usr/local/tmp/node-red-node-serialport.tgz
npm pkg set dependencies.node-red-node-serialport=2.0.3
/usr/local/etc/config/rc.d/redmatic restart

Bei npm pkg set die Versionsnummer aus npm ls in Schritt 2 eintragen. Dieser Eintrag ist wichtig: Fehlt der Node in der package.json, entfernt npm ihn bei der nächsten Installation über den Paletten-Manager wieder.

Nach dem Neustart ist der Node in der Palette von Node-RED verfügbar.

• Neue Version des Nodes: das alte Verzeichnis /usr/local/addons/redmatic/var/node_modules/node-red-node-serialport löschen und die Schritte 2 und 3 wiederholen. Nicht über den Paletten-Manager aktualisieren, der versucht wieder zu compilieren.
• RedMatic-Update auf eine neue Node.js-Hauptversion: das Modul mit einem Container der neuen Version neu bauen.
• Entfernen: über den Paletten-Manager oder mit npm uninstall node-red-node-serialport im Verzeichnis /usr/local/addons/redmatic/var.