YAML Tutorial – Using a YAML file to store data on the FieldServer & serve over Modbus TCP, BACnet/IP

FAQ

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

Yes! In this tutorial we will show you how to write a JsonPath expression to parse a YAML file for a specific data point (Lobby Temperature) – and then store that value onto a FieldServer. We will write a config.csv file for the FieldServer that will allow it to serve that stored value over Modbus TCP & BACnet/IP.

Example of an YAML File:


Download here: https://s.chipkin.com/files/uploads/2021/apr/ymalExample.yaml


If you wish to learn more about YAML syntax, we suggest you check out this website: https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html

Write a JsonPath to find the current Lobby Temperature (sensor)

To write a JsonPath, you will need to understand what they are and how to use them. Take a few moments to familiarize yourself with operators used in JsonPath:



Using the above information, let’s find the Lobby Temperature for the store – based on the information provided in the YAML file. To do that, we will use the following JsonPath:

$.store.sensor[1].value

Explanation: Since $ = the root object/element, and “store” is the child operator of the root, we will use $.store. sensor[1] refers to the 1st offset (child operator) of senor. Finally, to find the value of sensor[1], we added .value

Create a Node in the FieldServer to scan for updated values within the YAML file.

  1. First, let’s bring up the GUI of your Fieldserver. Put your own information in:

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


  2. Once you've logged into the FieldServer, look on the left side of the GUI for a menu. Once you've located the menu (see below): Click the Drivers tab and you'll see a drop-down menu. Then, click on XPath


  3. The page you're on now should be titled XPath Application Engine Configuration. Click on the Create Connection button under Connections:


  4. On this pop-up screen, we want to establish a Name for the connection, Type and Port.

    • Name: Create a name for this connection. Anything you’d like.
    • Type: The type of connection – either Ethernet or Serial.
    • Parameters/Port: The physical ethernet port to use.

  5. Press create. Next, please locate the Create Node button and then click it:

    eNow it’s time to use your URL for the YAML File and place it directly into a Node on the FieldServer.

    • Name: Use any name you’d like. This will be the name of the node you are creating.
    • Connection: Should default to your connection
    • URL: Here, insert the URL for where the YAML file is located. Here is the URL for the tutorial's YAML path:
    • Scan Interval: Insert how many seconds you would like in-between scans.

Create a Task in the FieldServer that will use the JsonPath expression to locate the Lobby Temperature within the YAML file. This task will also store the data into a data array; DA_AI, offset 40.

  • Start by clicking “Create Task” as seen in the screenshot:


  • ii. Then, we will fill in the information on the popup. Please fill in the following information to read the current Lobby temperature

    1. Name: Use any name you’d like. This will be the name of the Task you are creating.
    2. Node: It may default, but please choose the correct node you would like this task to run on.
    3. Data Broker: Select Protocol Engine since we will be using a PE-type config file. This is where the data of the task is mapped.
      • Name: The name of the Data_Array that will store the value from our Task. In the example config.csv 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.
    4. Pattern: The JsonPath expression will go here.

    5. $.store.sensor[1].value

    6. Type: Select the Type of data to parse. For this example, we will use YML>.
    7. When you are finished typing in the information, click “create”

***Important***: Click the "Save Configuration" button at the bottom of the screen for the changes to be saved to the FieldServer.

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.

  • Create a brand-new file with Notepad++

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


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 Communications are Working Properly


To see if this process has 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.

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