Node-RED Agent for the MindConnect API
This node enables the Node-RED users to upload timeseries, files and events to MindSphere. This project has started as a community effort at Siemens AG and is now available for general use.
Installing the node
# change to your ~./node-red/ foldercd ~/.node-red/npm install @mindconnect/node-red-contrib-mindconnect
Node-RED - Manage Palette Installation
You can install the node also via the Manage palette feature in the Node-RED administration UI.
- install to the .node-red folder if you have installed node-red globally
- install to the userDir directory if you have custom userDir
- make sure that your nodejs version is relatively current
How to use the Node-RED node
Step 1: Create (at least) one asset, agent, configuration and mappings
- Create an asset in Asset Manager for your data
- Create an agent of the type MindConnectLib [core.mclib] and store the agent.
- Create a new data configuration
- Create mappings to your asset.
Step 2: Get the initial agent configuration from Mindsphere Asset Manager
You can choose between:
- RSA_3072 public/private key pair (3072bit) for enhanced security which requires more computing power on the devices and
- SHARED_SECRET shared key (256bit) for lightweight devices.
If you want to use RSA_3072 you will have to create a 3072bit key for your device, eg. with openssl:
openssl genrsa -out private.key 3072
There is no additional configuration required for SHARED_SECRET security profile.
Step 3: Copy the agent configuration (and if necessary the private key to the node)
Step 4: Create and deploy the flow
Send data points
The node requires json objects as input in following format (e.g. from a function node)
const values =dataPointId: "1000000000" qualityCode: "1" value: "42"dataPointId: "1000000001" qualityCode: "1" value: "33.7"dataPointId: "1000000003" qualityCode: "1" value: "45.76";msg_time = ;msgpayload = values;return msg;
The node will validate if the data is valid for your agent configuration. his feature can be switched off in the settings but it is not recommended to do so.
Send data points in bulk
The node requires json objects as input in following format (e.g. from a function node if you want to use bulk upload)
const values =timestamp: "2018-11-09T07:46:36.699Z"values:dataPointId: "1000000000" qualityCode: "1" value: "42"dataPointId: "1000000001" qualityCode: "1" value: "33.7"dataPointId: "1000000003" qualityCode: "1" value: "45.76"timestamp: "2018-11-08T07:46:36.699Z"values:dataPointId: "1000000000" qualityCode: "1" value: "12"dataPointId: "1000000001" qualityCode: "1" value: "13.7"dataPointId: "1000000003" qualityCode: "1" value: "15.76";msgpayload = values;return msg;
Note: All MindSphere timestamps must be in the ISO format (use
The node requires json objects as input in following format (e.g. from a function node). You can send an event to any asset you have access to in your tenant. Just use the asset id in the entityid.
msgpayload =entityId: "d72262e71ea0470eb9f880176b888938" // optional, use assetid if you want to send event somewhere else :)sourceType: "Agent"sourceId: "application"source: "Meowz"severity: 30 // 0-99 : 20:error, 30:warning, 40: informationdescription: "Event sent at " +timestamp:additionalproperty1: "123"additionalproperty2: "456";return msg;
If you are using the custom events instead of MindSphere Standard Events please include the following switch in the message.
The node requires json objects as input in following format (e.g. from a function node). You can upload file to any asset you have access to in your tenant. Just use the asset id in the entityid.
msgpayload =entityId: "d72262e71ea0470eb9f880176b888938" //optional (per default files are uploaded to the agent)fileName: "digitaltwin.png" // you can also pass an instance of a BufferfileType: "image/png" //optional, it is automatically determined if there is no fileType specifiedfilePath: "images/digitaltwin.png" // required if you are using buffer instead of the file namedescription: "testfile";return msg;
If the experimental chunking feature is on, the files which are larger than 8MB will be uploaded in 8 MB Chunks.
Error handling in the flows
The node can be configured to retry all mindsphere operations (1-10 times, with delay of time * 300ms before the next try) If you need more complex flows, the node also returns the
msg_mindsphereStatus; // OK on success othervise errormsg_error; // The timestamped error message
properties which can be used to create more complex flows. (e.g. in the flow below, the unrecoverable errors are written in error.log file and the failed data is stored in backupdata.log file)
JWT Token Generation for SouthBound APIs
The node can be used to generate authentication tokens which you can use to call your own custom southbound APIs. The msg.headers will have a Mindsphere Authorization JWT.
if you just want to get the token without sending any data to MindSphere
Treat tokens as you would any other credentials.
MindConnect Node-RED playground provides following demo flows importing following data points to MindSphere
- Batched MQTT Data
- OPC-UA Data
- Real Weather Data to MindSphere
- Simulated Water Pump Data
- Custom SouthBound API Calls
The simulated water pump data can be inspected at
This application can be used without mindsphere credentials.
- username: firstname.lastname@example.org
- password: Siemens123!
This data is also used as an example for the KPI-Calculation and Trend prediction with help of MindSphere APIs. https://github.com/mindsphere/analytics-examples
If you have problems with your agent:
- Stop the agent.
- Move or delete the content of the .mc folder (the json files with configuration and authentication settings).
- Offboard the agent.
- Create new settings for the mindconnect library.
- copy the new settings to the node.
Reseting the agent settings from version 3.7.0
Since version 3.7.0. it is possible to delete the content of the .mc/agentconfig.json file and the agent settings directly from the node.
Press on the "delete local configuration" :wastebucket: button on the node, confirm the dialog and redeploy the node.
If you are having problems, it is a good idea to restart the Node-RED runtime completely.
Diagnostic in MindSphere
If the data is not arriving in your configured asset you should take a look if the data is beeing dropped in MindSphere because of a misconfiguration. The agent diagnostic button will lead you directly to the agent diagnostic application in the MindSphere.
Generating the documentation
You can always generate the current HTML documentation by running the command below.
#this generates a docs/ folder the with full documentation of the library.npm run doc
Set the http_proxy or HTTP_PROXY environment variable if you need to connect via proxy.
# set http proxy environment variable if you are using e.g. fiddler on the localhost.export HTTP_PROXY=http://localhost:8888
How to setup development environment
# create a directory ../devnodescd ..mkdir devnodescd devnodes# this registers your development directory with node rednpm link ../node-red-contrib-mindconnect# after that in you can start developing withcd ../node-red-contrib-mindconnectnpm run start-dev# your node red flows will be stored in the ../devnodes directory
This project has been released under an Open Source license. The release may include and/or use APIs to Siemens’ or third parties’ products or services. In no event shall the project’s Open Source license grant any rights in or to these APIs, products or services that would alter, expand, be inconsistent with, or supersede any terms of separate license agreements applicable to those APIs. “API” means application programming interfaces and their specifications and implementing code that allows other software to communicate with or call on Siemens’ or third parties’ products or services and may be made available through Siemens’ or third parties’ products, documentations or otherwise.