Creating a Connection (CON) File Manually
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)
This section describes how to create a connection file manually and defines the connection file parameters. After you manually create the connection file, you can use the Connections widget to import the connection file. See Creating Connections Using the CMS Connections Widget for information on how to use the Connections widget.
This section consists of the following:
Using Connection Files
With 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.
You should use the Connections widget to import connection files (*.con) and to deploy the connections.
Once you import your connection file, use the Connection widget to make sure your connection template settings are what you expect.
You should also use the Connections widget to remove connections from devices, or to delete connection templates (which also removes the connections from the devices).
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.
- Use the Deployed Connections tab to remove the connections, but keep the connection template.
- 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 embedded metadata tags anywhere in the file, and typically in the first line:#filetype,con
Connection files are CSV files categorized by the extension .con, .csv, or .con.csv (not case sensitive). The #filetype tag is equal to con (not case sensitive) and is identified by its file name. A connection file can be imported with any of the mentioned file extensions, and must use CSV formatting. In order to be able to double-click the file and view it in Excel, you should use the .csv or .con.csv extension. The file will be most easily identified using .con.csv.
The following examples are provided:
- Example formulas
- Example CSV files
1. Example formula – the following formula can be added to a connection file first, by opening the file in Excel, and then by pasting the file formula.
This example formula appears in Excel or the Connections widget such as:
{"state":{"transform":"$ ? 1 : 0"},"value":"$"}
The corresponding CSV file format for the above formula is to double all double quotes, and add double quotes at the beginning and end of the formula. This is handled automatically if you add the formula above using Excel. If you change the connection file using notepad you will need to add the CSV format as shown below.
If you open the file in a text editor (i.e., notepad), you will see the following:
"{""state"":{""transform"":""$ ? 1 : 0""},""value"":""$""}"
2. Example CSV files – already show converted formulas. Just copy the CSV file data to a text editor (i.e., notepad) and save it with a .csv extension (or .con.csv). You can then view the connection file in Excel.
Connection (CON) File Parameters
A connection file contains the following columns (not case sensitive, and parameter columns can be in any order):
| 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 Fixed. If 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 Type | Target 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 Name | Datapoint 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. 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. |
| Direction | Source 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 Exclusive, Non-Exclusive, No, 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. 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. 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. |
| 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 Yes, No, 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. 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, 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. |
| 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
Use 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. 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.
Template Names use a Fixed (specify Device Name) or Relative (Specify Device Type) Reference Type.
The Template Names that specify Device Type require you to assign the device to a Context or Target Type (e.g., Floor or Room). Contexts are created and viewed using the Planning widget and devices are assigned to a context using the Device widget.
When creating a Template Name for structured datapoints, you need to specify $ which means entire value, or specify the preset or transform for each field. That is, you cannot create a rule that specifies a transform for just a specific field. It is specified for either the entire value $ (which means all the fields), or you have to create separate transforms for each field.
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.
If you have presets or localization enabled for any connection rule in a connection template, then you may see different connection results if you modify the presets and/or localization after deploying the connections. That is, if you deploy a connection template with presets and localization configured, but not specified in the Datapoint Properties widget, your connection will work one way, and after you change the presets or localization in the Datapoint Properties widget, the connection may work a different way.
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.
For IMM only
Single Connection Template
The following connection file example shows a connection with both the source datapoint and destination datapoint using the same datapoint type.context and device type.
#filetype,con |
Fixed versus Relative Reference Types
The following connection file example shows a connection with the source datapoint using a fixed reference type, and a destination datapoint using relative reference type. For fixed reference type, the device name is specified. For relative reference type, you have to specify Contexts, Target Type, and Device Type. In addition, if you are using relative datapoints and all the devices are LON device, you need to make sure a point-to-point connection is used instead of peer-to-peer.
#filetype,con |
This connection example above is made into a point-to-point by specifying the map to be as follows: "{""$"": ""$""}".
LON Peer-to-Peer Connection (DMM only)
The following connection file example (Device Name specified) shows two peer-to-peer connection (source and destination devices are LON devices) the format without using map, transform, presets, and localization.
#filetype,con |
Peer-to-peer connections are configured in the edge devices so you will see faster updates as the source datapoint is sent directly to the destination datapoints. This means that you do not have to set up Datapoint Properties widget for peer-to-peer connections to work.
LON Point-to-Point Connection (IMM only)
This is the same connection as above, but a map formula is added for IMM.
#filetype,con |
With Source Map
The following connection file example (Device Name specified) shows how the map parameter can be used when going from a scalar datapoint to a structured datapoint. The map parameter allows you to modify the source datapoint values.
#filetype,con |
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)
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 |
With Transform
The following connection file example shows the format for transform. Transforms allow you to create a transformation formula on either the source or destination datapoints. This feature is useful if you have multiple destinations, but the destination datapoint values are treated differently. In the example below, the source datapoint value is "(4 * source_datapoint_value) + 5" and the other is "3 * source_datapoint_value".
#filetype,con |
When using the transform parameter, you will almost always use a transform function as shown above.
With Presets
The following connection file example shows the format for presets. Presets allows you to selectively control which datapoint source values are propagated to the destinations. It can also be used if the source and destination datapoint types are different. Only source values that match a source preset and have a matching destination preset are propagated to a destination. You will need to configure the preset values in the Datapoint Properties widget (or DLA file) first, and then deploy the connections.
#filetype,con |
When using presets, it is important to always setup the Datapoint Properties prior to deploying the connection template. Once you deploy the connection, any preset changes that you make will be used without having to re-deploy the connection template. As a result, the connection will work differently if you make preset changes before deploying the template vs. if you make preset changes after you deploy the connection template.
With Localization
The following connection file example shows the format for localization.
#filetype,con |
When using localization, it is important to always setup the Datapoint Properties prior to deploying the connection template. If you setup the localization after deploying the connection you will get different connection results.
With Presets and Localization (One Source and Two Destinations)
The following connection file example shows the format for presets and localization. Configure the presets and localization in Datapoint Properties widget prior to deploying the connection template.
When presets and localization are used on both the source and destination, the source value goes through the source localization. Next, if there is a match to any source preset value, then the source preset is checked against the destination preset. If there is a match, then the destination preset value goes through a reverse destination localization, and is finally sent to the destination datapoint.
#filetype,con |
When using presets and localization, it is important to always setup the Datapoint Properties prior to deploying the connection template. If you setup the presets or localization after deploying the connection, then you will get different connection results.