FOR SMartServer 3.3 and prior releases, the LOCATIONS widget is called the Map Widget.

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.  A campus may be a region, such as Northern California, a site such as the Olympic Village, or a campus such as the University of California.  An area may be an area in a campus, such as a parking lot or street, or an area on a floor such as a VAV zone.  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.

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 and Setting Location

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, or click the Set Location () button.
     
     
     • A view similar to the following appears:
       
       
       
       
     • Click the map to set the building location. The latitude and longitude fields are set based on the building coordinates.
       
       
       
       
   • 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, hover 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

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

You can visualize a context and see the devices that are assigned to it, as well as child contexts. To do so, perform the following steps:

1. 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

You can display a context on a map. To do so, perform the following steps:

1. 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 Locations widget.
   
   

See Working with Maps for more information about Locations 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 

Managing Device Clustering

To decluster devices, click the Cluster Radius button () on the Locations 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. See Testing Devices and Managing Datapoints for more information about device state colors.

Showing Device Information

To show the device information, click the Show Device Information button () on the Locations 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. See Testing Devices and Managing Datapoints for more information about device state colors.

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 Locations 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 Locations widget to hide or show zones as shown below. To show zones, perform the following steps:

1. Open the Devices widget, EDGE DEVICES tab.
   
   
   
   
   
2. Click the Action button () and select the Show All on Map action.
   
   
   
   
   The Locations widget appears.
   
   
   
   
3. Click the Show Zones button () to show zones.
   
   
   
   Click the Hide Zones button () to hide zones.
   
   
   
   
4. To exit this view, click the Menu button ().
   
   A view similar to the following appears.
   
   
   
   
5. Click the Back button ().
   
   The main Locations widget map view appears.
   
   

Managing Devices

The Locations widget provides the ability to perform some general device management operations. To do so, click the desired device on the map and select the action that you want to perform. Actions are available based on device type and state as described in the sections below.

Segment Controllers

Segment Controller

•  – show alarm information, if any exist (refer to the Setting up Alarm Email Notifications section)
  
  
• – replace a device (refer to the Provisioning, Deprovisioning, and Replacing Devices section)

Edge Devices

Edge Devices

• – show floor plan (refer to the Managing Floor Plans section below)
  
  
•  –  edit floor plan (refer to the Managing Floor Plans section below)
  
  
•  – remove floor plan (refer to the Managing Floor Plans section below)

Managing Floor Plans

Showing Floor Plans

To view floor plans, perform the following steps:

1. Open the Locations widget.
   
   
   
   
2. Click the edge device for which you are viewing a floor plan.
   
   Actions similar to the following appear.
   
   
   
   
3. Click the Show Floor Plan button ().
   
   A view similar to the following appears allowing you to view the floor plan.
   
   
   
   
4. Click the edge device shown on the floor plan.
   
   A view of the devices appears with additional actions that you can perform based on device state.
   
   
   
   
5. Click the desired operation:
   
   
   •  – view device datapoints (refer to the Testing Devices and Managing Datapoints section for more information about the Datapoints widget)
     
     
   •  – show alarm information, if any exist (refer to the Setting up Alarm Email Notifications section)
     
     
   • – replace a device (refer to the Provisioning, Deprovisioning, and Replacing Devices section)
     
     
   • – remove from floor plan (removes the device from the floor plan)
     
     
   • – deprovision a device (refer to the Provisioning, Deprovisioning, and Replacing Devices section)
     
     
   • – test a device (refer to the Testing Devices and Managing Datapoints section)
     
     
6. To exit the Devices view, click the Close button ().
   
   
   
   The floor plan view appears.
   
   
   
   
7. To exit the floor plan view, click the Menu button ().
   
   A view similar to the following appears.
   
   
   
   
8. Click the Back button ().
   
   The Locations widget map view appears.
   
   

Editing Floor Plans and Location

To edit a floor plan, perform the following steps:

1. Open the Locations widget.
   
   
   
   
2. Click the edge device for which you are editing a floor plan.
   
   Actions similar to the following appear.
   
   
   
   
3. Click the Edit Floor Plan button ().
   
   A view similar to the following appears allowing you to edit the floor plan settings.
   
   
   
   
4. To change the location, click the Set Location button ().
   
   A view similar to the following appears.
   
   
   
   
5. Specify the new latitude and longitude as needed.
   
   
6. Click SAVE to set the new location.

Removing Floor Plans

To remove a floor plan, perform the following steps:

1. Open the Locations widget.
   
   
   
   
2. Click the edge device for which you are removing a floor plan.
   
   Actions similar to the following appear.
   
   
   
   
3. Click the Remove Floor Plan button ().
   
   A confirmation dialog box similar to the following appears.
   
   
   
   
4. Click OK to remove the floor plan.