node-red-contrib-omron-eip 0.2.0

package/MANUAL.md

@@ -0,0 +1,457 @@
+# Omron EtherNet/IP Nodes for Node-RED — User Manual
+
+A complete guide to using the `node-red-contrib-omron-eip` nodes to read and write Omron
+NX/NJ controller tags from your Node-RED flows. No programming required.
+
+This manual assumes the nodes are already installed (see `DOCKER_INSTALL_AND_TEST.md` or the
+README) and that you can open the Node-RED editor.
+
+---
+
+## Contents
+
+1. [Concepts: how it fits together](#1-concepts-how-it-fits-together)
+2. [The three nodes at a glance](#2-the-three-nodes-at-a-glance)
+3. [Setting up the PLC connection (config node)](#3-setting-up-the-plc-connection-config-node)
+4. [The read node — every field explained](#4-the-read-node-every-field-explained)
+5. [The write node — every field explained](#5-the-write-node-every-field-explained)
+6. [Variable names: scalars, arrays, structures, nesting](#6-variable-names-scalars-arrays-structures-nesting)
+7. [Message formats in and out](#7-message-formats-in-and-out)
+8. [Triggering: messages, polling, and on-deploy](#8-triggering-messages-polling-and-on-deploy)
+9. [Test Connection, Load and Validate Published Variables](#9-test-connection-load-and-validate-published-variables)
+10. [Error handling](#10-error-handling)
+11. [Common flow recipes](#11-common-flow-recipes)
+12. [Performance & best practices](#12-performance-best-practices)
+13. [Troubleshooting](#13-troubleshooting)
+
+---
+
+## 1. Concepts: how it fits together
+
+Three pieces work together:
+
+- **The controller (PLC).** Your Omron NX/NJ. It exposes *tags* (variables) over EtherNet/IP.
+- **The connection (config node `omron-plc`).** A single shared connection to one controller.
+  You set it up once; many read/write nodes use it.
+- **The operations (`omron read`, `omron write`).** The nodes you drag into flows to actually
+  read or write tags.
+
+The key idea: **one connection, many operations.** You don't configure an IP on every node —
+you create one PLC connection and point your read/write nodes at it. Behind the scenes, all
+operations to that controller share a single, auto-reconnecting link.
+
+A typical flow looks like:
+
+```
+[ trigger ] → [ omron read ] → [ do something with the value ]
+[ event ]   → [ omron write ] → [ confirm / next step ]
+```
+
+where *trigger* is anything that produces a message (an inject node, a timer, a dashboard
+control, another flow).
+
+---
+
+## 2. The three nodes at a glance
+
+| Node | Category | What it does |
+|---|---|---|
+| **omron-plc** | config | Holds the controller IP + messaging mode and the shared connection. Not placed on the canvas directly — created from a read/write node's PLC field. |
+| **omron read** | Omron | Reads one or more tags. Outputs the values. Blue, download icon. |
+| **omron write** | Omron | Writes one or more tags. Orange, upload icon. |
+
+Both operational nodes have **two outputs**: the **top** output carries successful results,
+the **bottom** output carries errors.
+
+---
+
+## 3. Setting up the PLC connection (config node)
+
+You create the connection the first time you add a read or write node:
+
+1. Drag an **omron read** (or **omron write**) node onto the canvas and double-click it.
+2. Next to the **PLC** field, click the **pencil** icon to add a new connection.
+3. Fill in the config node:
+
+| Field | What it is |
+|---|---|
+| **Name** | A friendly label, e.g. "Line 3 NX102". Optional but recommended — it's what you'll see in the PLC dropdown. |
+| **Address** | The controller's IP address (the EtherNet/IP port your machine/container can reach), e.g. `192.168.250.1`. |
+| **Messaging** | **UCMM** (recommended) or **Class 3 connected**. Leave on UCMM unless you have a specific reason (see below). |
+
+4. Click **Add** to save the connection, then **Done** on the node.
+5. **Deploy.** The connection is created when you deploy — not before.
+
+### UCMM vs Class 3
+
+**Use UCMM** (the default) for virtually all setups, especially a direct PC-to-PLC link. It's
+faster, parallelizes, and has no large-array limit.
+
+**Class 3** only helps when traffic routes through a gateway, comms module, or backplane to
+reach the controller. On a direct connection it's slower (it serializes requests) and can't
+read very large arrays. If the controller rejects Class 3, the library silently falls back to
+UCMM, so enabling it never breaks anything — it just may not help.
+
+One config node per controller is the norm. If you have two PLCs, make two config nodes.
+
+---
+
+## 4. The read node — every field explained
+
+Open an **omron read** node. Hover the small ⓘ icons in the editor for inline reminders; here's
+the full reference.
+
+**Connection**
+- **Name** — optional canvas label. If blank, the node shows the tags it reads (e.g.
+  "read: Counter, Speed").
+- **PLC** — which connection to use. Pick an existing config or create one.
+
+**Variables**
+- **Variables** — the list of tags to read, one per row. Free-form symbolic names (see
+  section 6). You can read scalars, whole arrays, whole structures, members, and elements.
+- **Connect & validate** (button) — loads the live tag list from the controller for
+  autocomplete and checks each name (✓ found / ✗ not found). Requires a deployed PLC config
+  (section 9).
+
+**Output**
+- **Shape** — how results are emitted:
+  - *one message: payload = { name: value }* — all tags in a single message as an object.
+  - *one message per tag (topic = name)* — a separate message per tag, with `msg.topic` set
+    to the tag name and `msg.payload` to its value.
+- **Msg override** — the name of a message property that, if present, replaces the configured
+  variable list at runtime. Default `variables` (i.e. set `msg.variables`). Lets a flow choose
+  what to read dynamically.
+
+**Trigger**
+- **Repeat** — milliseconds. If > 0, the node self-polls at that interval (in addition to
+  responding to incoming messages). 0 = only read when a message arrives.
+- **Read once shortly after deploy** — performs one read ~1.5 s after deploy/restart, to fetch
+  an initial value with no trigger.
+
+---
+
+## 5. The write node — every field explained
+
+Open an **omron write** node.
+
+**Connection**
+- **Name** — optional canvas label.
+- **PLC** — which connection to use.
+
+**Values**
+- **Source** — where write values come from:
+  - *From incoming message* — values arrive in `msg.payload` when the node is triggered. The
+    Variables rows are **names only**.
+  - *Fixed value(s) set here* — values are configured in the node. Each Variables row gains a
+    **typed value** field (number / boolean / string / JSON). The incoming message only
+    triggers the write; its payload is ignored.
+
+**Variables**
+- **Variables** — the tags to write, one per row. In *Fixed* mode each row also has a value and
+  a type selector. In *From message* mode, names only.
+- **Connect & validate** — same as the read node.
+
+**Options**
+- **Verified write** — after writing, the node reads the value back and confirms it matches
+  what you sent. A normal write already gets an accepted/error reply from the controller, which
+  is enough almost always; verified write additionally catches the rarer case where the
+  controller *accepts* the write but the value isn't what you intended afterward — e.g. the PLC
+  program clamps it to a limit (you send 5000, it stores 4000), or another device overwrites the
+  tag immediately. Use it for important values (setpoints, recipe parameters). It costs one
+  extra read per tag, so it's slightly slower — leave it off for normal or high-rate writes. It
+  only checks the moment right after writing; a later change to the tag can't be detected.
+
+**Trigger**
+- **Repeat** — milliseconds. If > 0, the node writes automatically at that interval. With
+  *Fixed* values, this can force/hold a tag with nothing wired upstream.
+- **Write once shortly after deploy** — one write ~1.5 s after deploy/restart. With *Fixed*
+  values, sets a tag to a known state at startup.
+
+---
+
+## 6. Variable names: scalars, arrays, structures, nesting
+
+Tags are addressed by their **symbolic name** exactly as defined in the controller. The same
+text field handles every case — there are no separate "array mode" or "struct mode" controls.
+
+| You want | Type the name | Read result / write value |
+|---|---|---|
+| A scalar | `Counter` | a number/boolean/string |
+| A whole array | `MyArray` | a JS array `[…]` |
+| One array element | `MyArray[3]` | a single value |
+| A whole structure | `MyStruct` | a JS object `{…}` |
+| A structure member | `MyStruct.Speed` | a single value |
+| Element of an array in a struct | `MyStruct.History[2]` | a single value |
+| Member of a struct in an array | `Machine.Axes[2].Position` | a single value |
+| Deeper nesting | `Cell.Stations[1].Tools[3].Offset` | a single value |
+
+**Whole vs. member.** Reading or writing a whole array/structure moves all of it in one
+operation — the fast path for bulk data (section 12 of the install/test guide). Reading or
+writing a single member touches just that piece.
+
+**Writing whole structures safely.** A whole-structure write overwrites *every* member. If
+another writer might change a member at the same time, write the specific member
+(`MyStruct.Speed`) instead to avoid a read-modify-write race.
+
+---
+
+## 7. Message formats in and out
+
+### Read output
+
+*One message* shape (default) — `msg.payload` is an object keyed by tag name:
+```json
+{ "Counter": 42, "Speed": 1500 }
+```
+When reading a single tag, `msg.topic` is also set to that tag name.
+
+*Per tag* shape — one message per tag:
+```
+msg.topic = "Counter"   msg.payload = 42
+msg.topic = "Speed"     msg.payload = 1500
+```
+
+If some tags in a batch fail (e.g. one name is wrong), the good values still come through and
+the failures appear on `msg.errors = { name: reason }`.
+
+### Write input (when Source = From incoming message)
+
+**One configured variable** — send the bare value:
+```js
+msg.payload = 1500
+```
+
+**Multiple configured variables** — send an object keyed by name:
+```js
+msg.payload = { "Setpoint": 1500, "Mode": 3, "Enable": true }
+```
+
+**A whole structure or array as a value** — nest it under the variable name:
+```js
+msg.payload = { "Recipe": { "Speed": 100, "Steps": [1, 2, 3] } }
+msg.payload = { "Profile": [10, 20, 30, 40] }
+```
+
+### Write output
+
+On success the message passes through with `msg.payload` set to the map of what was written,
+e.g. `{ "Setpoint": 1500 }`. On failure, the error output carries `msg.error` (a readable
+summary naming the variable and reason) and `msg.errors` (per-variable detail).
+
+> **Data types matter.** Node-RED's inject node defaults `msg.payload` to **string**. Sending
+> the string `"1500"` to a numeric tag fails. Set the inject (or your upstream node) to emit a
+> **number** for numeric tags, **boolean** for BOOLs, **JSON** for arrays/objects.
+
+### Data type reference
+
+The value type you choose (number / boolean / string / JSON) is a **Node-RED** type, not the
+PLC type. The library knows each tag's real Omron type and encodes your value automatically.
+The write node also has a built-in **Data type reference** button showing this table.
+
+| Node-RED type | Sysmac / Omron types | How to enter the value | Range / notes |
+|---|---|---|---|
+| **number** | SINT | integer | -128 … 127 |
+| **number** | INT | integer | -32,768 … 32,767 |
+| **number** | DINT | integer | -2,147,483,648 … 2,147,483,647 |
+| **number** | LINT | integer (64-bit) | ±9.22e18 — see 64-bit note |
+| **number** | USINT | integer | 0 … 255 |
+| **number** | UINT | integer | 0 … 65,535 |
+| **number** | UDINT | integer | 0 … 4,294,967,295 |
+| **number** | ULINT | integer (64-bit) | 0 … 1.84e19 — see 64-bit note |
+| **number** | BYTE | integer (8-bit bit string) | 0 … 255 |
+| **number** | WORD | integer (16-bit bit string) | 0 … 65,535 |
+| **number** | DWORD | integer (32-bit bit string) | 0 … 4,294,967,295 |
+| **number** | LWORD | integer (64-bit bit string) | 0 … 1.84e19 — see 64-bit note |
+| **number** | REAL | float (single) | ~7 significant digits |
+| **number** | LREAL | float (double) | ~15 significant digits |
+| **number** | ENUM | integer (enum value) | 0 … 4,294,967,295 |
+| **boolean** | BOOL | true / false | |
+| **string** | STRING | text | up to 1986 characters (this controller) |
+| **JSON** | ARRAY (of any type) | a JSON array, e.g. `[1,2,3]` | whole-array write |
+| **JSON** | STRUCT (UDT) | a JSON object, e.g. `{"Speed":100}` | whole-structure write |
+| **JSON** | UNION | a JSON object/array | layout is type-specific |
+| **number** | DATE, DATE_AND_TIME | nanoseconds since 1970 (epoch ms × 1,000,000) | reads back as a date; verified to ms precision |
+| **number** | TIME, TIME_OF_DAY | nanoseconds (a number) | duration; verified to ms precision |
+
+**64-bit note (LINT / ULINT / LWORD):** these can exceed JavaScript's safe integer limit
+(~9.0e15). Values within that range work as plain numbers; beyond it, precision can be lost
+entering them as a JS number — handle very large 64-bit values with care.
+
+**Date and time types (DATE, DATE_AND_TIME, TIME, TIME_OF_DAY):** send a **number of
+nanoseconds**, with the value-type set to `number`.
+- **DATE / DATE_AND_TIME** use nanoseconds since 1970-01-01 UTC — i.e. epoch milliseconds ×
+  1,000,000. For example, `1767270896789000000` is 2026-01-01 12:34:56.789 UTC. They read back
+  as a date (an ISO timestamp in the payload).
+- **TIME / TIME_OF_DAY** are a nanosecond duration — e.g. `5000000000` is 5 seconds.
+- These are **verified to millisecond precision**. The full nanosecond value is a very large
+  (19-digit) integer, so digits below the millisecond can be lost when entered as a plain
+  number; values are reliable down to the millisecond. **String input is not accepted** for
+  these types — use a number.
+
+**Out-of-range values are rejected** with a clear error (e.g. a BYTE only accepts 0–255).
+
+### Generating example JSON
+
+Both nodes can generate an example of their message shape so you don't have to construct it by
+hand:
+
+- **Read node — "Show output JSON"** (in the Output section): generates an example of the
+  `msg.payload` this node will emit, based on the variables you've added and the selected
+  output shape. In one-message mode it shows the `{ name: value }` object; in per-tag mode it
+  shows the `{ topic, payload }` form.
+- **Write node — "Show input JSON"** (shown in *From incoming message* mode): generates an
+  example of the `msg.payload` to send this node. For a single variable it shows the bare
+  value; for multiple it shows the `{ "VarName": value, ... }` object.
+
+Both include a **Copy** button. Press **Test Connection, Load and Validate Published
+Variables** first and the examples use the **real types** (numbers, booleans, strings,
+arrays, structures) pulled from the controller; otherwise they show generic `<value>`
+placeholders with a note reminding you to validate.
+
+---
+
+## 8. Triggering: messages, polling, and on-deploy
+
+Both nodes act when triggered. There are three trigger sources, and they combine:
+
+1. **Incoming message** — the default. Any message arriving at the node's input fires it. Wire
+   an inject, a timer, a dashboard control, or another flow into it. (For writes in *From
+   message* mode, the message also carries the value.)
+
+2. **Repeat (self-poll)** — set Repeat to N ms and the node fires itself every N ms with no
+   upstream node. For reads, this is steady polling. For writes with *Fixed* values, this
+   forces/holds a tag.
+
+3. **Once after deploy** — fires a single operation ~1.5 s after the flow deploys/restarts.
+   Good for fetching an initial value or setting a startup state.
+
+You can use any combination. A read node can self-poll *and* respond to messages. A write node
+can fire once at deploy *and* on incoming events.
+
+> **A note on writes that fire themselves:** continuously writing the same value is occasionally
+> what you want (a heartbeat, holding an enable bit), but usually writes should happen in
+> response to an event. Use Repeat/after-deploy on writes deliberately.
+
+---
+
+## 9. Test Connection, Load and Validate Published Variables
+
+Both edit panels have a button labeled **"Test Connection, Load and Validate Published
+Variables"** under the variable list. It:
+
+- Connects to the controller (via the deployed PLC config),
+- Loads every variable that is marked **"Publish Only"** (or Input/Output) on the controller,
+- Gives you **autocomplete** as you type variable names,
+- Marks each configured name with **✓** (exists on the controller) or **✗** (not found).
+
+**It only works after you Deploy.** The button talks to the running flow, which only knows
+about a PLC config once it's been deployed. If you click it on a brand-new, undeployed config
+you'll see "config node not found or not deployed yet" — just Deploy first, then click it.
+
+The button is a convenience for catching typos before runtime. It is **not required** —
+reads and writes work whether or not you've validated. (If validation ever reports a connection
+error, it means the editor backend couldn't reach the PLC; check the connection the same way as
+any read.)
+
+---
+
+## 10. Error handling
+
+Errors are surfaced three ways, so you can handle them however your flow prefers:
+
+1. **Second output (error port).** The bottom output emits a message on failure, with
+   `msg.error` describing what went wrong (and `msg.errors` for per-variable detail on writes).
+   Wire it to a debug node, a notification, a retry, etc.
+
+2. **Catch nodes.** Errors also raise through Node-RED's standard mechanism, so a **Catch** node
+   anywhere on the flow tab will receive them — useful for centralized error handling.
+
+3. **Status badge.** The colored dot under the node shows the latest state: green (ok), blue
+   (working), yellow (connecting / partial), red (error, with a short reason).
+
+Common errors are decoded to plain language, e.g.:
+- *"variable not found on the controller — check the name and that it is published"* (the tag
+  doesn't exist or isn't published to the network),
+- *"type mismatch — expected an integer Number, got string"* (you sent the wrong data type),
+- *"reply data too large — use UCMM for large arrays"* (a large array read over Class 3).
+
+---
+
+## 11. Common flow recipes
+
+### Read one tag on a button press
+```
+[ inject (button) ] → [ omron read: Counter ] → [ debug ]
+```
+
+### Poll a dashboard of values every 250 ms
+```
+[ omron read: Speed, Position, Status  · Repeat 250ms ] → [ ui_text / chart ]
+```
+No inject needed — the read self-polls. Put many tags in one read node; one request fetches
+them all.
+
+### Write a setpoint from a dashboard slider
+```
+[ ui_slider ] → [ change: set msg.payload to { "Setpoint": payload } ] → [ omron write (from message): Setpoint ]
+```
+Or, for a single variable, skip the reshaping — the slider's numeric `msg.payload` goes
+straight into a write node configured with the one variable `Setpoint`.
+
+### Set initial values when the flow starts
+```
+[ omron write (fixed): Mode=1, Enable=true  · Write once after deploy ]
+```
+Nothing upstream needed; it fires once at deploy.
+
+### Heartbeat / watchdog
+```
+[ omron write (fixed): Heartbeat=… · Repeat 1000ms ]
+```
+
+### Read, decide, write
+```
+[ inject ] → [ omron read: Level ] → [ switch: Level > 80? ] → [ omron write (fixed): Pump=false ]
+```
+
+### Bulk-move a recipe (whole structure)
+```
+[ inject (JSON: {"Recipe":{…}}) ] → [ omron write (from message): Recipe ]
+[ inject ] → [ omron read: Recipe ] → [ debug ]   // reads the whole struct back
+```
+
+---
+
+## 12. Performance & best practices
+
+- **Batch reads.** Put multiple tags in one read node rather than many single-tag nodes — one
+  request fetches them all, far more efficiently.
+- **Use whole arrays/structures for bulk data.** Reading `MyArray` in one go is dramatically
+  faster than reading `MyArray[0]`, `MyArray[1]`, … individually.
+- **Pick a sensible poll rate.** On a direct connection an NX102 comfortably handles, for
+  example, ~50 tags every 100 ms, ~100 tags every 250 ms, ~200 tags every 500 ms. Don't poll
+  faster than you need; split fast-changing and slow-changing data onto separate read nodes
+  with different Repeat intervals.
+- **Prefer member writes over whole-structure writes** unless you intend to set everything, to
+  avoid clobbering concurrent changes.
+- **Match data types.** Numbers for numeric tags, booleans for BOOLs, JSON for arrays/objects.
+- **Keep UCMM** unless you specifically route through a gateway.
+- **One config node per PLC**, shared by all its read/write nodes.
+
+---
+
+## 13. Troubleshooting
+
+| Symptom | Likely cause / fix |
+|---|---|
+| "config node not found or not deployed yet" | You used Connect & validate (or ran a flow) before deploying. **Deploy first.** |
+| Write fails: "type mismatch …" | You sent the wrong type (commonly a string to a numeric tag). Set the inject/upstream payload type to number/boolean/JSON. |
+| Read/write error: "variable not found" (CIP 0x05) | The tag name is wrong, or the tag isn't published to the network. In Sysmac Studio, make it a global variable with Network Publish = Publish Only, and transfer the project to the controller. |
+| Node status stays yellow "connecting…" | The node can't reach the PLC. Verify the address, and that the machine/container running Node-RED can reach the PLC (e.g. ping it from the same host/container). |
+| "reply data too large" on a big array | You're on Class 3; switch the config node to UCMM for large arrays. |
+| Editor shows old node UI after an update | Hard-refresh the browser (Ctrl-Shift-R) to clear cached node HTML. |
+| Connect & validate reports a connection error | The editor backend can't reach the PLC. Same checks as a failed read; confirm the deployed config's address is reachable. |
+| Some tags read fine but others fail in a batch | The failures are on `msg.errors`; the good values still come through. Check the failed names. |
+
+For protocol-level detail, performance numbers, and the underlying library, see the `omron-eip`
+library docs (`README.md`, `EXAMPLES.md`, `PROTOCOL.md`, `NX102_PERFORMANCE.md`).