The objective of this tutorial is to teach you how to retrieve a list of data points related with each other such as belonging to a common space or floor and then trigger some batch commands.

Let's work on VayanData office and let's find some lights to play with (out of business office hours if we don't to get again some complaints from the team (wink) )


Step1: Get all data points related to a light

We are looking for every data point belonging to a light equipment. This means that each data point should inherit from a "Light" defined as a Equipment asset, therefore each data point should have a tag called "equipmentType" with the value "Light". Let's use /v1/operate/points and inject a simple query for a start: query=equipmentType='Light' 

GET {{base-api-url}}/v1/operate/points?query=equipmentType='Light'

Many data-points are available all the points related to the site:

 

Can we narrow down the search to a specific space? Yes of course. Using the Structure hierarchy, we can learn all spaces of a floor for example. See API: Explore assets using hierarchies.

Let's say we found out that one of VayanData office has this identifier: "2gZcGjShL32wxpKmgUgQmp" (we could also use the displayName but it's more random if multiple spaces have a similar name)

So let's add to the query spaceId='2gZcGjShL32wxpKmgUgQmp'

GET {{base-api-url}}/v1/operate/points?query=equipmentType='Light' and spaceId='2gZcGjShL32wxpKmgUgQmp'

We're getting a much smaller number of results (15 data points)

One result is giving a numerical value while others are giving boolean values. Hmm, not so easy to guess which one to use.

Let's ask the BOS for more tags, we can use the parameter called "additionalFields". We are specifically looking at the type of points (pointType) and the dimension. Internally, there are "dictionaries of tags", b is the default one so we need to add it as a prefix. Let's add it to the query:

GET {{base-api-url}}/v1/operate/points?query=equipmentType='Light' and spaceId='2gZcGjShL32wxpKmgUgQmp'&additionalFields=b:pointType&additionalFields=b:dimension

Very interesting result:

The three different points are all "Command" meaning that we can indeed change the value. The boolean data point has a "Light Control" dimension while the numerical points has a "Percentage" dimension. So one is for light on/light off and the other for dimming.

All right, we have all information we need know to switch off all lights of VayanData. We need to target Light Control Command data points.

Send a batch command

We will be using the POST query /v1/operate/points

This endpoint requires a body with a query and the type of action we want to perform: set indefinitely a value, override for a little period of time etc.

Let's create our body using our previous query:

{
    "query": "equipmentType='Light' and spaceId='2gZcGjShL32wxpKmgUgQmp' and dimension='Light Control'",
    "action": "inactive",
    "value": false,
    "duration": "5000"
}

And send the query

POST {{base-api-url}}/v1/operate/points

We can see The dataValue returned by the query shows the value before the command is actually sent:


Damn, it's dark now (tongue)


You can read the current value of the data points:

GET {{base-api-url}}/v1/operate/points?query=equipmentType='Light' and spaceId='2gZcGjShL32wxpKmgUgQmp' and dimension='Light Control'

You can see the status "overridden" and the value set to false for one hour:

Go beyond the example

This is just an example on how you can play with tags and queries to get and control whatever data points or resources you need from the BOS. Try it out with other data points. As always, VayanData office is the perfect place to try out any scenario you may have, get in touch with us to gain access.