When you are working with projects with many devices and elements, it can take a long time to manually enter all the required inputs. 

To help with this process, Consibio Cloud has a feature called 1-click configurations, which are pre-defined setup templates, that you can open up, supply a few inputs, and then the system helps you create all the included contents in bulk. This can be used for everything from setting up devices, configuring the dashboard, creating alarms and much more.

This is a guide to help you create your own 1-click configuration files. 
Before you begin experimenting with you own 1-click configuration files, be aware that they potentially can change everything in you Consibio Cloud project (however, changes are always limited to the given project).

Therefore, if you are testing new configuration files, it can be a good idea to create a new Consibio Cloud project to run your tests in. When you have something you are sure works, delete the test project and run the 1-click configuration in the intended project.

Overview

1-click configuration files (1-click configs for short) are essentially JSON-files (simple text files with a special syntax and a .json file type) formatted in a specific way, that makes it possible for Consibio Cloud to parse the contents.

Top-level structure

On a top-level, 1-click configs have the following structure:

{
    "config": {
        "alarms": {},
        "devices": {},
        "elements": {},
        "reports": {},
        "widgets": {},
        "departments": {}
    }, 
    "user_input": {
    }
}

There are two primary sections in the file: a "config" section and a "user_input" section. The config section contains all the information that will be used to create/modify the contents of the Consibio Cloud project. As shown, this can be used to create or modify the setup of alarms, devices, elements, reports, widgets and departments. The setup of these are described in the sections below.

Values in the config section can either be static, or they can use templates, that change depending on inputs from the user running the 1-click config in the Consibio Cloud project. These template fields are defined in the user_input section of the 1-click config.

If a 1-click config is used multiple times with the same inputs, it will not create new config entries, but overwrite the ones already defined in the project. 

Example

Say we want to create a 1-click config, that makes it very easy to create a new alarm, that triggers each time an element has a value that is over 9000. The element, should be selectable by the user running the 1-click config. For that, we need to define an entry in the alarms section describing the alarm configuration, and define the needed user_input:

{
    "config": {
        "alarms": {
            "over_9000_alarm_{{my_element_id}}": {
                "name": "Over 9000 alarm ({{my_element_id}})",
                "type": "interval",
                "alarm_parameter": "{{my_element_id}}",
                "upper_limit": 9000
            }
        }
    }, 
    "user_input": {
        "my_element_id": {
            "name": "Element to use as alarm input",
            "type": "element_id"
        }
    }
}

As seen, you can leave out any sections, that you don't use in the 1-click config.

Select the file:

Now, you see an input field. Use it to select an element (here, we selected a measurement called "H2S"):

When you go to the alarm tab, you should now see that an alarm has been created for the element:

User inputs

User inputs are templates, that can be used in the config section and change the content values depending on selections made by the user running the 1-click config.

The 1-click config can hold any number of user inputs. Each input is defined by a template id, which is used in the config section to refer to the input's value. For each of these inputs, a name and type of the input must be defined. The name simply defines what is shown to the user during selection and the type defines what kind of input is required from the user.
For some inputs, a default value can additionally be defined, which will be used if the user does not provide an input. These parameters are structured in the user input section as such:

{
    "user_input": {
        "<user_input_1>": {
            "name": "<name of input>",
            "type": "<type of input>"
        },
        "<user_input_2>": {
            "name": "<name of input>",
            "type": "<type of input>",
            "default": <default value of shortname_2>
        },
    }
}

Here, two user inputs are shown with the template id's <user_input_1> and <user_input_2>. These template id's must be unique, but you can define any number of them you like.

So in our Over 9000 alarm example above, the 1-click config uses a single user input with the template id my_element_id and a type of element_id.

Supported input types

There are currently 5 different input types, you can use in the user inputs section:

Using user inputs in the config section

The whole purpose of user inputs is to use them in the config section. When writing the config section, you can use a template placeholder, that refers to a specific user input based on it's template id. These placeholders can be placed anywhere in the config section by writing the template id enclosed in double brackets:

{{<user_input_1>}}

User inputs can be used to set the value of different fields in the config section, like shown for the alarm_parameter field in the Over 9000 alarm example above:

                "alarm_parameter": "{{my_element_id}}", 

In this case, this structure ensures that the selected element will be used as the basis for the alarm.

However, the templates can also be used as a small part of a larger field. For example the name field in the Over 9000 alarm is defined as:

                "name": "Over 9000 alarm ({{my_element_id}})",

If the user selected an element with the id "my_element_123", then the created alarm would have the full name "Over 9000 alarm (my_element_123)" (note the parenthesis around the template in the field). Such a structure can make it much easier to distinguish it from other alarms in the user interface once created, if multiple alarms are created from the same 1-click config by running it several times with different user inputs.

Using templates in config section ids

Templates can also be used directly in the id's of the entities in the config section. In the Over 9000 alarm example, this is done as such:

{
    "config": {
        "alarms": {
            "over_9000_alarm_{{my_element_id}}": {

Such a structure has two effects, which can be very useful:

1. It ensures, that a new alarm will be created, whenever the user changes the value of the my_element_id input. Therefore, the same 1-click config can be used many times with different inputs to quickly create equally many new alarms in the project.
   
   
2. If the 1-click config is called two times with the same input, then the second time it is called, it will simply overwrite the already created alarm. This can be used to reset the alarm to the default settings defined in the 1-click config.

Therefore, if you put some thought into when and how you put templates directly into config id's, you can therefore define the behaviour of the system when the 1-click config is called several with the different combinations of user inputs.

Global templates

There are some values, that are globally available even though you don't specifically define them in the user input section. You can use these in the config section without any doing anything further or asking for an input by the user. These are listed below:

These template id's are also reserved and you cannot use them in your own user input section.

Config Sections

You can use 1-click configs to alter the setup of almost all the different entities (devices, elements, reports etc.) in a Consibio Cloud project. You can see all the different types of entities in the config section of the Top-level structure shown above. In all cases, the key used for the given entity represents that entity's id and nested entries are the fields for the given entity. In the Over 9000 alarm example, the id is over_9000_alarm_{{my_element_id}} and the nested keys name, type, alarm_parameter and upper_limitare fields of the alarm config.

When defining them, we have to follow a specific schema for the different fields in each entity type. The schema for each entity type are listed in the sections below.

Schemas

alarms

devices

Channels

The channels defined for a device maps different inputs and outputs to elements and configures various settings for the I/O operations. A channel can implement different protocols or drivers for specific chipsets or sensors and the collection of available channels is continuously growing, as we increase support for various signals and protocols.

However, some channels depend on specific hardware (eg. a RS485 transceiver for Modbus RTU or various discrete circuitry analog 4-20 mA signals) so the selection of available channels depend on the type of device, the combination of expansion boards used and the firmware version of the device.

This gives a lot of different combinations to consider, which is beyond the scope of this guide. So here we only present how to setup the channels, which are most commonly configured using 1-click configurations. If you want to go further than that, please reach out on support@consibio.com and we will provide the documentation needed on request.

Channels and subchannels

A channel is general specification for a type of signal or protocol, that should be configured on the device. That could be a ModbusTCP channel, a ModbusRTU channel, a 4-20mA input channel etc.

A channel has one or more subchannels. One subchannel is always mapped directly to one element. For a ModbusTCP channel, you would create a subchannel for each register, that is then mapped to an element in Consibio Cloud.

Channels can have configurations on both the channel level and the subchannel level. The structure and fields of these configurations depend on the individual channel type. 

Modbus TCP

ModbusTCP channels can be used on Consibio's Network Connector devices. These are often used to collect many different values from a SCADA system or a single PLC and send them to Consibio Cloud. Therefore, they are often used to integrate tens or hundreds of different values and thus require a lot of different entries and is a perfect fit for 1-click configurations.

ModbusTCP channels are defined with a channel id of the form modbusTCP::<IP> where <IP> should be replaced with the IP address of the modbus server. If this is always fixed, it can be entered directly in the 1-click config, but if it changes from time to time, it would be a good candidate for a user input.

If you for example want to create a 1-click config for reading a temperature measurement on a ModbusTCP server with slave_id 1, that is saved as a REAL datatype on register 41125, but let the user define the IP address of the server, then you could structure it like this:

{
    "config": {
        "devices": {
            "{{device_id}}": {
                "channels": {
                    "modbusTCP::{{ip_address}}": {
                        "sub_channels": {
                            "temp": {
                                "config": {
                                    "dt": "REAL",
                                    "input": true,
                                    "reg": 41125,
                                    "slave": 1
                                },
                            "element_id": "my_element_id_{{ip_address}}"
                        }
                    }
                }
            }
        },
        "elements": {
            "my_element_id_{{ip_address}}": {
                "name": "Temperature ({{ip_address}})",
                "unit": "°C",
                "element_type": "monitor",
                "color": "#1eab81",
                "source": "devices/{{device_id}}/modbusTCP::{{ip_address}}/temp",
            }
        },
    }, 
    "user_input": {
        "device_id": {
            "name": "Device to use as gateway",
            "type": "device_id"
        },
        "ip_address": {
            "name": "IP Address of Modbus server",
            "default": "10.4.1.11",
            "type": "ip_address"
        },
    }
}

This would allow the user to first select a device to use as gateway and then enter the IP address of the server and everything else would happen automatically. This could also easily be extended further with the reading of many more registers, the automatic creation of associated widgets etc.

Note that we here embed the IP address in the id of the element, such that a unique element will be created for each different modbus server, this 1-click config is executed for. 

elements

reports

widgets

departments

Upcoming features

We are working on a feature, where we can host the 1-click configurations for you such that it easily can be shared in your organization, but it's not possible yet, so for now you have to save the files yourself.