Docs
mobileIoT Suite
Documentation

How-To: Sending data to the Data Portal

This guide provides a step-by-step introduction to using the IoT Builder tool. By following the instructions below, you’ll learn how to send signals from an ecomatDisplay or CR3171 to the Data Portal.

⚠ Important Note :
This guide applies to the ifm mobileIoT IoTBuilder CR31xx.package version 3.0.0.0 or newer.
The guide below is using a CR3171 firmware version 3.1.0.

Use cases

The IoT Builder tool allows you to transmit data from your PLC to the Data Portal. Two device families are currently supported. The CODESYS logo indicates where device programming is required.

Sending data from ecomatDisplay
ℹ Good to know:
The communication between the ecomatDisplay and a CR3171 is encrypted via HTTPS.

One use case is sending data over Ethernet from an ecomatDisplay to one of the mobileIoT gateways:

Sending data from the CR3171

Another use case is to program the CR3171 to collect Data from one of the CAN Buses using the ifmRawCAN.library or receiving data over Ethernet from any IP device and then using IoT Builder to send it to the Data Portal:



Prerequisites

1. Added CR3171 with minimum FW 3.1.0

2. Running data contract (at least CZ1100 )

3. The time on the device you are using CODESYS on should be set correctly. Otherwise, the time of the data in the Data Portal will be different

4. Setting up the mobileIoT gateway:

CR3171

  1. Log into the WebUI of the CR3171 by following CR3171 WebUI Login
  2. Set a password for the file upload to the device by following Setting password for file upload.
  3. Set a password for the API by following setting password for api.

5. Installed CODESYS packages on the service pack version for your device you are programming with CODESYS:

Install packages

5.1 Launch CODESYS Installer and select the appropriate service pack

⚠ Important Note :
Close all instances of the service pack in which you are going to install the packages


5.2 Install the CODESYS package exported from IoT Builder after deployment. (See Deployment )

After installation you should see:


5.3 Install the latest IIoT Libraries SL package by searching for it in the CODESYS Installer:


6. If using this on the CR3171, you have to enable the CODESYS Runtime via WebUI to be able to connect to the device via CODEYS:


⚠ Important Note :
The versions may differ after your installation, due to newer released packages.


Step 1: IoT Builder in mobileIoT suite

Project settings and signal definition

1. To begin, click on "IoT Builder" to open the tool.


2. Enter General Project Information

  1. Project information: Name of your project
  2. Project target :
    1. Selecting a machine: Data Portal configuration of selected machine is getting adjusted
    2. Selecting a gateway: Only export of IoT Builder project settings and CODESYS related files
  3. My setup:
    1. Controller type: Device the IoT Builder is going to run on
      1. ecomatDisplay with CR3170 : Any ecomatDisplay together with a CR3170
      2. ecomatDisplay with CR3171 : Any ecomatDisplay together with a CR3171
      3. CR3171 : On the CR3171 itself
    2. Controller interface: Always ETH
    3. Modem IP Address: IP of the mobileIoT gateway
  4. GPS
    1. Enable: Enable if GPS data is needed (enabled by default on CR3171 FW ≥ 1.7.0)
    2. Cycle: Time interval for GPS data collection
    3. Distance: Not used for CR3170 and CR3171

3. Define your signals you want to send to the Data Portal

  1. Signal type: Standardized metric or create own metric
  2. Signal details: Customize name and unit
  3. Configuration
    1. Cycle : Time interval for data collection
      ⚠ Important Note :
      Cycle time must be minimum 15 seconds.
    2. Trigger : Variable in CODESYS triggering logging of the Application Variable. Define this variable if you want to log the value of the variable on an event.
    3. Application variable : Name of the CODESYS variable holding the value
    4. Type : CODESYS data type
    5. Category :
      1. Up counter: The value is counting up
      2. Down counter: The value is counting down
    6. Permission : Access control in Data Portal

  4. Transformation : Optional value transformation


Deployment to your machine

The deploy button deploys the signals to the Data Portal to the selected machine and lets you export the settings as well as CODESYS Code and package.


1. Deploy settings for your machine


2. Post deployment

If you have an already running IoT Builder in your CODESYS application and you just want to update the signals that have changed use this option:


If you dont have a running IoT Builder in your CODESYS application select the second option. This "Archive file" will include a CODESYS package and if necessary all Application variables defined as signals can be added into a GVL (global variable list) for use in CODESYS.


Step 2: Import into CODESYS

Importing mobileIoT program

1. Open a new or existing CODESYS project

2. Select the Application in the device tree and navigate to Project -> Import PLCopenXML... -> Select project.xml out of the archive file from the export of IoT Builder.
Afterwards you should see the following:


Confirm and the program gets imported:

⚠ Important Note :
The folder mobileIoT must appear inside the Applications tree.
If not, make sure you have selected Application when importing the project.xml file.


3. Add library to the project:
Library Manager -> Add Library -> Select or search for ifm_mobileIoT

4. Resolve placeholder if necessary:
Library Manager -> Placeholders -> Check for empty libraries and select a version

⚠ Important Note :
For system libraries beginning with version 3.5 you should never choose a library above your service pack and patch version.
For example: When using SP19 Patch 7, you should not use a system library above V3.5.19.7
⚠ Important Note :
Repeat this process until all placeholders are set.


5. Make sure that you have choosen the ifmGateway library that is according to your mobileIoT gateway (in this example ifmGatewayCR3171):


6. Assigning the mIoT PRG to a task:
Make sure, that the mIoT task is assigned to a task by drag and dropping the PRG on any task


Setting user and password

  1. Open GVL_mobileIoT
  2. Set the username for gsGatewayUsername :
    The username for the CR3171 is     api .
  3. Set the password for gsGatewayPassword :
    This is the password which you have set in the WebUI for API.
  4. Set the password for gsFileUploadPassword :
    This is the password which you have set in the WebUI for File upload.
⚠ Important Note:
All passwords need to be base64 encoded.
To do this use for example Base64 Converter
⚠ Important Note:
Usernames for CR3170:
admin (FW >= RUT9_R_00.07.06.3)
root (FW < RUT9_R_00.07.06.3)


Adding values to your signals

1. Open the GVL_mobileIoT

2. You should see variables defined in IoT Builder:


3. In a separate PRG, assign values:

GVL_mobileIoT.uiAmbientHumidity := 40;


Snapping a value of your signal

By default values are logged cyclically. In our example we have defined that the value of uiAmbientHumidity will be logged every minute. If you want to log the value at an specific event or in between the minute, you can use the xSnapAmbientHumidity variable:

xSnapAmbientHumidity := TRUE;

The value is logged on a rising edge of the variable.


Adding mobileIoT status screen

The ifm_mobileIoT.library includes a mobileIoT_StatusScreen which is a visualization of different status information of the gateway. It visualizes the stGatewayStatus output enum of the fbGatewayManager of the imported mIoT PRG.

  1. Open or create a visualization
  2. Navigate to Visualization Toolbox -> ifm_mobileIoT -> Drag and Drop the mobileIoT_StatusScreen into the visualization


3. Set the X- and Y-Position to 0:


4. After adjusting the screen it could look like this:


After downloading the application you can see different values and statuses in the visualization:

⚠ Important Note :
Due to missing information from device side, its possible that not all values are getting displayed.


Library compatibility

The following describes the compatibility of the libraries with each other:


Library Release History

ifm_mobileIoT library
V3.0.0.0
  • initial release
V3.0.1.0
Changes
  • If the library is not officially released by ifm, the mobileIoT_StatusScreen will add an "RC" (release candidate) to the screen.
Bug fixes
  • The uiNrOfFilesInDownloadDir and uiNrOfFilesInUploadDir outputs of the GatewayManager function block were lower than the actual values.


ifmGatewayCR3171 library
V3.0.0.0
  • initial release
V3.0.1.0
Changes
  • Cloud-to-Machine: While files are being transferred from the cloud to a machine, the file extension is .part until the transfer is complete. If the transfer from the cloud to the machine stops for any reason, the .part file remains and is removed when the same file name is transferred again.
  • Cloud-to-Machine: If a file with the same name already exists on the target device, the newly transferred file will be given the extension _1, followed by _2, and so on.
Bug fixes
  • Machine-to-Cloud: The transfer to the cloud stopped after an unpredictable amount of time