node-red-contrib-omron-eip 0.2.0

package/nodes/omron-read.html

@@ -0,0 +1,299 @@
+<script type="text/javascript">
+  RED.nodes.registerType('omron-read', {
+    category: 'Omron',
+    color: '#7fb3d5',
+    defaults: {
+      name:        { value: '' },
+      plc:         { value: '', type: 'omron-plc', required: true },
+      variables:   { value: [] },
+      varProp:     { value: 'variables' },
+      outputShape: { value: 'object' },
+      pollMs:      { value: 0, validate: function (v) { return v === '' || v === undefined || !isNaN(Number(v)); } },
+      fireOnDeploy:{ value: false },
+    },
+    inputs: 1,
+    outputs: 2,
+    outputLabels: ['result', 'error'],
+    icon: 'font-awesome/fa-download',
+    paletteLabel: 'omron read',
+    label: function () {
+      if (this.name) return this.name;
+      const names = (this.variables || []).map(v => v.name).filter(Boolean);
+      if (names.length === 0) return 'omron read';
+      if (names.length <= 2) return 'read: ' + names.join(', ');
+      return 'read: ' + names.length + ' tags';
+    },
+    oneditprepare: function () {
+      const node = this;
+      $('#node-input-variable-container').css('min-height', '120px').editableList({
+        addItem: function (row, index, data) {
+          data = data || {};
+          $(row).css({ display: 'flex', 'align-items': 'center' });
+          const input = $('<input/>', { type: 'text', class: 'omron-var-name',
+            placeholder: 'e.g. Counter  ·  MyStruct.Speed  ·  Arr[3]  ·  WholeArray  ·  WholeStruct' })
+            .css({ flex: 1, 'margin-right': '6px' }).appendTo(row);
+          input.val(data.name || '');
+          // If tags were already loaded this session, give new rows autocomplete too.
+          if (node._omronTags && node._omronTags.length) {
+            input[0].setAttribute('list', 'omron-tags-datalist');
+          }
+          $('<span/>', { class: 'omron-var-badge' }).css({ width: '18px', 'text-align': 'center' }).appendTo(row);
+        },
+        removable: true, sortable: true,
+      });
+      (this.variables || []).forEach(v => $('#node-input-variable-container').editableList('addItem', v));
+
+      $('#omron-validate-btn').on('click', function () {
+        const cfgId = $('#node-input-plc').val();
+        const statusEl = $('#omron-validate-status');
+        if (!cfgId || cfgId === '_ADD_') {
+          statusEl.html('<i class="fa fa-exclamation-triangle"></i> Select & deploy a PLC config first.').css('color', '#b30000');
+          return;
+        }
+        statusEl.html('<i class="fa fa-spinner fa-spin"></i> Connecting…').css('color', '#888');
+        $.getJSON('omron-eip/' + cfgId + '/tags')
+          .done(function (data) {
+            const tags = data.tags || [];
+            statusEl.html('<i class="fa fa-check"></i> ' + tags.length + ' tags loaded').css('color', '#3a7d3a');
+            $('#node-input-variable-container').find('.omron-var-name').each(function () {
+              const base = $(this).val().split(/[.\[]/)[0];
+              const badge = $(this).siblings('.omron-var-badge');
+              if (!base) { badge.text(''); return; }
+              if (tags.indexOf(base) !== -1) badge.html('<i class="fa fa-check" style="color:#3a7d3a;" title="Green check: this tag name was found on the controller — it exists and is readable."></i>');
+              else badge.html('<i class="fa fa-times" style="color:#b30000;" title="Red X: this tag name was NOT found on the controller. Usually a spelling mistake, or the tag has not been shared to the network (in Sysmac Studio its Network Publish must be set to Publish Only)."></i>');
+            });
+            let dl = $('#omron-tags-datalist');
+            if (dl.length === 0) dl = $('<datalist id="omron-tags-datalist"></datalist>').appendTo('body');
+            dl.empty();
+            tags.forEach(t => dl.append($('<option>').attr('value', t)));
+            // Remember tags (and types, if returned) so rows added later get autocomplete
+            // and the "Show output JSON" button can use real types.
+            node._omronTags = tags;
+            node._omronTypes = data.types || {};
+            // Attach the list and "nudge" each input so the browser shows the dropdown
+            // affordance immediately (without this, the arrow only appears after the value
+            // changes, i.e. type-then-delete).
+            $('#node-input-variable-container').find('.omron-var-name').each(function () {
+              this.setAttribute('list', 'omron-tags-datalist');
+              // Dispatching an input event registers the freshly-attached datalist.
+              this.dispatchEvent(new Event('input', { bubbles: true }));
+            });
+          })
+          .fail(function (xhr) {
+            const e = (xhr.responseJSON && xhr.responseJSON.error) || 'connection failed';
+            statusEl.html('<i class="fa fa-times"></i> ' + e).css('color', '#b30000');
+          });
+      });
+
+      // ---- Show output JSON ----
+      // Returns an example value for a tag based on its known type category, or a generic
+      // placeholder if types haven't been loaded (validate not yet pressed).
+      function exampleValue(name) {
+        const types = node._omronTypes || {};
+        const base = name.split(/[.\[]/)[0];
+        const cat = types[name] || types[base];
+        // If the name targets an element/member, a known whole-array/struct type doesn't apply.
+        const isIndexedOrMember = /[.\[]/.test(name);
+        switch (cat) {
+          case 'bool':     return false;
+          case 'float':    return 0.0;
+          case 'number':   return 0;
+          case 'string':   return '';
+          case 'datetime': return '<date/time>';
+          case 'array':    return isIndexedOrMember ? 0 : [];
+          case 'struct':   return isIndexedOrMember ? 0 : {};
+          default:         return '<value>';   // unknown / not validated
+        }
+      }
+
+      function currentNames() {
+        const names = [];
+        $('#node-input-variable-container').find('.omron-var-name').each(function () {
+          const n = $(this).val().trim();
+          if (n) names.push(n);
+        });
+        return names;
+      }
+
+      function buildOutputJson() {
+        const names = currentNames();
+        const validated = node._omronTypes && Object.keys(node._omronTypes).length > 0;
+        const shape = $('#node-input-outputShape').val();
+        let html = '';
+        if (names.length === 0) {
+          return '<div class="omron-typeref-note">Add one or more variables first.</div>';
+        }
+        if (shape === 'perTag') {
+          // One message per tag.
+          const first = names[0];
+          const example = { topic: first, payload: exampleValue(first) };
+          html += '<div class="omron-typeref-note">This node emits <b>one message per tag</b>. ' +
+            'Each message looks like:</div>';
+          html += '<pre class="omron-json" style="background:#f4f4f4;color:#1a1a1a;border:1px solid #d0d0d0;border-radius:3px;padding:8px 10px;font-family:monospace;font-size:12px;line-height:1.45;white-space:pre;overflow-x:auto;margin:6px 0;">' + JSON.stringify(example, null, 2) + '</pre>';
+          if (names.length > 1) {
+            html += '<div class="omron-typeref-note">…and similarly for: <code>' +
+              names.slice(1).join('</code>, <code>') + '</code>.</div>';
+          }
+        } else {
+          const obj = {};
+          names.forEach(n => { obj[n] = exampleValue(n); });
+          html += '<div class="omron-typeref-note">This node emits <b>one message</b> with ' +
+            '<code>msg.payload</code> =</div>';
+          html += '<pre class="omron-json" style="background:#f4f4f4;color:#1a1a1a;border:1px solid #d0d0d0;border-radius:3px;padding:8px 10px;font-family:monospace;font-size:12px;line-height:1.45;white-space:pre;overflow-x:auto;margin:6px 0;">' + JSON.stringify(obj, null, 2) + '</pre>';
+        }
+        if (!validated) {
+          html += '<div class="omron-typeref-note"><i class="fa fa-info-circle"></i> ' +
+            'Values shown are generic placeholders. Press <b>Test Connection, Load and ' +
+            'Validate Published Variables</b> to fill in the actual types ' +
+            '(numbers, booleans, strings, arrays, structures).</div>';
+        }
+        html += '<button type="button" class="red-ui-button red-ui-button-small omron-copy-btn">' +
+          '<i class="fa fa-copy"></i> Copy</button>';
+        return html;
+      }
+
+      $('#omron-outjson-btn').on('click', function () {
+        const box = $('#omron-outjson');
+        box.html(buildOutputJson());
+        box.toggle();
+        box.find('.omron-copy-btn').on('click', function () {
+          const txt = box.find('pre.omron-json').first().text();
+          navigator.clipboard && navigator.clipboard.writeText(txt);
+          $(this).html('<i class="fa fa-check"></i> Copied');
+          setTimeout(() => $(this).html('<i class="fa fa-copy"></i> Copy'), 1500);
+        });
+      });
+    },
+    oneditsave: function () {
+      const vars = [];
+      $('#node-input-variable-container').find('.omron-var-name').each(function () {
+        const name = $(this).val().trim();
+        if (name) vars.push({ name });
+      });
+      this.variables = vars;
+    },
+  });
+</script>
+
+<script type="text/html" data-template-name="omron-read">
+  <div class="omron-banner">
+    <i class="fa fa-info-circle"></i>
+    <b>Deploy after editing.</b> Reads run against the deployed flow. After adding/changing the
+    PLC config or variables, click <b>Deploy</b> before testing or using <b>Connect &amp; validate</b>.
+  </div>
+
+  <div class="omron-section-title">Connection</div>
+  <div class="form-row">
+    <label for="node-input-name">
+      <i class="fa fa-tag"></i> Name
+      <i class="fa fa-info-circle omron-info" title="A nickname for this read block, shown under its icon on the workspace (the editing canvas). It is purely cosmetic and only helps you tell blocks apart when you have several. Leave it blank and the block will simply label itself with the tag names it reads."></i>
+    </label>
+    <input type="text" id="node-input-name" placeholder="(optional label)">
+  </div>
+  <div class="form-row">
+    <label for="node-input-plc">
+      <i class="fa fa-server"></i> PLC
+      <i class="fa fa-info-circle omron-info" title="Which controller (PLC) this block reads from. A 'PLC connection' is a saved entry that holds the controller's network address; you set it up once and then every read and write block can share it, so you do not re-enter the address each time. Use the dropdown to pick one you already made, the pencil button to edit it, or the plus button to create a new one. This must be filled in — without a PLC chosen, the block cannot read anything."></i>
+    </label>
+    <input type="text" id="node-input-plc">
+  </div>
+
+  <div class="omron-section-title">Variables</div>
+  <div class="form-row">
+    <label style="vertical-align:top;">
+      <i class="fa fa-list"></i> Variables
+      <i class="fa fa-info-circle omron-info" title="The tags you want to read — one per row. A tag (also called a variable) is a named piece of data inside the controller, like a counter or a temperature. Type the name exactly as it is spelled in your Sysmac Studio program (names are case-sensitive). Examples of what you can type: Counter (a single value); MyArray[3] (item number 3 of a list — the number in brackets picks which item); MyArray (a whole list at once); MyStruct.Speed (one named field inside a group — the dot picks the field); MyStruct (a whole group at once). Tip: typing just the name of a whole list or group, with nothing in brackets or after a dot, reads all of it in one shot — the fastest way to read a lot of data. Tip: click the Test Connection button below to get name suggestions as you type."></i>
+    </label>
+    <div style="display:inline-block; width:68%;">
+      <ol id="node-input-variable-container"></ol>
+      <div style="margin-top:6px;">
+        <button type="button" class="red-ui-button red-ui-button-small" id="omron-validate-btn"
+          title="Click to connect to the controller and pull in the full list of available tags. This turns on name suggestions as you type, and marks each tag you have entered with a green check if it exists on the controller or a red X if the name was not found. You must click Deploy first, because this talks to the live controller.">
+          <i class="fa fa-refresh"></i> Test Connection, Load and Validate Published Variables
+        </button>
+        <i class="fa fa-info-circle omron-info" title="What this button does: it connects to your controller and downloads the names of all tags that have been made available to the network (in Sysmac Studio, tags with Network Publish set to Publish Only or Input/Output). Those names then appear as you-type suggestions in the tag boxes, and each tag you have entered gets checked — a green check means it exists on the controller, a red X means the name was not found (usually a typo or a tag that is not published). Note: you must Deploy first, because the check happens against the live, running controller — not the editor."></i>
+        <span id="omron-validate-status" style="margin-left:8px; font-size:12px; color:#888;"></span>
+      </div>
+    </div>
+  </div>
+
+  <div class="omron-section-title">Output</div>
+  <div class="form-row">
+    <label for="node-input-outputShape">
+      <i class="fa fa-sign-out"></i> Shape
+      <i class="fa fa-info-circle omron-info" title="How the readings are packaged and passed to the next block in your flow. (A 'message' is the packet of data that travels along the wires between blocks.) ONE MESSAGE: every tag you read is bundled together into a single message, as a list of name-and-value pairs — best when you want all the readings together, for example to show on a dashboard or save to a log. ONE MESSAGE PER TAG: each tag is sent as its own separate message, with the tag name attached as a label called the 'topic' — best when the next block expects one value at a time, such as a charting block. If you are not sure, leave it on ONE MESSAGE."></i>
+    </label>
+    <select id="node-input-outputShape" style="width:68%;">
+      <option value="object">one message: payload = { name: value }</option>
+      <option value="perTag">one message per tag (topic = name)</option>
+    </select>
+  </div>
+  <div class="form-row">
+    <label for="node-input-varProp">
+      <i class="fa fa-code"></i> Msg override
+      <i class="fa fa-info-circle omron-info" title="ADVANCED — most people can leave this exactly as it is. Normally this block reads the fixed list of tags you typed above. This setting lets a different part of your flow decide, on the fly, which tags to read instead — by including the tag name(s) inside the incoming message. This box just names which field of the incoming message to look in (the default, variables, means it looks at msg.variables). If that field is present when a message arrives, those tags are read; if it is absent, the list above is used as normal. Example use: a dropdown menu on a screen lets an operator choose which tags to read, and this block reads whatever they picked. If none of that applies to you, ignore this box."></i>
+    </label>
+    <input type="text" id="node-input-varProp" style="width:68%;" placeholder="variables">
+  </div>
+  <div class="form-row">
+    <label>&nbsp;</label>
+    <button type="button" class="red-ui-button red-ui-button-small" id="omron-outjson-btn"
+      title="Click to see a preview of the data this block will send out, based on the tags you have added and the Shape you chose above. This is just a helpful preview — it does not read the controller or change anything. It is handy when setting up the blocks that come after this one, so you know what their incoming data will look like.">
+      <i class="fa fa-sign-out"></i> Show output JSON
+    </button>
+    <i class="fa fa-info-circle omron-info" title="Shows an example of the data this block produces, so you can see exactly what the next block will receive. If you click the Test Connection button first, the example uses the real kinds of values your tags hold (whole numbers, true/false, text, lists, groups). If you have not connected yet, it shows generic placeholders like <value> instead. The Copy button copies the example text so you can paste it into another block. This preview is informational only — it does not contact the controller."></i>
+    <div id="omron-outjson" style="display:none; margin-top:8px;"></div>
+  </div>
+
+  <div class="omron-section-title">Trigger</div>
+  <div class="form-row">
+    <label for="node-input-pollMs">
+      <i class="fa fa-clock-o"></i> Repeat
+      <i class="fa fa-info-circle omron-info" title="Makes this block read by itself, repeatedly, on a timer — so you do not need anything wired into its input to make it read. Enter how often to read, in milliseconds: 1000 means once every second, 500 means twice a second, 250 means four times a second. (It will also still read any time a message arrives at its input.) Leave this at 0 to read ONLY when something triggers it. Tip: do not set this faster than you truly need — very small numbers send a flood of requests and can overload the controller. For example, reading 100 tags every 250 ms is comfortable on most controllers."></i>
+    </label>
+    <input type="text" id="node-input-pollMs" style="width:120px;" placeholder="0">
+    <span style="margin-left:6px;">ms (0 = message-driven only)</span>
+  </div>
+  <div class="form-row">
+    <label>&nbsp;</label>
+    <label style="width:auto;">
+      <input type="checkbox" id="node-input-fireOnDeploy" style="width:auto; vertical-align:middle;">
+      Read once shortly after deploy
+      <i class="fa fa-info-circle omron-info" title="When ticked, this block reads its tags one time on its own, about 1.5 seconds after you click the Deploy button (or after Node-RED restarts). This is handy for grabbing an initial value as soon as everything starts up, instead of waiting for the first trigger or timer. Leave it unticked if you do not need a reading at startup. ('Deploy' is the button that saves and starts your flow running.)"></i>
+    </label>
+  </div>
+</script>
+
+<script type="text/html" data-help-name="omron-read">
+  <p>Reads one or more variables (tags) from an Omron NX/NJ controller over EtherNet/IP.</p>
+
+  <h3>Triggering</h3>
+  <p>A read fires when a message arrives. <b>Repeat</b> adds timer-based self-polling, and
+  <b>Read once after deploy</b> fetches an initial value at startup. These can be combined.</p>
+
+  <h3>Variables</h3>
+  <p>One row per tag. Symbolic names support the full address syntax:</p>
+  <ul>
+    <li><code>Counter</code> — a scalar</li>
+    <li><code>MyArray</code> — a whole array · <code>MyArray[3]</code> — one element</li>
+    <li><code>MyStruct</code> — a whole structure · <code>MyStruct.Speed</code> — a member</li>
+    <li><code>MyStruct.History[2]</code> — element of an array inside a structure</li>
+    <li><code>Machine.Axes[2].Position</code> — member of a structure inside an array</li>
+  </ul>
+  <p>Reading a whole array or structure in one row is the fastest way to move a lot of data.
+  Click <b>Connect &amp; validate</b> to load live tag names (autocomplete + ✓/✗ checking).</p>
+
+  <h3>Dynamic variables</h3>
+  <p>Override the configured list per message via the property named in <b>Msg override</b>
+  (default <code>msg.variables</code>): a tag name or an array of names.</p>
+
+  <h3>Outputs</h3>
+  <p><b>Port 1 (result):</b></p>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">object | any</span></dt>
+    <dd>One-message mode: <code>{ "Counter": 42, "Speed": 1500 }</code>. Per-tag mode: the value, with <code>msg.topic</code> = name.</dd>
+    <dt>errors <span class="property-type">object</span></dt>
+    <dd>Present only if some tags in a batch failed: <code>{ name: reason }</code>.</dd>
+  </dl>
+  <p><b>Port 2 (error):</b> emitted on outright failure; reason on <code>msg.error</code>. Also reaches Catch nodes.</p>
+</script>

package/nodes/omron-read.js

@@ -0,0 +1,135 @@
+'use strict';
+/**
+ * omron-read — reads one or more Omron tags.
+ *
+ * Triggers: an incoming message always fires a read. Optionally also self-polls on a timer,
+ * and/or fires once shortly after deploy.
+ *
+ * Variables: configured as a list in the edit panel, overridable per-message via
+ * msg.variables (string or string[]).
+ *
+ * Output: two ports. Port 1 = success, port 2 = error.
+ *   - 'object' shape (default): one message, msg.payload = { name: value, ... }.
+ *     msg.topic = the variable name when exactly one was read. Per-tag failures (when some
+ *     tags exist and others don't) appear on msg.errors = { name: reason }.
+ *   - 'perTag' shape: one message per variable, msg.topic = name, msg.payload = value.
+ */
+const { resolveReadVariables, shapeReadResult, describeError } = require('./common');
+
+module.exports = function (RED) {
+  function OmronReadNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    node.plcConfig = RED.nodes.getNode(config.plc);
+    node.varProp = config.varProp || 'variables';          // msg property for overrides
+    node.outputShape = config.outputShape || 'object';      // 'object' | 'perTag'
+    node.names = (config.variables || []).map(v => (typeof v === 'string' ? v : v.name)).filter(Boolean);
+    node.pollMs = Number(config.pollMs) > 0 ? Number(config.pollMs) : 0;
+    node.fireOnDeploy = !!config.fireOnDeploy;
+
+    let pollTimer = null;
+    let deployTimer = null;
+
+    if (!node.plcConfig) {
+      node.status({ fill: 'red', shape: 'ring', text: 'no PLC config' });
+      return;
+    }
+
+    // Reflect connection state on the status badge when idle.
+    function idleStatus() {
+      if (node.plcConfig.connected) node.status({ fill: 'green', shape: 'dot', text: 'connected' });
+      else node.status({ fill: 'yellow', shape: 'ring', text: 'connecting…' });
+    }
+    node.plcConfig.on('plc-state', idleStatus);
+    idleStatus();
+
+    async function doRead(msg, send, done) {
+      const controller = node.plcConfig.getController();
+      const names = resolveReadVariables(node.names, msg ? msg[node.varProp] : undefined);
+
+      if (names.length === 0) {
+        const err = new Error('No variables to read (none configured and none on the message).');
+        finishError(err, null, msg, send, done);
+        return;
+      }
+
+      node.status({ fill: 'blue', shape: 'dot', text: `reading ${names.length}…` });
+      try {
+        await node.plcConfig.whenReady();
+        // partial:true so per-tag errors come back inline rather than rejecting the whole call.
+        const resultMap = await controller.readVariables(names, { mode: 'auto', partial: true });
+        const shaped = shapeReadResult(resultMap, node.outputShape);
+
+        if (shaped.kind === 'perTag') {
+          for (const item of shaped.items) {
+            const base = msg ? RED.util.cloneMessage(msg) : {};
+            if (item.error) {
+              base.error = describeError(item.error, item.topic);
+              base.topic = item.topic;
+              send([null, base]);
+            } else {
+              base.topic = item.topic;
+              base.payload = item.payload;
+              send([base, null]);
+            }
+          }
+        } else {
+          const item = shaped.items[0];
+          const out = msg ? RED.util.cloneMessage(msg) : {};
+          out.payload = item.payload;
+          if (item.topic !== undefined) out.topic = item.topic;
+          if (item.errors) out.errors = item.errors;
+          send([out, null]);
+        }
+
+        const anyErr = shaped.items.some(i => i.error) ||
+                       (shaped.items[0] && shaped.items[0].errors);
+        if (anyErr) node.status({ fill: 'yellow', shape: 'dot', text: 'read w/ some errors' });
+        else node.status({ fill: 'green', shape: 'dot', text: `read ${names.length} ok` });
+        if (done) done();
+      } catch (err) {
+        finishError(err, names[0], msg, send, done);
+      }
+    }
+
+    function finishError(err, varName, msg, send, done) {
+      const text = describeError(err, varName);
+      node.status({ fill: 'red', shape: 'dot', text: text.slice(0, 32) });
+      const errMsg = msg ? RED.util.cloneMessage(msg) : {};
+      errMsg.error = text;
+      errMsg.payload = null;
+      send([null, errMsg]);
+      if (done) done(err);          // also surfaces to Catch nodes
+      else node.error(text, errMsg);
+    }
+
+    node.on('input', function (msg, send, done) {
+      // Node-RED 1.0+ always provides send/done; guard for older cores just in case.
+      send = send || function (...a) { node.send(...a); };
+      doRead(msg, send, done);
+    });
+
+    // Self-poll: fire reads on a timer with no upstream node.
+    if (node.pollMs > 0) {
+      pollTimer = setInterval(() => {
+        doRead(null, (arr) => node.send(arr), null);
+      }, node.pollMs);
+    }
+
+    // Fire once shortly after deploy (give the connection a moment to come up).
+    if (node.fireOnDeploy) {
+      deployTimer = setTimeout(() => {
+        doRead(null, (arr) => node.send(arr), null);
+      }, 1500);
+    }
+
+    node.on('close', function () {
+      if (pollTimer) clearInterval(pollTimer);
+      if (deployTimer) clearTimeout(deployTimer);
+      node.plcConfig.removeListener('plc-state', idleStatus);
+    });
+  }
+
+  RED.nodes.registerType('omron-read', OmronReadNode);
+};