How to install Edge Connector

Summary

This document will teach users how to complete prerequisites as well as installation of Edge Device in the next operating systems: Ubuntu 20.04 and Centos 8.5+ (and later versions).

 

Prerequisites

Log in As a Root User

To be able to execute installation commands into the computer’s Terminal, the user must log in as a root user to obtain permission to enter commands that will install new software. To do so, follow the steps below:

 

1. Open the Terminal.
2. Enter the command: su, and then press Enter.
3. 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 1: User Logged In as a Root User

 

 

Enable the ‘cgroups’ in the operating system

To be able to install the Edge Connector, the user must enable the ‘cgroups’ in the operating system. To do so, follow the steps below:

 

To enable these cgroups options, boot the device with 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 in it.

For Centos 8.5

cgroup_enable=memory cgroup_memory=1 systemd.unified_cgroup_hierarchy=0      

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

 

How to install Edge Connector

First of all, the user must create a new Edge Device to be able to download the Edge Connector installation package.

 

 

Create a new Edge Device

To create a new Edge Device, follow the steps below:

1. Navigate to: Shop Floor Control > Configuration > IIoT Configuration > Edge Devices.
2. Select CREATE EDGE DEVICE. A pop-up window will appear.

Figure 2: Edge Devices Portlet

 

3. Enter the Edge Device Name.
4. Select the Functionality Name:

• DataIngestionGroup
• CloudPrintingGroup
• MachineInterfaceGroup
• FileUploader

5. Select the Functionality Version.
6. Select SAVE to save changes or CANCEL to abort.

 

Figure 3: Create Edge Device Pop-up Window

 

 

 

Download and Install The Edge Device Installation Package

1. Navigate to: Shop Floor Control > Configuration > IIoT Configuration > Edge Devices.
2. Hover the cursor over the Edge Device previously created.
3. Select Download to download the zip file.
4. Right-click on the zip file.
5. Select Extract Here.
6. Open the downloaded folder.
7. Make sure the file ggcV2.sh exists.
8. Open the Terminal.
9. Login as a root user.
10. Enter the command: sudo sh ggcV2.sh, and then press Enter to execute the script.

 

How to manage the Edge Connector service from Terminal

To be able to execute any of the commands used to manage the Edge Connector service, the user must open the terminal and login as a root user.

 

Stop The Service

1. Open the Terminal.
2. Login as a root user.
3. Enter the next command: sudo systemctl stop greengrass.service, and then press Enter.

 

 

Disable The Service

1. Open the Terminal.
2. Login as a root user.
3. Enter the next command: sudo systemctl disable greengrass.service, and then press Enter.

 

 

Remove The Service

1. Open the Terminal.
2. Login as a root user.
3. Enter the next command: sudo rm /etc/systemd/system/greengrass.service, and then press Enter.

 

 

Verify That The Service Is Deleted

1. Open the Terminal.
2. Login as a root user.
3. Enter the next command: sudo systemctl daemon-reload && sudo systemctl reset-failed, and then press Enter.

 

 

Delete Greengrass

1. Open the Terminal.
2. Login as a root user.
3. Enter the next command: sudo rm -rf /greengrass/v2, and then press Enter.

 

 

How to Reinstall an Edge Device

It is possible for the  user to reinstall an Edge Device, although the deployment job is already executed, it will not download the lambdas when executing the script, nevertheless, the user can access the Edge Devices page, select the edge device, and then click the Redeploy icon to redeploy the edge device.

 

Testing Cases

Server: https://portal-uat.42-q.com/
Site: gbs_test

 

 

Data Ingestion

1. Create a new Edge Device whose functionality Name belongs to DataIngestionGroup.
2. Select an Edge Device.
3. Select the Edit icon.
4. Select the CLIENT DEVICES tab.
5. Select CREATE CLIENT DEVICES.

Figure 4: Edge Device Info Pop-up Window

 

6. Select the Client Device from the drop-down list.
7. Select ASSOCIATE.
8. Select the Download icon to download the script.
9. Right-click on the zip file.
10. Select Extract Here.
11. Open the extracted folder.
12. Open the file MqttTest.py.
13. Find the line that contains: ‘# Change This’.
14. Modify the data information to be sent; users may see an example below:

 

  message = {
                "measurements": [ {
                "timestamp": str(loc_dt), 
                "quality": "true", 
                "id": "GGC.V2.device.test001", 
                "value": random.randint(0,40)}], 
                "agent_id": "P88",             
                "data_acquisition_ts": str(loc_dt)
            }
 

15. Open the Terminal.
16. Login as a root user.
17. Enter the command: sudo -H -u ggc_user python3.8 MqttTest.py/sudo -H -u ggc_user python3.11 MqttTest.py, and then press Enter.

 

 

 

Machine Interface

1. Create a new Edge Device whose Functionality Name belongs to MachineInterfaceGroup.
2. Hover the cursor over the Edge Device previously created.
3. Select Download to download the zip file.
4. Right-click on the zip file.
5. Select Extract Here.
6. Open the downloaded folder.
7. Make sure the file ggcV2.sh exists.
8. Open the Terminal.
9. Login as a root user.
10. Enter the command: sudo sh ggcV2.sh, and then press Enter.
11. Go to the Terminal.
12. Enter the command: sudo -H -u ggc_user python3.8 tcpServer.py/sudo -H -u ggc_user python3.11 tcpServer.py.
13. Use an API Client to simulate sending the below data by Postman or RESTful client, then it will return the result 200 and the message: “publish message to topic successfully.”

Note: The red font part can be modified according to the actual situation.

 

URL: https://portal-uat.42-q.com/mes-api/gbs_test/greengrass/v2/publish

Method: Post

Data:
{
  "topic": "snunv/machine-interface/snunv_E30_UAT_Demo_02",
  "payload":{
  "host": "127.0.0.1",
  "port": "9100",
  "content": {
    "event_id": 3,
    "event_name": "Part Re-Validation Pending",
    "data": [
      {
        "workstation": "WS1",
        "station": "1-1",
        "material": "",
        "board": "",
        "msg": ""
      },
      {
        "workstation": "WS1",
        "station": "1-2",
        "material": "",
        "board": "",
        "msg": ""
      }
    ]
  }
}
}

 

Figure 5: Open Source API Client Insomnia

 

15. Navigate to the computer’s folder: /greengrass/v2/logs.
16. Go to the Terminal.
17. To view the log of the machine interface, enter the command: tail -f snsnv_MachineInterface.log
18. View the message received in tcpServer.

 

 

Figure 6: TCP Server Message (Machine Interface)

 

Cloud Printing

1. Create a new Edge Device whose Functionality Name belongs to CloudPrintingGroup.
2. Hover the cursor over the Edge Device previously created.
3. Select Download to download the zip file.
4. Right-click on the zip file.
5. Select Extract Here.
6. Open the downloaded folder.
7. Make sure the file ggcV2.sh exists.
8. Open the Terminal.
9. Login as a root user.
10. Enter the command: sudo sh ggcV2.sh, and then press Enter.
11. Enter the command: sudo -H -u ggc_user python3.8 tcpServer.py/sudo -H -u ggc_user python3.11 tcpServer.py.
12. Request print either by LE Print or Postman:

 

 

By LE Print

1. Add a printer by navigating to: Administration > Label Engine Admin > Printer.
2. Select Add.

 

Figure 7: Adding a Printer

 

Note: The TCPIP Address should be the address of the printer. Or in case users want to start a TCP Server, users should access the Edge Devide downloaded folder, and then execute the command: ‘'sudo -H -u ggc_user python3.8 tcpServer.py/sudo -H -u ggc_user python3.11 tcpServer.py'’ as a simulator.

 

3. Create a print job by navigating to: Production > Label Engine Labels > LE Labels.
4. Select a label.
5. Select the Print button. A pop-up window will appear.
6. Select the Printer Name created previously.
7. Enter the Entry value.
8. Select the Test Print button.

 

 

Figure 8: Creating a Print Job

 

9. Navigate to the computer’s folder: /greengrass/v2/logs.
10. Open the Terminal.
11. Login as a root user.
12. Enter the command: tail -f snsnv_CloudPrinting.log.
13. View the message received in tcpServer.

 

 

Figure 9: TCP Server Message (Cloud Printing Command)

 

 

File Uploader

 

1. Create a new Edge Device whose Functionality Name belongs to FileUploader.
2. Hover the cursor over the Edge Device previously created.
3. Select Download to download the zip file.
4. Right-click on the zip file.
5. Select Extract Here.
6. Open the downloaded folder.
7. Make sure the fileggcV2.sh exists.
8. Open the Terminal.
9. Login as aroot user.
10. Enter the command: sudo sh ggcV2.sh, and then press Enter.
11. Enter the command:sudo sh fileUploader.sh
12. Ask the 42Q mes-support team to provide a palindrome clientID and secret which can access the mes-api and PTSR database.Choose one of the following methods to modify the parameters ClientId and Secret.

 

Option 1: Directly edit the core_config.json file.

Edit the /greengrass/v2/core_config.json file and add ClientId and Secret as shown below. The other parameters don’t need to be changed.
{

    "MaximumUploads":"3",

    "PoolMaxWorkers":"10",

    "RetentionDays":"7",

      "PlantCode":"****",

    "ClientId":"****",

    "Secret":"****",

    "FileType":[

        {

            "SubFolder":"/",

            "MachineType":"panacim",

            "Processer":[

                {

                    "Extension":".xml",

                    "Parser":"panacim"

                }

            ]

        }

    ]

}

Option 2: Modify through the Edge device page.   The ClientId and secret can be defined in the settings. Navigate to 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.  

Figure 10: Settings 

13. Then restart Greengrass by running the next command: sudo systemctl restart greengrass.service  
14. Test Steps

•      Put the panacim xml file to the folder(step1 installed)
•      If the xml file is uploaded successfully, check the success folder.
•    After xml file into the success folder,go to Mesweb portlet to check Material on board, Material on board by batch,Material where used reports.  
•    Go to Multimedia maintenance portlet, input Site( e.g SANM-E30) on Tenant Name input box,input PTS on Tag Name input box,click search button,will see the new uploaded xml file.

 

Troubleshooting

The Python, Python package index, SDK and Java are fully automated installed in installation script ggcV2.sh. Manual installation is only required if the installation fails. Please see the details below.

How to install Python

To be able to install the Edge Connector, the user’s computer must install the Python 3.8 version.
To verify the current computer’s Python version follow the steps below:

 

1. Open the Terminal.
2. Login as a root user.
3. Enter the command: python3 -V, and then press Enter.
4. 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

 

How to install the package management system Pip (Python Package Index)

To be able to install the Edge Connector, the user must install the package management system Pip. For installation, Browse to the folder where you unzipped the Edge device, right-click it, select Open in Terminal, and then type the following command in the Terminal.

•  Ubuntu

                sudo apt update

                sudo apt-get install wget   

                wget --no-check-certificate https://bootstrap.pypa.io/get-pip.py 

                sudo python3.11 get-pip.py / sudo python3.8 get-pip.py

                sudo -H -u ggc_user python3.11 -m pip install -r requirements.txt --user / sudo -H -u ggc_user python3.8 -m pip install -r requirements.txt --user  

•  Centos

                sudo yum update -y

                wget --no-check-certificate https://bootstrap.pypa.io/get-pip.py

                sudo python3.11 get-pip.py /   sudo python3.8 get-pip.py

                sudo -H -u ggc_user python3.11 -m pip install -r requirements.txt --user / sudo -H -u ggc_user python3.8 -m pip install -r requirements.txt --user

 

 

How to install the Python SDK (System Development Kit)

To be able to install the Edge Connector, the user must install. To do so, follow the steps below:

 

1. To install the Python SDK, enter the command:python3.11 -m pip install awsiotsdk or python3.8 -m pip install awsiotsdk, and then press Enter.
2. Next step is to install the necessary libraries.
3. Enter the command:python3.11 -m pip install awscrt or python3.8 -m pip install awscrt, and then press Enter.
4. Enter the command:python3.11 -m pip install awsiot or python3.8 -m pip install awsiot, and then press Enter.
5. Enter the command:python3.11 -m pip install tzlocal or python3.8 -m pip install tzlocal , and then press Enter.
6. Enter the command:python3.11 -m pip install pytz or python3.8 -m pip install pytz , and then press Enter.

 

How to install Java

To be able to install the Edge Connector, the user’s computer must have installed Java.
To verify the current computer’s Java version follow the steps below:

 

1. Open the Terminal.
2. Login as a root user.
3. Enter the command: java -version, and then press Enter.

 

• Ubuntu:

            sudo apt update

            sudo apt install openjdk-11-jre  

• Centos

            sudo yum update -y

            sudo yum install java-11-openjdk

 

Unable To Execute HTTP Request

If while installing the Edge Connector the user gets the following error:
Unable to execute HTTP request: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target.

 

The user can solve this issue following the steps below:

1. Open the Terminal.
2. Login as a root user.
3. Enter the command: cd /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.312.b07-1.amzn2.0.2.x86_64/jre/lib/security/java.security
4. Use the keyboard arrows to find the next line: jdk.security.caDistrustPolicies=SYMANTEC_TLS
5. Comment out the previous line by adding a hash symbol at the beginning of the line. It must look like this: #jdk.security.caDistrustPolicies=SYMANTEC_TLS
6. Comment out the next line: /etc/pki/ca-trust/extracted/java keytool -trustcacerts -keystore "/etc/pki/ca-trust/extracted/java/cacerts" -storepass changeit -importcert -alias aws-trust -file "/etc/pki/ca-trust/source/amazontrust.crt"

 

 

 

Fail to start cloud printing or receive messages

If the user gets the following error:
Fail to start cloud printing or receive messages.
2022-07-28T12:50:30.771Z [INFO] (pool-2-thread-18) sndnv_CloudPrinting: eventstreamrpc.py:308,<Connection at 0x7f3c6da7ea30 /socket/greengrassv2_ipc.sock:0> connected. {serviceInstance=0, serviceName=sndnv_CloudPrinting, currentState=RUNNING}
2022-07-28T12:50:38.068Z [ERROR] (pool-2-thread-19) sndnv_CloudPrinting: FATAL: lambda_runtime.py:146,Failed to import handler function "ggPrint.function_handler" due to exception: Error when retrieving credentials from container-role: Error retrieving metadata: Received non 200 response (500) from ECS metadata: Failed to get connection. {serviceInstance=0, serviceName=sndnv_CloudPrinting, currentState=RUNNING}
2022-07-28T12:50:38.069Z [ERROR] (pool-2-thread-19) sndnv_CloudPrinting: FATAL: lambda_runtime.py:426,Failed to initialize Lambda runtime due to exception: Error when retrieving credentials from container-role: Error retrieving metadata: Received non 200 response (500) from ECS metadata: Failed to get connection. {serviceInstance=0, serviceName=sndnv_CloudPrinting, currentState=RUNNING}
2022-07-28T12:51:28.784Z [INFO] (pool-2-thread-27) sndnv_CloudPrinting: shell-runner-start. {scriptName=services.sndnv_CloudPrinting.lifecycle.shutdown.script, serviceInstance=0, serviceName=sndnv_CloudPrinting, currentState=STOPPING, command=["/greengrass/v2/packages/artifacts/aws.greengrass.LambdaLauncher/2.0.10/lambda-..."]}
2022-07-28T12:51:28.834Z [INFO] (pool-2-thread-18) sndnv_CloudPrinting: Tearing down overlay tmpfs mounts. {serviceInstance=0, serviceName=sndnv_CloudPrinting, currentState=STOPPING}

 

The user can solve this issue following the steps below:

1. Open the Terminal.
2. Login as a root user.
3. Enter the command: pip3 config set global.cert /usr/lib/ZscalerRootCertificate-2048-SHA256.crt

 

If it still do not work, do the following:

1. Close Zscaler, then restart Greengrass by running the next command: sudo systemctl restart greengrass.service
2. After restarting, open Zscaler again.