All Collections
Connect your Devices
Connect your Kontrolog devices over LoRaWAN to Ubidots
Connect your Kontrolog devices over LoRaWAN to Ubidots

Learn how to connect Kontrolog devices to Ubidots through TTN to monitor sensor readings, output status, perform remote control, and more.

S
Written by Sergio M
Updated over a week ago

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

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

  1. Register your Kontrolog device In The Things Network and then, on the left side menu, select “Integrations” → “Webhooks”.

  2. Create a new webhook by selecting the "Add Webhooks" option.

  3. Then select “Custom Webhook”.

  4. 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:

  1. To successfully complete this step, you must refer to the section “Create UbiFunction for downlink messages” in this guide.

  2. To save the code and start using it click on “make it live” at the menu on the left side.

  3. 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.

  1. 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

  1. The following is a summary of the communications protocol, if you would like more details, please contact Omicron IoT Solutions.

  2. All data frames sent to the device must be in a hexadecimal numeric system.

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.

Did this answer your question?