Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Info

For SmartServer 3.0-3.2, see Defining Datapoint Connections (Release 3.0-3.2)

For SmartServer 2.9 or prior, see Defining Datapoint Connections (Release 2.9) 

...

Info
titleWith SmartServer 3.3 or higher

Connections are no longer automatically deployed by importing a connection file. Additionally, importing an empty connection file (i.e., a connection file header, but no rules or connection template details defined) does not delete connections. Instead, the Connections widget should be used to deploy and remove connections. 

A Connection Template (specified by a Template Name) comprises two or more lines in the CSV file. All lines in the connection file that apply to the same Template Name will have the same Template Name. Each connection template specifies one or more source datapoints and one or more destination datapoints.

...

Depending on your SmartServer application, it can take one to five minutes for connections to be deployed or removed. That is, if you deploy a connection and the Connection widget Connection Templates tab indicates that the connection template is deployed, the connection actually may not yet have been fully processed, and it can take several minutes for the connection to work. You may be able to speed up this process by using the Devices widget pause button to stop background datapoint monitoring, but remember to resume this feature when you are finished deploying or removing connections, otherwise your datapoints will not be updated with newer values.

...

The SmartServer needs to be able to communicate with the device in order to create or remove connections.

Importing a New Connection File

Each time a new connection file is added, the new rules (based on Template Name) are checked against the existing rules. A rule that is in the existing and new connection file is unchanged. Any new rule that is added, and any old rule that does not exist in the new connection file, is deleted. Therefore, in order to add, change, or delete connections, a new connection file with all the desired connections needs to be imported.

Clearing Connections

The CMS Connections widget should be used to clear connections.

  1. Use the Deployed Connections tab to remove the connections, but keep the connection template.
  2. Use the Connection Templates tab to delete the connection template, and remove the connections from the devices.

...

The SmartServer needs to be able to communicate with the device in order to create or remove connections.

Creating a Connection File

...

A connection file contains the following columns (not case sensitive, and parameter columns can be in any order):

Note
titleUsing formulas

For more information about specific parameters and formulas, see also Using Presets, Localization, and Map in the Defining Connection Templates section.

If you are using presets

entries blank.

Presets should be defined in the Datapoint Properties widget or the DLA file file prior to the deployment of connections. If you configure Presets in the Datapoint Properties widget or the DLA file after deploying connections, then different connection results will be produced.

title

Prior to SmartServer 3.3

Prior to SmartServer 3.3

, this parameter was comprised of Presets and Repeat Presets.

For backward compatibility of the Presets and Repeat Presets fields, these fields will be imported, but will no longer be exported. The SmartServer will use preset definitions from the Datapoint Properties widget if the Use Presets is specified as Exclusive or Non-Exclusive

Localization should be defined in the Datapoint Properties widget or the DLA file file prior to the deployment of connections. If you configure Localization in the Datapoint Properties widget or the DLA file after deploying connections, then different connection results will be produced

.Prior to SmartServer 3

.

3

Prior to SmartServer 3.3, this parameter was comprised of Localization and Repeat Localization.

For backward compatibility of the Localization field, this field will be imported and converted to a transformation setting, but will no longer be exported. If a connection file specifies both a Localization value and a Transform value, then the SmartServer will combine them into a single Transform value. The SmartServer will use localization definitions from the Datapoint Properties widget if specified in the Use Localized Value field.

For backward compatibility of the Repeat Localization field, this field will be imported, but will no longer be exported. The SmartServer will use localization definitions from the Datapoint Properties widget if specified in the Use Localized Value field. If repeat localization is true, then the value specifies that the localization rule defined on the same line as the true is repeated for all subsequent destination datapoints without defined localization rules. In this case, the SmartServer will copy the localization to all other datapoints without a defined localization rule and always set the repeatLoc property to false when sending to IAP/MQ. If Repeat Localization is not true, then the localization rule is not repeated.

Parameter                      Description
Template Name

Connection unique identifier. All connection filters with the same template name define a connection template. There should be at least one source and at least one destination entry with the same Template Name.

Reference Type

Specifies the type of datapoint reference. Values may be Fixed or Relative (case insensitive). If Reference Type is not specified, it is assumed to be FixedIf a Device Name is specified then Reference Type is assumed to be Fixed. If a Device Name is not specified then Reference Type is assumed to be Relative.

Fixed datapoint means that you are specifying the device name.  Contexts, Target Type, Target Name, and Device Type can be blank.

Relative datapoint means that you are specifying a device type based on a context.  

Contexts

List of full context paths that the template applies to, with optional wildcards for any level of the context hierarchy. Context paths are separated with a semicolon.

If contexts are specified for a fixed datapoint reference, and the context does not match any of the contexts containing the device specified with the device name, the CMS will display a warning message.

If a connection template contains context-relative datapoints, then contexts should be defined for that template, otherwise no connections will be created. Only the first Contexts entry that is found for a template is used (others are ignored). The CMS will always export an empty value for the context for a specified context that does not match one of the contexts of the device specified by the device name.

Target TypeTarget Type is used when Reference Type is Relative. Valid values are: blank, none, campus, campus area, building, floor, floor area, or room (case insensitive; spaces and separators are ignored).
Target Name

Target Name filter is used with Target Type.

Example: The Target Type is room and you have the following room names: boiler, kitchen, office A, office B. If you specify "office" for the Target Name, then this connection Template Name only applies to office A and office B.

Device NameDatapoint XIF name. This parameter must be specified for a fixed datapoint. This parameter is ignored with warning for context-relative datapoints. The CMS will always export an empty value for a context-relative datapoint reference. 
Device Type

Device Type Name. This field is required for a context-relative datapoint reference. This field is optional for a fixed datapoint reference.

If the Device Type is specified for a fixed datapoint reference and the Device Type does not match the Device Type of the device specified with the Device Name, then the CMS will display a warning message. The CMS will always export an empty value for the type for a specified device type that does not match the device type of the device specified by the device name.

Datapoint Name

Datapoint XIF name.

note

Each datapoint has a datapoint instance name and a datapoint XIF name. The datapoint XIF name is shown in the CMS Datapoints widget (called the Datapoint Browser widget for SmartServer 3.3 and prior releases) details view and in the Datapoint Properties widget. This parameter specifies the datapoint XIF name.

DirectionSource or Destination. If the field is not specified, or is specified but empty, the direction will be source for non-writable datapoints and destination for writable datapoints.
Map

Mapping formula (JSON object) where $ is source value. This field is used for Source Map only. For destination mapping, use Localization or Preset Map.  $ is source value and map formula.

Examples:

Scalar (temperature in Celsius to temperature in Fahrenheit):

{"transform": "$ * 1.8 + 32"}

Map formula to go from scalar to  structure datapoint (SNVT_count to SNVT_Switch which has two fields, state and value):   

{"state":{"transform":"$ ? 1 : 0"},"value":"$"} 

If doing a FAN IN connection, and the source datapoints have different map formulas, then you need to create separate rules for each source datapoint and include the same list of destination for each rule.

(optional parameter)

Use Presets

Use Presets values may be ExclusiveNon-ExclusiveNo, or blank. This field is optional when importing a connection file, and if not included or blank, the default value for a connection member will be Non-Exclusive.

All sources must share the same presets. On import, if multiple sources have Use Presets values, only the first is used. Destinations may have different Use Presets values defined. The SmartServer will always 1) export a Use Presets column, 2) include the value for a connection template in the first connection member entry, and 3) leave all subsequent connection member entries blank.

Note
title
Info
Use Localized Value

Use Localized Value specifies whether or not to apply the localization transformation specified for the datapoint in the Datapoint Properties widget. The valid values for this field are YesNo, or blank. If this field is not included or is blank, the default value for a connection member will be Yes. If transformation is not defined in the Transform field, then the default is Yes, and the localization transform that is defined in the Datapoint Properties is used; otherwise the default is No.

The same localization rule applies to all sources in a connection template. This field is optional when importing a connection file. All sources must share the same localization. On import, if multiple sources have localization definitions, only the first is used. Destinations may have different localization defined.

The SmartServer CMS will always export a Use Localized Value column.

Note
titleIf you are using localization
Info
title
Transform

Transform defines a transformation to be applied to the datapoint. For a source value, the transformation will be applied to the value prior to sending the value to the destinations. For a destination, the transformation will be applied to a received value prior to sending the value to the destination. 

...

Connection file presets and localization are independent of Datapoint Properties (or DLA file) presets and localization, and only apply to the connections. Datapoint Properties (or DLA) presets and localization do not apply to connections. Converting a temperature datapoint from degrees Celsius to degrees Fahrenheit is typically done through the Datapoint Properties (or DLA file) and not the connection file. 

For more information about specific parameters and formulas, see also Using Presets, Localization, and Map in the Defining Connection Templates section.

Connection File Examples

Info
titleUse of quotation marks

Quotation marks are used for parameters and values that have spaces.

Examples: 

"Datapoint Name"
"AV/7/Room Temperature"

Using map, presets, and localization in datapoints is optional. A datapoint can have map only (sources), presets only, localization only, all (i.e., map, presets, and localization), or none. When both presets and localization are used, the presets map are typically configured based on the localization value. Therefore, when an update is received, the value needs to be localized first before mapping to a preset string. And, when a preset string is entered, the map value needs to be transformed using the revert transformation rule to get the native value. 

...

titleUsing formulas

For more information about specific parameters and formulas, see also Using Presets, Localization, and Map in the Defining Connection Templates section.

To use the example files shown in this section, first copy the text to a text editor (e.g., notepad), then save as text, and finally change the extension to .con.csv. At this point, you can view the files using Excel.

...

The LON peer-to-peer connection shown below is only available for LON devices (DMM mode only). All other examples show point-to-point connections, which are used for all protocols including BACnet, Modbus, and LON connections. For point-to-point connections, you should configure the Datapoint Properties widget prior to deploying the connection template.

...

For example, consider a scenario where you only configured the destination localization (you did not apply a source localization) and you want to send a temperature value from one device to another, where both devices use Celsius, and Fahrenheit values appear in the SmartServer CMS. In this case, once you deploy your connection template and the source datapoint changes, the value sent to the destination will be incorrect, since the localization should be set for both datapoints, not just the destination. Therefore, all updates to the destination will be incorrect. However, if you set the localization in the Datapoint Properties widget for the source to transform the temperature reading to Fahrenheit, the connection will work correctly without having to re-deploy of the template. The outcome is that the connection results changed based on when you configured the presets and localization.  

...

...

If you have presets or localization enabled for any connection template, connection rule, then you must always configure the preset and localization settings in the Datapoint Properties widget before deploying the connection template.

Note
titleFor IMM only
For IMM only, and if all connections are only between LON devices, then you must always specify a map formula. If a map formula is not already specified, then you must add a map formula of "{"$":"$"}" (as shown for the Connections widget or in an Excel spreadsheet), or add "{""$"":""$""}" to map directly in the connection file. In DMM, a map formula is not required.

...

LON Peer-to-Peer Connection (DMM only)
Anchor
LON DMM
LON DMM

Note
Note: Used for DMM only. Source and destination datapoints are the same datapoint type.

...

LON Point-to-Point Connection (IMM only)

Note
Note: For IMM only, and if all connections are only between LON devices, then you must always specify a map formula. If a map formula is not already specified, then you must add a map formula of "{"$":"$"}" (as shown for the Connections widget or in an Excel spreadsheet), or add "{""$"":""$""}" to map directly in the connection file.

...

You can add a single map formula to the connection template, which is applied to all source datapoints. 

With Two Sources and One Destination (Different Source Mapping)

Note
Requires two source rules, one for each destination.

The following connection file example shows two sources that are connected to, and one destination, with each source having a different mapping transformation. Since each source has a different mapping formula, you need to create multiple connection template (i.e., separate templates for each mapping transformation):

  • create a connection template for sourceA/destA
  • create another connection template for sourceB/destA
#filetype,con
"Template Name","Reference Type",Contexts,"Target Type","Target Name","Device Name","Device Type","Datapoint Name",Direction,Map,"Use Presets","Use Localized Value",Transform
c9,Fixed,,,,PulseGen-2,pulseGen-1,device/0/nvoCount,Source,"{""transform"": ""3.5*$""}",No,No,
c9,Fixed,,,,PulseGen-1,pulseGen-1,device/0/nviPower,Destination,,,No,
C8,Fixed,,,,PulseGen-1,pulseGen-1,device/0/nvoCount,Source,"{""transform"": ""sqrt($)""}",No,No,
C8,Fixed,,,,PulseGen-1,pulseGen-1,device/0/nviPower,Destination,,,No,

...