@samuraimittal/node-red-alicat 0.1.1

Node-RED nodes for Alicat mass flow and pressure controllers over Modbus TCP: one supervised socket per device, priority queue, decoded engineering units.

npm install @samuraimittal/node-red-alicat

@samuraimittal/node-red-alicat

Node-RED nodes for Alicat Scientific mass flow and pressure controllers over Modbus TCP:

• one supervised connection per instrument, shared by every node and kept across redeploys;
• a priority queue that puts valve commands ahead of polling;
• readings decoded into engineering units, with a quality flag and a timestamp on every message;
• setpoints in mass-flow, pressure and valve-drive modes, and a node that maintains a desired state.

The package has zero runtime dependencies.

Status: early release (0.x). Settings and messages may still change between minor versions; the CHANGELOG lists every change.

• Hardware-tested on a Gen-2 unit (firmware 10v20) and a Gen-1 unit (9v07). Other firmware is covered by the simulator. See docs/hardware-validation.md.
• Modbus TCP only for now; Modbus RTU and serial connections are planned.

Not affiliated with or endorsed by Alicat Scientific, Inc.

Contents

• Install
• Quick start
• The nodes
• Compatibility
• Status dots
• Messages
• Errors
• Deploys, stop and safety
• Troubleshooting
• Moving away from global variables
• Developing

Install

Requires Node-RED 4.0 or newer and Node.js 18.5 or newer, as Node-RED 4 does (Node-RED 5 itself needs Node.js 22.9+).

In the Node-RED editor: Menu → Manage palette → Install, search for @samuraimittal/node-red-alicat. Or from a shell, in your Node-RED user directory (usually ~/.node-red):

cd ~/.node-red
npm install @samuraimittal/node-red-alicat

Restart Node-RED. The nodes appear in the palette under Alicat.

Quick start

Without hardware: the package ships a simulator that behaves like a real 10v20 controller.

cd ~/.node-red
npx --no -- alicat-sim --port 5020     # a second one for example 05: npx --no -- alicat-sim --port 5021
npx --no -- alicat-sim --list          # other profiles, e.g. --profile 9v07-bench for Gen-1 firmware

--no makes npx use the installed simulator and never download a package of that name.

In Node-RED, use Menu → Import → Examples → @samuraimittal/node-red-alicat → 01-poll-and-dashboard, then deploy. The examples point at 127.0.0.1:5020 (and 5021 for the two-station example).

With an instrument:

1. Drag an alicat read node onto the flow and open it.
2. Next to Device, click the pencil to add a device. Enter the instrument's IP address and keep port 502.
3. Click Test connection. It shows the firmware, what the setpoint controls, and live readings.
4. Deploy. The node's status shows the live mass flow, for example 12.47 SLPM.

For firmware before 10v07 (Gen-1), also pick the data frame layout in the device settings. extended-7 matches the common 7-slot frame (absolute, gauge and barometric pressure, temperature, volumetric flow, mass flow, setpoint).

The nodes

Every node has full help in the editor's help panel. The examples cover each node:

Compatibility

Status dots

Messages

Every output carries msg.alicat:

A node that has no device selected, or invalid settings, shows a red status and fails every message with EINVALIDARG (outcome not-sent), so the problem reaches Catch nodes instead of messages vanishing.

When an instrument stops answering, a read node sends one message with quality: "stale" or "offline" and then waits. It never keeps sending frozen values as if they were live. Check msg.alicat.quality === "good" before using a value for a control decision.

Outcomes:

Errors

Failures go to Catch nodes. msg.alicat.error.code is one of a fixed set (it is part of the public API):

The operating-system error (for example ECONNREFUSED) is in the log and in err.cause.

Deploys, stop and safety

• One connection per instrument. All nodes using a device share it. Redeploying, even repeatedly, keeps the same connection: the instrument never sees a reconnect. A second device configuration for the same IP is refused instead of opening a second socket.
• Stop flows and shutdown close the connection immediately, so the instrument's connection slot is free for other masters.
• The instrument is left as it is on deploy, stop and shutdown: setpoint, mode and valve state don't change. Node-RED is not a safety controller, and Alicat's communications watchdog is not available over Modbus TCP. Put the equipment in a safe state with your own sequence (see example 06) and with independent safety hardware.
• alicat control starts empty after a deploy or restart: it does nothing until it receives a desired state.
• Hold closed with fallback (opt-in on alicat command): if the instrument is still finishing another command, setpoint 0 is written at once as well.
• One master. The command registers are shared between all masters. If a PLC or HMI also sends commands, results can be reported as unknown, and the log warns about another master.

Modbus TCP has no authentication. See SECURITY.md for network and editor guidance.

Troubleshooting

The Test connection button in the device configuration identifies the instrument before you deploy, and reuses the live connection if there is one. It only opens new connections to port 502; to test an instrument or simulator on another port, list the port in settings.js as alicatModbus: {probePorts: [5020]} (npm run dev does this for its simulators). Frame trace (Advanced) logs every Modbus frame.

Moving away from global variables

Flows that poll a device into many global variables, and drive it by writing a target into a global, can move over gradually (example 07):

1. alicat read publishes one frozen snapshot per instrument to context ({ts, quality, values, status, units, …}), from a single writer. Existing readers keep working; they should check quality and age.
2. Send setpoints and valve states to alicat control through link call, so the caller gets a result or an error instead of polling a global.
3. Feed analytics (smoothing, slopes, peaks) from messages, using msg.alicat.ts for time.

Developing

npm install
npm run check          # lint, typechecks, tests with coverage gate, runtime smoke test, package contents
npm run dev            # Node-RED on http://127.0.0.1:1880 with this package linked, plus simulators on 5020-5022
npm run sim            # simulated 10v20 MFC on 127.0.0.1:5020 (drops idle links after 20 s, like the real unit)
npm run sim -- --list  # available simulator profiles
npm run probe -- 192.0.2.10 info   # bench probe for a real unit (writes need --write)
npm run test:compat    # runtime smoke test, needs only Node-RED (CI: Node 18 with Node-RED 4.0 and 4.1, and the packed tarball)
npm run soak -- --hours 24 --real 192.0.2.10   # long-running soak test, see test/soak/soak.js
npm run diagram        # rebuild the architecture diagram in docs/diagrams/ after changing tools/diagram/spec.js

With npm run dev, import the examples from Menu → Import → Examples → @samuraimittal/node-red-alicat. Examples use the simulators on 5020 and 5021; 5022 is a Gen-1 (9v07) replica that needs the extended-7 layout. The Node-RED user directory is .dev/node-red; delete it to start fresh.

Conventions, tests and the hardware rules for contributors: CONTRIBUTING.md. Hardware checks (read-only unless enabled) are described in docs/hardware-validation.md. How the pieces fit together: docs/architecture.md, with a diagram of every file and the main flows (docs/diagrams/, editable in Excalidraw). The register map as verified on hardware: docs/register-map.md.

Layout

License

Apache-2.0. Alicat is a trademark of Alicat Scientific, Inc.; this project is not affiliated with or endorsed by Alicat Scientific.