Getting sensor data via API using Node Assistant

In this tutorial, we will query the Openweather API to get the external temperature for our building location, bring this into Twinview, and place it on the project dashboard.

Step 1 - Review the API Documentation

We first need to check and confirm that the API can provide the data we need as well as the following understanding:

• The Datatype what is returned for the 'temperature' attribute.
• What info do we need to provide the API so that it can return the temperature for our location
• How we Authenticate with the API
• Any rate limits or Poll limits

We can review the documentation here:

https://openweathermap.org/current

We can see that the API uses basic authentication, and all we need to do is pass our API key {API key) into the URL as a parameter along with the Longitude {Lon} and Latitude{Lat} of our building,

https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={API key}

We need to update the URL above, placing the {Lon} and {Lat} placeholders with our actual building location's Longitude and Latitude values. You can use a website like https://www.latlong.net to get this.

We must also replace the {API Key} placeholder with our OpenWeatherMap API key. To do this, we must log into OpenWeatherMap and go to the 'My API keys' page. You can access this here:

https://home.openweathermap.org/api_keys

Once you have replaced all 3 placeholders in the URL, your new URL should look like the one below (your API Key and Lon Lat values will be different from those shown).

https://api.openweathermap.org/data/2.5/weather?lat=55.007790&lon=-1.590460&appid=4cytopa9eac79a8r5e31ef21a75aab567a

Step 2 - Testing the Endpoint with Postman

Before we create the IOT Data Stream in Twinview, testing the endpoint we have just created using a free tool like Postman is good practice. Postman is the industry standard tool for testing and playing around with APIs.

In simple terms, we will use Postman to make a HTTP GET call to the API URL endpoint and view the response.

Step 2.3 - Change the HTTP method to GET

We must ensure that the HTTP request (on the left side of the URL) is GET.

If the request was successful, we should see the weather information in the body section. The data object that is returned is called the 'payload'. The data is structured in a standard schema called JSON.

We can also see that the server sent a 200 response when we made the web request. This means that the request was 'Successful, and we can now create the device in Twinview.

Step 3 - Create an IOT Data Stream Device in Twinview

To add a new IOT Data Stream in Twinview, we must first:

1. Create a new IOT integration Interface
2. Add an IOT Data Stream to the interface.
3. Create a device security group, add the newly created IOT Data Stream to it, and then give ourselves permission to access the Device security group.

Step 3.1 - Create a new IOT Integration Interface

When in the project, click on IOT Integrations in the left-hand main menu. If you don't see this menu then your user role does not have permission to access IOT integrations, or your Twinview subscription does not include the IOT and Analytics packages,

In the IOT Integrations modal, click 'Add' and give your IOT Integration a name, such as 'External API Services.' We must also select a Reference, which should be set to Twinview Direct Integration.

Click Save, and a new field called 'Subdomain' will appear. Enter "Ingestion" into this interface, then click Save again.

Step 3.2 - Create a new IOT Data Stream Device

Now that we have created our 'IOT Integration Interface,' we can add the IOT Data Streams to the integration interface. Each IOT Data Stream is in a single data point, e.g. 'Temperature, Humidity, CO2, etc'.

When in the project, click the 'IOT Integrations' in the left-hand side menu, and when the modal opens, you should see the IOT interface we created in step 3.1. Click 'Devices' to show all 'IOT Data Stream' devices set up on the interface. At the moment, we don't have any, so we must create one by clicking the 'Add'' button.

Give your IOT Data Stream Device a name and make sure the 'Type' is set to 'Sensor', then click 'Save'.

The IOT Data Stream Device will be created, and a new modal will appear that allows you to specify its details. For this training exercise, the only fields we need to check are the 'Data Type' and the 'Suffix' fields.

We can review the Openweather API to find the Data Type and, optionally, any Suffix we may want to add.

https://openweathermap.org/current

We can see from the API document that the Temperature Datatype the API will return is a Numeric value, so we must ensure that we set the 'Data Type' to 'Number' (See 1 below).

The documentation also shows that the Temperature value was returned in 'Kelvin', so we can add the symbol 'K' in the optional suffix field (See 2 Below).

You will also notice that the Edit Device modal shows the 'Endpoint' URL and the request type POST. You will also see that Twinview shows an example payload structure. We will need this information in the next few steps. However, we can access this information anytime we want from the IOT Data Stream Devices list, so for now, we can click 'Save' to create our IOT Data Stream Device.

Even though we have just added a new IOT Data Stream Device successfully if we tried to add the data stream to a dashboard widget the device would not show in the list when we try do so, this is because when you create a new IOT Data Stream Device it does not belong to any security groups.

This behaviour is by design, such as making the device accessible before it has been applied to a security group or adding it automatically to an existing security group, meaning everyone would have access to the IOT Data Stream device.

To create a new security group while in the project, go to the 'Settings ', which is accessible from the main left-hand menu.

In the Setting dialogue, click the 'Device Group' tab and then click 'Add' to create a new Device Group.

Name your device group and click 'Save' to create the Device Group. Once the Group has been created, click the 'View' button to open the device group.

On the Device group window, we first need to add the IOT Data Stream Device we created earlier to our new 'Device Group'. To do this, we click on the 'Devices' tab and then click the 'Use' bottom button against the IOT Data Stream Device we created earlier.

We have successfully assigned the IOT Data Stream Device to the Device Group. Next, we need to assign ourselves to the Device Group so that the IOT Data Stream Device will be available for us to use on widgets, dashboarding and reporting. To do this, click on the 'Users' tab and click 'Use' on your user and any other users you want to be able to access this IOT Data Stream Device.

Now that you have successfully created and added the IOT Data Stream Device to a device group, the next step is to start publishing data to the Data Stream from the Openweather API.

The issue is that the Twinview Ingestion service wants us to POST data to it (as shown above), and the open weather API wants us to make a GET Request to get the data. What we need is some middleware service to do the following

•  On a set heartbeat/frequency:
  • GET the data from the Openweather API.
  • Transform the data and extract the value we need.
  • Format the results into the JSON object required by Twinview.
  • POST this data to the Twinview Ingestion service.

This is where the Twinview Node Assistant visual scripting interface can help. Node Assistant runs on Twinview Physical Gateways and Twinview virtual (cloud-hosted) gateways. Because we are getting the IOT data from a web API (Openweather) and not a local network, a physical gateway is not needed, and a virtual gateway would work in this scenario.

Step 4.1. - Load up Node Assistant and Login

If your Twinview subscription included IOT Analytics, you would have been assigned a Node Assistant device login.

Navigate to your gateway URL https://{YOUR_GATEWAY_URL}, and you should see a login screen (as below). Enter your username and password as provided by Twinview., then click 'Login'.

Step 4.2. - Once logged in, we first create a new flow

Once you are logged in, you should add a new flow by clicking on the "+" to the far right of the flow tabs.

A new tab will be created once the "+" is clicked. Double-click this new tab, and a nodal will slide from the right. Give the tab a name by completing the Name field and then clicking 'Done'.

We now have a clean canvas on which to create our flow. We are going to replicate the HTTP GET request we made in step 2 of this article, but instead of using Postman software, we are going to create a flow in Node Assistant to make an API call every 30 minutes, extract the value we need, and send this to Twinview's ingestion service.

Below is a simple diagram of this process.

First, search for an Inject node in the left node browser and drag this onto the Flow Canvas as shown.

Next, we need a HTTP Request Node. Search for this in the node browser and drag this onto the canvas, behind the inject node, and wire output the inject node into the input of the HTTP request node.

Now, let's configure some settings in the 'Inject node'. To do this, double-click the inject node*, and the edit modal screen should slide from the right.

*The inject node may have changed its label to be called 'timestamp'.

We must click the 'Inject once after' check and change the dropdown to 'every 30 minutes'.

This tells the flow to run straight away and every 30 minutes thereafter.

Click 'Done' to save the settings.

Next, we have to configure the HTTP request node. To do this, we double-click the node and configure it as below.

• The Method should be set to 'GET' as we are getting information from the API.
• The URL is the endpoint where we are making the request, as per the Openweater documentation. This is the same URL we used in sections 1 and 2 to make the Postman request. The URL must include the API key, and the Lon/Lat passed as parameters.
• The <- Return should be set to 'a Parsed JSON Object' as we know that this API returns JSON.

Click 'Done'

Before we run the flow, we need to add a debug node to check that it's working and see that the data payload has been returned from the API. To do this, we must search for the 'debug' node in the node pallet and drag it onto the canvas after the HTTP request node.

We now need to open the 'debug' console to see the output of the debug node and see if it is working. The debug console is on the right-hand side and can be turned on by clicking the 'ladybug' icon at the top left.

To start the script and fire the flow, we need to click the blue save button at the top right. Once saved, the flow will start and then fire every 30 minutes automatically. If successful, you should see a payload of data received by Node Assistant.

Congratulations! We have successfully created an automated script that calls the Openweather API every 30 minutes and gets the response sent to Node Assistant.

The next step is we need to extract the piece of data we need and send this to the IOT Data Stream Device called 'Openweather-Sensor-Temprature' we created in Twinview (in Step 3.2) every 30 minutes.

Search for the 'function' node in the node browser and drag this onto your canvas. Double-click the node to edit and paste the following into the code area:

msg.payload = {
    "uuid": "df9e9320-58c0-4d01-8d70-b24dfb509c05",
    "state": msg.payload.main.temp,
};
return msg;

Give the Function a name and connect it to your HTTP request node output.

In the last few steps, we have set up an automatic flow that fires every 30 minutes and gets data from the Openweather API. We then extract the data we need and format this into a payload that the Twinview Ingestion services require, including adding our device UUID.

Now, we need to send the payload to the Twinview 'Ingestion' service. To do this, we will use another HTTP request node, which we will place after the function node.

We need to edit the HTTP request node we just added and change the Method to POST (as we will post data to Twinview). We must also specify where to send the data by entering the Twinview Data ingestion service URL in the URL field. Either of the Twinview Ingestion URLs below will work.

https://ingestion.twinview.com/twinview/devices/event

Injestion URLhttps://ingestion.twinview.com/twinview/devices/event

Congratulations! Your IOT Data Steam Devices are now set up and receiving data!

The next step is to go and create a dashboard and add a widget to show the data,

Hopefully, this Tutorial was useful in walking through the process of connecting data from a third-party source into Twinview, the power/potential of Node Assistant, and the part it plays in this process.

This tutorial was a basic introduction and has not even begun to scratch the surface of what is possible. More advanced API authentication methods, including OAuth2, are supported, and we highly recommend receiving advanced training. Some of the more advanced functions, such as looping and extraction, can improve efficiencies and processes, especially when working on larger projects with 10,000 devices.