KMC Commander and Node-RED Application Guide

Introduction

Node-RED may appear in two places in KMC Commander. The Node-RED network protocol (in Network Explorer, under Add Network) is primarily for future use. See Network Protocol (for Specific Preprogrammed Devices) on page 2. This application guide, however, is primarily about the Node-RED add-on. The Node-RED add-on functions in KMC Commander if an additional add-on license has been purchased. Click the Add-ons (cloud) icon ☁️ (on the left, below the Dashboard icon) and click the Node-RED icon to open Node-RED. See Add-On (for Customer Custom Programming) on page 3.

NOTE: If you do not see the Node-RED add-on icon, you do not have the needed extra license. Contact KMC Controls for an additional purchase and installation instructions.

KMC Controls, 19476 Industrial Drive, New Paris, IN 46553 / 877-444-5622 / Fax: 574-831-5252 / www.kmccontrols.com

"Types" of Node-RED with KMC Commander

Network Protocol (for Specific Preprogrammed Devices)

The Node-RED protocol option is for interfacing with local devices (such as for a leak detection kit). For such applications, the Node-RED snap (application package) must also be installed in the local KMC Commander IoT appliance/gateway. If the Node-RED snap has not been preinstalled or automatically installed, the user must install it using PuTTy (or equivalent terminal software) and the SSH (Secure SHell) credentials for that appliance.

NOTE: PuTTY is an open-source terminal emulator. For more information about SSH, see the Configuring SSH Settings topic on KMC Commander Help (or the same topic in the KMC Commander Installation Guide PDF).

To install the Node-RED snap and discover a Node-RED network:

1. Contact KMC Controls for instructions on installing Node-RED on a local KMC Commander appliance/gateway.
2. See the Configuring a Node-RED Network topic on KMC Commander Help (or the same topic in the KMC Commander Installation Guide PDF) for instructions on configuring and discovering a Node-RED network.

Diagram Description: A network diagram shows app.kmccommander.com in the cloud, connected to a KMC Commander IoT Appliance/Gateway, which in turn connects to a Leak Detector or Other Device. A separate diagram illustrates the Node-RED Protocol connecting a Client (Browser) to the KMC Commander IoT Appliance/Gateway.

Add-On (for Customer Custom Programming)

The Node-RED add-on is a license to run Node-RED on a cloud server. Clicking on the Node-RED add-on shortcut redirects to that server. Seeing and using that add-on requires an additional purchased add-on license. Contact KMC Controls about purchasing the license.

Node-RED is a drag-and-drop visual programming tool with a browser-based editor. It uses flow-based programming, which is a programming paradigm that defines applications as networks of “black box” processes. The “black boxes” (nodes or blocks) exchange data across predefined connections by passing messages. Node-RED was originally developed by IBM but is now open source, which has generated many free development resources.

The Node-RED add-on provides a means of expanding and integrating KMC Commander's capabilities. Some Node-RED application examples include:

• Integrating KMC Commander with APIs.
• Connecting KMC Commander data to other devices and databases.
• Creating custom web pages and dashboards.
• Running control code for KMC Commander to command functions within HVAC controllers or other devices.

The Node-RED interface, when properly licensed, is accessible through your browser. You do not need to install any additional software on your computer to use it. The KMC Commander version of Node-RED includes palettes specific to KMC Commander. See Commander and Users Palettes on page 6.

Diagram Description: A system architecture diagram depicts a "KMC Node-RED (Heroku Server)" connected to app.kmccommander.com. This central service connects to a "KMC Commander IoT Appliance/Gateway". A "Client (Browser)" also connects to app.kmccommander.com, accessing the Node-RED Add-On interface.

Starting the Node-RED Add-On

To start using the Node-RED add-on:

1. Click the Add-Ons (cloud) icon ☁️.
2. Click the Node-RED icon (which opens the Node-RED login page in a new browser tab).
3. Enter the login credentials. (If needed, contact KMC Controls for the default Node-RED username and password.)
4. Click Login.

Diagram Description: A screenshot shows the Node-RED login page requiring username and password, with a "Login" button. Another screenshot displays the Node-RED flow editor with various nodes and a URL https://api.kmccommander.com.

Tabs and Deployment

CAUTION: Do NOT delete the JWT (JSON Web Token) Login tab or edit its contents! (If you do, you may not be able to log in again.)

Do NOT delete the Initialize Globals tab and be very careful about editing its contents! (If you do, a variety of functions may stop working.)

The Examples tab provides samples of reusable flows relating to KMC Commander. To find additional examples:

1. Go to the Menu (three lines in upper-right corner) ☰.
2. Select Import, which opens the Import nodes window.
3. Select the Local tab.

Create new flow tabs by clicking the + to the right of the tabs. Double-click the new tab to rename, add a description, and/or delete it.

The Deploy button (near the upper right corner) deploys the nodes from the editor to the server. It has four options (described in the buttons) when clicked.

Diagram Description: A Node-RED interface screenshot highlights the menu icon (☰), the "Import" option leading to an "Import nodes" window with a "Local" tab, and the "Deploy" button with its options: "Full", "Modified Flows", "Modified Nodes", "Restart Flows".

Commander and Users Palettes

To facilitate programming, a library of KMC Commander-specific commands are included in the Commander palette in the left pane. The Users palette has nodes relating to KMC user permissions and logins.

NOTE: Most nodes specific to KMC Commander are recognizable by their up-and-down-triangles icon ▲▼.

NOTE: Additional palettes can be added by clicking the Menu (three lines) button ☰, selecting Manage palette, clicking the Install tab, and searching for key words (e.g., dashboard).

To access the nodes:

1. Drag out a node/block from the palette onto the sheet/window.
2. Double-click the node to enter properties.

NOTE: For more information about a particular node, click the node and look in the info tab.

Commander palette nodes and their functions briefly described include:

• addDeck—adds a deck to the dashboard.
• checkQuery—provides standard query result properties.
• createCard—adds a card to the dashboard.
• createConnection—sets the (message) connection between a device and a network in the database.
• createDevice—sets the payload to create a device in the KMC Commander database.
• createNetwork—sets the payload to create a network in the KMC Commander database.
• createPoint—sets the payload to create a point in the KMC Commander database.
• createVar—creates a variable to add to the KMC Commander database.
• dividePoint—divides a point's current value by either a fixed value or the current value of another object.
• getGlobal—provides access to the global variables loaded from KMC Commander on the Initialize Globals tab.
• getProps—provides point properties from the Query Check node plus an additional filter.
• invertCurVal—inverts the current value of a point (e.g., 1 to 1/2, 10 to 1/10).
• maxPoint—finds the maximum current value of two or more points in the data flow.
• minPoint—finds the minimum current value of two or more points in the data flow.
• nameObjects—sets the payload to a point name on a given device in the Commander database. The node creates templates for point, device, and network in an object called “topic.”
• negateCurVal—negates the current value of a point (e.g., 1 to −1 or 10 to −10).
• roundPoint—rounds the current value of points to the assigned precision (e.g., 12.3456 to 12).
• selectTrendData—provides trend properties from the input point plus an additional date range filter.
• selectTrendTimeRange—creates the time span (date range) to query the API for trend data.
• sumPoints—sums the current value of two or more points in the KMC Commander database.
• syncToClock—Takes an input from an inject node (set for a repeating 1-second interval) and outputs a message synchronized with the real (system clock) time at the selected Sync time interval (1-minute, default).
• tagPoint—adds tags to one or more points in the KMC Commander database.
• unTagPoint—removes tags from one or more points in the KMC Commander database.
• v1Parser—converts zinc into JSON for earlier KMC Commander BX/V1 API.

User palette nodes and their functions include:

• getPage—checks an http GET response from the KMC Commander API to see if the results are complete, and if not, the “next” output is triggered to perform another GET.
• hash8 — generates a bcrypt password hash.
• setUrl—provides authorization for http requests accessing the API. It includes an optional query field for use when sending a query argument to the API and supports variable names for the mustache web template system.
• storeCookie—helps store cookies to user globals.
• userCredentials—sets the username and password for the project.
• v1Login—used for encryption in earlier KMC Commander BX/V1 API.
• verifyJwt—sets the User Id for use in creating user-specific objects.

Diagram Description: A Node-RED interface screenshot shows the left-hand pane with "KMC Commander" and "User" palettes, listing nodes such as addDeck, checkQuery, getPage, and hash8.

Usage Tips

Below are some important tips for using Node-RED with KMC Commander:

• Nodes have only one input (unlike some blocks in KMC's block programming), but outputs from multiple nodes can be attached to the single input of a node.
• An (output) debug node is needed on a string to see the results on the debug tab screen. If results from multiple debug nodes are showing in the screen, hovering over a particular text outlines the relevant node.
• An (input) inject node starts a flow (manually or periodically) and can inject data into the flow.
• A (function) switch node gives you logic capability such as (among others) greater than, is between, contains, and is true.
• The (function) change node is useful for narrowing down information of an object (such as reducing all the properties of an object down to just the current value). A change node also allows you to set values.
• Use a (User) setUrl node when you want to pull a point from the KMC Commander API. Change the Query string to the desired tag. Use AND/OR to narrow down options. The syntax is the same as in Data Explorer (see the Data Explorer topic on KMC Commander Help, or the same section in the KMC Commander Installation Guide PDF).
• The (Commander) getGlobal node gets object information from the Initialize Globals tab so that flows can be streamlined. For example, if you need to write to a setpoint through the API, you can use getGlobal to access the ID and use the ID in the POST to update the value.
• KMC Commander can only provide data at a finite rate so the efficient use of bandwidth should always be considered. For example, don't query all the points in the system on a continuous basis when a limited query will do (e.g., “sensor and temp” to get temperature sensors).

Diagram Description: A screenshot details the properties panel for a Node-RED "inject" node, showing fields for "Name", "Payload", "Topic", and timing configurations.

Node-RED Resources

The Node-RED add-on is meant for advanced KMC Commander users, and instructions for using Node-RED are beyond the scope of this document. For more Node-RED information:

• See the Examples tab for reusable flows relating to KMC Commander.
• Clicking a node/block displays information about it in the info tab on the right side of the screen. Click the Show help (book icon) ? button to see more help information about that node. (Double-clicking the node also opens the edit properties panel.) Click the i button (next to the help tab) ℹ️ to get back to the info tab.
• Click the KMC Commander logo at the upper left of the screen to go to tips at api.kmccommander.com.
• See nodered.org for general information.
• See nodered.org/docs/ for help. See especially the Cookbook for examples that can be copied and then imported into Node-RED from the clipboard.

Diagram Description: A KMC Controls logo is displayed on a computer monitor.

Important Notices

The material in this document is for information purposes only. The contents and the product it describes are subject to change without notice. KMC Controls, Inc. makes no representations or warranties with respect to this document. In no event shall KMC Controls, Inc. be liable for any damages, direct or incidental, arising out of or related to the use of this document.

KMC Controls® and the KMC logo are registered trademarks of KMC Controls. KMC Commander™ is a trademark of KMC Controls. All other products or name brands mentioned are trademarks of their respective companies or organizations.

All rights reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in any form by any means without the written permission of KMC Controls, Inc.

All KMC Commander support documents are available on the KMC Controls website. Type the KMC Commander part number (e.g. CMDR-ADVT-WIFI-BASE) in the Search field. Log in to see all available files.

The information in the KMC Commander Installation Guide PDF is also available in an online format at help.kmccommander.com.

For advanced applications, api.kmccommander.com has information about the KMC Commander application programming interface.

NOTE: Documents, product design, and product specifications are subject to change without notice.

©2022 KMC Controls, Inc.