Generic Adapter - The Node-red case

Generic Adapter – The Node-red case

March 10, 2022

As we presented in the blog entry dedicated to AURORAL Adapters, it is necessary to provide a piece of software to connect smart hubs or infrastructures of sensors with the AURORAL software.

To minimise the effort, the bAvenir team wants to provide a framework to quickly develop adapters and where lots of support and automations can get a heavy load out of the way. For this purpose Node-red environment has been chosen and added as an official extension of the AURORAL Node, that can be downloaded and install at the same time as the Node.

The framework: Node-RED

Node-RED is an open source programming framework, which is accesible through browser editor an enable users with little or none programming experience to create applications. It can be used also for connecting things to AURORAL platform, because it has wide list of supporting platforms and protocols. For simplifying somunication with Auroral agent we developed a plugin for Node-RED. It can be installed using Node-RED built in Palette manager, but if you install Node-RED using our AURORAL Node cli, it will be included.

Registering first thing and publishing property

After installing and running the AURORAL Node (Selecting the Node-RED extension), you will be able to access the Node-RED dashboard. Visit http://localhost:1880 to access the Node-RED dashboard.

Node-RED is on first startup empty and you need to setup a connection to Auroral agent.

Look for Auroral section in left view, drag auroralDevice and place it to page. Now we are going to create new device and register it to Auroral.

Empty Node-RED

Double click on placed device, this will open following view:

Device edit dialog - empty

As you can see we do not have Agent connection, so open Agent connector settings with pencil button. Connection to Agent is auroral-agent:4000. Other settings do not need to be changed.

Agent connection dialog

Next hit done, which will take you back to device editor. As you can see agent connection is now set up, and you can fill other settings.

You need to provide a valid Thing Description and specify wether you plan to use your Device for listening to events or read properties from remote devices.

Device edit dialog

When everything is configured properly, you can confirm with Done. There will be blue dot in the corner of device, which signalise that you need to deploy changes. After you deploy, node will inform you about registration status.
When node statuse is TD mismatch, you need to open node's properties and use Get TD or Upload TD buttons to fix mismatch.
If status of device is Registered – not enabled, please check that you did not forget to enable device in the platform. After enabling you need to redeploy flow to detect changes.

To be able to provide data using this device, you need to connect the 'properties' output of the device to your custom flow to read data from your infrastructure (this flow needs to end with a auroralResponse block). Your custom flow needs to do the following things:

Start with the output properties of your device block. It works as a trigger, every time some other devices requests to read your properties, that output will initiate your flow passing the information needed to identify the request inside the msg object (msg is the standard data object passed in Node-red).

{
"_auroralReqId": "id needed to process the request",
"pid": "unique property identificator",
"oid": "unique object identificator",
"adapterId": "unique identificato in your infrastructure"
}

The intermediate blocks depend on your infrastructure, they must read data from your real sensors or data sources and transform the payload into JSON-LD (Standard AURORAL data exchange format).
Finally you need to pass this JSON-LD within msg.payload to the Response block. You should keep also _auroralReqId in the msg object. It is also possible to add msg.statusCode to the msg object, default value will be 200.

An example with static data can be seen below: TestDevice flow

For this device was used this Thing Description:

{
  "title": "Sensor1",
  "@context": "https://www.w3.org/2019/wot/td/v1",
  "@type": [
    "Ontology:DeviceType"
  ],
  "securityDefinitions": {
    "nosec_sc": {
      "scheme": "nosec"
    }
  },
  "description": "Sensor example for the node-red adapter",
  "properties": {
    "temp": {
      "@type": "Ontology:PropertyType",
      "description": "Retrieve temperature of my device",
      "forms": [
        {
          "href": "http://localhost:1250/api/property/000-111-222/temp",
          "op": "readproperty"
        }
      ],
      "title": "temp",
      "type": "number"
    },
    "status": {
      "@type": "Ontology:PropertyType",
      "description": "Retrieve status of the device",
      "forms": [
        {
          "href": "http://localhost:1250/api/property/000-111-222/status",
          "op": "readproperty"
        }
      ],
      "title": "status",
      "type": "string"
    }
  },
  "security": "nosec_sc"
}

When device is successfully deployed, you are able to view oid in its properties tab (in case you need it for interaction)

TestDevice flow

Do not forget to enable device in auroral NM (https://auroral.dev.bavenir.eu/nm), otherwise you will receive error.

Publishing event

Steps to create Auroral device which is ment to publish event are similar as in first case. Only difference is Thing Description, which need to contain events:

{
  "@context": "https://www.w3.org/2019/wot/td/v1",
  "@type": "Ontology:DeviceType",
  "title": "EventSource",
  "description": "Sensor example for the node-red adapter",
  "securityDefinitions": {
    "nosec_sc": {
      "scheme": "nosec"
    }
  },
  "security": "nosec_sc",
  "events": {
    "alert": {
      "title": "alert",
      "@type": "Ontology:PropertyType",
      "description": "Notifications that are pushed to AURORAL from my sensor",
      "forms": [
        {
          "op": [
            "subscribeevent"
          ],
          "href": "http://localhost:1250/api/event/000-111-222/alert"
        }
      ]
    }
  }
}

As you can see, when you register device with events attribute, Auroral device representation in Node-RED now has input, which is used to publish events.

TestDevice flow – When sending event, messege needs to contain these attributes: – msg.type = 'event' – msg.eid = 'alert' – msg.payload = data sent through event

Subscribing to event

Subscribing to event is possible on every device, it does not need any special attributes in Thing Description. In this case we will use Thing Description without parameters and events:

{
  "@context": "https://www.w3.org/2019/wot/td/v1",
  "@type": "Ontology:DeviceType",
  "title": "EventSource",
  "description": "Sensor example for the node-red adapter",
  "securityDefinitions": {
    "nosec_sc": {
      "scheme": "nosec"
    }
  },
  "security": "nosec_sc"
}

Event subscription is defined in Device properties, with checkbox called Allow event subscription

Event subscription location – When subscription is enabled, there is option to specify array of oid + eid. It needs to be in strict format. It's example can be seen in next picture. Event subscription detail

When subscribing is enabled, you can connect your event handling part of the code to output called Subscribed events. In message are attributes msg.oid and msg.eid, to determine source of event ( in case when item is subscribing to more than one event)

Retrieving property from other device

To retrieve data from Auroral device you need to register and activate some device, which will send required requests (these step is the same as in previous parts). In this example we will again use Thing Description without properties and events (to simplify things)
Thing Description:

{
  "@context": "https://www.w3.org/2019/wot/td/v1",
  "@type": "Ontology:DeviceType",
  "title": "EventSource",
  "description": "Sensor example for the node-red adapter",
  "securityDefinitions": {
    "nosec_sc": {
      "scheme": "nosec"
    }
  },
  "security": "nosec_sc"
}

Next you need to enable Allow getProperty checkbox, which will enable 'property' input in device. )
Here is again example flow for getting property. You need to use for example switch node to provide these attributes to input message:
- msg.type = 'property'
- msg.oid = '111-222-333'
- msg.pid = 'temperature'

Flow - Subscribing to event

Note: It is also possible to send a JSON body with information for updating if the remote device supports that operation. Just add the body as msg.payload = { ... }

Getting registrations

There is another node, which is used for retrieving registered devices under your agent. It does not require any special parameters on input and outputs array of registered devices (with some other attributes)

Flow - Getting registered items

Message containing one registration:

{
  "payload": [
    {
      "type": "Device",
      "adapterId": "d4t34fre",
      "name": "Sensor1",
      "privacy": "Private",
      "properties": [
        "temp",
        "status"
      ],
      "events": [
        "alert"
      ],
      "oid": "54d846cd-6318-4bc5-a82f-bff105c68694"
    }
  ]
}

Brought to you by the AURORAL community, keep posted! 💪