When you connect to a site, you may know nothing about it: How big is it? What is it made of? Which equipment does it contain? How are the data points organized?

All these questions can actually be asked to a BOS, thanks to its API. Let's see how!



Hierarchies concept

A Linksper BOS instance is made of many assets linked together by relationships. (See Linksper assets to learn more) They form together a graph database, with a certain complexity. That complexity depends on the site and of the details of implementation of Linksper.

To explore a graph database and discover its content in a logical way, we need two things:

  • A starting point
  • A path to jump from one asset to another

This is what we call hierarchies. A hierarchy is a point of view on the system, how do you look at it.

So you may want to discover the building structure with its floors, its spaces, the equipment per space etc. You may also be interested only in the air flow distribution: what are the main equipment dealing with fresh air (AHU...), to follow the terminal units they are feeding and then spaces etc. There are many ways to look at the systems of a building, this is precisely what we are gonna do next.  


See Linksper assets hierarchies to learn more about it.


Getting the list of available hierarchies

Prerequisite: you are already connected to a Linksper instance through the API. If not, please see Get started with Linksper API


All the hierarchies are available with the query: 

GET /v1/explore/hierarchies


The list of hierarchies will depend on your site implementation. StructureAssets and SubsystemAssets are default ones.


Learn assets from a localisation perspective

The Structure hierarchy will explore the building from a geographic point of view. It will show us the assets underneath each other all the buildings, all their respective floors, spaces, equipment and finally their data points.

You can use this query:

GET /v1/explore/hierarchies/StructureAssets?depth=3

Since we ask for 3 layers depth, It will give you the site, the associated buildings and for each building, the associated floors.


Some key comments here:

  • The bigger the depth the deeper we get in the graph (up to the data points).
  • Each asset will give its kind: Model, Equipment, Device, Data...
  • Each asset has a unique id. This is the identifier you will reuse to learn more about an asset.

You will notice there are only a few fields per asset. This is intended to make the response. But you can override it by defining more field.


Let's get deeper with the Structure Assets hierarchy with a level 6 depth:


You can notice other assets as we get deeper in the graph:

  • In the second basement, there is a space called "B2 Parking Spot 1"
  • It contains an Equipment "B2_CCP_01"
  • This equipment contains some data-points such as "Plug effective command"


Well you think now: "Cool! I can see some equipment but what the hell is "B2_CCP_01"??"

You have two ways to learn about it:

  • Option1: You can ask with the same query to display additional tags, there is a parameter for that. If you studied the Equipment asset, you will know that the equipmentType tag is what you're looking for (from the Equipment data Model).
  • Option2: You can explore in details this specific equipment using a dedicated query.


Option1: Use the equipmentType tag

  • We simply add a new parameter: additionalFields = b:equipmentType
  • We can then discover the equipment is a "Electric Car Charging Point"


Option2: Let's explore with more details this Equipment asset

We will be using:

GET {{base-api-url}}/v1/explore/assets/:id

The id is the asset id, which is in our case:  l0T3riQPwNFT3v4kTREGH

Let's add to the query additional fields "allTags" to have as much information as possible on this particular asset:

 


This is a lot of tags... You can refer to Equipment asset to understand them.

Learn equipment assets from their type

Let's continue with other hierarchies. In this case, we don't mind about the geographical structure of the building but we want to explore all equipment assets by their type. Example: explore all HVAC equipment, all equipment related to Plumbing etc.

We will be using the same query but with SubsystemAsset as a name of a hierarchy

GET /v1/explore/hierarchies/SubsystemAssets?depth=3



We can see from the result, some Control Damper equipment from the HVAC subsystem.


We don't see any Data assets here. It's simply because we used a level 3 depth. To get the data points we would need to use a level 4 depth.



Learn the metering hierarchy

In almost every building, the energy manager will ask to get the metering hierarchies: which meter is a submeter of another. Well thanks to the API, it never has been as simple as that:


GET /v1/explore/hierarchies/MeteringDistribution?depth=3




Note that this hierarchy will provide only Data assets. Submetering is done between data points only.

The dataValue will usually show you a consumption index. If you need a consumption over a period of time, get the data point id and use this query: {{base-api-url}}/v1/operate/histories/:id?retrieveValues=true


Example for retrieving historical values of a data point: