The Kontrolog device is a programmable controller for IoT (Internet of Things) designed for remote and real-time control and monitoring of different processes with high security and precision requirements. It can be connected to a touchscreen HMI for local visualization and configuration.
The Kontrolog devices have a dual communication module Sigfox/LoRaWAN that allows them to send data to Ubidots through either of these two networks, giving it a plus in different application fields, such as industry, agriculture, water quality, home automation, among others.
Following this guide you’ll be able to connect the Kontrolog to Ubidots using The Things Network (TTN). From there, you’ll be able to perform, among other things:
Remote monitoring and visualization of current measurements, state of the outputs and sensor’s variable records, in graphs and data tables, for up to 2 years.
Remote configuration of the device parameters.
Alarm management for variables out of range, battery levels, and AC power failure.
Set alarm limits, alarm events, and notifications via email, SMS, voicemail, Telegram messaging service, or webhooks.
Requirements
The Things Network (TTN) account
1. Setting up the Kontrolog
The Kontrolog is powered by a two-wire power cable connected to its AC1 and AC2 inputs (shown in the image below) and connected to the 110 - 220 VAC, 50/60 Hz lines. Alternatively, the AC1 line can be jumpered to the terminals CM1 and CM2, if you wish to use either of the 12A relay outputs: RE1 or RE2 (note that each 12A output uses 2 terminal blocks).
Once the equipment is powered, it will start its “normal operation state”, which can be recognized when the LED shown in the image below flashes every second.
2. Setting up TTN
2.1. Callback configuration for LoRaWAN uplink messages
Register your Kontrolog device In The Things Network and then, on the left side menu, select “Integrations” → “Webhooks”.
Create a new webhook by selecting the "Add Webhooks" option.
Then select “Custom Webhook”.
Configure the Webhook as follows, and then press “Save Changes”.
General settings:
Webhook ID: ID assigned by you.
Webhook format: JSON
Endpoint settings:
Base URL: This is the URL generated in the third section of this guide by the uplink UbiFunction in the field "HTTPS Endpoint URL”, without the function's name. The resulting URL should look like:
https://parse.ubidots.com/prv/your_ubidots_username
Downlink API Key: Information given in “Downlink API Key”, below.
Request authentication: Unchecked.
Enabled messages:
Uplink message: Enable and add the path with the name of the Uplink UbiFunction that will be created in the third section of this guide. The resulting URL should look like this:
/your_ubifunction_name
Example: /kontrolog-uplink
All other fields remain unchecked.
You’ll see this in the “Webhooks” section:
2.2. Downlink API Key
To obtain this parameter, follow the steps below:
1. In TTN, go to the application associated with your Kontrolog device and select “API Keys”.
2. Select the option “Add API Key”.
3. Configure the webhook as follows and then press “Create API Key”.
Name: The name that you want to assign to the new API Key for downlink messages. Example: downlink-key.
Rights:
Grant all current and future rights: Disabled.
Grant individual rights: Enable and check:
“Link as Application to a Network Server for traffic exchange, i.e read uplink and write downlink”.
“Read application traffic (uplink and downlink)”.
4. The following window will appear, copy the API key (after closing it will never be shown again) and click on “I have copied the key”.
5. Then edit and copy this API key in your Webhook → "Downlink API key".
2.3. Format for uplink payload
1. In TTN, go to the application associated with your Kontrolog device and select “Payload formatters” → “Uplink” on the left side menu.
2. Then, enter the following information in the corresponding fields:
Formatter type: Custom JavaScript formatter
Formatter code: Copy and paste the next function code:
function decodeUplink(input) {
var data_payload = "";
for(i = 0; i < input.bytes.length; i++){
var chr = input.bytes[i].toString(16);
if(chr.length == 1)
chr = "0" + chr;
data_payload += chr;
}
return {
data: {
//data_raw: input.bytes
data: data_payload
},
warnings: [],
errors: []
};
}
3. Uplink function to post data to Ubidots
Below is the representation of how information travels from a Kontrolog device to Ubidots through the LoRaWAN network:
3.1. Create the UbiFunction for uplink messages
To process and decode the data frames sent to Ubidots it’s necessary to create an UbiFunction.
With this process you’ll create a function that decodes the Omicron IoT Solutions' own communication protocol. This protocol is loaded in the default firmware of the Kontrolog, however, you also have the option to program on your own for the Kontrolog using blocks of code provided by Omicron (visit the following link for more information). If you use your own communication protocol, you’ll have to create your own decoder in Ubidots. |
1. Once in the UbiFunction’s code editor page, delete the sample code and paste the one corresponding to your Kontrolog’s version in the following link:
2. In the code, replace these fields:
Token: A token is a unique key that authorizes requests sent to Ubidots. To obtain your token, you can follow the steps found in this guide.
In the downlink_request function, place in the URL field the URL generated by the downlink UbiFunction in the field "HTTPS Endpoint URL".
Notes:
To successfully complete this step, you must refer to the section “Create UbiFunction for downlink messages” in this guide.
To save the code and start using it click on “make it live” at the menu on the left side.
In the given UbiFunction code, all sensor readings are divided by 10. However, depending on the type of sensor chosen, scaling may have to be done by 100, or scaling may not be necessary (see Table 5).
Therefore, you must adjust the sensor reading on the Dashboard (multiply or divide by 10 or others), if required.
3.2. Communications protocol for Uplink messages
The following is a summary of the communications protocol, if you would like more details, please contact Omicron IoT Solutions. |
The data-sending frame for the LoRaWAN network has a standard size of 18 or 20 bytes, depending on whether it is Kontrolog 9.2 or 9.3. For this network, the uplink data frame sent by the Kontrolog has the structure shown in the following table.
Table 1
Bytes 0 and 1 | Bytes 2, 3, 4 | Bytes 5, 6, 7 | Byte 8 | Byte 9 | Bytes 10 and 11 |
Message Code: 4 Bits Sensor 1: 12 Bits | Sensor 2: 12 Bits Sensor 3: 12 Bits | Sensor 4: 12 bits Sensor 5. 12 bits
|
Battery Voltage |
AC Voltage | AC Current: 10 bits Status of the Output: 6 Bits |
Bytes 12, 13, 14, 15 | Byte 16 | Byte 17 | Bytes 18 and 19 |
Unix timestamp: 32 bits. Seconds elapsed since 1970 |
Downlink message: 1 bit
| Position of the data stored in memory: 8 bits | Output # 5 current: 12 bits (Only for Kontrolog 9.3) |
Message code: Code that indicates whether the message is a normal operation message or an alert message.
Sensor 1 to 5: Current value of the sensors connected to ports 1 to 5.
Battery voltage, AC voltage, AC current: Voltage at the connection port for external 12 V battery, supply AC voltage read by the instrument 0 to 255 VAC, and AC current value read by the sensor.
Status bits: The status of the relay outputs are indicated. The bit 0 indicates general alarm status, where 0: no alarm active 1: some alarm active.
Unix timestamp: Timestamp in seconds elapsed since 1970 used to record the date and time of messages received on the platform, and to store with a correct timestamp the messages backed up in memory in case of network connection loss.
Downlink message: Announces that the device is available to receive downlink messages.
Position of the data stored in memory: Memory position of a message backed up in case of network loss. Up to 140 messages can be stored.
Output # 5 current: Value of the current at output #5 (4-20mA) scaled by 100.
4. Downlink function to get data from Ubidots
4.1. Create UbiFunction for downlink messages
To send data frames from Ubidots to the Kontrolog device it’s necessary to create an UbiFunction.
With this process you’ll create a function that sends data frames from Ubidots to the Kontrolog devices, according to the Omicron IoT Solutions' own communication protocol. This protocol is loaded in the default firmware of the Kontrolog, however, you also have the option to do your own programming for the Kontrolog using code blocks provided by Omicron (visit the following link for more information). If you use your own communication protocol, you’ll have to create your own function to send downlink messages from Ubidots. |
Once in the UbiFunction’s code editor page, delete the sample code and then paste the code found here and replace this field:
Token: A token is a unique key that authorizes requests sent to Ubidots. To obtain your token, you can follow the steps given in this link.
To save the code and start using it click on “make it live” at the menu on the left side.
4.2. Communications protocol for downlink messages
|
The downlink message sent from the application software has a maximum of 8 bytes and is interpreted as follows:
Table 2
Byte 0 | Byte 1 | Byte 2 | Bytes 3, 4, 5, 6 | Byte 7 |
Group of parameters | Reserved (0x00) | Selected parameter | Data or value: 4 Bytes | New downlink pending |
The following table shows the possible groups of parameters that can be modified:
Table 3. Group of parameters
Group of parameters | Hexadecimal code | Group Selected |
1 | 0x01 | Configuration parameters of sensor 1 |
2 | 0x02 | Configuration parameters of sensor 2 |
3 | 0x03 | Configuration parameters of sensor 3 |
4 | 0x04 | Configuration parameters of sensor 4 |
5 | 0x05 | Configuration parameters of sensor 5 |
6 |
0x06 | Configuration parameters of battery sensor |
7 |
0x07 | Configuration parameters of AC Voltage sensor |
8 |
0x08 | Configuration parameters of current sensor |
11 | 0x0B | Configuration parameters for output 1 |
12 | 0x0C | Configuration parameters for output 2 |
13 | 0x0D | Configuration parameters for output 3 |
14 | 0x0E | Configuration parameters for output 4 |
15 | 0x0F | Configuration parameters for output 5 |
20 | 0x14 | General settings for the Kontrolog device |
22 | 0x16 | Settings for the RTC |
4.2.1. Modification of sensor parameters (parameter group 1 to 8)
This group of downlink messages allows you to modify parameters such as:
Alarm limits,
Alarm delays,
Activate/deactivate a sensor, among others.
Refer to tables 4 and 5 to find out the types of parameters that can be modified for the inputs.
Table 4. Sensor parameters
Parameters for sensors | Hexadecimal code | Name | Observation |
2 | 0x02 | Type of sensor | Sensor Type (See Table 5) |
4 | 0x04 | Enable/Disable Sensor | 1: Sensor Enabled 0: Sensor Disabled |
5 |
0x05 |
Reading Adjustment (Offset) | Reading adjustment (offset) of the sensor:
To adjust the reading value of a sensor, a linear scaling can be used, in the form:
Adjusted V. = ( Read V. + Offset)*Slope. |
6 | 0x06 | Lower Alarm Limit | Lower Alarm Limit |
7 | 0x07 | Upper Alarm Limit | Upper Alarm Limit |
8 |
0x08 | Alarm Activation Time Delay in seconds | Time in seconds to delay the alarm activation |
9 | 0x09 | Reading Record Address | Modbus |
10 |
0x0A |
No. of records to be read on Modbus
Load Resistance for the Current Sensor | Modbus: Number of registers to be read.
For the current sensor only: Load resistance: 60 ohms for 30A transformer 36 ohms for 50A transformer 18 ohms for 100A transformer |
11 |
0x0B |
Data format | Modbus register format 0 : Integer 1 : Integer with one (1) tenth (multiplied by 10) 2 : Integer with two (2) tenths (multiplied by 100) 3 : Float (IEEE 754-2008) 4 : Inverse Float (starts the transmission of the frame from the least significant byte) |
12 |
0X0C |
Slope (or scaling) | Slope value (scaling) of the sensor:
To adjust the reading value of a sensor, a linear scaling can be used, in the form:
Adjusted V. = ( Read V. + Offset)*Slope. |
Table 5. Sensor Types
Sensor Type | Hexadecimal code | Description | Resolution (in tenths) |
1 | 0x01 | Digital Sensor 0/1 | 0 |
2 | 0x02 | Current Sensor 4 - 20mA | 2 |
3 | 0x03 | Voltage Sensor 0 - 10V | 2 |
4 |
0x04 | Temperature Sensor NTC 10K - 3950 |
1 |
5 |
0x05 | Ambient Temperature Sensor |
1 |
6 | 0x06 | Ambient Humidity Sensor | 1 |
7 | 0x07 | Digital Pulse Counter 0/1 | 0 |
8 | 0x08 | Remote value sent from the platform | 1 |
9 | 0x09 | Modbus Input | 1 |
10 | 0x0A | Frequency Input (Input No. 5 only) | 1 |
Example:
We want to modify the type of sensor of input N°1, to configure it as a 4-20mA current sensor.
To edit Sensor 1’s configuration parameters you must select “Parameter Group 1: 0x01”. Then, in Table 4, you’ll see that the numeric code corresponding to the “Sensor Type” configuration is 2: 0x02. Finally, refer to Table 5 to see that the numeric code corresponding to the 4-20mA “Current Sensor” is 2: 0x02.
There are also no more downlink messages accumulated or pending to be downloaded since we only wanted to set up a single configuration.
Then:
Parameter group: 01
Parameter for sensors: 02
Data or value: 00 00 00 00 02
New downlink pending: 00
Therefore, the following frame is sent by a downlink message:
0x 01 00 02 00 00 00 02 00
4.2.2. Modification of output parameters (Parameter group 11 to 15)
This group of downlink messages allow you to modify parameters such as:
Function assigned to an output,
Control variable,
Set-point, among others.
To know the types of modifiable parameters for the outputs, refer to Tables 6 to 8
Table 6. Output parameters
Output parameters | Hexadecimal code | Name | Observation |
1 |
0x01 |
Remote command output status | Changes the state of the analog or relay output (1: closed, 0: open), when the output control function is configured to remote commands (Tables 7 and 8: 0x01). |
2 |
0x02 |
Selected Control Function | Type of Control Actuation for the Output, See Tables 7 and 8. |
3 |
0x03 |
Assigned Control Signal | 0 : No Control Signal 1 to 5 : Sensor Inputs 1 to 5 |
4 |
0x04 |
Set-Point Value | Desired value for control from -40.0 to 2047.0 |
5 |
0x05 |
Control Differential or Hysteresis | 0.0 to 20.0, is the Control Range programmed around the Set-Point. |
6 |
0x06 |
Control Type (Invert Output) | For the Control Function: 0 : Normal Output (cooling) 1 : Inverted Output (heating)
For the Timer function: 0 : The timer is activated when the Control Signal is less than the Set-Point. 1 : The timer is activated when the Control Signal is greater than the Set-Point.
For the Event Counter: 0: If # Pulses < Set-Point ==> Output = OFF If # Pulses >= Set-Point ==> Output = ON 1: If # Pulses < Set-Point ==> Output = ON If # Pulses >= Set-Point ==> Output = OFF |
7 |
0x07 | Cycle Time ON programmed for the Timed Output
Cycle Time for the PID Control |
1 to 32767 seconds |
8 |
0x08 | Cycle Time OFF programmed for the Timed Output
Time to make Control Calculations for the PID Control | 0 to 32767 seconds |
9 |
0x09 | PID Control: Proportional Action | 0 to 50% |
10 | 0x0A | PID Control: Integral Action | 0 to 50 |
11 | 0x0B | PID Control: Derivative Action | 0 to 50 |
12 |
0x0C | PID Control: Maximum Power to apply at the Output | 10 to 100% |
Table 7. Control Function Types assigned to a Digital Output
Control Function | Hexadecimal code | Description |
0 | 0x00 | Output Disabled |
1 |
0x01 | Digital Output controlled by remote commands sent from platform (0/1) |
2 |
0x02 | Digital Output follows associated Digital Sensor Input |
3 | 0x03 | On/Off Control Function |
4 | 0x04 | Timer Function |
5 |
0x05 | Remote Alarm Function (1: Alarm present on any of the 8 sensors, 0: No sensor is in Alarm State) |
6 | 0x06 | Event Counter |
7 | 0x07 | PID Control |
32 |
0x20 | This command allows resetting the output: it clears timers and counters and resets the output to OFF for 10 seconds, then reapplies the previously selected Control Function. |
Table 8. Control Function Types assigned to the output No. 5 Analog (only applies to Kontrolog 9.3)
Control Function | Hexadecimal code | Description |
0 | 0x00 | Output Disabled |
1 |
0x01 | Analog output value sent from the platform: Supported range 0 to 1000 0 = 0.0% = 4mA 1000 = 100.0% = 20mA. |
2 |
0x02 | Analog output (4-20mA) proportional to an associated analog input. 4mA: Input Value <= Input Lower Limit (Parameter 6 Table 3-1) . 20mA: Input Value >= Upper Input Limit (Parameter 7 Table 3-1). |
7 |
0x07 | PID Control Proportional output 4-20mA 0 % : 4mA 100 % : 20mA. |
32 |
0x20 | This command allows resetting the output: it clears timers and counters and resets the output to OFF: 4mA for 10 seconds, then reapplies the previously selected Control Function. |
Note: Output resolution 0.1% or 0.016 mA
Example 1:
We want to assign the “Control output 1” as an ON/OFF control function. Therefore, the “Set-Point” should be set to 37.1.
To edit configuration parameters of “Output 1”, you must select “Parameter Group 11: 0x0B”. Then, in Table 6 you can see that the numeric code corresponding to the “Control Function” configuration is 2: 0x02. Finally, you should refer to Table 7 to see that the numerical code corresponding to the “Control Function ON/OFF” is 3: 0x03.
Lastly, as a second configuration is still to be performed by means of a downlink message, which will be the modification of the “Set-Point”, then it’s indicated that a new downlink is still pending: 1: 0x01.
Consequently, the following frame is sent by a downlink message:
0x 0B 00 02 00 00 00 03 01
Then we proceed to modify the “Set-Point” to 37.1. Therefore, according to Table 6, it’s observed that the numerical code to modify the “Set-Point” is 4: 0x04. It’s also indicated there that the “Set-Point” has a decimal resolution, which means that the number sent through the downlink message must be scaled by 10; thus, 371: 0x173 is sent.
No more configurations will be sent for the moment by means of downlink messages.
As a result, the following data frame is sent:
0x 0B 00 04 00 00 01 73 00
Example 2:
The output 2 is configured with the type of control function of the remote commands sent from the platform. It’s desired to remotely activate the relay. Therefore, according to Table 6, the numerical code to send a remote command to modify an output status is 1: 0x01. It’s also indicated there that a 1 must be sent to close the relay. As a result, the following data frame is sent:
0x 0C 00 01 00 00 00 01 00
4.2.3. General settings of the Kontrolog devices (Parameter group 20)
Table 9. General settings parameters
General Settings Parameters | Hexadecimal code | Name | Observation |
1 |
0x01 |
TPU | Time of publication (in minutes) of sensor data. |
4 |
0x04 |
Normal restart of the device | Send parameter = 1, performs a software reset of the device. |
6 |
0x06 |
Configure communication module | Identifies the type of communications module used by the device. 0: Disabled 1: Sigfox 2: WiFi 3: LoRaWAN |
8 |
0x08 |
Number of uplink messages to make a downlink | Every how many Uplink messages it queries the platform if it has a downlink or configuration message.
|
9 |
0x09 |
RF Zone | Send parameters: 1: For the Europe region. 2: For the regions USA, Mexico, Brazil. 4: For the regions Latin America and Australia. |
4.2.4. Configurations for the RTC (Parameter group 22)
Table 10. RTC parameters
RTC Parameters | Hexadecimal code | Name | Observation |
1 |
0x01 |
Time Stamp | Timestamp in seconds elapsed since 1970 (Unix). Used to synchronize the RTC and to correctly store messages backed up in memory. GMT-0 time zone is used. |
2 |
0x02 |
Time Zone | Time zone where the device is located. Not critical for backing up messages to memory. |
For the device to synchronize its RTC correctly for all networks, it’s required to send a message to synchronize the time: 0x160001{time_stamp}00, when there are no other downlink messages pending to be sent. This way, the time will be synchronized correctly in the device, which is key to perform time-dependent tasks.
Also, to display the correct time on the screen, the Time Zone must be sent with the command: 0x160002{time_zone}00.
5. Send downlink messages with an Ubidots widget
To send the remote configuration messages you must create a new HTML canvas widget. To do so, follow the steps below:
1. Click on the "+" button at the upper right corner of your dashboard. Once the widget drawer opens, look for and select the HTML Canvas option.
2. Click on the "code editor" box to edit and enter your HTML, CSS and JS code.
3. Once the code editor opens, paste the following codes in each corresponding tab, and then click on “accept”.
Note:
You must put your token in the JavaScript code. A token is a unique key that authorizes requests sent to Ubidots. To obtain your token, you can follow the steps given in this link.
4. Next, click on the "3rd party libraries" box, add the following libraries, and click on “accept”.
https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js
https://use.fontawesome.com/releases/v5.3.1/js/all.js
5. After finishing the configuration of your widget click on “save”.
6. After saving the configuration, you will see a widget like the one shown in the following image. To change its size, drag the little arrow at the bottom right of the widget.
7. Finally, make sure your Kontrolog device is associated with the dashboard where your newly created widget is located. To do this, click on the dashboard menu button (the hamburger button located at the upper left corner of the dashboard).
8. Edit the dashboard and make sure that:
Your dashboard is “dynamic (single device)”.
The “default device” of the dashboard is your Kontrolog device.
After clicking on “save” you can now use this remote configurator widget to remotely set parameters of your associated Kontrolog device, according to the Omicron IoT solutions downlink communications protocol.