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 region, 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, for example, be an area in a campus, such as a parking lot or street, or an area on a floor such as a VAV zone. An area can also be created within a region. 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 an area
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

If you set or change your SmartServer's location by assigning a context, or by manually setting the location, then the SmartServer's timezone may also be changed accordingly. Changing the SmartServer's timezone does not affect the SmartServer's location. 

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. With SmartServer 4.2 and higher, devices within an area belong to that area, as well as any other context it is assigned to.
3. Area contexts can exist in a region, campus, or floor context where an area can physically be defined/drawn.
4. The location of a campus, region, area within a region or a campus, and a building is defined on the map by clicking the Pick Geoposition button () and using the polygon tool.
5. Floor, rooms, and areas are represented as a shape on an imported floor plan. If the area is the child of a region, then you have to define the area on the map by clicking the Pick Geoposition button () and using the polygon tool.

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.

With SmartServer 3.4 and higher, you can clear locations for a device by unassigning the the device from a context. See Viewing and Managing Devices Assigned to a Context below. With SmartServer 3.3 or prior, 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 Configure Your SmartServer (Release 3.3 and Prior).

Contexts are not supported in Independent Management Mode (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

The CMS creates a top-level World context by default that includes the Earth's surface. A user with suitable permissions can create campus, building, or area contexts directly in the World context, and can also create segment controllers and edge devices directly in the World context. This may be used, for example, for outdoor lighting systems where segment controllers and lighting controllers may be defined directly in the World context without a campus, building, or area. Alternatively, this may be used to create an area context for a region, which in turn contains segment controllers and lighting controllers for an outdoor lighting system.

Region Context

To create a region context, perform the following steps:

1. Open the SmartServer CMS.
   
   
2. Open the Planning widget.
   
   
3. Click the Create Context button () on the Planning widget.
   
   
   
   The Create Context view appears.
   
   
   
   
4. Enter the context parameters as appropriate, including:
   
   
   • Name – name for the region.
   • Type – Region. This type is the parent context that houses all other types of contexts and can contain campus, building, and area contexts as children. It is the highest level entity in the context hierarchy. This type supports four geolocation latitude/longitude coordinates.
   • Description – optional description.
   • Import Image – allows you to optionally import an image. Importing images for users with a Field Tech role is not supported.
   • Custom Fields (Tag / Value) – optional tag/value pairs.
     
     
     
     

5. Click the Pick Geoposition button () to set the geolocation.

   The Pick Geoposition view opens.
   
   
   
   

6. Use the rectangle tool (  ) or the polygon tool (  ) to define the area on the map. 
   
    Use the + button to zoom in and the - button to zoom out on the map. You can modify the geoposition by first clicking the Edit button (), and then clicking and dragging the handles or marker. Save or cancel edits by selecting the appropriate option .

   
   

   
   
   

7. Click OK. 
   
   The Create Context view reappears.
   
   
   
   

8. Optionally, import an image of the area.
   
   
   
   

9. Click Save.
   
   The Planning widget appears with the region you created.
   
   

Campus Context

To create a campus context, perform the following steps:

1. Hover over the region context and select the Create Child Context button ().
   
   
   
   The Create Child Context view appears.
   
   
   
   
2. Enter the context parameters as appropriate, including:
   
   
   • Name – name for the campus.
   • Type – Campus. This type is the parent context that houses 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. This type supports four geolocation latitude/longitude coordinates.
   • Description – optional description. 
   • Import Image – allows you to optionally import an image. Importing images for users with a Field Tech role is not supported.
   • Custom Fields (Tag / Value) – optional tag/value pairs.
     
     
     
     

3. Click the Pick Geoposition button () to set the geolocation.

   The Pick Geoposition view opens. The region you created will appear on the map where the area was defined.
   

   
   

   
   
   

4. Use the rectangle tool (  ) to define the area on the map.
   
    Use the + button to zoom in and the - button to zoom out on the map. You can modify the geoposition by first clicking the Edit button (), and then clicking and dragging the handles or marker. Save or cancel edits by selecting the appropriate option .

   
   

   
   
   

5. Click OK. 
   
   The Create Child Context view reappears.
   
   
   
   

6. Optionally, import an image of the area.
   
   
   
   

7. Click Save.
   
   The Planning widget appears with the campus you created.
   
   

Building Context and Setting Location

To create a building context as described in the steps that follow, first set the location and then save the settings. Next, you can optionally add an image and define the related fields by editing the building context. 

1. Hover over the campus context and select the Create Child Context button ().
   
   
   
   The Create Child Context view appears.
   
   
   
   
2. Enter the context parameters as appropriate, including:
   
   
   • Name – name for the building.
   • Type – 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.
   • Description – optional description.
     
     
     
     
3. Click the Pick Geoposition button ().
   
   The Pick Geoposition view appears.
   
   
   
   

4. Use the polygon tool (  ) to define the area on the map.
   
    Use the + button to zoom in and the - button to zoom out on the map. You can modify the geoposition by first clicking the Edit button (), and then clicking and dragging the handles or marker. Save or cancel edits by selecting the appropriate option .

   
   

   
   
   

5. Click OK. 
   
   The Create Child Context view appears.
   
   
   
   
6. Click Save.
   
   The Planning widget appears with the building you created.
   
   
   
   
7. To optionally import an image of the building, hover over the building context and select the Edit button ().
   
   
   
   The Edit Child Context view appears.
   
   
   
   

8. Optionally, import the building image by clicking the Import Image area and selecting the image from your computer. For devices to appear where they are expected on the map, continue with the steps below setting Base Point, True North Angle, and Drawing Scale. 
   

   
   
   

9. Optionally, set the Base Point: x / y reference for measuring distances and positioning contexts and devices in relation to the drawing. The base point is specified as the pixel x,y coordinates of the starting point of the drawing coordinate system. The default base point is 0, 0 representing the upper-left point, which is the first point in the image. For the building context, this field is not used for calculations.
   
   
10. Optionally, set the True North Angle, which is specified as true north angle - project north angle. That is, if the project north angle is oriented straight up, and with that orientation true north is 90 degrees, then the angle to true north is 90 (90 - 0). The default true north angle is 0 degrees. This value may be fractional. For the building context, this field is not used for calculations.
    
    
11. Optionally, set the Drawing Scale, which is the number of pixels per linear meter (number of pixels / linear meters). This value may be fractional. The default is 3 pixels per meter. For the building context, this field is not used for calculations.
    
12. Optionally, set the Geographic Location: Latitude / Longitude, or click the Set Location () button. These fields define the real-world location of the base point in latitude and longitude coordinates. For the building context, this field is not used for calculations.
    
    
13. Click OK. 
    
    The Create Child Context view appears.
    
    
    
    
14. Optionally, set the Custom Fields (Tag / Value) pairs.
    
    
15. Click Update.
    
    The Planning widget appears with the building you created.
    
    

Floor Context

To create a floor context, perform the following steps:

1. Hover over the building context and then select the Create Child Context button ().
   
   
   
   The Create Child Context view appears.
   
   
   
   
2. Enter the context parameters as appropriate, including:
   
   
   • Name – name for the floor.
   • Type – 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 – optional description.
     
     
     
     
3. Click the Import Image Floor area and upload the selected floor plan image from your computer. For devices to appear where they are expected on the map, continue with the steps below setting Base Point, True North Angle, and Drawing Scale. 
   
   
   
   
4. Set the Base Point: x / y reference for measuring distances and positioning contexts and devices in relation to the drawing. The base point is specified as the pixel x,y coordinates of the starting point of the drawing coordinate system. The default base point is 0, 0 representing the upper-left point, which is the first point in the image. 
   
   
5. Set the True North Angle, which is specified as true north angle - project north angle. That is, if the project north angle is oriented straight up, and with that orientation true north is 90 degrees, then the angle to true north is 90 (90 - 0). The default true north angle is 0 degrees. This value may be fractional. 
   
   Example:
   
   
   1. Consider the following location on the map (the arrow points to true north): 
      https://www.google.com/maps/@37.2921622,-121.9884976,475m/data=!3m1!1e3

      
      
      
      

   2. The floor plan appears as follows (the arrow points to true north):
      
      
      
      

   3. Measure the angle (green arrow) between true north (red arrow) and current "north" (black line). Always calculate the true north angle in a counter-clockwise direction.
      

      
      

      
      
      

      For this example, the true north value is 132.25 degrees.
      
      
6. Set the Drawing Scale, which is the number of pixels per linear meter (number of pixels / linear meters). This value may be fractional. The default is 3 pixels per meter. 
   
   Example:
   
   
   1. Measure the size of the building (360.20m for this example).
      
      
      
      

   2. Determine the pixel size of the image (662 for this example). For a Windows PC, the pixel size is displayed with the image file. For a Mac, right-click the image file and select Get Info.
      
      
      
      

   3. Calculate the drawing scale.
      
      For this example: 662 / 360.20 = 1.84 pixels per meter.
7. Set the Geographic Location: Latitude / Longitude, or click the Set Location () button. These fields define the real-world location of the base point in latitude and longitude coordinates. 
   
   
   
   
   1. If you click the Set Location button, then the following view appears:
      
      
      
      

   2. Zoom in on the map to set the building location. The latitude and longitude fields are set based on the building coordinates.
      
       Use the + button to zoom in and the - button to zoom out on the map. You can modify the geoposition by first clicking the Edit button (), and then clicking and dragging the handles or marker. Save or cancel edits by selecting the appropriate option .

      
      

      

   
   
   
8. Optionally, set the Custom Fields (Tag / Value) pairs.
   
   
9. Click Save.
   
   The Planning widget appears with the floor you created.
   
   

Room or Area Context

An area is a context type that is defined by its scope (campus or floor plan) 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 floor plan-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.

To create a room or area context, perform the following steps:

1. Hover over the floor context and select the Create Child Context button ().
   
   
   
   The Create Child Context view appears.
   
   
   
   
   
2. Enter the context parameters as appropriate, including:
   
   
   • Name – name for the room.
   • Type – 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. 
     
   • Select color – use the color palette to select the color for the area definition.

     
     
     

3. Use the polygon tool (  ) to define the area.
   

   
   
   

4. Click Save.
   
   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. Use the Edit feature for this context to define the physical area.
   
   
   
   

Importing a Context

To import a context, see Importing and Exporting SmartServer Configuration Files. 

Importing a context is not available for SmartServer 4.0. 

Exporting a Context

To export a context, click the Export button () on the Planning widget. You can also export contexts using the Import/Export button (). See Importing and Exporting SmartServer Configuration Files. 

A CSV file is created and saved onto your computer. This file contains the following information:

• Id – identifier used to build the context hierarchy (e.g., floor in Parent Id contains the value of the building id, building refers to campus, and campus refers to world).
• Name – name of the context.
• Description – (optional) description of the context.
• Image – (optional) image file.
• Image Type – if an image file is supplied, then this column defines the file type.
• True North Angle – (optional) specifies true north angle - project north angle. That is, if the project north angle is oriented straight up, and with that orientation true north is 90 degrees, then the angle to true north is 90 (90 - 0). The default true north angle is 0 degrees. This value may be fractional. For the building context, this field is not used for calculations.
• Image Latitude / Image Longitude – (optional) defined the real-world location of the base point in latitude and longitude coordinates. For the building context, this field is not used for calculations.
• Base Point X / Base Point Y – (optional) reference for measuring distances and positioning contexts and devices in relation to the drawing. The base point is specified as the pixel x,y coordinates of the starting point of the drawing coordinate system. The default base point is 0, 0 representing the upper-left point, which is the first point in the image. For the building context, this field is not used for calculations.
• Drawing Scale – (optional) specifies the number of pixels per linear meter (number of pixels / linear meters). The default is 3 pixels per meter. This value may be fractional. For the building context, this field is not used for calculations.
• Location – (optional) defines the points of the context polygon. For a room and area on a floor, it is represented by x, y points on a drawing. For all other context types, it is represented by latitude and longitude. 
• Type – defines the type of context (e.g., world, region, campus, building, floor, room, or area).
• Enabled – defines context availability. Devices cannot be assigned to disabled contexts. Currently, all the contexts enabled by default and are not configurable.
• Custom Fields – (optional) tag/value pairs. There are two reserved tags: 
  • color – for the color of rooms and areas on floors
  • floor number – for floors
• Parent Id – identifier used to build the context hierarchy (e.g., floor in Parent Id contains the value of the building id, building refers to campus, and campus refers to world).

Managing Contexts

Editing a Context

To edit a context, perform the following steps:

1. Hover over the context name and select the Edit button ().
   
   
   
   The Edit view appears.
   
   
   
   

2. Edit the context parameters as needed. A context type cannot be changed once it has been defined.

3. Click Update to save your changes.

Cloning a Context

To clone a context, perform the following steps:

1. Hover over the context that you want to clone (room context called Entry in this example).
   
   
   
   
2. Select the Clone button ().
   
   A copy of the context appears in an edit view.

   
   
   
   

3. Make any necessary context edits and click Clone. 
   
   A copy of the context appears in the Planning widget.

Removing a Context

To remove a context, hover over the context name and select the Remove button ().

The selected context is removed from the Planning widget.

Viewing Context Details

From the Planning widget, you can 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

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.
To view a context dashboard, hover over the context name and select the View Context Dashboard button (). 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. If not, then a Dashboard tab not found confirmation message message will appear.

Viewing and Managing Devices Assigned to a Context

You can visualize a context and see the devices that are assigned to it, as well as child contexts. From this view, you can also provision, deprovision, or reprovision devices, as well as unassign devices from contexts. To perform these operations, follow the steps below:

1. Hover over the context name and select the Visualize button ().
   
   
   
   

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

   
   
   

2. Use the device's Action button () to perform the following actions:

   1. Provision the device

   2. Deprovision the device

   3. Reprovision the device

   4. Unassign the device from the context
      
      
      
      

3. Click Back to return to the Planning widget.

Showing a Context on a Map

You can display a context on a map, hover over the context name and select the Show on Map button ().

The context appears in the Locations widget.

See Working with Maps for more information about how to use the Locations widget.