What can we improve?

Documentation

(Edit)

Configurator

Requires: IP-Symcon >= 5.0

Describes the appearance and functionality of a configurator.

Example

This item is not supported by the Legacy Console. If a module with this element is opened in the legacy console, an error message appears.

General Parameters

Parameter Description
caption (optional) visible caption of the configuration list
columns (optional) (default: columns for address ("address") and name ("name")) Columns of the configuration list
delete (optional) (default: false) If true, a button is displayed behind each entry with InstanceID, which deletes the corresponding instance and updates the line in the configurator
name (optional) Name of the configuration list
rowCount (optional) (default: 0) visible number of lines; If there are more lines in the list, a scroll bar is shown - if the value is 0, the configuration list fills the remaining space in the instance editor. Only one configuration item can get all of the remaining space.
sort(optional) Sorting of the table. If this is not set, the list remains unsorted
type Configurator
values (optional) Entries of the form
visible (optional) (default: true) If true, the configurator is visible, otherwise it is invisible (since IP-Symcon 5.2)

If the parameters columns, sort or values are to be changed via UpdateFormField, the new values must be coded as JSON.

Parameters for Columns

Parameter Description
caption visible caption of a column
label visible caption of a column (deprecated)
name unique name of a column to refer to; the name cannot be "id", "parent", "create", "expanded" or "InstanceID"
visible (optional) (default: true) If false, the column is not displayed
width Width of the column in pixels, as a CSS string (e.g. "100px"); a single column may have the value "auto", which means that the width of this column uses the remaining available space. In the case of a tree, the value "auto" must be set for a column. The expansion symbols are displayed in this column.

Parameters for sort

Parameter Description
column Name of the column by which the list is sorted
direction The direction of the sort; "ascending" for an ascending order and "descending" for a descending order

Parameters for values

Parameter Description
address (optional) (default : "") If the default columns were used, the value for the address can be set with this parameter
create (optional) (default : error) Specification of the configuration of the created instance (More information)
expanded (optional) (default : false) If this value is true, the entry is expanded directly when the configuration form is loaded
InstanceID (optional) (default : 0) InstanceID of the device in the object tree, 0 if the device has not yet been created
id (optional) An identifier with which the entry for a tree display can be addressed as a parent node, id must be greater than 0
name (optional) (default : "") If the default columns were used, the value for the name can be set with this parameter
parent (optional) (default : 0) The id of a value can be set in this field, which becomes the parent node of this value in the tree display. For this, the parent value must come before of the child in the array. If "parent" is 0, the element is inserted at the top level.

Parameter for Create

There are various options for defining the instances to be created and their initial configuration.

Variant 1: Configuration of a Single Instance

In the first variant, a single instance and its configuration is defined. In this case create is an object that contains information about the ModuleID used and the initial configuration:

Parameters for configuration

Parameter Description
moduleID The module ID of the instance required or to be created
configuration The required configuration of the instance, see IPS_SetConfiguration, not coded as a JSON string
location (optional) (default: []) The list of strings indicates the initial position in the object tree. If the list is empty, the instance is created in the main category. Otherwise, the categories with the respective name are used hierarchically and created if necessary.
info (optional) (default: "") The initial description of the newly created instance; if an existing instance is used, the description is not overwritten.
position (optional) (default: 0) The initial position of the newly created instance; if an existing instance is used, the position is not overwritten.
name (optional) (default: module name or value of the "name" column) The initial name of the newly created instance; if an existing instance is used, the name is not overwritten. (since IP-Symcon 5.5)
noDiscovery (optional) (default: false) If this parameter is set to true, this entry is not displayed as a device in the Device Search and cannot be marked as read. In the case of a configuration as a chain (variant 2), the value of the first entry in the chain is used. If there are several possible configurations (variant 3), each configuration must have this parameter set to true so that the selection does not appear in the Device Search. (since IP-Symcon 5.4)
statusVariables (optional) (default: {}) This object specifies an initial configuration of the status variables. For each parameter of this status variable object, the variable with the ident of the parameter name is configured. The associated parameter is another object that defines the configuration of the variables. The variable configuration is used after the instance configuration has been adopted. Variables that are created later cannot be configured here. (since IP-Symcon 5.3)

Parameters for status variables

Parameter Description
name (optional) (default: specification by created instance) The status variable is renamed to this value. The name is translated through the localization of the configurator.

If an instance is created, it is created with the ModuleID and configuration specified by the configuration. As is usual with the creation of an instance, the new instance is linked to a valid physical parent instance, if possible. The physical parent instance of the configurator is preferably used here.

Variant 2: Configuration of a Chain

Alternatively, a chain of configurations can be used. This defines the entire physical chain for the newly created instance, usually the device, splitter and I/O. In this variant, data.create represents a list, the elements of which define the instances of the physical chain as in variant 1. The list begins with the device to be created and then continues with the next parent instance.

When creating a chain, existing parent instances are preferably reused, provided that these and their parent instances meet the requirements of the chain. However, the device itself will always be newly created.

Variant 3: Several possible Configurations

Finally, several configurations can be made available for selection. Here create is configured as an object with key/value pairs, whereby each value corresponds to a configuration as described in variant 1 or variant 2. If an instance is to be created in this representation, the user is given a selection of the designations. The instance is created with the settings of the selected item. The keys "moduleID" and "configuration" cannot be used here.

Colors in the Configuration List

What the individual colors mean in messages and in the configurator can be read under the color codes for [messages][messages] and configurators. The element presents this information as follows:

Color Condition
green InstanceID is 0, create is defined
red InstanceID is not 0, create is not defined or the defined InstanceID does not exist
gray The instance with the ID InstanceID is not configured as specified by create. If create represents a chain, the line is also displayed in gray if a physical parent is configured differently than defined in the chain
white InstanceID is 0, create is not defined (category)
white The instance with the ID instanceID is configured as specified by create. If create represents a chain, the line is only displayed in white if all physical parents are configured as defined in the chain

Use the Configurator Form Field in the Device Search

The console offers Instances that can be created centrally via the Device Search. This is done by regularly calling GetConfigurationForm for Instances of the type Configurator and Discovery and evaluating the parameter values for configurator fields. Only configurator and discovery instances that contain at least one configurator field are displayed in the Device Search. In this, values can also be empty. If the own instance is to be seen in the Device Search, the following conditions must therefore be met:

  • The instance must be of the type Configurator or Discovery
  • The search for devices must be started automatically when executing GetConfigurationForm. If the search takes longer, values should be left empty in an initial return, but after the search has been completed, the devices that can be created must be included in the return of GetConfigurationForm
  • The search should not be restarted when GetConfigurationForm is called repeatedly if it is currently running
  • An example implementation can be found here: SymconTest

Selected Line as a Variable in on-Actions

The use of the values of the configurator in scripts is analogous to Lists. All values are available there, including InstanceID and create. However, the configurator does not save any values in a property.

Example

// Basic example
{
    "type": "Configurator",
    "name": "Configuration",
    "caption": "Configuration",
    "delete": true,
    "values": [
        {
            "id": 1,
            "name": "Category",
            "address": ""
        },{
            "parent": 1,
            "name": "Calculation module - minimum",
            "address": "2",
            "create": {
                "moduleID": "{A7B0B43B-BEB0-4452-B55E-CD8A9A56B052}",
                "configuration": {
                    "Calculation": 2,
                    "Variables": "[]"
                }
            }
        },{
            "parent": 1,
            "name": "Computing module in the living room",
            "address": "2",
            "create": {
                "moduleID": "{A7B0B43B-BEB0-4452-B55E-CD8A9A56B052}",
                "configuration": {
                    "Calculation": 2,
                    "Variables": "[]"
                },
                "location": [
                    "Ground floor",
                    "Living room"
                ]
            }
        },{
            "parent": 1,
            "instanceID": 53398,
            "name": "Incorrect instance",
            "address": "4"
        },{
            "parent": 1,
            "name": "Calculation module - selection",
            "address": "2",
            "create": {
                "Maximum": {
                    "moduleID": "{A7B0B43B-BEB0-4452-B55E-CD8A9A56B052}",
                    "configuration": {
                        "Calculation": 3,
                        "Variables": "[]"
                    }
                },
                "Average": {
                    "moduleID": "{A7B0B43B-BEB0-4452-B55E-CD8A9A56B052}",
                    "configuration": {
                        "Calculation": 4,
                        "Variables": "[]"
                    }
                }
            }
        }, {
            "parent": 1,
            "name": "OZW772 IP-Interface",
            "address": "00:A0:03:FD:14:BB",
            "create": [
                {
                    "moduleID": "{33765ABB-CFA5-40AA-89C0-A7CEA89CFE7A}",
                    "configuration": {}
                },
                {
                    "moduleID": "{1C902193-B044-43B8-9433-419F09C641B8}",
                    "configuration": {
                        "GatewayMode":1
                    }
                },
                {
                    "moduleID": "{82347F20-F541-41E1-AC5B-A636FD3AE2D8}",
                    "configuration": {
                        "Host":"172.17.31.95",
                        "Port":3671,
                        "Open":true
                    }
                }
            ]
        }
    ]
}
 
// Example with renaming of status variables
{
    "type": "Configurator",
    "values": [{
        "name": "Calculation module (renamed status variables)",
        "address": "Address",
        "create": {
            "moduleID": "{A7B0B43B-BEB0-4452-B55E-CD8A9A56B052}",
            "configuration": {},
            "statusVariables": {
                "Minimum": {
                    "name": "Alternative name for minimum"
                },
                "Maximum": {
                    "name": "Alternative name for maximum"
                }
            }
        }
    }]
}

[messages]: /en/service/documentation/developer-area/sdk-tools/sdk-php/messages/#color codes

Deutsche Webseite verfügbar
Go to cart
Any questions?