node-red-contrib-omron-eip 0.2.0

package/nodes/common.js

@@ -0,0 +1,237 @@
+'use strict';
+/**
+ * Shared helpers for the omron-eip Node-RED nodes.
+ *
+ * This module deliberately contains NO Node-RED or omron-eip dependencies, so it can be
+ * unit-tested offline. It holds the message-shape parsing/normalization and error
+ * formatting that turn loose Node-RED messages into well-formed library calls and turn
+ * library errors into clear, actionable messages.
+ */
+
+/**
+ * Resolve the list of variable names a read/write operation should act on.
+ *
+ * Precedence: an explicit list on the incoming message overrides the node's configured
+ * list. This lets a flow drive the variable set dynamically while still supporting a
+ * static configuration.
+ *
+ * Accepted message overrides (on msg[varProp], default msg.variables):
+ *   - an array of strings: ['A', 'B', 'C']
+ *   - a single string:     'A'
+ * Anything else is ignored and the configured list is used.
+ *
+ * @param {string[]} configuredNames  names from the node's edit panel
+ * @param {*}        msgOverride       msg[varProp], may be undefined
+ * @returns {string[]} the resolved, non-empty list of names
+ */
+function resolveReadVariables(configuredNames, msgOverride) {
+  if (Array.isArray(msgOverride) && msgOverride.length > 0 &&
+      msgOverride.every(n => typeof n === 'string' && n.length > 0)) {
+    return msgOverride.slice();
+  }
+  if (typeof msgOverride === 'string' && msgOverride.length > 0) {
+    return [msgOverride];
+  }
+  return (configuredNames || []).filter(n => typeof n === 'string' && n.length > 0);
+}
+
+/**
+ * Build the {name: value} map for a write operation.
+ *
+ * Two value sources, chosen at the node level:
+ *
+ *   source === 'fixed':
+ *     Values come entirely from the node's configured rows. `fixedPairs` is an array of
+ *     { name, value } already type-coerced by the caller. The incoming message is only a
+ *     trigger and its payload is ignored.
+ *
+ *   source === 'msg':
+ *     Values come from the incoming message payload. Two accepted shapes:
+ *       - object keyed by variable name: { Setpoint: 1500, Mode: 3 }
+ *       - a bare value (number/boolean/string/object-for-struct), ONLY valid when exactly
+ *         one variable is configured: 1500  ->  { <the one configured name>: 1500 }
+ *
+ * Throws an Error with a precise, user-facing message when the shape can't be resolved.
+ *
+ * @param {Object}   opts
+ * @param {string}   opts.source        'fixed' | 'msg'
+ * @param {Array}    opts.fixedPairs    [{name, value}] (for source 'fixed')
+ * @param {string[]} opts.configuredNames  configured variable names (for source 'msg')
+ * @param {*}        opts.payload       msg payload (for source 'msg')
+ * @returns {Object} map of { variableName: value }
+ */
+function buildWriteMap(opts) {
+  const { source, fixedPairs, configuredNames, payload } = opts;
+
+  if (source === 'fixed') {
+    const pairs = (fixedPairs || []).filter(p => p && typeof p.name === 'string' && p.name.length > 0);
+    if (pairs.length === 0) {
+      throw new Error('Write node has no variables configured. Add at least one variable and value.');
+    }
+    const map = {};
+    for (const p of pairs) map[p.name] = p.value;
+    return map;
+  }
+
+  // source === 'msg'
+  const names = (configuredNames || []).filter(n => typeof n === 'string' && n.length > 0);
+
+  // Object payload keyed by variable name.
+  if (payload !== null && typeof payload === 'object' && !Array.isArray(payload)) {
+    const keys = Object.keys(payload);
+    if (keys.length === 0) {
+      throw new Error('Write expected msg.payload to be an object like { VariableName: value } but it was empty.');
+    }
+    return Object.assign({}, payload);
+  }
+
+  // Bare value payload — only valid for a single configured variable.
+  if (names.length === 1) {
+    if (payload === undefined) {
+      throw new Error(`Write expected msg.payload to hold the value for "${names[0]}" but it was undefined.`);
+    }
+    return { [names[0]]: payload };
+  }
+
+  // Bare value but multiple/zero configured variables: ambiguous.
+  const got = payload === null ? 'null' : Array.isArray(payload) ? 'array' : typeof payload;
+  if (names.length === 0) {
+    throw new Error(
+      `Write received a ${got} payload but no variables are configured. ` +
+      `Either configure variable names, or send msg.payload as an object like { VariableName: value }.`
+    );
+  }
+  throw new Error(
+    `Write expected msg.payload to be an object like { VariableName: value } because ${names.length} ` +
+    `variables are configured (${names.join(', ')}), but got a ${got}.`
+  );
+}
+
+/**
+ * Coerce a typed-input style value into a JS value for writing.
+ * Node-RED's typed input gives us a string plus a type tag; for the value types we type
+ * inline (num/bool/str/json) we convert here. (msg/flow/global are resolved by Node-RED
+ * before reaching us, so they arrive already as native values and pass through.)
+ *
+ * @param {*} value   the raw value (already native for msg/flow/global)
+ * @param {string} type  'num' | 'bool' | 'str' | 'json' | other
+ * @returns {*}
+ */
+function coerceTypedValue(value, type) {
+  switch (type) {
+    case 'num': {
+      const n = Number(value);
+      if (Number.isNaN(n)) throw new Error(`"${value}" is not a valid number.`);
+      return n;
+    }
+    case 'bool':
+      return value === true || value === 'true';
+    case 'json':
+      if (typeof value === 'string') {
+        try { return JSON.parse(value); }
+        catch (e) { throw new Error(`Invalid JSON value: ${e.message}`); }
+      }
+      return value;
+    case 'str':
+      return value == null ? '' : String(value);
+    default:
+      return value;
+  }
+}
+
+/**
+ * Shape the result of a multi-tag read into the message payload form the user chose.
+ *
+ * @param {Object} resultMap  { name: value | {__error: Error} } from readVariables
+ * @param {string} outputShape  'object' (default) | 'perTag'
+ * @returns {{ kind: 'single', items: [{topic, payload, error}] }}
+ *          A normalized description the node turns into one or many messages.
+ *          For 'object', items has length 1 with payload = the whole map (errors stripped
+ *          into a separate .errors field). For 'perTag', one item per variable.
+ */
+function shapeReadResult(resultMap, outputShape) {
+  const names = Object.keys(resultMap);
+
+  if (outputShape === 'perTag') {
+    return {
+      kind: 'perTag',
+      items: names.map(name => {
+        const v = resultMap[name];
+        const isErr = v && typeof v === 'object' && v.__error instanceof Error;
+        return {
+          topic: name,
+          payload: isErr ? null : v,
+          error: isErr ? v.__error : null,
+        };
+      }),
+    };
+  }
+
+  // 'object' (default): one message, payload is { name: value }, errors collected aside.
+  const payload = {};
+  const errors = {};
+  let hasError = false;
+  for (const name of names) {
+    const v = resultMap[name];
+    if (v && typeof v === 'object' && v.__error instanceof Error) {
+      errors[name] = v.__error.message;
+      hasError = true;
+    } else {
+      payload[name] = v;
+    }
+  }
+  return {
+    kind: 'object',
+    items: [{
+      topic: names.length === 1 ? names[0] : undefined,
+      payload,
+      errors: hasError ? errors : null,
+    }],
+  };
+}
+
+/**
+ * Turn an error from the library into a concise, user-facing string, decoding the common
+ * CIP status codes into plain language where we can.
+ *
+ * @param {Error} err  may be a CIPException (has .statusCode / .extendedStatusCode) or generic
+ * @param {string} [variableName]  the tag involved, if known
+ * @returns {string}
+ */
+function describeError(err, variableName) {
+  if (!err) return 'Unknown error';
+  const tag = variableName ? ` (variable "${variableName}")` : '';
+  const code = (err.statusCode !== undefined && err.statusCode !== null)
+    ? Number(err.statusCode) : null;
+
+  // Decode the CIP statuses users hit most often.
+  const HINTS = {
+    0x04: 'path segment error — check the variable name/syntax',
+    0x05: 'variable not found on the controller — check the name and that it is published to the network',
+    0x08: 'service not supported by the controller',
+    0x11: 'reply data too large — the value exceeds the connection limit (use UCMM for large arrays)',
+    0x13: 'not enough data — the value is shorter than the variable expects',
+    0x15: 'too much data — the value is larger than the variable, or the type does not match',
+  };
+  if (code !== null && HINTS[code]) {
+    return `CIP error 0x${code.toString(16).padStart(2, '0')}: ${HINTS[code]}${tag}`;
+  }
+
+  // Clean up the library's type-validation messages (thrown before anything hits the wire),
+  // e.g. "CIPDoubleInteger.fromValue: expected an integer Number, got string \"104\"".
+  let msg = err.message || String(err);
+  const m = msg.match(/^CIP\w+\.fromValue:\s*(.*)$/);
+  if (m) {
+    // Strip the internal class/method prefix; keep the human-readable reason.
+    return `type mismatch — ${m[1]}${tag}`;
+  }
+  return `${msg}${tag}`;
+}
+
+module.exports = {
+  resolveReadVariables,
+  buildWriteMap,
+  coerceTypedValue,
+  shapeReadResult,
+  describeError,
+};

package/nodes/omron-plc.html

@@ -0,0 +1,152 @@
+<script type="text/javascript">
+  RED.nodes.registerType('omron-plc', {
+    category: 'config',
+    defaults: {
+      name:      { value: '' },
+      address:   { value: '', required: true },
+      messaging: { value: 'ucmm' },
+    },
+    label: function () {
+      return this.name || this.address || 'omron-plc';
+    },
+  });
+</script>
+
+<script type="text/html" data-template-name="omron-plc">
+  <div class="omron-banner">
+    <i class="fa fa-info-circle"></i>
+    <b>Deploy after editing.</b> The connection to the PLC is created when you
+    <b>Deploy</b> the flow. A newly added or changed PLC config is not live until then.
+  </div>
+
+  <div class="omron-section-title">Connection</div>
+
+  <div class="form-row">
+    <label for="node-config-input-name">
+      <i class="fa fa-tag"></i> Name
+      <i class="fa fa-info-circle omron-info" title="A friendly name for this controller so you can recognize it later, for example Line 3 NX102 or Packaging PLC. It appears in the PLC dropdown on every read and write node. Optional, but recommended if you have more than one controller."></i>
+    </label>
+    <input type="text" id="node-config-input-name" placeholder="e.g. Line 3 NX102">
+  </div>
+
+  <div class="form-row">
+    <label for="node-config-input-address">
+      <i class="fa fa-globe"></i> Address
+      <i class="fa fa-info-circle omron-info" title="The network address (IP) of the controller, for example 192.168.250.1. This is the address of the controller's EtherNet/IP port. Important: the computer (or container) running Node-RED must be able to reach this address on the network — if you cannot ping it from there, the node cannot connect either."></i>
+    </label>
+    <input type="text" id="node-config-input-address" placeholder="192.168.250.1">
+  </div>
+
+  <div class="form-row">
+    <label>
+      <i class="fa fa-exchange"></i> Messaging
+      <i class="fa fa-info-circle omron-info" title="Two ways of talking to the controller. UCMM is the normal, recommended choice for almost everyone, especially when this computer connects straight to the PLC — it is faster and simpler. Class 3 only helps in special network setups (going through a routing gateway or across a backplane). When in doubt, leave it on UCMM. The box below explains both in more detail."></i>
+    </label>
+    <div style="display:inline-block;">
+      <label style="width:auto; margin-right:15px;">
+        <input type="radio" name="node-config-input-messaging" value="ucmm" style="width:auto; vertical-align:middle;">
+        UCMM (recommended)
+      </label>
+      <label style="width:auto;">
+        <input type="radio" name="node-config-input-messaging" value="class3" style="width:auto; vertical-align:middle;">
+        Class 3 connected
+      </label>
+    </div>
+  </div>
+
+  <div class="form-tips omron-tips">
+    <b>Which messaging mode?</b><br>
+    <b>UCMM</b> (unconnected) is the default and the right choice for almost every setup,
+    especially a direct PC-to-PLC connection. It is faster for high-rate and parallel reads,
+    has no large-array limitation, and needs no connection setup.<br><br>
+    <b>Class 3</b> (connected) opens a persistent CIP connection. It only helps when requests
+    travel through a routing gateway, a comms module, or across a backplane, where it avoids
+    re-resolving the path on every request. On a direct connection it is <i>slower</i> than UCMM
+    (a single connection serializes requests) and it cannot read very large arrays. Use it only
+    if your topology specifically benefits. If the controller rejects Class 3, the library
+    automatically falls back to UCMM.
+  </div>
+</script>
+
+<style>
+  /* Shared styling for the Omron node edit panels. */
+  .omron-banner {
+    background: #eaf4fb;
+    border: 1px solid #b6dcf5;
+    border-left: 4px solid #4a9fd8;
+    border-radius: 3px;
+    padding: 8px 10px;
+    margin-bottom: 14px;
+    font-size: 12px;
+    line-height: 1.5;
+    color: #2c5d7c;
+  }
+  .omron-banner .fa-info-circle { margin-right: 5px; }
+  .omron-section-title {
+    font-size: 11px;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: #888;
+    border-bottom: 1px solid #ddd;
+    padding-bottom: 4px;
+    margin: 14px 0 10px;
+    font-weight: 600;
+  }
+  .omron-info {
+    color: #b0b0b0;
+    margin-left: 4px;
+    cursor: help;
+    font-size: 12px;
+  }
+  .omron-info:hover { color: #4a9fd8; }
+  .omron-tips {
+    max-width: none;
+    background: #fbfbf6;
+    line-height: 1.5;
+  }
+  .omron-typeref-table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 12px;
+    margin-bottom: 8px;
+  }
+  .omron-typeref-table th,
+  .omron-typeref-table td {
+    border: 1px solid #e0e0e0;
+    padding: 4px 7px;
+    text-align: left;
+    vertical-align: top;
+  }
+  .omron-typeref-table th {
+    background: #f3f3f3;
+    font-weight: 600;
+  }
+  .omron-typeref-table code {
+    font-size: 11px;
+  }
+  .omron-typeref-note {
+    background: #fbfbf6;
+    border: 1px solid #eee;
+    border-radius: 3px;
+    padding: 8px 10px;
+    font-size: 12px;
+    line-height: 1.5;
+    color: #555;
+  }
+  .omron-json {
+    background: #f4f4f4 !important;
+    color: #1a1a1a !important;
+    border: 1px solid #d0d0d0;
+    border-radius: 3px;
+    padding: 8px 10px;
+    font-size: 12px;
+    line-height: 1.45;
+    overflow-x: auto;
+    white-space: pre;
+    margin: 6px 0;
+    font-family: monospace;
+  }
+  .omron-json * {
+    color: #1a1a1a !important;
+  }
+</style>

package/nodes/omron-plc.js

@@ -0,0 +1,131 @@
+'use strict';
+/**
+ * omron-plc — config node. Owns one shared NSeriesController for a controller, referenced
+ * by any number of omron-read / omron-write nodes. Holds the IP address and the UCMM/Class 3
+ * messaging choice. Manages the connection lifecycle and exposes a small helper API the
+ * operational nodes use (getController, whenReady, listTags).
+ */
+const { NSeriesController } = require('omron-eip');
+
+module.exports = function (RED) {
+  function OmronPlcNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    node.address = config.address;
+    node.messaging = config.messaging || 'ucmm';   // 'ucmm' | 'class3'
+    node.label = config.name || config.address;
+
+    // Build the resilient controller. autoConnect is false; we connect explicitly below so
+    // we can surface state to the operational nodes via events.
+    node.controller = new NSeriesController({
+      host: node.address,
+      useConnectedMessaging: node.messaging === 'class3',
+      keepAlive: true,
+      autoConnect: false,
+      // A light logger that forwards to Node-RED's log at debug level.
+      logger: {
+        debug: (m) => node.debug(m),
+        info:  (m) => node.debug(m),
+        warn:  (m) => node.warn(m),
+        error: (m) => node.debug(m),   // connection errors are surfaced via events instead
+      },
+    });
+
+    node.connected = false;
+    node.lastError = null;
+
+    node.controller.on('connect',    () => { node.connected = true;  node.lastError = null; node.emit('plc-state', 'connected'); });
+    node.controller.on('reconnect',  () => { node.connected = true;  node.lastError = null; node.emit('plc-state', 'connected'); });
+    node.controller.on('disconnect', () => { node.connected = false; node.emit('plc-state', 'disconnected'); });
+    node.controller.on('error',      (err) => { node.lastError = err; node.emit('plc-state', 'error', err); });
+    node.controller.on('dispatcherError', (err) => { node.lastError = err; });
+
+    // Kick off the initial connection. Failures here are normal (PLC may be offline at
+    // deploy time); the controller keeps retrying with backoff.
+    node.controller.connect().catch((err) => { node.lastError = err; });
+
+    /** Resolve when the controller is connected, or reject after timeoutMs. */
+    node.whenReady = function (timeoutMs = 8000) {
+      if (node.connected) return Promise.resolve();
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          node.removeListener('plc-state', onState);
+          reject(node.lastError || new Error(`Not connected to ${node.address} (timed out)`));
+        }, timeoutMs);
+        function onState(state) {
+          if (state === 'connected') {
+            clearTimeout(timer);
+            node.removeListener('plc-state', onState);
+            resolve();
+          }
+        }
+        node.on('plc-state', onState);
+      });
+    };
+
+    /** Return the shared controller (operational nodes call this). */
+    node.getController = function () { return node.controller; };
+
+    /**
+     * Pull the live tag dictionary from the controller (used by the editor's
+     * "Connect & validate" button). Returns a sorted list of published variable names.
+     */
+    node.listTags = async function () {
+      await node.whenReady(8000);
+      await node.controller.updateVariableDictionary();
+      const names = node.controller.userVariableList
+        ? node.controller.userVariableList()
+        : node.controller.variableList();
+
+      // Also expose each tag's type category so the editor can generate example JSON with
+      // correct placeholder values. We reach into the underlying NSeries dispatcher's
+      // variable map (name -> type instance) and classify by the instance class name.
+      const types = {};
+      try {
+        const plc = node.controller.plc;
+        const map = plc && plc.dispatcher &&
+          (plc.dispatcher.userVariables || plc.dispatcher.variables);
+        if (map) {
+          for (const [name, inst] of map.entries()) {
+            types[name] = classifyType(inst);
+          }
+        }
+      } catch (_) { /* types are best-effort; names still work */ }
+
+      return { tags: (names || []).slice().sort(), types };
+    };
+
+    // Map a CIP type instance to a coarse category the editor uses to pick a JSON example value.
+    function classifyType(inst) {
+      const n = inst && inst.constructor && inst.constructor.name || '';
+      if (n === 'CIPBoolean') return 'bool';
+      if (n === 'CIPReal' || n === 'CIPLongReal') return 'float';
+      if (n === 'CIPString') return 'string';
+      if (n === 'CIPAbbreviatedStructure' || n === 'CIPStructure') return 'struct';
+      if (n === 'CIPArray') return 'array';
+      if (/^Omron(Date|Time)/.test(n)) return 'datetime';
+      // All integer-ish types (SINT..LWORD, ENUM, BCD) -> number
+      return 'number';
+    }
+
+    node.on('close', async function (done) {
+      try { await node.controller.close(); } catch (_) {}
+      done();
+    });
+  }
+
+  RED.nodes.registerType('omron-plc', OmronPlcNode);
+
+  // ----- Editor-facing HTTP admin endpoint: list tags for a given config node -----
+  // Called by the edit panels' "Connect & validate" button. The :id is the config node's id.
+  RED.httpAdmin.get('/omron-eip/:id/tags', RED.auth.needsPermission('omron-plc.read'), function (req, res) {
+    const cfg = RED.nodes.getNode(req.params.id);
+    if (!cfg || cfg.type !== 'omron-plc') {
+      return res.status(404).json({ error: 'config node not found or not deployed yet' });
+    }
+    cfg.listTags()
+      .then((result) => res.json(result))   // { tags: [...], types: { name: category } }
+      .catch((err) => res.status(502).json({ error: err.message }));
+  });
+};