Datapoint Presets

Owned by Nina Cardillo
29-Sept-2023
Datapoint Presets is available with SmartServer 2.8 and higher.

Datapoint presets are discussed in Connections and Datapoint Objects property table.

This pages contains the following sections:

Using Presets and Localization Together

You can use both presets and localization properties at the same time.  When presets and localization are set for a datapoint, the presets map is configured based on the local value.  So when you get an update, the value needs to be localized first before mapping to a preset string.  Same with the other direction, when users input a preset string, the map value needs to be transformed using the reverse transformation rule to get the IAP value. 

The Presets Object

The presets object describes the presets.

  • Presets are optional. If the source/destinations do not have presets, the presets object is set to an empty object or null.
  • The presets object contains the presets transformations for the source and destinations.
  • The presets object is submitted with the connection object’s create or update actions and stored in the connection configuration objects.
  • The presets object is not stored in the connection object’s status.
  • The presets are optional.
  • Presets can be used with localization or can be used by itself.  If a localization rule is used, the presets are configured using the local values.
  • There is one presets map definition for the connection source. Multiple sources within the same connection use the same presets.  
  • Each destination can have different presets.
  • If the source/destinations do not have presets, the presets object is set to an empty object or null.
  • The presets transformation is applied at the data source and destination.
  • Data sent from segment S1 to segment S2 is first transformed using the presets definitions of segment S1. It reaches segment S2 in its preset form, and the destination segment S2 is responsible to apply the preset transformation (reverse transformation).

The following table describes the presets object properties:

Field Name       Type              Description
sourceObject. 
The presets transformation object for the source segment.

The source presets are global for all the datapoints sources. The source object is empty if there are no source presets.

{                                                          
  "$": {
     "transform": "$.value == 100 &&
       $.state == 1 ? \"ON\" : 
       $.value == 50 && $.state == 1 ?
       \"MID\" : $.value == 0 &&
       $.state == 0 ? \"OFF\" : \"INV\""
   }
}
destinationsList.
Items are the presets transformation object used in destination segment.

The name in the presets map for the datapoint source and destination must be exactly matched. If the destination onlyPreset option is set to true, the data will only be sent to the destination if the presets name maps to the destination presets. If the onlyPreset is set to false, the IAP/local value will be sent to the destination segment. 

The source object is empty if there are no destination presets.

[                                                           
   {
   "$": {
     "value": {
       "enumeration": {
         "source": "$",
         "map": {
           "ON": 90,
           "MID": 40,
           "OFF": 15
         }
       }
     },
     "state": {
       "enumeration": {
         "source": "$",
         "map": {
           "ON": 1,
           "MID": 1,
           "OFF": 0
         }
       }
     }
   },
   "onlyPreset": true
 }
]


In the following example, the data will not be sent to the destination segment.

presets: {                                                                                                                   
   source: {
     "$": {
         enumeration: {
           source: "$",
           map: {
               “1”: “OCCUPIED”,
               “0”: “UNOACCUPIED”,
           } //map
         } // enum
     }
   },
   destinations: [
   {
     "$": {
        enumeration: {
           source: "$",
           map: {
               "ON": 100,
               “OFF”: 0
           } //map
        } // enum
      },
     onlyPreset: true // only propagate the value 
                      // if preset value is present   
   }
   ]        // destination
}           // presets
repeatPresetsBoolean

The property repeatPresets is set to true if all the destinations use the same presets rule. If the repeatPresets is set to false and there are multiple destinations with presets, only the first destination uses presets. The rest of the destinations will not use presets.

The Presets Property

The Datapoint presets property of a datapoint object contains the following properties:

Field NameTypeDescription
enabledBoolean

(Required) Indicates whether to use presets. 

Possible values are True, False.

Default is True.

mapArray of Objects

(Optional) An array of presets to be used by this datapoint. It contains the preset string (the name property) maps to the corresponding IAP value (the value property).  map can be null or empty.  If map is not defined, there is no preset defined for this datapoint.

Field Name   Type              Description                                                                    
namestring

The name of the presets string.  name represents a specific native for a datapoint. 

valueobject

The presets value.  value has the same structure as the datapoint value.

Example:

map:[                                                                                                                           
{
   name:”OFF”,
   value: {
        state: SW_RECALL_SCENE,
        setting: {value: 0.0},
        scene_number:255
   }
},
  {
   name:”MAX”,
   value:{
         state: SW_RECALL_SCENE,
         setting: {value: 0.0},
         scene_number:1
}
},
  {
   name:”MID”,
   value:{
        setting: {value: 0.0},
        state: SW_RECALL_SCENE,
        scene_number:2
   }
},
{
   name:”MIN”,
   value:{
        state: SW_RECALL_SCENE,
        setting: {value: 0.0},
        scene_number:3
   }
}
]

Examples

Example 1

This example shows a datapoint property using presets:

Datapoint property with presets
received on glp/0/w73pa/fb/dev/lon/nc.3/if/DeviceA/0

{
   nvoHeatSetpoint: {
        default: null,
        desc: "",
        cat: "in",
        lt.cfg: {
            persistent: false,
            label: " nvoHeatSetpoint ",
            unit: "°F",
            handle: 17,
            length: 3,
            address: 16366,
            tag: {
            },
            forward: {
            },
            dynamicType: "static",
            status: {
            }
        },
        monitor: {
            rate: 10,
            lt.cfg: {
                propagationHeartbeat: 0,
                propagationThrottle: 0,
                maxRcvTime: 0,
                propagationThreshold: 0
            },
            cat: "data",
            inFeedback: false,
            report: "change",
            throttle: 0
        },
        presets: {
            enabled:true
            map:[
                { name:"OCCUPIED", value:69.80 },
                { name:"UNOCCUPIED", value:60.80 },
                { name:"STANDBY", value:65.00 }
           ]
        },
        property: false,
        type: "0000000000000000-0/SNVT_temp_p ",
        value: 69.8,
        state: "normal"
    },
}

Example 2

This example shows the presets where the datapoint is a structure.

Datapoint property with presets
    presets: {
        enabled:true
        map:[
            { name:"OFF", value:{state: SW_RECALL_SCENE, setting: {value: 0.0}, scene_number:255}},
            { name:"MAX", value:{state: SW_RECALL_SCENE, setting: {value: 0.0}, scene_number:1}},
            { name:"MID", value:{state: SW_RECALL_SCENE, setting: {value: 0.0}, scene_number:2}},
            { name:"MIN", value:{state: SW_RECALL_SCENE, setting: {value: 0.0}, scene_number:3}}
        ]
    },

Example 3

This example is in three parts. The first part shows a map being used to connect the source preset value and destination with different preset names.  

presets: {
   source: {
      "$": {
         transform: "$.value == 100 && $.state == 1 ? \"ON\" : \"OFF\""
      }
   },

   destinations: [
   {
      "$": {
         enumeration: {
            source: "$",	// the source enumeration value
            map: {
               "OCCUPIED": 72.0,
               "UNOCCUPIED": 68.2
            }  // map
            }  // enum
         },    // "$"
         onlyPreset: true   // only propagate the value if preset value is present
       } ]             // destinations
}            // presets


The above connection object needs the following map in the destination to translate ”ON” and “OFF” to “OCCUPIED” and “UNOCCUPIED”. Otherwise the value won’t be sent to the destination segment.

map: {
   "$": {
      enumeration: {
         source: "$",	  // the source enumeration value
         map: {
            "ON": "OCCUPIED",	 // source "ON" becomes "OCCUPIED",
            "OFF": "UNOCCUPIED", // source "OFF" becomes "UNOCCUPIED",
         }  // map
      }   // enum
   }   
}


With both transformations present, the destinations segment does the translation first (”ON” and “OFF” to “OCCUPIED” and “UNOCCUPIED) before it transforms the preset value.

destinations: [
   {
     map: {
        "$": {
           enumeration: {
              source: "$",  // the source enumeration value
              map: {
                 "ON": "OCCUPIED",
                 "OFF": "UNOCCUPIED"
              } //map
           }  // enum
       }  // "$"
     },   // map
     "$" : {
        enumeration: {
            source: "$",	// the source enumeration value
            map: {
               "OCCUPIED": 72.0,
               "UNOCCUPIED": 68.2
            }  //map
         }  // enum
      },  // "$"
      onlyPreset: true // only propagate the value if preset value is present
} ]

Example 4

In this example, the map transforms the source preset value to the destination preset value, where the first destination is a standard scalar SNVT_lev_percent type, and a second destination is a datapoint value of standard type SNVT_switch.

presets: {
   source: {
      "$": {
         enumeration: {
            source: "$",
            map: {
               "100": "ON",
               "50": "MID",
               "0": "OFF"
            }  //map
         }  // enum
      }
   },

   destinations: [
   {
      "$": {
         enumeration: {
            source: "$",
            map: {
               "ON": 97,
               "MID": 47,
               "OFF": 0
            } //map
         }  // enum
      },
      onlyPreset: true 
   },

   {
      "$": {
         value: {
            enumeration: {
               source: "$",
               map: {
                  "ON": 100,
                  "MID": 50,
                  "OFF": 0
                } //map
             }  // enum
         },
         state: {
            enumeration: {
               source: "$",
               map: {
                  "ON": 1,
                  "MID": 1,
                  "OFF": 0
               } //map
            }  // enum
         }
      }
      onlyPreset: true // only propagate the value if preset value is present
    }
  ]   // destinations
}  // presets