Constraints

Constraints are an important part of the parameter descriptor. It specifies a legal range of values which the value of the parameter may take. Certain constraints also impact how the parameter is displayed within DashBoard. Certain widgets require specific constraints, while others may behave in different manners depending upon the constraint applied to the parameter. For array parameters, the same constraint applies to each element of the array.

Constraints are specified through a numeric identifier called ctype. The supported constraint types are:

Constraint Name

ctype

Param Types

Description

NULL_CONSTRAINT

0

All

Parameter is unconstrained.

RANGE_CONSTRAINT

1

INT16_PARAM

INT32_PARAM

INT16_ARRAY

INT32_ARRAY

FLOAT_PARAM

FLOAT_ARRAY

Parameter is bounded by a min-max range. Display min-max range may be different from the value range.

CHOICE_CONSTRAINT

2

INT16_PARAM

INT16_ARRAY

Parameter must be selected from a set (enumeration) of name-value pairs (up to 255 choices)

EXTENDED_CHOICE

3

INT16_PARAM

INT16_ARRAY

Parameter must be selected from a set (enumeration) of name-value pairs (more than 255 choices)

STRING_CHOICE

4

STRING_PARAM

STRING_ARRAY

Provides a set of available choices. Parameter may be selected from this set, but arbitrary values are also permitted.

RANGE_STEP_CONSTRAINT

5

INT16_PARAM

INT32_PARAM

INT16_ARRAY

INT32_ARRAY

FLOAT_PARAM

FLOAT_ARRAY

Parameter is bounded by a min-max range. Step size indicates the amount to increment/decrement the value each time it is changed.

ALARM_TABLE

10

INT16_PARAM

INT32_PARAM

INT16_ARRAY

Each bit in the parameter is a status flag, so param can display 16 or 32 concurrent named error conditions.

EXTERNAL_CONSTRAINT

11

All

Indicates that the constraint is encoded in an external object, rather than encoded within the descriptor.

Constraints are normally embedded within the parameter descriptor however; they may also be encoded separately as external objects (which allow longer choice lists, etc.).

A detailed definition of each constraint type, and rules for encoding each constraint, are provided below.

Note:            The constraint is considered to be a contract for the parameter. DashBoard will not attempt to set a parameter to a value that violates the constraint. Similarly, the device must ensure that the value reported for each parameter complies with the constraint. Behavior of some control software may be unpredictable if the reported value violates the constraint.

Unconstrained

To leave a parameter unconstrained, use the NULL_CONTRAINT constraint. Any parameter which does not have any other constraint applied must specify the NULL_CONSTRAINT.

Range Constraints

To constrain a numerical parameter to a specific range of values, the RANGE_CONSTRAINT or RANGE_STEP_CONSTRIANT must be specified. Both constraint types allow a minimum and maximum parameter value (minValue, maxValue). Additionally, an optional display minimum and maximum value (minDisp, maxDisp) may also be specified. This allows the display range to map to normalized parameter range. The value to be displayed is determined by the following linear mapping:

 

       

 

Note that minDisp and maxDisp must be the same data type as the parameter. For example, to display the value of a 12-bit register (0-4095) as a percentage, set

·          (minValue, maxValue) = (0, 4095)

·         (minDisp, maxDisp) = (0, 100)

The difference between RANGE_CONSTRAINT and RANGE_STEP_CONSTRAINT is the latter also allows a step size to be specified. The step is specified in the same data type as the parameter and is the minimum change increment on the parameter value (not necessarily the display value).

Note             It is strongly recommended that the range (maxValue – minValue) be evenly divisible by the provided step size. Otherwise, when starting from the minimum, the parameter will use values of minValue + n * stepSize and when starting from the maximum, the parameter will use values of maxValue – n * stepSize.

Range constraints applied to an array parameter apply to all members of the array.


 

Choice Constraints

Choice constraints allow a parameter to provide a list of choices. CHOICE_CONSTRAINT and EXTENDED_CHOICE constraints provide a mechanism to create a set of enumerated values for an INT16 or INT32 parameter. This allows integer types to be limited to a specific set of valid values, as well as providing a mechanism to provide text choices in the DashBoard UI for these parameters.

STRING_CHOICE constraint provides a set of default values which may be populated in a STRING_PARAM, however unlike CHOICE_CONSTRAINT and EXTENDED_CHOICE, it does not limit the user to only these values, any arbitrary value may still filled into the string.

Alarms

Assigning an ALARM_TABLE constraint to an integer parameter tells DashBoard to treat the integer as an array of alarms. When alarms are set, they will impact the overall status reporting of the device.

External Constraints

An EXTERNAL_CONSTRAINT is used to indicate that the constraint for this parameter is provided in an external object, rather than embedded within the parameter descriptor.

This constraint simply provides a reference to the external object, encoded as shown in the following table.