Skip to content

Equipment Extraction

When starting with a raw dataset from scans, the first step in imposing structure is to model individual pieces of equipment. Generally speaking, scanning for points using different APIs results in a list of points (e.g., BACnet objects or API endpoints) which may be grouped by device or in some other way. However it is common for the raw data to not reflect the true structure of the equipment, since multiple pieces of mechanical equipment maybe be grouped on a single controller or gateway.

The goal of equipment extraction is twofold:

  1. Construct a type for each target piece of equipment.
  2. Create instances of that model for each actual piece of equipment on the site.

Using the Management Console to Model Equipment

The management console contains advanced support for system modeling flows and creating large-scale models of attached systems. The starting point for equipment modeling is the Object Explorer once data has been imported or discovered using the appropriate protocol driver.

Equipment modeling takes place one equipment type at a time; therefore, the first step is to perform an inital exploration of the data in Object Explorer to find a type of equipment to model; for instance, a particular type of VAV box or air handler. Configure the filters so that, as near as possible, the object explorer shows all points from all of those pieces of equipment. You may want to filter on vendor name; object name, or other properties to achieve this.

Extracting Equipment IDs

Once you have made a preliminary selection of points from the target list, the first step in creating equipment entities from these points is to extract a list of equipment identifiers from them. An equipment identifier should uniquely identify each piece of equipment, rather than the controller. For instance, you may want to create an equipment identifier for each terminal unit, air handler, pump, and so on.

ID Extraction

Although it is commonplace for the equipment identifiers to be available somehow in the points list, it is also common for the names to be embedded in other strings or otherwise obfuscated. For instance, a point named RoomTemp_001 may indicate that the point is the room temperature sensor for a unit named 001. Therefore, NF allows the user to perform a number of different string manipulations to extract the target identifier. In this example, a good identifier might be zone_101.

Equipment extraction is started by clicking "Extract Equipment" in the upper-right of the Object Explorer; this opens the extraction tray. In the first step, a preview of the IDs to be generated is displayed on the right; while on the left the user controls tools for extracting and modifying IDs present in the underlying data.

Equipment Extraction Tray

In this step, the goal is to refine the list of equipment IDs until they produce the desired list of equipment instances. It is important that all points from a single piece of equipment produce the same identifier, so that the points are grouped correctly.

  • The Extraction Column controls which attribute is used as the input for ID generation.
  • The Basic Extraction Mode tab gives simple options for extracting equipment identifiers from the underlying data; for instance, by splitting on a character, or using find and replace.
  • The Advanced Extraction Mode allows the creation of JavaScript functions in order to perform more advanced string manipulation.
  • The right-hand side of the screen displays a preview of the generated IDs; as well as input IDs which are dropped or generate an error during processing.

Defining an Equipment Type

Once a the list of equipment IDs has been finalized, the next step is to map these to an equipment type. A type is derived from an ontology; but is customized to match the needs of a site. For instance, an ontology may contain a class for Variable Air Volume boxes specifying a list of marker tags, point list, and so in; but from a relatively generic point of view.

There are three main concepts we use when creating models for equipment:

  • Equipment Classes are essentially templates for a piece of equipment. They are defined in advance and shared between sites, and they contain the scaffolding for how a type of equipment should be modeled. For instance, Normal ships with a rich set of equipment classes which can represent many different types of equipment, from air handlers to sensors. Each class has a unique name, and defines a set of marker tags (as in Haystack), a set of possible relationships, and a list of points which the equipment may have.

  • Equipment Types are derived from classes and represent a specific type of equipment present at a site. For example, a site may have several dedicated outdoor air systems (DOAS) units; during equipment extraction, the user will create an equipment type derived from an equipment class, which has the actual list of desired points, marker tags, and other attributes for use at that site.

  • Equipment Instances represent specific pieces of equipment; e.g., an single DOAS unit. They are associated with an actual points list, and can be labeled with differnt attributes as specified by the type. As in Haystack, or Brick, each instance has a unique identifier (id) which uniquely names that piece of equipment.

classDiagram
  direction LR
  Class "1" --> "0..n" Type
  Type "1" --> "1..n" Instance
  class Class {
    name
    markers
    attributes
    optional attributes
    relationships()
    points()
  }
  class Type{
    local name
    local name
    attributes
    relationships()
    points()
  }
  class Instance{
    id
    type name
    markers
    attribute values
    relationships()
    points()
  }

To create a type, users may either select from an existing type previously created at the site; or create a new type by deriving it from one available in the ontology. The equipment builder allows for dynamically creating new equipment type by adding sub-components. For instance, when modeling a VAV, the user can add a thermostat, supply and return ducts, and damper in order to create the appropriate model definition and points list.

Equipment Type Creation

After generating an equipment type by selecting a base type and adding sub components, the definition can be further customized by adding additional attributes, marker tags, desired points list and relationships.

Previewing Results

The final step before creating the equipment instances is to preview the results. At this point, the user should check that all IDs and points were extracted as expected; and enter any attribute values manually. The preview allows a user to see which points are associated with each piece of equipment, and if the equipment is new or an update to a previously created one.

Equipment Preview