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

Note: If Python 3.8 is not installed, please refer to the following links to install Python 3.8:

• For users using the CentOS operating system: https://computingforgeeks.com/how-to-install-python-3-on-centos/
• For users using the Ubuntu operating system: https://linuxize.com/post/how-to-install-python-3-8-on-ubuntu-18-04/

 

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. To do so, click on the next link and follow the instructions: https://linuxize.com/post/how-to-install-pip-on-ubuntu-18.04/.

 

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: pip3 install awsiotsdk, and then press Enter.
2. Next step is to install the necessary libraries.
3. Enter the command: pip3 install awscrt, and then press Enter.
4. Enter the command: pip3 install awsiot, and then press Enter.
5. Enter the command: pip3 install tzlocal, and then press Enter.
6. Enter the command: pip3 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.

Note: If Java is not installed, please refer to the following link to install Java:

• For users using the CentOS operating system: https://linuxize.com/post/install-java-on-centos-8/

 

 

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 Group Name:

• DataIngestionGroup
• CloudPrintingGroup
• MachineInterfaceGroup
• FileUploader

5. Select the Group 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.

Note: For the next two steps it is recommended to turn off the ZScaler Client Connector, otherwise.

10. Enter the command: cd GreengrassV2, and then press Enter.
11. Enter the command: sudo ./ggcV2.sh, and then press Enter to execute the shell 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 trigger it on the portlet by removing it from the group, then adding it to the group that will deploy again.

 

 

Testing Cases

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

 

Data Ingestion

1. Create a new Edge Device whose Group 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", 
                "client_id": "P88", 
                "data_acquisition_ts": str(loc_dt)
            }
 

15. Open the Terminal.
16. Login as a root user.
17. Enter the command: python3  MqttTest.py, and then press Enter.

 

 

Machine Interface

1. Create a new Edge Device whose Group 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. Download the next file: tcpServer.py.
12. Go to the Terminal.
13. Enter the command: sudo python tcpServer.py.
14. 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": "9090",
  "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 Group 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. Download the next file: tcpServer.py.
12. Go to the Terminal.
13. Enter the command: sudo python tcpServer.py.
14. 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 download the tcpServer.py file, and then execute the command: ‘sudo python3 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. Download fileUploader.sh and smb.config and put them in one folder.

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

2. Create or update edge device 

• Create a new one(For first install)
• Update the existing edge device by adding it to FileUpload Group.

 

3. Install Edge Device

• If using the existing edge device, please stop greengrass by command:sudo systemctl stop greengrass.service  
• Download and unzip the greengrass package locally.
• Ask the 42Q mes-support team to provide a palindrome clientID and secret which can access the mes-api and PTSR database.
• Edit core_config.json, add ClientId and Secret as below. The other parameters don’t need to be changed.

  {

    "MaximumUploads":"3",

    "PoolMaxWorkers":"10",

    "RetentionDays":"7",

    "ClientId":"****",

    "Secret":"****",

    "FileType":[

        {

            "SubFolder":"/",

            "MachineType":"panacim",

            "Processer":[

                {

                    "Extension":".xml",

                    "Parser":"panacim"

                }

            ]

        }

    ]

}  

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

 

4. Test Steps

       4.1. Put the panacim xml file to the folder(step1 installed)

     If the xml file is uploaded successfully, check the success folder.

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

   4.3.Go toMultimedia 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.

  Note - Pre Configure for Centos 8.5 / Ubuntu 22.04

For Centos 8.5+ and Ubuntu 22.04,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, add the following command in it.

For Centos 8.5

cgroup_enable=memory cgroup_memory=1 systemd.unified_cgroup_hierarchy=0

    https://lh7-rt.googleusercontent.com/docsz/AD_4nXeso-JnSLZN5Idy9O059iv7CsFCWQmV5nPOR5uYBTg1JlCu5WBb9POiYkMvSjRot4hYRR6V-lyWOS-TqVB2A1GVEFfLl11S-l9pzXjooADvmfJs0mkvf6RdM2WXc8oixydPihg7C2fEwqdWQgNS7mGfAisN?key=ijdfwBlD0A_o0DwLpjzutQ  

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

 

Troubleshooting

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.