node-red-contrib-tag-engine

Tag Engine Node for Node-RED

The Tag Engine Node for Node-RED is a set of nodes that allow seamless integration of the Tag Engine library into Node-RED flows. These nodes enable users to interact with tags and tag groups directly within Node-RED, facilitating the management of tag values and the emission of events to subscribers.

Introduction

The Tag Engine Node for Node-RED provides two custom node types: cx_tags_in and cx_value_emitter. These nodes allow users to interface with tag groups, set tag values, and emit events based on tag changes directly within Node-RED.

Node Types

cx_tags_in

The cx_tags_in node allows users to set tag values programmatically within Node-RED flows. It receives input messages containing tag values and updates the corresponding tags in the Tag Engine. Users can configure this node to handle individual tag updates or batch updates for multiple tags simultaneously.

cx_value_emitter

The cx_value_emitter node emits tag values as output messages within Node-RED flows. Users can configure this node to emit tag values on startup, in response to input messages, or based on specific conditions. This node is useful for integrating tag values into downstream processing logic within Node-RED.

Installation

To install the Tag Engine Node for Node-RED, follow these steps:

1. Ensure you have Node-RED installed and running.

2. Install the tag-engine library using npm:

npm install cx-tag-engine

3. Install the Tag Engine Node for Node-RED using npm:

npm install node-red-contrib-tag-engine

Usage

After installing the Tag Engine Node for Node-RED, you can use the cx_tags_in and cx_value_emitter nodes like any other Node-RED nodes. Simply drag and drop them onto your Node-RED flow canvas and configure their properties as needed.

Properties

cx_tags_in Node:

• Group: The name of the tag group to which the tag belongs.
• Tags Batch: If checked, input of the cx_tags_in should be a map which mapping tag names to their values.
• Tag Name: The name of the tag to be updated or emitted.
• Force Emit: If checked, the cx_tags_in node will emit an event even if the tag value is not changed.
• Flush Time: The time interval (in milliseconds) at which the tag should save to database. Value will only be kept in memory if this flush time is set to 0.

cx_value_emitter Node:

• Emit On Start: If checked, the cx_value_emitter node will emit tag values on startup.
• Emit All Changes in Group: If checked, the cx_value_emitter node will emit all tag values in the specified group when any tag value changes.
• Group Payload: If checked, the output message will contain the group name in the payload.
• Tag List:
  • Prevent Emit on Change: If checked, the cx_value_emitter node will not emit an event when the tag value changes but the output will contain this tag's value if other tag value changes.

Input of cx_tags_in Node

// single tag
payload: number | boolean | string

// multiple tags if Tags Batch is checked
payload: {
  tagName1: number | boolean | string,
  tagName2: number | boolean | string
}

// Additional data can be send in metadata which will be used by the backend, but this will not be saved in database
{
    metadata: {
        // other data
    },
    payload: number | string | boolean | object
}

Output of cx_value_emitter Node

// single tag
{
    payload: number | string | boolean | object
}

// multiple tags
{
    payload: {
        tagName1: number | string | boolean | object | null
        tagName2: number | string | boolean | object | null
    }
}

// grouped payload
{
    payload: {
       groupName1: {
           tagName1: number | string | boolean | object | null
           tagName2: number | string | boolean | object | null
       },
       groupName2: {
           tagName3: number | string | boolean | object | null
         tagName4: number | string | boolean | object | null
       }
    }
}

Environment Variable

Tag Engine supports the utilization of environment variables within group names and tag names. This feature proves particularly beneficial in subflows. For instance, if you've configured an environment variable named index within the properties of a subflow, you can employ ${index} within the group name or tag name to dynamically reference its value.

Util

In NodeRED function node, you can use the following code to get the tag or its value.

const value = RED.util.cxGetTagValue(groupName, tagName)
const tag = RED.util.cxGetTag(groupName, tagName)