/
How to use Node-RED client library to interact with onesait Platform?

How to use Node-RED client library to interact with onesait Platform?

Introduction

Node-RED is nowadays a very popular programming tool, allowing developers to create programs visually. From a very wide palette of nodes, developers can create flows by wiring them together. Developers can also create their own nodes to fulfill their needs and then share them with the community via NPM. Developing PoCs using a flow engine like Node-RED is easy and quick.

onesait Platform already provides a flow engine within its Control Panel, with a straightforward connection to the data stored on the platform. This page presents the client library to interact with onesait Platform from a Node-RED instance running in a client device (another system, a Raspberry Pi ...)

Nodes description

The client package has six user nodes featuring different operations over the platform, plus one config node dealing with the connection details. Let's describe each node in detail: 

  •  

    • onesait-platform-insert: this node inserts data in an ontology. The following parameters are required:

    • onesait-platform-delete: this node deletes data from an ontology according to a query, or by RTDB ID. The following parameters are required:

      • Ontology: name of the ontology. To create an ontology, please go to https://lab.onesaitplatform.com/controlpanel/ontologies/list

      • Delete Type: the type may be by query-based or by Id.

      • Query/Id: query or id to be deleted, depending on the chosen type.

      • Query Type: SQL or NATIVE (MongoDB for CloudLab deployment).

    • onesait-platform-query: this node executes a query on an ontology. The following parameters are required:

    • onesait-platform-update: this node updates data in an ontology. The following parameters are required:

      • Ontology: name of the ontology. To create an ontology, please go to https://lab.onesaitplatform.com/controlpanel/ontologies/list

      • Update Type: type, may be by query-based or by Id.

      • Id: instance id to be updated.

      • Query: query; its result will be updated.

      • Query Type: SQL or NATIVE (MongoDB for CloudLab deployment)

    • onesait-platform-leave: this node closes the current session with the platform.

    • onesait-platform-subscribe: this node subscribes to any interaction with the selected ontology. The following parameters are required:

    • onesait-platform-connection-config: configuration nodes are globally scoped by default. This means that the state will be shared between flows. This node represents a shared connection to a remote system. In that instance, the config node is responsible for creating the connection (MQTT) and making it available to the nodes that use the config node. A REST interface is also a possibility to connect to the platform. The following parameters are required to define the connection:

      • IoTClient: name of the digital client.

    •  

      • Instance: name of the instance of the digital client.

      • Token: any token associated to the digital client.

      • Renovate session every: minutes elapsed, after which the connection will be renewed. The default value is 5 minutes

      • Protocol: protocol that will be used in the connection.  REST and  MQTT values can be chosen. Some specific parameters have to be filled for each case:

        • MQTT:

          • IP: IP of the platform server.

          • Port: Port of the MQTT connection to the platform.

          • Enable SSL/TLS security: Enable the check box to select SSL/TLS connection.

          • Certificate: If the previous check is selected, a certificate will be needed.

        • REST:

          • Endpoint: adress of the server where the platform el hosted. If https protocol is user, SSL/TLS sill be activated automatically.

          • Enable SSL/TLS security: If enabled, some extra SSL/TLS configuration will apear. It is not required even if https protocol is used.



Installation process

Firstly, you need to install Node.js from the official Node.js home page. Once installed, you may test your setup by opening a command prompt and running these commands: 

  • node --version

  • npm --version

At this point, Node.js should be installed and the versions would be appearing on the command prompt. The next step is installing Node-RED. To do so, run this command:

  • npm install -g --unsafe-perm node-red

When finished, you should be able to run Node-RED by running the command node-red on your prompt of choice. This version has already a good chunk of usable nodes that you can test at http://localhost:1880

The last step is installing onesait Platform Node-RED client is to run this command:

  • npm install node-red-contrib-onesait-platform

You might also install the client nodes from the Node-RED web interface from the right-hand side command menu→Manage palette, and then look for onesait:

At the end, it is necessary to restart Node-RED, and then the onesait nodes should appear as part of your palette.



Using the nodes from the example

There is an example flow available online to accelerate your learning curve when using this client library. It is available at https://flows.nodered.org/flow/989c8da7c08465f132882f24740c835f 

Once imported, your flow should look like this:

Even though this looks kind of messy, it is a simple flow to showcase all the capabilities from the nodes. This example is working out of the box since it has valid credentials from a demo user created for this example on our CloudLab instance. Let's dive into the several blocks and explaining them in detail:

CONNECTION-CONFIG

For the connection config node, it is embedded in the rest of the nodes as the server configuration property. Here you can see the values for one of the nodes in the example, using a REST interface to communicate with the platform.

QUERY

These two branches are performing an on-demand QUERY over onesait Platform data. All of our nodes have the option to input the node variables either manually or using an input message.