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:
Type | Description | Supports default values? |
text |
An arbitrary string of text | Yes |
number |
A number. Can both be integer and floating points values. | Yes |
device_id |
The id of a device claimed into the current project. | No |
ip_address |
A special kind of text string, that must be formatted like an IP address | Yes |
element_id |
The id of an element defined in the current project. | No |
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:
- 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.
- 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:
Type | Description |
|
The user id of the user running this 1-click configuration. |
|
The id of the currently active project. |
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_limit
are 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
Field | Data type | Default value | Description |
alarm_owner |
string |
|
The owner of the alarm. |
alarm_parameter |
string | "" |
The element id used to evaluate the state of the alarm. |
|
string must be either "interval" , "offline" or "bitwise" |
"interval" |
The type of the alarm. See the guide on Alarms for a description of the functional description of the different types. |
bit_position |
number | 0 |
Only applicable to alarms with type = "bitwise" .The bit position to evaluate in the current value of the element referenced in the alarm_parameter field. If the bit is high, the alarm is activated and vice versa. |
lower_limit |
number | NaN |
Only applicable to alarms with type = The lower limit of the alarm parameter. The alarm will activate, when the measured value is below this value. |
upper_limit |
number | NaN |
Only applicable to alarms with type = The upper limit of the alarm parameter. The alarm will activate, when the measured value is above this value. |
department_id |
string | "" |
The id of the department, that this alarm is associated to. |
private |
boolean | false |
If this alarm is only visible to the user listed as the alarm_owner or if it's visible to anyone with access to the given project. |
max_offline |
number | 1.0 |
Only applicable to alarms with type = The number of hours allowed without new measurements received from the |
devices
Field | Data type | Default value | Description |
name |
string | "" |
The name of the device. |
max_offline |
number | 0 |
The maximum time in seconds between tranmissions. |
|
number | 60 |
The maximum time in seconds between sensor samplings. |
channels |
map | {} |
The channels map different sensor inputs and outputs signals to specific elements. This is described further below. |
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
Field | Data type | Default value | Description |
name |
string | "" |
The name of the element. This name will also be reflected in all widgets showing values from this elements, so it's good practice to keep it short. |
unit |
string | "" |
The unit of the parameter, that this element represents (eg. "°C" og "ppm" ) |
color |
string (hex code) | "" |
The hex color code used for the element, eg. "#FF2D00" |
element_type |
string must be either |
"monitor" |
The type of the element. This determines if the element represents an input value (monitor) or output value (actuator). |
source |
string |
"" |
A string containing a path to where the value of this element is created (like a specific subchannel on a device). |
department_id |
string | "" |
The id of the department, that this element is associated to. |
reports
Field | Data type | Default value | Description |
name |
string | "" |
The name of the report. |
report_interval |
string must be either |
"weekly" |
The interval, that this report should automatically be generated with and sent to the subscribers (defined only in the frontend). If set to "never" , the report can still be generated manually in the frontend with the defined settings |
|
string | "{{current_user}}" |
The owner of the report. |
element_ids |
[string] array of strings |
[] |
An array of the element ids, that should be included in the report. |
widgets
Field | Data type | Default value | Description |
type |
string must be either
element-tile ,
element-btn-tile , datalog-plot , or
recent-alarms |
"" |
The type of widget to create. |
folder |
string | "" |
The widget id of the parent folder. |
|
number | 0 |
An integer used to determine the order, that the widgets should be shown in the dashboard. |
|
string | "New folder" or "New group" |
Only applicable when type =folder or type =group . |
element |
string | "" |
Only applicable when Element id that this widget should show values from. |
elements |
[string] array of strings |
[] |
Only applicable when Array of element id's, that should be included in the line chart. |
dynamic_name_from_element |
string | "" |
Reference to an element id, who's value will be used as the name of the widget. If left empty, the value in the name field will be used. |
departments
Field | Data type | Default value | Description |
name |
string | "" |
The name of the department. |
batch_mode |
boolean | false |
Whether this departement is operated in batch mode. |
|
number | 0.0 |
Only applicable when Unix timestamp in seconds indicating when the last batch was started. |
batch_end |
number | 0.0 |
Only applicable when Unix timestamp in seconds indicating when the last batch was stopped. |
batch_active |
boolean | false |
Only applicable when Whether the department is currently running an active batch. |
dynamic_name_from_element |
string | "" |
Reference to an element id, who's value will be used as the name of the department. If left empty, the value in the
|
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.