How to install Edge Connector

Introduction

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:

 

1. Open the Terminal.
2. Login as a root user.
3. Enter the command: cat /etc/default/grub, and then press Enter.
4. Enter the command: reboot, and then press Enter. This command will reboot the operating system in order to apply the changes.

 

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

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.

 

Figure 4: Edge Devices Portlet

 

 

4. Right-click on the zip file.
5. Select Extract Here.
6. Open the downloaded folder.
7. Make sure the file ggcV2.sh exists.

 

 

Figure 5: Downloaded Folder Content

 

 

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.

 

Figure 6: Edit Icon

 

 

4. Select the CLIENT DEVICES tab.
5. Select CREATE CLIENT DEVICES.

 

Figure 7: Edge Device Info Pop-up Window

 

 

6. Select the Client Device from the drop-down list.
7. Select ASSOCIATE.

 

Figure 8: Associate Client Device Pop-up Window

 

 

8. Select the Download icon to download the script.

 

 

Figure 9: Download Client Device Icon

 

 

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 10: 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 11: 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 12: 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 13: 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 14: TCP Server Message (Cloud Printing Command)

 

 

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.