42Q-MES0184-IIoT Configuration

42Q Home > IIoT > Device Self Service

 

 

 

IIoT Configuration Device Self Service Version MES 15.81 Revision F1  

 

 

 

 

Introduction

The concept of GGC stands for “Green Grass Computer”, the word: “Computer” also refers to any kind of device. This document will teach users how to configure, install, and deploy a GGC, as well as create and set up a Device Self-Service for establishing a connection between the computer (device) and the 42Q portal to send data (payloads).

 

Prerequisites

• Only Linux is supported for the computer or device to install the Green Grass Core. The related shell scripts and test code only work on Linux systems (Windows is not currently supported).
• Python 3.8 or higher must be installed and configured to run the test code.

Operating System and Software Requirements

• Linux kernel version 4.4 or later (Ubuntu 20.04 and CentOS 8.5).
• Java Runtime Environment (JRE) version 11 or greater (included in the installation script).
• Python version 3.8 for functions that use the Python 3.8 runtime (included in the installation script).

 

Cgroups Requirements

The AWS IoT Greengrass Core software currently only supports Cgroups v1, not v2. In order to satisfy AWS Greengrass Core dependencies as stated in the official documentation "Setting up AWS IoT Greengrass core devices"  (Setting up AWS IoT Greengrass core devices - AWS IoT Greengrass ), the system should be configured with the following Linux kernel parameters and restarted:

To enable these Cgroups options, boot the device using the following Linux kernel parameters:

[https://docs.aws.amazon.com/greengrass/v2/developerguide/troubleshooting.html#lambda-cgroups-not-mounted

Step 1:  sudo vi /etc/default/grub
Find GRUB_CMDLINE_LINUX, and add the following command to it.

• For Centos 8.5

cgroup_enable=memory cgroup_memory=1 systemd.unified_cgroup_hierarchy=0

Figure 1: Command 

IIOT command.png

• For Ubuntu 22.04

cgroup_enable=memory cgroup_memory=1 systemd.unified_cgroup_hierarchy=false

Step 2: Enter the command: sudo update-grub
Step 3: Restart the system. sudo reboot
Then check the Cgroup, response tmpfs is right.
 root@:~# stat -fc %T /sys/fs/cgroup/tmpfs
 

Adjusting Cgroup configuration

1. Edit /etc/default/grub - Find the line that starts with "GRUB_CMDLINE_LINUX=" and append or change the following values: cgroup_enable=memory cgroup_memory=1 systemd.unified_cgroup_hierarchy=false - Save the file
2. Apply the configuration change by running: update-grub
3. Restart the system
4. Verify that the Cgroup configuration has been set to v1 by running the following command and ensuring that the response is "tmpfs": stat -fc %T /sys/fs/cgroup/;

 

 

Network requirements

The Green Grass Core device  must be able to access the following endpoints through specific ports:

• https://www.amazontrust.com/repository/AmazonRootCA1.pem.
• https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-2.12.6.zip.
• greengrass-ats.iot.us-east-1.amazonaws.com. Ports: 443.
• .iot.us-east-1.amazonaws.com. Ports: 443.
• .credentials.iot.us-east-1.amazonaws.com. Ports: 443.

For more details on what traffic needs to be authorized and why, please visit the official AWS documentation.

 

Functional Description

There are three different functional components: CloudPrinting, MachineInterface, FileUploader, and DataIngestion.
To access the Edge Devices portlet, navigate to: Shop Floor Control > Configuration > IIoT Configuration > Edge Devices.

Figure 2: Accessing Edge Devices

 

Figure 3: Edge Devices Functions

 

1. Users can query the list of all devices by Edge Device Name or Functionality Name.
2. Users can create a new Edge Device.
3. Users can activate or deactivate the certificate status. 
4. Users can view or edit the details of the edge device and its logs.
5. Users can download the Edge device software.
6. Users can Upgrade this edge device with more features.
7. Users can get all functional components through this button when no functional components are deployed on their local core device.
8. Users can Delete the edge device.
9. Settings allow users to configure or get the palindrome information which can be used by the functionalities in the IIoT application. 

 

Figure 4: Settings

 

Edit Edge Device

When the status of the Edge Device is "Healthy", select the Edit button to enter the Edge Device information. The users can add functionality, associated client devices, and view its logs.

 

Figure 5: Edit Button

 

Components 

The components tab allows users to view all components installed in this Edge device. It displays the version and status of the installed components.

 

Figure 6: Components Tab

 

Deployments

The Deployments tab allows users to view all the Functionality statuses installed in this Edge device. 

 

Figure 7: Deployments Tab

 

Functionality

1. Select the FUNCTIONALITY tab.

 

Figure 8: Functionality tab

 

2. Select theADD FUNCTIONALITY.

 

Figure 9: Add Functionality 

 

3. Users can edit or delete the functionality. Each functionality supports two versions (1.0 and 1.1) and users can switch between these versions (from 1.0 to 1.1 or from 1.1 to 1.0).

 

Figure 10: Edit Functionality Version

 

Note: An Edge device will install Python 3.11 by default however it supports both Python 3.8 and Python 3.11. A single functionality can only be set to either Version 1.0 or Version 1.1. Ensure that the appropriate Python version is installed locally:

• Functionality Version 1.0 requires Python 3.8.
• Functionality Version 1.1 requires Python 3.11.

Users can execute the following two new scripts in the terminal to install Python 3.11 and Python 3.8.

• sudo sh Install_Python3.8.sh
• sudo sh Install_Python3.11.sh
   

 Figure 11: Python Scripts

 

4. Users can use the settings option in the Edge device Functionality tab to manage the functionality configurations.

 

Figure 12: File Upload Setting

 

Client Devices 

1. Select the CLIENT DEVICES tab.
2. Select ASSOCIATE CLIENT DEVICES.

 

Figure 13: Client Devices Tab

 

3. Enter the name of the Client Device to be created.

Note: The name can be up to 128 characters. Valid characters: a-z, A-Z, 0-9, underscore (_), and hyphen (-).

4. Select SAVE.
5. Users can activate or deactivate the certificate status. 
6. The Client Device tab supports batch downloads and deletions.

 

Figure 14: Creating a Client Device

 

Assets

The Asset is used to enable the 42Q/Machine communication feature. For more information, refer to How to Configure a bidirectional event-link communication channel between IT and OT. 

1. Select the Assets icon to manage the assets that integrated the shadows/machines.
2. Users can Select and Delete multiple assets at once.

 

Figure 15: Manage Assets

3. At the Assets page, select ADD ASSET.

 

Figure 16: Add Assets

4. Select the Asset Type, Assets, and add the Attributes.
   • Asset Type: The users can select the Asset Type that already exists, or create a new asset Type by selecting the Add button.
   • Assets: The users can select the Assets that already exist, or create a new asset by selecting the Add button.
   • Attributes: Add the attributes of the asset. Note: The attributes will be associated with the Asset Type. One Asset Type can have multiple attributes. The channels for this asset type should have the same value.  Channel: Optional, Each protocol or driver used in a server project is called a channel.  A server project may consist of many channels with the same communications driver or with unique communications drivers. A channel acts as the basic building block of an OPC link. This group is used to specify general channel properties, such as the identification attributes and operating mode.  The channel in the attribute is optional, but If the customer needs to use Kepware to change/update tag value from MQTT messages, you would need to enter the channel(same as the channel in Kepware) when defining the asset type.  
5. Select SAVE, then close the assets page to return to the Edge Device Info page.

Logs

1. Select the Logs tab to view GreenGlass logs for each Edge Device and for various functionalities, such as Data Ingestion, Cloud Printing, Machine Interface, and File Uploader.
2. Users can filter the logs by Message, Functionality Nam, Start Time, and End Time.

 

Figure 17: Logs Tab

 

3. Select the required log and log details option to see the detailed information of the log.

 

Figure 18: Log Details

 

Install 42Q Edge Software

CloudPrinting

 

Figure 19: Cloud Printing

 

Please follow the steps below to create a 42Q Cloud Printing Edge Device in 42Q:

1. Navigate to: Shop Floor Control > Configuration > IIoT Configuration > Edge Devices.
2. Select CREATE EDGE DEVICE to create a new Green Grass Core.

 

Figure 20: CREATE EDGE DEVICE Button

 

3. Enter the Edge Device Name of the Green Grass Core. The name can be up to 128 characters. Valid characters are: a-z, A-Z, 0-9, colon (:), underscore (_), and hyphen (-).
4. Select the Group Name as CloudPrintingGroup.

Note: Once the Functionality Name is selected, the Functionality Version will automatically be selected.

 

Figure 21: Create Edge Device Form

 

5. Select the checkbox next to the desired Edge Device.
6. Select the Download icon to download the Edge Device ZIP file.

 

 

Figure 22: Downloading The Files

 

7. Right-click on the ZIP file.
8. Select Extract Here to unzip the file.
9. Open the Terminal.
10. Enter the command: sudo su, and then press Enter.
11. Enter the root user’s password, and then press Enter.

Note: If the word: root@ appears before the computer’s username as in the image below, it means that you are logged in as a root user.

 

Figure 23: User Logged In as a Root User

 

12. Enter the next command: sh ggcV2.sh, and then press Enter.

Note: After the script is installed successfully, users can navigate to the local device’s path: /greengrass/v2 to check the installed folder; logs are contained in the path: /greengrass/v2/logs.

 

Figure 24: Edge Device Folder

 

Testing Label Printing Function Using Label Engine Screens

1. Navigate to: Administration > Label Engine Admin > Printer.
2. Select Add.

 

Figure 25: Add Printer Button

 

3. Enter the Printer Name.
4. Select the Resolution from the drop-down list.
5. Select the Connectivity Type as Edge Device.

 

Figure 26: Entering The Printer Details

 

Note: The TCP IP Address should be the address of the printer or start a TCP Server as a simulator by executing the next command in the Terminal:

 sudo -H -u ggc_user python3.8 tcpServer.py or sudo -H -u ggc_user python3.11 tcpServer.py. The FiletcpServer.py be included in the Edge Device ZIP file.

6. Navigate to: Production > Label Engine Labels > LE Labels.
7. Search for the label called “entry”, which will print whatever "Entry" value is passed.
8. Select the checkbox next to the printer name.
9. Select Print.

 

Figure 27: Print Button

 

10. Select the Printer Name previously created.
11. Enter a value in the Entry field.
12. Select Test Print.

 

 

Figure 28: Entering Test Print Data

 

13. Open the Terminal.
14. Navigate to the local device’s path: /greengrass/v2/logs.
15. Enter the next command: tail -f {envide}_CloudPrinting.log. After that, a message will be received to confirm the successful testing.

 

Figure 29: Successful Testing Message

 

 

 

MachineInterface

This function is used for sending commands to machines from the cloud.
Below there is an example of stopping a machine when the server finds MSD material expired.

 

Figure 30: Server Stopping A Machine Due To Material Expired Diagram

 

The diagram above is divided into three steps:

1. Install an Edge Device on a server in the plant.
2. The plant creates a new local application that can communicate with the Edge Device by TCP and also can send commands to machines.
3. The Cloud application will send commands to the Edge Device, then the Edge Device will forward the message to the local application through TCP/IP.

Please follow the steps below to create a 42Q Cloud Machine Interface Edge Device in 42Q:

1. Navigate to: Shop Floor Control > Configuration > IIoT Configuration > Edge Devices.
2. Select CREATE EDGE DEVICE to create a new Green Grass Core.
3. Enter the Edge Device Name of the Green Grass Core. The name can be up to 128 characters. Valid characters are: a-z, A-Z, 0-9, colon (:), underscore (_), and hyphen (-).
4. Select the Group Name as MachineInterfaceGroup.

Note: After selecting the Group Name, the Group Version will automatically be selected.

 

5. Select the checkbox next to the desired Edge Device.
6. Select the Download icon to download the ZIP file.
7. Right-click on the ZIP file.
8. Select Extract Here to unzip the file.
9. Open the Terminal.
10. Enter the command: sudo su, and then press Enter.
11. Enter the root user’s password, and then press Enter.
12. Navigate to the extract folder by using the command: cd {folder path}.
13. Enter the next command: sh ggcV2.sh, and then press Enter.

Note: After the script is installed successfully, users can navigate to the computer’s path: /greengrass/v2 to check the installed folder; logs are contained in the path: /greengrass/v2/logs.

 

14. Open Postman to test its functionality.
15. Select POST as HTTP Method.
16. Enter the URL.
17. Enter the Topic.
18. Enter the Output.
19. Enter the Error.

 

Data nomenclature example:
URL: https://portal-uat.42-q.com/mes-api/[SiteName]/greengrass/v2/publish
Topic: [Envide]/machine-interface/[Envide]_[Edge device name]
Output: [Envide]/machine-interface/results
Error: [Envide]/machine-interface/errors

 

Figure 31: Sending The Payload Using Postman

 

20. Open the Terminal.
21. Navigate to the local device’s path: /greengrass/v2/log to view the logs.

 

 

Figure 32: Successful Payload Sending Logs

 

Note: If the message from the previous image is printed in your local log, the function has succeeded.
Adding the corresponding configuration for PTS allows PTS to send messages to Edge Device.

 

DataIngestion

Please follow the steps below to create a 42Q Cloud Data Ingestion Edge Device in 42Q:

1. Navigate to: Shop Floor Control > Configuration > IIoT Configuration > Edge Devices.
2. Select CREATE EDGE DEVICE to create a new Green Grass Core.
3. Enter the Edge Device Name of the Green Grass Core. The name can be up to 128 characters. Valid characters are: a-z, A-Z, 0-9, colon (:), underscore (_), and hyphen (-).
4. Select the Group Name as DataIngestionGroup.

Note: After selecting the Group Name, the Group Version will automatically be selected.

 

5. Select the checkbox next to the desired Edge Device.
6. Select the Download icon to download the ZIP file.
7. Right-click on the ZIP file.
8. Select Extract Here to unzip the file.
9. Open the Terminal.
10. Enter the command: sudo su, and then press Enter.
11. Enter the root user’s password, and then press Enter.
12. Enter the next command: sh ggcV2.sh, and then press Enter.

Note: After the script is installed successfully, users can navigate to the computer’s path: /greengrass/v2 to check the installed folder; logs are contained in the path: /greengrass/v2/logs.

 

13. Select theEdge Device, andselect theEdit button.
14. Select theCLIENT DEVICES tab.
15. Select ASSOCIATE CLIENT DEVICES.

Figure 33: CLIENT DEVICES TAB

 

16. Enter the name of theClient Device to be created.

Note: The name can be up to 128 characters. Valid characters: a-z, A-Z, 0-9, underscore (_), and hyphen (-).

17. Select SAVE.
18. Select the Download icon to download the Client Device ZIP file.
19. Right-click on the ZIP file.
20. Select Extract Here to unzip the file.

 

Figure 34: Creating a Client Device

Figure 35: Client Device Folder

 

21. Open the MqttTest.py file.
22. Find the line that contains: ‘# Change This’.
23. Modify the data information to be sent; users may see an example below (user’s will be different).

 

Figure 36: Data To Be Modified

 

24. Open the Terminal.
25. Enter the next command: python MqttTest.py, and then press Enter. The result should be similar to the image below:

Figure 37: Result Of Executing The MqttTest.py File

 

26. Navigate to the local device’s path: /greengrass/v2/log to view the logs.

 

Figure 38: Successful MqttTest.py Running Logs

 

Note: If the message from the previous image is printed in your local log, the function has succeeded.

 

File Uploader

OS: 

• Ubuntu 20.04 / 22.04
• Centos 8.5

The following is an example of FileUploader.

1. Select the desired Edge Device and download the ZIP file. Then, right-click and choose 'Extract Here' to unzip the file. 

 

Figure 39: Folders

 

2. Open Terminal and execute the following command: sudo sh fileUploader.sh

 

Figure 40: Enter the command

 

3. Create or update edge devices in 42Q. 

• Visit IIoT configuration in 42Q, and create a new edge device. (For first-time install)

 

Figure 41: Create Edge Device

 

• Update the existing edge device by adding it to the FileUpload Group. (For existing edge devices)

 

Figure 42: Add Functionality

4. Install Edge Device:

• For existing edge devices, please stop greengrass by the following command: sudo systemctl stop greengrass.service
• Download and unzip the greengrass package locally.

 

Figure 43: Edge device tab

 

• Ask the 42Q mes-support team to provide a palindrome client ID and a secret that can access the mes-API and PTSR database.
• Edit core_config.json and add ClientId and Secret as given below. 

{
    "MaximumUploads":"3",
    "PoolMaxWorkers":"10",
    "RetentionDays":"7",
    "ClientId":"****",
    "Secret":"****",
    "FileType":[
        {
            "SubFolder":"/",
            "MachineType":"panacim",
            "Processer":[
                {
                    "Extension":".xml",
                    "Parser":"panacim"
                }
            ]
        }
    ]
}
The ClientId and secret can also be defined in the settings. The ClientId and Secret correspond to the Token and Key on the Settings page. The Token and Key on the Settings page are site-level and will be applied to all edge devices within the site. The other parameters don’t require a change.

• Open the terminal, and install greengrass by executing the command: sudo sh ggcV2.sh

 

Things

In this portlet, users can make sure whether the AWS Cloud has stored the data uploaded successfully or not.
To do so, follow the steps below:

1. Navigate to: Shop Floor Control > Configuration > IIoT Configuration > Things.

Figure 28: Things Portlet

DSS Things Portlet.png

 

       2. If the “Thing ID” is the same as the “id” configured in MqttTest.py file, it means that AWS Cloud has already stored the data uploaded.

       3. To search for a specific thing, users can use the filters by Thing ID, Thing Time, and Thing Updated Time. Enter the appropriate value in the filter field; the system will automatically search the value. 

       4. Select the Refresh icon to refresh the records on the page. 

 

Figure 29: Thing ID

 

Locations

The Locations portlet allows users to assign a location to the Edge Devices in order to identify their Physical Location.
To add a location, follow the steps below:

1. Navigate to: Shop Floor Control > Configuration > IIoT Configuration > Locations.

 

Figure 30: Locations Portlet

DSS Locations Portlet.png

2. Select the ADD LOCATIONS button.

Figure 31: ADD LOCATION Button

3. Enter the Site.
4. Enter the Physical Location.
5. Select the SAVE button.

Figure 32: Creating A Location

 

Groups

Users can create different groups of Edge Devices. Each group must have a unique name and one or more Thing IDs associated with it.

Add a Group

To add a group, follow the steps below:

1. Navigate to: Shop Floor Control > Configuration > IIoT Configuration > Groups.
2. Select the ADD GROUP button.

 

Figure 33: ADD GROUP Button

900px

3. Enter the Unique Group Name.
4. Select a Thing ID.
5. Select the SAVE button.
6. Select the Refresh icon to refresh the records on the page.

Figure 34: Creating A Group

 

Add a Rule To An Existing Group

To add a rule, follow the steps below:

1. Hover the mouse over a Group Name from the Group list.
2. Select the Edit Group icon.
3. Select a rule from the Select Rules drop-down list.
4. Select the SAVE button.

Figure 35: Editing A Group

 

Notification Setup

Before creating any rules, users have to set up notifications. Each user can subscribe to one or more SNS topics (Simple Notification Service); these users will receive notifications via text messages or email.
To set up notifications, follow the steps below:

1. Navigate to: Shop Floor Control > Configuration > IIoT Configuration > Notification Setup.

 

Figure 36: Notification Setup Portlet

DSS Notification Setup Portlet.png

2. Select the CREATE SNS TOPIC button. A pop-up window will appear.

Figure 37: CREATE SNS TOPIC Button

900px

3. Enter the Topic Name.
4. Select the SAVE button.
5. Select the Refresh icon to refresh the records on the page. 

Figure 38: Create SNS Topic Pop-up Window

 

5. Hover the cursor over the Topic.
6. Select the Subscribe icon. A new pop-up window will appear.

Figure 39: Subscribe Icon

900px

 

7. Select the SUBSCRIBE TO SNS TOPIC button. A new pop-up window will appear.

Figure 40: SUBSCRIBE TO SNS TOPIC Button

DSS SUBSCRIBE TO SNS TOPIC Button.png

 

8. Select the Notification Method (Email or Phone).
9. Enter the Notification End Point (email address).
10. Select the SUBSCRIBE TO SNS TOPIC button to save the information.

 

Figure 41: Subcribing To A SNS Topic

 

11. The Subscribe List will display the Pending Confirmation and Confirmed End Points.

Figure 42: Subscribe List

DSS Subscribe List.png

 

12. A confirmation mail will be sent to the entered email address. Open the mail.
13. Select the Confirm subscription link.
14. A window will be opened in a new tab confirming the subscription. To unsubscribe select the “click here to unsubscribe” link, else close the window.

 

Rules

In this portlet, users can create, view, edit, and delete rules. After setting up notifications, users may create rules that will trigger alerts. Each rule is associated with one or more Groups or Thing IDs.

1. Navigate to: Shop Floor Control > Configuration > IIoT Configuration > Rules.

 

Figure 43: Rules Portlet

DSS Rules Portlet.png

 

 

Add Rule

1. Select the Add Rule button. A new pop-up window will appear.

 

Figure 44: Add rule
DSS addrule.png

 

2. Enter the Rule name, Notification interval, SNS topic, and Maximum Alert times. 
3. Check in the box to receive alerts for the things that have not uploaded measured data for more than the given time.

 

Figure 45: Entering Publish Rule Information

 

Next, select one of the two Bounds (rules):

• Threshold: This rule will trigger an alert whenever a measured value crosses a specific threshold.
• Independent: This rule will trigger an alert whenever a measured value satisfies the user-defined criteria.

 

Figure 46: Defining A Bound

 

4. If the Threshold is selected, choose one option from the Boundary Considerations list and the Control Values list.
5. Enter the Limit Value.
6. Select one of the Rule Options.
7. Select the Save button.

 

Edit and Delete Rule

1. Select the Edit button. A new pop-up window will appear.

 

Figure 47: Edit Rule

DSS editrule.png

 

2. Users can edit Notification Interval, SNS topic, Maximum Alert times, andBoundary except Rule name. 

 

Figure 48: Editing the options

 

3. Select the Save button to complete the action. 
4. Select the Delete button to delete the rule.

Figure 49: Delete rule 

DSS deleterule.png

 

Mapping

1. Select the Mapping icon to apply a rule to the Things and Groups.

Figure 50: Mapping the rule
DSS mapping the rule.png

2. Users can select Things and Groups for the rule or remove some existing things from the rule.

 

Figure 51: Selecting Things and Groups

3. Select the Save button to complete the action.
4. Select the Refresh icon to refresh the records on the page.

Figure 52: Refresh the Page
DSS refreshpage.png

 

Alerts

After setting up notifications and rules, when a rule’s conditions comply, the alerts will be triggered, causing the notifications to be sent to the subscribed users.
To access the Alerts portlet, follow the steps below:

1. Navigate to: Shop Floor Control > Configuration > IIoT Configuration > Alerts.

 

Figure 53: Alerts Portlet

DSS Alerts Portlet.png

 

2. To search for a specific alert, users can use the filters: Thing ID, Rule, Rule Type, Status, and Alert Time. To do so, enter the appropriate value in the filter field; the system will automatically search the value.
3. Select the Refresh icon to refresh the records on the page. 
4. Users can filter the Alerts record with multiple statuses

 

Figure 54: Thing ID And Rule Filters

900px

 

Figure 55: Alert Status

 

• Alerting: Processing.
• Auto Stop Alert: There are ‘max alert times’ in the rule, if the system already sends out the message/mails equal to the ‘max alert times’, marking it as ‘Auto Stop Alert’.
• Acknowledged: If a user received the email or message, he could mark it as acknowledged to stop the system from sending events/emails. (User click the acknowledge button)
• Auto Processed: Edge device/Client application/OPC received events and response success.

5. To acknowledge an alert, select an alert checkbox.
6. Select the Acknowledge Alert button.

 

Figure 56: Acknowledge An Alert

 

Dashboard

 

1. Navigate to: Reporting > IIoT Dashboard.
2. Select the + icon to create a new widget.

 

Figure 57: Add (+) Icon

 

3. Enter the Widget Name.
4. Select one of the types of widgets:

• Historical
• Predictive
• Variation: This option requires entering the Lower and Upper Control Limit.
• CPK/PPK(Single Thing Only): This option requires entering the Lower and Upper Control Limit. This type of widget is not possible to associate with groups, only Things.

5. Select one or more Group Name from the GROUPS tab.
6. Select the THINGS tab.
7. Select the Thing ID that matches the "id" value previously configured in the MqttTest.py file.
8. Select the SAVE button located at the end of the Add Widget Form.

 

Figure 58: Creating a Widget

 

9. Select the show/hide icon to view the values of the widget created.

 

Figure 59: Show/Hide Icon

Note: Users can check the payload sent through either of the following:

• IIoT widget.