Open Control Architecture

Basic Architecture

Features:

• Real-time global commutation (<0.5s latency) of any payload type between millions of devices
• Open source and licence free for life
• Battle hardened, standard and secure technologies
• Simple to use for plumbers and electricians
• Can connect to anything, physical or web based, and make use of commercial services and APIs
• Implement a standard dictionary structure to enable interoperability between systems

Controls software is written in Node-RED version 2+.

Communications between systems is performed using MQTT.

We have chosen to base the Open Controls Architecture on Node-RED for a number of reasons:

• Open source and free to use at will
• Cross platform, from PCs, to cloud servers to embedded devices, the Raspberry Pi, and many industrial PLCs
• Very stable, having been actively developed for over 10 years with the likes of IBM
• Simple to use with a visual interface that compares to electrical wiring
• Software can be copied and pasted from one system to another, dropped in and wired up
• Infinitely versatile with standard and custom components available from an online library to achieve almost any function or connect to any system
• Complex software can be built in a hurry, dragging components in and wiring up, then refined and packaged into neat and updateable components
• Built on Node.js and JavaScript, possible the world's most active software environment as used on all web pages
• Used by almost everyone - from hobbyists through to mobile phone companies - with considerable community support
• Provides a means to easily implement new and existing technologies and online services, including machine learning, peer-to-peer communications, databases, and encryption

Node-RED version 2 (or higher) is required for the latest active MQTT management.

In addition to the standard Node-RED set of Nodes we make use of the following. These can be easily installed into any instance of Node-RED from the Palette Manager:

• node-red-contrib-heatweb provides a set of nodes to implement the protocols used on this site
• node-red-dashboard provides a live user interface
• node-red-node-email provides email functions

Other Nodes are used, and can be installed as required.

Software works through payloads of data (messages) passing along virtual (and real) wires, from one node to another. Messages have both a payload and a topic.

A node can be:

• a function block within Node-RED (a Node-RED Node)
• an instance of Node-RED (a Controller Node)
• any point in the communications network (e.g. an MQTT Broker)

Each instance of Node-RED has an identifier, stored under global.node

camelCase is used for variable names and topics, where the first letter of additional words are capitalised, and spaces removed.

• Only letters and numbers should ever be used in naming.
• Dashes (-) may be used to create hierarchy as described below
• Underscores ( _ ) can be used at a software level, to add functionality, but not at an operational or user level.
• Spaces, full stops, commas, apostrophes, or any special characters must NEVER be used in naming.

Communications

A standardised 5 level MQTT topic structure is used throughout. network / node / device / group / key.
See https://github.com/heatweb/heat-network

Systems run a local Mosquitto MQTT broker to distribute data both internally and to enable external subscriptions.

Additional local MQTT brokers can be established through Docker Containers.

The external network identifier, used for all data published to external MQTT brokers, is stored under global.networkId
This must be unique (long) and without spaces.

Data from within a node or from connected devices is assigned a local network identifier of "local" (stored under global.localNetworkId) so that the node's external network identifier can be changed without affecting internal software. Separate internal and external identifiers also allows for separate message rates, where local traffic can be high speed. Node-RED is used to apply Reporting By Exception rules, to limit traffic to significant values (e.g. 0.25C), and save bandwidth.

In the real world, devices and networks are nested - a building may have a network ID, but this may be fed from a plantroom, also with its own identity. To accommodate nested networks, a dash is used to prefix topics (and hence the network ID) and thereby maintain a five level topic structure - important for wildcard subscriptions to work..

myNetwork/plantroomNode/plantroomNode/settings/title = "Main Plantroom Controller"

block1/blk1node/blk1node/settings/title = "Block 1 Controller"  !!! DO NOT USE COMMON NETWORK IDs

Adding a prefix to sub-networks ensures networks remain unique on a higher level server. E.g. There may be two unconnected networks with sub-networks called "block1".

myNetwork-block1/blk1node/blk1node/settings/title = "Block 1 Controller"

anotherNetwork-block1/blk1node/blk1node/settings/title = "Block 1 Controller"

Where managing multiple networks, it is advised to use long and non-descriptive unique identities. When creating new configurations a random 8-16 character ID should be generated.

e.g. Ea5lQXfF2tmBlzYk

Nodes should also be given unique identities. Nodes Id's can be shorter as they only need to be unique within a network, rather than globally (in the whole world).

e.g. jxt15Ewk

The titles of networks, as well as nodes, can be saved and found under its device setting.

Ea5lQXfF2tmBlzYk/jxt15Ewk/network/settings/title = "My Heat Network"

Ea5lQXfF2tmBlzYk/jxt15Ewk/jxt15Ewk/settings/title = "Main Plantroom Controller"

And to simplify for sub-nodes it is possible to use a node's id as the node's network identifier.

a5lQXfF2tmBlzYk-fg4jS8s7/fg4jS8s7/network/settings/title = "Block 1 Heat Network"

a5lQXfF2tmBlzYk-fg4jS8s7/fg4jS8s7/fg4jS8s7/settings/title = "Block 1 Controller"

a5lQXfF2tmBlzYk-fg4jS8s7-nnf555dE/nnf555dE/nnf555dE/settings/title = "Block 1, Flat 17 Controller"

Handling Data

Within Node-RED a Message Handler Node is used to handle data generated locally.

• The Node has two outputs - one for local traffic, and one for external traffic.
• Report by exception rules are applied to external traffic.
• The Node formats topics to the five level standard, adding group and device if missing.
• The Node stores data into global.readings, along with any attributes within the incoming message, as well as timestamps.
• The Node stores historical data into global.readingsHistory, along with timestamps, removing repeat values.
• New attributes are read from incoming messages, and existing attributes added to outgoing traffic.
• Handles the set data group, altering settings and saving to disk.
• Handles the json/sync topic, updating stored device readings and attributes to incoming sync data.
• Handles the cmd/sync topic, sending stored device readings and attributes as JSON.
• Handles the cmd/request topic, sending stored data as per requests.
• Additional routing can be performed within Node-RED, including selection of retained vs unretained routes.

Handler Nodes use a configuration node to store setup information including network and node identities.

Routing Data

Where a number of nodes sit on a Local Area Network (LAN) it is common to use a central local MQTT broker.

Traffic can be routed to a Cloud MQTT broker by the use of MQTT Bridges. These run on an MQTT broker, and can re-publish messages filtered by topic (networkId) to another broker. Bridges are managed outside of Node-RED.

Additional Report By Exception rules can be applied inline.

On larger networks where data is shared between local nodes, Reporting By Exception can be centrally managed using a Node-RED instance, along with any additional MQTT broker functions such as providing backup routes.

Cloud based instances of Node-RED, as used on this Wiki, are often used to pull together data from various MQTT brokers into one place.

Complex Architecture

MQTT allows granular sharing of data and the scaling of complex network topologies.

Security and Access Control

Each MQTT Broker runs its own security settings, with a list of users and associated topic permissions (read & write). Additional bridges enables data between MQTT brokers to be managed, and allows common user/password lists to be utilised. Password lists are based on hashed passwords (one way encryption) so that original passwords are never known or shared.

Devices within a local network (LAN) can be protected using standard firewall rules with port forwarding used to expose MQTT services as required. Pulling all data and communications through MQTT allows all other external routes to be more easily locked down, with only secure MQTT ports to the LAN Broker exposed online. In this way external access is completely ruled by the same MQTT users and password structure.

User access rules are stored in an ACL File, with the following powers:

• Access rules can be applied to read and write permissions separately.
• Wildcards can be applied to rules, on any of the topic levels. This allows, for example, a particular user to be given access to myNetwork/+/+/meter/# providing access to meter data from myNetwork, all nodes and devices.
• General rules can be setup for all users, providing global data.
• Rules can include special fields, such as the MQTT client id or username. This allows general rules to be setup that, for example, provide nodes with access to their own data.

Data Groups

The topic group is used to define the type of data. Values include:

• dat (operational data)
• stat (statistics and status)
• settings (persistent settings)
• cmd (a command)
• set (command to change a setting)
• system (software and networking)
• meter (meter data)
• alarm (alarms and warnings)
• ana (analogue readings)
• json (JSON formatted data)
• modbus (Modbus serial data)
• design (preloaded design data)

Topic groups that are manufacturer or organisation specific, should use an all CAPITAL group identifier. This should represent the organisation, be unique, and may include dashes to create multiple groups under a single organisation.

• TIL (Thermal Integration Ltd.)
• PCDB (SAP Product Characteristics Database)
• BENCHMARK (Benchmark information)

Manufacturer specific data groups can be used by systems to load a manufacturer's default data attributes, enabling the protocol to be extended as required.

They allow, for example, multiple organisations to publish the same data on a device (such as a heat network) without collisions.

Data Attributes

Attributes (metadata) provide additional information about data, such as units and a description. They include:

• units (units for data)
• title (short description)
• points (maximum data points to store in history)
• deadband (the deadband used for external communications)
• timestamp (unix time data is generated or handled)
• changed (unix time data last changed)
• attributes (an object containing custom attributes)

Attributes are generally loaded from a central index (GitHub or LAN hosted), providing additional information such as units and descriptions. This is to avoid the need to locally describe data, and to assist in compatibility. Custom attributes may be added inline to messages and will override defaults. See https://raw.githubusercontent.com/heatweb/heat-network/master/devices/default_topics.json

Loaded attributes are saved in a global Node-RED object,and will be added to messages as they are handled, and stored into readings alongside the value (payload). They are however not transmitted through MQTT - only topics and payloads are transmitted by default. As such it is important to try and use standard topics where possible, selecting a topic by its standard attributes.

The flow below shows a message object, with attributes, before and after going through an MQTT connector.

Note that only the topic and payload survive transit.

Note that dat/tOut is a standard topic, so the attributes (units and title) would be added back in by a Handler Node.

Attributes can be transmitted through MQTT in one of two ways:

• A special command cmd/sync can be sent to a nodes message handler asking it to publish a full JSON object for a device (or devices), including all data groups, values, and attributes. The command payload is an MQTT topic including wildcards, e.g. local/# (all), or +/+/boiler1/#. The reply for each device that matches is sent on the corresponding topic, e.g. myNetwork/node123/boiler1/json/sync and can be handled by a receiving system.
• Packaging a message as a JSON object, value and attributes, and send this instead of just the value. A receiving system can work out the payload is JSON and handle appropriately.

Attributes take up a lot more bandwidth in traffic, and as they are generally static or default values, only custom attributes need to be transmitted, and only at startup or on request.

Node-RED Global Objects

Within Node-RED, data and attributes are stored within the global.readings object.

Data stored in global objects is held in processor memory and not on disk.

The current data can be viewed within Node-RED in the data explorer.

Data within the readings object is nested according to the topic (excluding the node as more than one node may publish data on a device).
network -> device -> group -> key

e.g. a message with a topic myNetwork/node123/myDevice/dat/outputTemperature  would be stored in (global).readings.myNetwork.myDevice.dat.outputTemperature.value

Internally, message topics can be truncated and the network and node will be filled in. The data group will be assumed to be "dat" if not supplied, representing operational data.

e.g. a message with a topic setpoint  would be stored in (global).readings.local.myNode.dat.setpoint.value

The following code could be used to read data and its attributes for output.

 var localNetworkId = global.get("localNetworkId");
 var node = global.get("node");

 var reading = global.get("readings." + localNetworkId + "." + node + ".dat.outputTemperature");

 var output = "The value of " + reading.title + " is " + reading.value + reading.units;  
 // "The value of Output Temperature is 35°C

Historic data is saved into the global.readingsHistory object, in the same structure as global.readings, but containing an array of timestamped values.

Persistent settings for a node (or application) are held on disk and in the global.settings object. This is for local operational settings.

Settings have a type, may have maximum and minimum values, units and a title. Certain types require additional fields such as select from a list settings.

Standard settings include:

• title (system title / name)
• io (system input/output configuration in JSON format)
• postCode (UK Postal Code)
• latLong (comma separated latitude and longitude)
• email (comma separated list of email addresses for alarms and reports)

The snapshot below shows a variety of setting types including numeric/text values, html, or JSON objects and arrays.

Persistent settings for local devices are held on disk and in the global.deviceSettings object, and are specific to a device (or node).