node-red-contrib-omron-eip 0.2.0

package/README.md

@@ -0,0 +1,472 @@
+# node-red-contrib-omron-eip
+
+Node-RED nodes for reading and writing **Omron NX / NJ Sysmac** controller tags over
+EtherNet/IP, by symbolic tag name — no memory maps, offsets, or PLC-side gateway blocks. Built
+on the [`omron-eip`](https://www.npmjs.com/package/omron-eip) library (installed automatically).
+
+The package adds two working nodes plus one connection node:
+
+- **omron-plc** — a *configuration node* that holds one controller connection (its IP address
+  and messaging mode). You create it once and every read/write node shares it, so they all use
+  a single, auto-reconnecting connection to the controller.
+- **omron read** — reads one or more tags. Can run when a message arrives, on a repeating
+  timer, and/or once shortly after deploy.
+- **omron write** — writes one or more tags. The value(s) can come from the incoming message or
+  be fixed in the node.
+
+Tags are addressed exactly as they are named in Sysmac Studio, including nested ones —
+`Counter`, `MyArray[3]`, `MyStruct.Speed`, `Machine.Axes[2].Position`, and so on.
+
+---
+
+## Requirements
+
+- **Node-RED 3.0 or newer**, on **Node.js 16 or newer**.
+- An Omron **NX/NJ** controller reachable on the network from the machine running Node-RED.
+- In **Sysmac Studio**, each tag you want to reach must be a **global variable** with
+  **Network Publish = "Publish Only"** (or "Input/Output"), and the project must be
+  **transferred to the controller**. A variable that isn't published cannot be read or written
+  by any EtherNet/IP client — this is the single most common reason a tag "isn't found."
+
+---
+
+## Install
+
+From the Node-RED editor: **Menu → Manage palette → Install**, search
+`node-red-contrib-omron-eip`, and click **Install**.
+
+Or from the command line, in your Node-RED user directory (e.g. `~/.node-red`):
+
+```bash
+npm install node-red-contrib-omron-eip
+```
+
+The `omron-eip` library is pulled in automatically as a dependency. Restart Node-RED; the nodes
+appear under the **Omron** category in the palette. (Running in Docker? See
+**[DOCKER_INSTALL_AND_TEST.md](./DOCKER_INSTALL_AND_TEST.md)**.)
+
+---
+
+## UCMM vs Class 3 — which connection to choose
+
+EtherNet/IP explicit messaging can run two ways, and you pick one when you set up the PLC
+connection:
+
+- **UCMM (Unconnected Messaging)** — the **default and recommended** choice for almost
+  everyone, especially when the PC/Node-RED machine talks directly to the controller. Requests
+  are sent without setting up a persistent session, they can run in parallel, and there is no
+  limit on large array reads.
+- **Class 3 (Connected Messaging)** — opens one persistent connection and sends requests over
+  it. This only helps in specific topologies where traffic is **routed through a gateway, a
+  communications module, or across a backplane**, where keeping a connection open avoids
+  re-resolving the route on every request. On a direct connection it is **slower** (a single
+  connection serializes requests) and it **cannot read very large arrays**. If a controller
+  declines Class 3, the library automatically falls back to UCMM, so enabling it can never break
+  a connection — at worst it simply doesn't help.
+
+**Rule of thumb: leave it on UCMM** unless you specifically know your network path benefits from
+Class 3.
+
+These nodes have been tested against **NX1P2**, **NX102**, and **NX502** controllers, in both
+UCMM and Class 3 modes, reading and writing scalars, strings, structures, arrays, and Omron
+date/time types.
+
+---
+
+## Walkthrough
+
+A complete first-time setup, from connecting to a controller through reading and writing tags.
+
+### 1. The two nodes, and the "not configured" marker
+
+![Read and write nodes, showing the unconfigured marker](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/1%20Connect%20to%20PLC.png)
+
+Dragging the package onto your canvas gives you the two nodes you'll use: a **read** node and a
+**write** node. Before either can do anything, it needs to know *which controller* to talk to —
+that's the job of the PLC connection. A node that has no controller attached shows a small **red
+triangle** in the corner (Node-RED's "this node isn't fully configured" marker). We'll clear it
+by creating a PLC connection. You can do this from inside either node; here we'll start in a
+**read** node.
+
+### 2. Add a PLC connection
+
+![Adding a new PLC configuration](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/2%20Connect%20to%20PLC%202.png)
+
+Open the read node (double-click it). Next to the **PLC** field, click the pencil/add button to
+create a new controller connection. This opens the PLC configuration panel.
+
+### 3. Name it, set the address, and choose the messaging mode
+
+![Naming the PLC, entering the IP, choosing UCMM or Class 3](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/3%20Connect%20to%20PLC%203.png)
+
+Give the connection a **Name** you'll recognize (for example `Line 3 NX102`), and enter the
+controller's **IP address** (for example `192.168.250.1`).
+
+Two things to get right here:
+
+- **Networking.** The machine running Node-RED must be able to reach that IP. The PLC and the
+  PC/server need to be on the **same network and subnet** (or have a route between them). A good
+  sanity check is to `ping` the controller's IP from the machine running Node-RED before going
+  further — if you can't ping it, the node won't connect either.
+- **Messaging mode (UCMM or Class 3).** Choose **UCMM** unless you have a specific reason not
+  to — it's faster on a direct connection, runs requests in parallel, and has no large-array
+  limit. Pick **Class 3** only when you're reaching the controller *through* a routing
+  gateway/comms module or across a backplane, where a held-open connection saves re-resolving
+  the route each time. (See the "UCMM vs Class 3" section above. If in doubt, UCMM.)
+
+### 4. Save, then **Deploy** before testing
+
+![Deploy before testing reads and writes](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/4%20Connect%20to%20PLC%204.png)
+
+Close the configuration panel (Done/Add), then click **Deploy** in the top-right of Node-RED.
+This is important: the PLC connection only actually connects to the controller **after you
+deploy**. Several features below — loading the tag list, validating names, test reads/writes —
+talk to the *live, running* connection, so they won't work until you've deployed at least once.
+
+### 5. Point a read (or write) node at the connection
+
+![Selecting the PLC connection in a read or write node](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/5%20Connect%20PLC%20to%20Read%20or%20Write.png)
+
+Open your read node again. In the **PLC** dropdown, select the connection you just created. The
+red triangle clears — the node now knows which controller it belongs to. Any other read or write
+node can select the same connection; they'll all share that one connection to the controller.
+
+### 6. Test Connection, Load and Validate Published Variables
+
+![The Test Connection / Load / Validate button](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/6%20Load%20Tags.png)
+
+Click **Test Connection, Load and Validate Published Variables**. This one button does three
+useful things at once:
+
+1. **Tests the connection** to the controller (confirming the IP, network, and that it's
+   reachable).
+2. **Loads the controller's published tag list** — every variable you marked *Network Publish =
+   Publish Only* in Sysmac Studio. These names then become **auto-complete suggestions** as you
+   type tag names.
+3. **Validates the tags you've already entered** — each gets a green check (✓) if it exists on
+   the controller, or a red X (✗) if the name wasn't found (a typo, or a tag that isn't
+   published).
+
+Remember it talks to the live controller, so you must have **deployed first** (step 4).
+
+### 7. Add the tags you want to read
+
+![Adding variables, with the dropdown suggestions](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/7%20Add%20the%20tags%20you%20want%20to%20read.png)
+
+Add one row per tag you want to read. After loading the tag list (step 6) you can pick names
+from the **dropdown** instead of typing them, which avoids spelling mistakes. You can read:
+
+| You want | Type this |
+|---|---|
+| a single value | `Counter` |
+| one element of an array | `MyArray[3]` |
+| a whole array at once | `MyArray` |
+| one field of a structure | `MyStruct.Speed` |
+| a whole structure at once | `MyStruct` |
+| something deeply nested | `Machine.Axes[2].Position` |
+
+Reading a **whole** array or structure in one row (just its name, no `[index]` or `.field`) is
+the fastest way to pull a lot of data — it's a single request rather than many.
+
+### 8. Read output — one message, or one message per tag
+
+![Read output shape options](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/8%20Read%20output%20options.png)
+
+The **Output** setting controls how the readings are packaged into the message(s) the node
+sends out. (A "message" is the data packet that travels along the wires to the next node.) Say
+you read three tags — `Counter = 42`, `Speed = 1500`, `Temp = 21.5`:
+
+**One message, `payload = { name: value }`** (the default)
+All tags come out together in a **single message**, as an object keyed by tag name:
+
+```json
+{ "Counter": 42, "Speed": 1500, "Temp": 21.5 }
+```
+
+Use this when you want all the readings together — to show on a dashboard, build a record, write
+a log row, or hand a complete snapshot to a function node. It's the most common choice.
+
+**One message per tag (`topic` = tag name)**
+Each tag comes out as its **own separate message**. Reading three tags emits three messages:
+
+```
+message 1 →  msg.topic = "Counter"   msg.payload = 42
+message 2 →  msg.topic = "Speed"     msg.payload = 1500
+message 3 →  msg.topic = "Temp"      msg.payload = 21.5
+```
+
+Use this when the next node expects **one value at a time**, with the name in `msg.topic` — the
+classic example is the Node-RED **chart** node (it uses `topic` as the series name and `payload`
+as the point), or when you want to route each tag to a different place with a switch node.
+
+**If you're not sure, leave it on "one message."**
+
+### 9. Msg override — let an incoming message choose what to read
+
+![Dynamic variable read via msg override](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/9%20Dynamic%20Variable%20Read.png)
+
+This is the one people find confusing, so here it is plainly.
+
+**Normally**, the node reads the fixed list of tags you typed in step 7. **Msg override** lets a
+*different* part of your flow decide what to read, on the fly, by putting the tag name(s) inside
+the message that triggers the node. The box just names **which property of the incoming message
+to look at** — the default is `variables`, meaning the node checks `msg.variables`.
+
+How it behaves: when a message arrives, if that property is present, the node reads **those**
+tags instead of its own list; if the property is absent, it reads its configured list as normal.
+
+What you can put in `msg.variables` (from a function node, a change node, a dashboard control,
+etc.):
+
+```js
+// read several tags, named in an array:
+msg.variables = ["Pressure", "FlowRate", "MotorMode"];
+
+// read just one tag, as a string:
+msg.variables = "Pressure";
+
+// it accepts nested names too:
+msg.variables = ["Machine.Axes[0].Position", "Recipe.Speed"];
+```
+
+**Why use it:** so one read node can serve many situations instead of building a separate node
+for each set of tags. For example, an operator picks a machine from a dashboard dropdown; a
+function node sets `msg.variables` to that machine's tag names; the single read node reads
+whatever was chosen.
+
+**If you don't need any of that, leave this field alone** — with no `msg.variables` on the
+incoming message, the node simply reads the list you configured.
+
+### 10. Show output JSON — preview the exact output
+
+![Show output JSON preview](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/10%20show%20read%20output%20format.png)
+
+Clicking **Show output JSON** previews exactly what this node will send, in the shape you chose
+in step 8. If you ran **Test Connection / Load / Validate** first, the preview fills in the real
+*kinds* of values your tags hold (whole numbers, true/false, text, lists, structures); if you
+haven't connected yet, it shows generic placeholders. This is just a preview to help you set up
+the nodes that come *after* this one — it doesn't read the controller or change anything. There's
+a **Copy** button to paste the example elsewhere.
+
+### 11. Read triggers — Repeat, and Read once after deploy
+
+![Read trigger options](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/11%20alternative%20triggers.png)
+
+By default a read node reads whenever a message arrives at its input. Two optional triggers let
+it read on its own:
+
+- **Repeat (ms)** — makes the node read **by itself, repeatedly, on a timer**, with no input
+  wired in. The number is the interval in milliseconds: `1000` = once per second, `500` = twice
+  per second, `250` = four times per second. (It will *also* still read when a message arrives.)
+  Leave it at **0** to read **only** when triggered by an incoming message. *Tip:* don't poll
+  faster than you actually need — very small intervals flood the controller. Reading a modest
+  batch every 250 ms is comfortable on most controllers; tighter loops should read only a few
+  tags.
+- **Read once shortly after deploy** — when ticked, the node performs **one** read
+  automatically about 1.5 seconds after you Deploy (or after Node-RED restarts). This is handy
+  for grabbing an initial value at startup instead of waiting for the first trigger or timer.
+
+(`Deploy` is the Node-RED button that saves and starts your flow running.)
+
+---
+
+Now the **write** node. It shares the same PLC connection, tag-name syntax, validate button, and
+trigger options as the read node, so this section focuses on what's different about writing.
+
+### 12. The write node
+
+![Write node with the unconfigured marker](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/12%20write%20setup.png)
+
+Drag a **write** node onto the canvas. Like the read node, it starts with the red "not
+configured" triangle until you attach a PLC connection.
+
+### 13. Select the PLC, then choose where values come from
+
+![PLC selected; Source = From incoming message vs Fixed value(s)](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/13%20from%20incoming%20message%20input.png)
+
+Select the **PLC** connection you already made (same one the read node uses — they share it).
+The key write-only setting is **Source**, which controls where the value to write comes from:
+
+- **From incoming message** — the value is supplied by the message that triggers the node.
+- **Fixed value(s) set here** — you type the value into the node itself.
+
+We'll cover **From incoming message** first (highlighted), then **Fixed** in step 16.
+
+### 14. From incoming message — add the tag names
+
+![Validate + add a variable in message mode](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/14%20from%20incoming%20message%20setup.png)
+
+In **From incoming message** mode, you list **only the tag names** to write (no value boxes) —
+the values will arrive on the message. Just like the read node, use **Test Connection, Load and
+Validate Published Variables** to load the tag list and get dropdown suggestions and ✓/✗
+checking, then add the tag(s) you want to write.
+
+### 15. Show input JSON — the exact message this node expects
+
+![Show input JSON, two-variable example](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/15%20from%20incoming%20message%20input%20format.png)
+
+Click **Show input JSON** to see exactly what message to send this node. This is a **reference**
+for whatever feeds the write node (an inject node, a dashboard control, a function node) — it
+shows the `msg.payload` format for the tags you've added. The format depends on how many tags
+you're writing:
+
+```js
+// ONE variable — send the value directly as the payload:
+msg.payload = 1500;
+
+// MULTIPLE variables — send an object keyed by tag name:
+msg.payload = { "Setpoint": 1500, "Mode": 3, "Enable": true };
+
+// a whole structure or array — send an object/array as that tag's value:
+msg.payload = { "Recipe": { "Speed": 100, "Steps": [1, 2, 3] } };
+```
+
+So whatever sends a message into this node must put the value(s) in `msg.payload` in this shape.
+As with the read node, if you've validated first, the preview shows the real value types for
+your specific tags.
+
+### 16. Fixed value(s) — set the value right in the node
+
+![Fixed value mode with a "value to write" field per tag](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/16%20fixed%20value%20type.png)
+
+Switch **Source** to **Fixed value(s) set here** and each tag row gains a **value to write**
+field. Now the node writes those exact values every time it's triggered — the triggering message
+is just a "go" signal and its contents are ignored.
+
+The value field is a standard Node-RED typed input, so you can enter either:
+
+- **a static value** — type a constant: a number like `1500`, text, true/false, etc. (choose the
+  matching type in the small dropdown — see step 17), **or**
+- **a value pulled from elsewhere** — switch the field's type to `msg.`, `flow.`, or `global.`
+  to write whatever is in a message property or a context variable at the moment the node fires
+  (for example `flow.targetSpeed`).
+
+Use **Fixed** when the value is constant (forcing a mode, a test value, a startup state), or
+when you want to pull from flow/global context rather than the triggering message's payload.
+
+### 17. Data type reference
+
+![Data type mapping table](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/17%20data%20type%20table.png)
+
+The **Data type reference** button opens a table mapping every Omron/Sysmac tag type to what you
+should enter. The important idea: the small **type dropdown** beside a fixed value
+(number / true-false / text / JSON) describes the kind of value **you are entering** — it is
+**not** the controller's tag type. You don't have to match the exact Omron type; the node
+converts your value to whatever the real tag is. As a guide:
+
+- numeric tags (SINT, INT, DINT, REAL, LREAL, etc.) → enter a **number**
+- BOOL → **true/false**
+- STRING → **text**
+- a whole structure or array → **JSON** (an object or array)
+- **64-bit integers** (LINT, ULINT) → numbers within JavaScript's safe range work directly; for
+  very large values, be aware precision can be lost (these are large 64-bit values).
+- **Date / time types** (DATE, DATE_AND_TIME, TIME, TIME_OF_DAY) → enter a **number of
+  nanoseconds**. DATE / DATE_AND_TIME use nanoseconds since 1970 (epoch ms × 1,000,000)
+  and read back as a date; TIME / TIME_OF_DAY are a nanosecond duration (e.g. `5000000000` =
+  5 seconds). These are reliable to **millisecond** precision.
+
+### 18. Verified write
+
+![Verified write option](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/18%20verify%20write.png)
+
+When **Verified write** is ticked, right after writing, the node **reads the value back and
+checks it matches** what you sent — and reports an error if it doesn't.
+
+Why bother, when a normal write already gets an "accepted/error" reply from the controller (which
+is enough almost every time)? Verified write catches the rarer case where the controller says
+*accepted* but the stored value still isn't what you intended — for example:
+
+- the controller's **own program limits/clamps** the value (you send `5000`, but program logic
+  caps it at `4000`), or
+- **another device or the program overwrites** that tag a split second later.
+
+Turn it on for **important values** — setpoints, recipe parameters, mode changes — where you want
+positive proof the value landed. The trade-off is one extra read per tag, so it's slightly
+slower; leave it **off** for ordinary or high-rate writes. (One limit: it checks only the instant
+right after writing — a change made later can't be detected.)
+
+### 19. Write triggers — Repeat, and Write once after deploy
+
+![Write trigger options](https://raw.githubusercontent.com/ucsballen/omron-eip/main/images/19%20trigger.png)
+
+Same two optional triggers as the read node:
+
+- **Repeat (ms)** — writes **by itself on a timer**, with nothing wired in; the number is the
+  interval (`1000` = once per second). Combined with a **Fixed** value, this can continuously
+  hold a tag at a set value — a "heartbeat" signal, or keeping an enable bit on. Leave at **0**
+  to write **only** when triggered. Use this deliberately: most writes should happen in response
+  to an event, not constantly on a timer.
+- **Write once shortly after deploy** — writes **one** time about 1.5 seconds after Deploy (or a
+  restart). With a **Fixed** value, it's a simple way to put a tag into a known starting state at
+  startup, with nothing wired into the input.
+
+---
+
+## Outputs and error handling
+
+Both nodes have **two output ports**:
+
+1. **Result** — the successful read result (read node) or a pass-through with `payload` set to
+   what was written (write node).
+2. **Error** — anything that failed comes out here, so you can wire error handling without it
+   interrupting the success path.
+
+Each node also calls `node.error()` (so flow-wide **Catch** nodes work) and shows the last
+status on the node's **status badge** under its icon. Common controller errors are decoded into
+plain language — for example *"variable not found on the controller — check the name and that it
+is published to the network"* for CIP status `0x05`.
+
+---
+
+## Reading & writing arrays, structures, and nested data
+
+Addressing is symbolic, so you just type the path — there are no special modes:
+
+| You want | Tag name |
+|---|---|
+| whole array | `MyArray` |
+| one array element | `MyArray[3]` |
+| whole structure | `MyStruct` |
+| a structure member | `MyStruct.Speed` |
+| array element inside a structure | `MyStruct.History[2]` |
+| member of a structure inside an array | `Machine.Axes[2].Position` |
+
+For writes, a whole structure/array takes an object/array value; a member/element takes a single
+value. Writing a single member (`MyStruct.Speed`) is safer than rewriting the whole structure,
+because writing the whole structure replaces **every** field in it — including ones another
+writer may have changed.
+
+---
+
+## Troubleshooting
+
+- **Red triangle on a node** → it has no PLC connection selected. Open it and pick (or create)
+  one in the **PLC** field.
+- **Validate / read / write does nothing or errors right after editing** → you haven't
+  **Deployed** since the change. These features talk to the live connection, which only exists
+  after a deploy.
+- **"variable not found" (CIP 0x05)** → the tag name is wrong, **or** the tag isn't published.
+  In Sysmac Studio set it to a global variable with **Network Publish = Publish Only** and
+  **transfer the project** to the controller.
+- **Can't connect at all** → check the network. From the machine running Node-RED, confirm you
+  can `ping` the controller's IP, and that both are on the same subnet/route. In Docker, the
+  *container* must be able to reach the PLC (see the Docker guide).
+- **Large array fails under Class 3** → switch the connection to **UCMM**; Class 3 can't carry
+  very large array replies. (UCMM is the recommended default anyway.)
+
+---
+
+## More documentation
+
+- **[MANUAL.md](./MANUAL.md)** — a complete, plain-language reference: every field on every node,
+  message formats, flow recipes, and troubleshooting.
+- **[DOCKER_INSTALL_AND_TEST.md](./DOCKER_INSTALL_AND_TEST.md)** — installing into a Docker-based
+  Node-RED, plus a full feature-test sequence against a real controller.
+- **[omron-eip](https://www.npmjs.com/package/omron-eip)** — the underlying library, if you want
+  to use it directly from Node.js.
+
+---
+
+## License
+
+GPL-2.0, matching the `omron-eip` library it is built on.