Defining Contexts (Release 3.3 and Prior)

For SmartServer 3.4 and higher releases, see Defining and Using Contexts

You can create contexts to organize devices within the SmartServer IoT to mirror their locations within the physical site to facilitate effective system planning and navigation. A context is a digital representation of a real world region, area, or space.  You will use the CMS Planning widget (introduced in SmartServer 2.8) to view, create, organize, edit, and delete contexts.  Other CMS widgets use the context information to organize your devices by the contexts you define. For example, you can organize sequence of operations, dashboards, and connections by contexts. See the SmartServer IoT Node-RED Tutorial for a getting started tutorial on creating a sequence of operation and applying it to a context within the system.

For each context you create, you select a context type which can be a campus, building, floor, room, or area.  The context type represents a location within a site.  You can associate other system entities such as datapoints, devices and users with these contexts to provide a physical location reference to these entities.  For example, you can use contexts to identify select specific devices or user interfaces such as the following:

  1. All temperature sensors in a building
  2. All the Node-RED sequences that connect temperature sensors in an area to the VAV controller in the area
  3. All the analytics dashboards showing device status for a campus

This topic consists of the following sections:

Setting up Contexts

Contexts have the following simple properties in order to build up an actual site:

  1. All contexts types (except area context) are hierarchical and a device belonging to a context also belongs to its parent contexts.
  2. Area contexts are the exception and are location based. Devices within an area belong to that area, as well as any other context it is assigned to.
  3. Area contexts can only exist in a campus or a floor context where an area can physically be defined/drawn.
  4. Campus and buildings have geolocations. Floor, rooms, and areas are represented as a shape on an imported floor plan.
  5. Contexts can be defined any time, cloned, or imported.

The Planning widget is used to create contexts and also to assign devices to specific contexts. It is encouraged that all workflow begin with defining context before devices are provisioned if the project requires mapping devices to a physical site.

SmartServer 3.3 or higher

With SmartServer 3.3 or higher, you can clear locations for a device, which causes the device to be unassigned from any contexts and removes it from the map. See Clearing Device Location in the Configure Your SmartServer section.

Note: Contexts are not supported in IMM using the IzoT Net Export (iNex) tool. Running the iNex tool deletes devices and then re-adds them in the SmartServer CMS, which causes the context assignments to be removed.

Creating a Context

Campus Context

  1. To create a new campus context, click the Create Context button () on the Planning widget.



    The Create context view appears.



  2. Enter the context parameters as appropriate, including:





    • Name
    • Type  select Campus. This type is the parent context that houses all other types of contexts and can contain only building and area contexts as children. It defines a physical facility and is comprised of multiple buildings, and is the highest level entity in the context hierarchy. This type supports four geolocation latitude/longitude coordinates.
    • Description
    • Custom Fields (Tag / Value)

  3. Click the pick Geopositioning button () to set the geolocation.

    Note: The top level geozone for all contexts types is the World geozone, shown in the Planning widget as all context.

    The Planning map opens.



  4. Use the rectangle tool (  ) to define the area on the map.



  5. If needed, modify the geolocation by first clicking the Edit button (), and then clicking and dragging the handles or marker.



  6. Save or cancel edits by selecting the appropriate option .

  7. Click OK.

    The Create context view reappears.



  8. Click CREATE.

    The new campus context appears on the Planning widget.

Building Context

  1. To create a new building context for a single building context project, click the Create Context button () on the Planning widget.



    The Create context view appears.



  2. Enter the context parameters as appropriate, including:







    • Name
    • Type  select Building. This type is the next level of hierarchy after campus that contains only Floor and Area context types. It defines a physical building and is comprised of one or more floors. This type supports single geolocation latitude/longitude coordinates and street address.
    • Latitude / Longitude
    • Description
    • Custom Fields (Tag / Value)

  3. Click CREATE.

    The new building context appears on the Planning widget.

Creating a Child Context

Floor Context

  1. To create a floor child context, scroll over the context name.

    Options appear on the Planning widget.



  2. Select the Create Child Context button () on the Planning widget.



  3. Enter the context parameters as appropriate, including:







    • Name
    • Type  select Floor. This type is the subsequent context type that contains room and area context types and contains the floor plan image. It defines a physical floor in a building and is comprised of one or more rooms. A floor context type nested below the building are geolocated relative to the building context type they are nested below. A floor and room context type nested below the building are geolocated relative to the building context type they are nested below. The room and area context types defined below the floor context type are relative to their position assigned on the floor plan image.
    • Description
    • Tag / Value

  4. Click the Import Image Floor area.



  5. Upload the selected floor plan image from your computer.



  6. Click CREATE.

    The new floor child context appears on the Planning widget.

Room or Area Context

An area is a context type that is defined by its scope (campus or floorplan) and meets the following criteria:

  • Has three or more vertices (the sides defined by the vertexes do not overlap).
  • Contains all devices that are within the boundaries defined by the vertices. Containment with an area does not preclude containment with any other areas or contexts, as shown in the figure below.

  • Exists only in a campus or a floor.
  • Cannot be nested within other areas, buildings, or rooms (areas are not hierarchical).
    • In a campus, all areas are at the same hierarchy as other buildings and campus-level areas.
    • In a floor, all areas are at the same hierarchy as other rooms and floorplan-level areas, even if an area’s boundaries covers a room completely (as shown in the figure below).

See Applying Contexts and Devices to Flows for more information and refer to the steps below to create a room or area context type.

  1. To create a room / area child context, scroll over the context name.

    Options appear on the Planning widget.



  2. Select the Create Child Context button () on the Planning widget.



  3. Enter the context parameters as appropriate, including:







    • Name
    • Type  select Room – This type defines a physical room entity in a building and is comprised of multiple areas. Or select Area  This type is a free context defined by a polygon on a campus or a floor. Areas can intersect each other and other contexts. All devices that fall within an area belong to that area. It defines the smallest unit of a context that represents a small area in the physical world. Area contexts can be nested below any other context type and are always relative to the parent context. 

  4. Use the rectangle tool () to define the physical area of the context.



  5. Click CREATE.

    The new room / area child context appears on the Planning widget.



    If a physical area for the context is not defined, an indicator will appear as shown below.



    Use the Edit feature for this context to define the physical area.

Importing a Context

Note: Any preexisting zones and/or geozones in the SmartServer IoT system must be cleared prior to importing contexts.

  1. To import a context, click the Import button () on the Planning widget.



    The Import view appears.


  2. Select the file to imported and place it onto the DROP FILE HERE area.

  3. Click IMPORT.

    The context hierarchy appears on the Planning widget.

Exporting a Context

To export a context, click the Export button () on the Planning widget.

A CSV file is created and saved onto your computer.

Managing Contexts

Editing a Context

  1. To edit a context, scroll over the context name.

    Options appear on the Planning widget.



  2. Select the Edit button () on the Planning widget.



    The Edit view appears.



  3. Edit the context parameters as needed (Type parameter cannot be changed once it has been defined for a context).

  4. Click UPDATE to save your changes.

Cloning a Context

Existing contexts can be cloned at any level of the hierarchy, creating a deep copy of all the children.

  1. To clone a context, scroll over the context name.

    Options appear on the Planning widget.



  2. Select the Clone button () on the Planning widget.



    The Clone context view appears.



  3. Edit the context parameters as needed (Type cannot be changed once it has been defined for a context). You will need to change the context location because two different contexts cannot exist within the same latitude and longitude coordinates. 

    Location considerations for context cloning

    • Campuses cannot intersect other campuses.
    • Buildings cannot have the same location as other buildings.
    • Rooms and areas cannot have the same locations, but they can intersect each other.
    • Floors have no constraints.



  4. Click CLONE.

    A copy of the context appears on the Planning widget.

Removing a Context

  1. To remove a context, scroll over the context name.

    Options appear on the Planning widget.



  2. Click the Remove button () on the Planning widget.



    The selected context is removed.

Viewing Context Details

From the Planning widget, easily gather all the information associated with a particular context. This dashboard includes the following information:

  • Parent context
  • Children contexts
  • Location of the context (point/area) on a map view
  • System entities linked to the context

Contexts can also be shown in a map view.

Viewing Context Dashboard

  1. To view a context dashboard, scroll over the context name.

    Options appear on the Planning widget.



  2. Select the View Context Dashboard button ()on the Planning widget.



    If the context is assigned to a flow that utilizes Node-RED dashboards, then the Node-RED dashboard view will appear as shown in the example below.

    Note: In order for the dashboard to appear, the flow must be enabled in the Sequencing widget. See SmartServer IoT Node-RED Tutorial for more information about getting started with the Sequencing widget and Node-RED flows and dashboards.




    Otherwise, the following message will appear:


Viewing Devices Assigned to a Context and Child Contexts

  1. To visualize a context and see the devices that are assigned to a context, as well as child contexts, scroll over the context name.

    Options appear on the Planning widget.



  2. Select the Visualize button () on the Planning widget.




    The DEVICES ASSIGNED TO CONTEXT appears on the context information dashboard. (Click the CHILD CONTEXTS tab to view child context information.)

    Note: To best view all of the information on this dashboard, click the Expand button (). 



  3. Using the Action button ()for a selected device that is assigned to the context, you can provision the device, deprovision the device, reprovision the device, or unassign the device from the context.



  4. Using the Action button () for one or more selected devices that is assigned to the context, you can provision selected device(s), deprovision selected device(s), reprovision selected device(s), or unassign selected device(s) from the context.



  5. Click CANCEL to return to the Planning widget.

Showing a Context on a Map

  1. To show a context on a map, scroll over the context name.

    Options appear on the Planning widget.



  2. Select the Show on Map button () on the Planning widget.



    The context appears in the Map widget.

See Working with Maps for more information about the Map widget routines.

Working with Maps

Use the Zoom button () to focus the map to the desired geographic area.

Click the  +  button to zoom in, or the  –  button to zoom out.

The Reset Filter button () may be used to reset views to the default settings. 

Setting the Map View

Click the Map View button () to set the map display with one of the following options:

  • OpenStreetMap
  • Google Streets
  • Google Terrain
  • Google Hybrid 

Showing Devices on a Map

To show devices on a map, perform the following steps:

  1. Open the Devices widget.
  2. click the Action button () on the Devices widget and select the Show on Map action.


The selected device is displayed on the Map widget.

Managing Device Clustering

To decluster devices, click the Cluster Radius button (on the Map widget and use the slider (scale 1-10) to decluster / cluster devices. More devices will appear on the map as the slider number is decreased; devices will appear clustered (grouped) as the slider number is increased.


The color of the device cluster indicates alarm status as follows: green indicates that all nodes in the cluster are alarm free; yellow indicates that one or more of the nodes in the cluster has an alarm; and red indicates that all nodes in the cluster have an alarm.

Showing Device Information

To show the device information, click the Show Device Information button () on the Map widget and select one of the following options: 

  •  – show devices grouped/ungrouped by segment controller

  •  – show device status (provisioned or deprovisioned). The device status information appears on the map. The SmartServer CMS uses colors to differentiate device state. Green represents imported devices that match the actual device; and yellow represents imported devices that ambiguously match the actual device.

With SmartServer releases prior to 2.8, the following show device information options appear:

  •  – show devices grouped by segment controller

  •  – show device status (provisioned or deprovisioned). The device status information appears on the map. The SmartServer CMS uses colors to differentiate device state. Green represents imported devices that match the actual device; and yellow represents imported devices that ambiguously match the actual device.

  •  – show device brightness level (%)

  •  – show link quality indicator (LQI) for communications with the gateway. The LQI may be a value between 0 and 1. Use the slider to set the threshold value. Options for Receive and Transmit provide the ability to check the link both ways.



  •  – show GPS information

Showing Devices by Status

To quickly filter and display devices on the map based on their operating status, click the Show Device Status button () on the Map widget.

The filter options are as follows:

  •  – show devices that are provisioned

  •  – show devices that are deprovisioned

  •  – show provisioned devices that are down

  •  – show provisioned devices that are not communicating (suspect state)

  •  – show devices that are being provisioned (alternating blue/green colors)

  • – show devices with marginal health status indicating that a failure was reported by the device, typically during provisioning (i.e., the device could be reached but it would not provision due to an error unrelated to communication). For drivers that implement marginal state, this device status is available with SmartServer 3.2.

Showing Zones

For devices that are assigned to a context, a Hide / Show Zones button () is available on the Map widget to hide or show zones as shown below.


Click the Hide Zones button ()  to hide zones



Click the Show Zones button () to show zones

Creating Devices

  1. To create a device, click the Edit button () on the Map widget, click on the map, and select the CREATE DEVICE action.



  2. Refer to the Discovering, Defining, or Importing Devices section for more information.

Managing Devices

The Map widget provides the ability to perform some general device management operations. To do so, click the desired device on the map and select the following routines (as available based on device state):