FieldServer Tutorial – Using XPath Expressions to extract live data points from an API. And how to serve that data over Modbus TCP and BACnet/IP

FAQ

Can a FieldServer read data points off an XML File & serve them over Modbus and BACnet to my BMS?

Yes! The FieldServer can use XPath expressions to locate specific data points from an XML file. That data can be stored into a data array and served over 130+ protocols - including Modbus and BACnet. Let's explore this in detail...

Look at this example of an XML File:



When the FieldServer receives data in XML format, it may look like the above example. In this example, the FieldServer can read data from sensor id=’1’, sensor id=’e224’, device floor='7' room='702', device floor=’2’ room='205' , and device floor=’16’ room='1604'. Each sensor provides temperature, light, and volume data. While each device provides occupancy, alarm, and temperature data.

Let’s say we want to know whether Room 1604 on the 16th floor is vacant or not. To do that, we will need to locate that data within XML using Xpath. We would use the following Xpath Expression:

//device[@room='1604'][1]/occupancy[1]

In our example, this expression returns “false”. According to this XML file, room 1604 on the 16th floor is not occupied.

The following table shows other Xpath expressions and values that would be returned:


Also, please look at the following tables if you'd like to further your understanding of the syntax for XPath Expressions:

FieldServer Tutorial – Using XPath Expressions to extract current weather data points from an API & serve over Modbus TCP, BACnet/IP

In this example, we will be extracting live weather data using a free open-source API called OpenWeather. We will request this data in XML format using an API Call. Then, we will create XPath expressions to extract specific data points from the XML File. Next, using the API Call & XPath expressions, we will store those values onto that FieldServer. Finally, we will create a configuration file which will allow the FieldServer to serve those data points over Modbus TCP and BACnet IP.


Step 1 - Create an Account on OpenWeatherMap.org

  1. Click on this link: OpenWeatherMap.org's Sign-up Page. Then, create an account.

  2. An email verification will be sent to you. Please check your email and verify to proceed.

  3. After your email has been verified, click on the “API keys” Tab (as seen below):

  4. Locate the “Create Key” section. Type in any name you’d like, and press “Generate”. This will create a unique API key for you.

  5. Note: The newly generated API key is unique to you and your subscription. Please save this key to a .txt file or at least leave the browser window open as we will be referring to this key shortly.

Step 2 - Generate an API call (using your API key) to get current weather data in Vancouver, BC

  1. First, please visit this web page: OpenWeatherMap.org/current

    Our next task is to use the information from this page to create an API Call. Note: This section – located near the top of the page (or see below) - will show you how to write an API call.


    Note: You may also add these parameters to the API call: q, appid, mode, units, lang:

    Here is the example API call from their documentation

    api.openweathermap.org/data/2.5/weather?q={city name}&appid={API key}


  2. Since we want the current weather in Vancouver - replace {cityname} with Vancouver and {API key} with your generated API Key (see "YOURAPIKEYHERE"). Note: It takes time for the generated API key to become active. If your key isn't active yet, please retry again later. This is how it should look…

    http://api.openweathermap.org/data/2.5/weather?q=Vancouver&appid=YOURAPIKEYHERE


  3. Before we paste this API call into our browser, let’s add a couple additional parameters. Since we want the data presented to us in XML format, we will add &mode=xml at the end of the URL. Since we want this data to be in metric units, we will also need to add &units=metric. If we’ve done it properly, the finalized API call should look like this:

    http://api.openweathermap.org/data/2.5/weather?q=Vancouver&appid=YOURAPIKEYHERE&mode=xml&units=metric

  4. Copy and Paste the above API call into your browser. Remember to replace YOURAPIKEYHERE with your generated API key or it will not work properly. If you’ve done this correctly, you will see an XML file that appears formatted like this this (Your values will be different since the weather changes):
Write an XPath expression to extract data from the XML file

  1. First, click on this URL used for formatting XML files xpather.com

    Delete the current code that is pasted in there. Then, copy and paste your generated XML file inside. Then, locate and click the “Format” button:


  2. Let’s find the current temperature value for the city of Vancouver – based on the information provided in the XML File. To do that, we will use the following XPath expression

    /current/temperature/@value

    If you copy the above XPath expression and paste it into the box in the upper left corner of the xpather.com page (see below), you should see something similar. Note: Your values may be different from mine (current temperature).


  3. Next, let’s find the current humidity in Vancouver. To find this value, we will use the following XPath Expression:

    /current/humidity/@value


    If you copy the above XPath expression and paste it into the box in the upper left corner of the xpather.com page (see below), you should see something similar. Note: Your values may be different from mine (current humidity).

Place the API Call and XPath Expressions into the FieldServer

  1. Bring up the GUI of your Fieldserver. Please use the following URL and be sure to include the IP address of your FieldServer.

    http://{YourFieldServerIPAddress}/chipkin/ui/#


  2. Once you’re in, look on the left side and locate the Menu. Click the ‘Drivers’ tab and you’ll see a drop-down menu. Then click on ‘XPATH’ (see image below):


  3. Locate the “Create Connection” button under Connections – then click it:

  4. Create the connection

    • Name: create any name for this connection.
    • Type: connection type – either Ethernet or Serial.
    • Parameters/Port: physical ethernet port to use.
    • Click "Create"

  5. On that same page, please locate the Create Node button and then click it:
  6. Now it’s time to use your API call and place it directly into a Node on the FieldServer. To do that, we will use the following information to create a node.

    • Name: use any name you’d like.
    • Connection: should default to your connection
    • URL: Insert your API call's URL. This is the API call that we created earlier.
    • http://api.openweathermap.org/data/2.5/weather?q=Vancouver&appid=YOURAPIKEYHERE&mode=xml&units=metric

    • Scan Interval: Insert how many seconds you would like in between scans.

  7. Next, click “Create Task” as seen in the screenshot:

  8. One task will be created for EACH XPath Expression. First, let’s use the XPath expression for current temperature in Vancouver.

    • Name: use any name you’d like. "Temperature" is suggested.
    • Node: It may default, but please choose the correct node you would like this task to run on.
    • Data Broker: Select "Protocol Engine" since we will be using a PE-type config file.
      • Name: The name of the Data_Array that will store the value from our Task. In the example config.csv (Section 5) we will define our Data_Array as DA_01. To store and serve the data, remember the name you choose here so you can include it in your config.csv file.
      • Start: Starting offset value goes here. In the data array we just defined (DA_01), we will need to choose which starting offset to store the data in.
    • Pattern: The XPath expression will go here.

      /current/temperature/@value

    • Pattern: It may default, but please choose the correct node you would like this task to run on.
    • Type: Select "XML"
    • Click "Save"

  9. Create a new task to store the current Humidity value in Vancouver

    • Note: Watch the offsets. Since we used offset “0” for the temperature, we will use offset “1” for the humidity. You cannot use the same offset to store more than one data point.

    • If you've followed the steps properly, your screen should look like this:

Write a Configuration File for the FieldServer

Now that our XPath tasks are running, let’s say you (or a customer) would like to have these data points served via Modbus/TCP and/or BACnet IP. We can do that by writing up a configuration file to be uploaded onto the FieldServer.


  1. Create a brand-new file with Notepad++

  2. Copy & paste the code below into the new Notepad++ file. Save the file as config.csv.

Upload the configuration file to the FieldServer


  1. Go back to the FieldServer GUI

  2. Locate “Diagnostics” on the left-side menu & click it.

    • It will bring up a screen that looks like this:

  3. On the left menu, click on “Setup” and then “File Transfer

  4. Click Choose Files – Locate the Config.csv file, open it, then click Submit.

    • Once the download is complete, a message bar will appear confirming that the configuration was updated successfully.

  5. Click the System Restart Button at the bottom of the screen. Also, click “OK” if you see a pop-up. This will put the new file into operation. Please wait until the process has fully completed (may take up to six minutes).

Verify the Data Stream


To see if this process worked as planned, let’s check the Data Array named DA_AI to see if there is incoming data on offset “0” and “1”.

  1. First, under the “Navigation” Menu, click on 'View'.

  2. Under that drop down, click on “Data Arrays .

  3. Lastly, click on “DA_AI”

    • If you’ve followed all the steps correctly, you will notice that there is data being stored in Data Array DA_AI, under offsets “0” and “1”. Do a sanity check on these values to ensure that offset “0” correlates to a viable temperature in Celsius, and offset “1” appears to be a realistic % of humidity.

XPath Tutorial Conclusion:


As you can see, on Data Array ‘DA_AI’ there is incoming data on offsets “0” and “1”. On offset “0” we can read that the current Temperature in Vancouver is 6.27°C. Also, the Humidity in Vancouver is 87%. These values are constantly updating every 30 seconds (scan-interval) with the current weather values.

What can you do with these values? Quite a bit! Outdoor weather of high winds, rain levels, freezing temperatures, snow, high humidity etc. can cause damage to essential business functions. Imagine an airport during a heavy freeze/snow. If required to land on an iced surface, it may be difficult for a pilot to ensure the safety of their passengers. With these values, reactionary measures can take place. If there is below freezing temperatures, an automated response might be to heat up the asphalt to reduce the ice. This would obviously require more than one system to do, and this is just an example. The possibilities are endless.

XPath Support FAQ:


  1. Where can I find out more information on XPath?

  2. What website can I use to try out XPath expressions?

    • We recommend http://xpather.com/ because you can copy & paste your XML file into it and test live XPath expressions to see if they are valid.

  3. What happens if the website goes down that is providing the XML file?

    • Currently, the driver will continue to serve the last known values. However, we plan to update this in the future.

  4. Can you use multiple nodes within the XPath Application Engine?

    • Yes. You can use different URLs within each node to pull data from various sources.

  5. How many different values can you obtain using the XPath Expressions?

    • It depends. FieldServers have a certain # of points that are allowed – based on the Firmware. The standard FS QuickServer allows for 250 points, but this can always be upgraded to allot for more.


Gateway Selector

Select your combination of protocols.
Protocol 1
Protocol 2

Contact Us

Contact us via phone (+1 866-383-1657) or leave a detailed message below for sales, support, or any other needs

*Required Field
*Required Field
I'd like to receive the newsletter. *Check email for confirmation.
*Required Field
8:00am - 12:00pm 12:00pm - 5:00pm