# Creating an AWS Greengrass connection

# AWS Greengrass overview

# Why using GreenGrass ?

Combining ThingPark Enterprise OCP together with AWS IoT Greengrass provides enterprises with a dependable local infrastructure to implement their Industrial IoT use cases.
img

AWS IoT Greengrass extends AWS services onto local devices, so that they can act locally on the data ingested, while still taking advantage of the cloud.

ThingPark Enterprise OCP powers highly available LoRaWAN(tm) private networks to ensure efficient sensors’ data aggregation, and smoothly connects to the local AWS Greengrass Core Instance using its Greengrass Connector.

With this solution, sensors’ data can be aggregated and processed locally, and either synchronized to the cloud or delivered to the local application.

# Key Benefits

Executed Locally – Managed globally - Combining Greengrass with ThingPark Enterprise OCP, you don’t have to send your data to a distant cloud which saves you time in cases when milliseconds matter. Data is collected, processed and routed locally to ensure compliancy with the strictest security policies. Although the solution runs locally, Greengrass Core instances are managed from the cloud, ensuring a consistent deployment and maintenance of AWS workloads across multiple facilities, as well as a global application of the company security policies.

No cloud-dependency - AWS Greengrass ensures service continuity with spotty or no cloud connectivity. You may continue to perform local logic and actions based on LoRaWAN sensor input, even during loss of cloud connectivity, and buffer data until the Internet connection is restored. This complements a similar local buffering feature in LoRaWAN infrastructure gateways provided by ThingPark Enterprise and ensures that all critical sensor data is recovered after infrastructure or local connectivity outages.

A dependable infrastructure - Mission critical applications require a fully redundant system, end to end. At radio level this can be provided by leveraging macro-diversity, ensuring that 2 or more gateways provide connectivity to each sensor. ThingPark Enterprise Network Server can also be deployed in HA mode with or without georedundancy, and the same applies to your Greengrass server.

Optimal cloud service consumption - Not all data is worth being sent to the cloud, especially when using high-cost or bandwidth-limited backhaul connections. AWS Greengrass embeds local Lambda compute, local messaging and machine learning inference capabilities to allow data aggregation, transformation or filtering according to your needs. Such data processing is made simple with ThingPark Enterprise support for device CoDecs, making data available in JSON format to the Greengrass Core instance.

# How to install AWS GreenGrass

Install your AWS GreenGrass in 4 steps. img

  1. Set Up your GreenGrass Group
  2. Greengrass Core local installation
    2.a. Linux Greengrass Core local installation
    2.b. Windows 10 Greengrass Core local installation
  3. Connecting with Thingpark
  4. End to end testing

# Set Up your GreenGrass Group

  1. To start with AWS IoT Greengrass you need first to create a Greengrass group: go to AWS IoT Core console and select GreenGrass -> Classic (V1) -> Groups -> Create Group

img

  1. On next screen select Use default creation

img

  1. Fill the group name and press Next

img

  1. Select a name for the Greengrass Core device and a Thing Type (existing or create a new one) and press Next

img

  1. On Review Group creation page, press Create Group and Core

img

  1. On the final page press Download these resources as a tar.gz to save the Greengrass Core device settings that allow local Greengrass to communicate with AWS IoT Core.

On this page you can also download Greengrass Core software to install it on your device. Alternative is to use the docker version of it, as we detail later in the doc.

img

  1. Press Finish and you will see the new Greengrass Group is created.

img

  1. Select the newly created GreenGrass Group

img

Important note

Each Greengrass Group has one Core.
We will create automatically a single virtual device (GreenGrass Aware Device GGAD) that will connect to local Greengrass and multiplex all messages over a MQTT connection. This GGAD is created only when an uplink is sent.
Also we need to add Subscriptions from local to cloud (for uplink path) and from cloud to local (for downlink path). See Creation of subscriptions
Of course Greengrass allows much complex scenarios like Device -> Lambda -> Device all local, without sending data to cloud at all. The customer can define other Subscriptions, Lambdas etc than default ones.

# Linux Greengrass Core local installation

  1. The downloaded certificate tar.gz file at the end of the Greengrass group creation contains 2 folders: certs and config.
    Extract the archive for example under /greengrass folder, so you will have /greengrass/certs and /greengrass/config paths.

Beside Core Device certificate/privateKey you need also AWS Root CA too:

curl https://www.amazontrust.com/repository/AmazonRootCA1.pem -o
/greengrass/certs/root.ca.pem

2a. For Linux env run the following command (assuming you use /greengrass folder):

docker run \--rm \--privileged \--init -it \--name aws-iot-greengrass
\--entrypoint /greengrass-entrypoint.sh -v
/greengrass/certs:/greengrass/certs -v
/greengrass/config:/greengrass/config -v
/greengrass/ggc/var/log:/greengrass/ggc/var/log -p 8883:8883
amazon/aws-iot-greengrass

# Windows 10 Greengrass Core local installation

  1. The downloaded certificate tar.gz file at the end of the Greengrass group creation contains 2 folders: certs and config.
    Extract the archive under C:/greengrass folder, so you will have C:/greengrass/certs and C:/greengrass/config paths.

  2. You also need to download the AWS Root CA:

  curl https://www.amazontrust.com/repository/AmazonRootCA1.pem -o
    C:/greengrass/certs/root.ca.pem
  1. Start Greengrass core by running the following command:
    docker run --rm --privileged --init -it --name aws-iot-greengrass -v c:/greengrass/certs:/greengrass/certs -v c:/greengrass/config:/greengrass/config -v c:/greengrass/ggc/var/log:/greengrass/ggc/var/log -p 8883:8883 amazon/aws-iot-greengrass

After execution, it should open the bash prompt. Then, Remount the proc directory as rw by running this command:

mount -o remount rw /proc

After remounting the proc directory, edit the protected_hardlinks with this command:

echo 1 \> /proc/sys/fs/protected_hardlinks

Edit the protected_symlinks with this command:

echo 1 \> /proc/sys/fs/protected_symlinks

Start greengrass with the command below:

./greengrass-entrypoint.sh

The result could be similar to:

bash-4.2# ./greengrass-entrypoint.sh
grep: /greengrass/ggc/deployment/group/group.json: No such file or directory
Setting up greengrass daemon
Validating hardlink/softlink protection
Waiting for up to 1m10s for Daemon to start

Greengrass successfully started with PID: 15

Note

Alternative is to follow the instructions how to install Greengrass Core software depending on your OS: AWS IoT Greengrass downloads (opens new window)

  1. At this point you can go to the Greengrass Group page and from Actions menu do a new Deploy, so that the latest config done on the cloud is synced with local Greengrass.

img

  1. Select Automatic detection on next page of the deployment:

img

After a few seconds you should be able to see the deployment result:

img

What we did until now was to run and configure the Greengrass Core software so that in can communicate with AWS IoT Core over MQTT using the Core Device:

img

Note

All security details could be found here : Overview of AWS IoT Greengrass security (opens new window)

img

Now devices can connect to the local Greengrass Core broker over MQTT using Group CA and device certificate/privateKey and use their thingName as a clientId of the MQTT connection. To be able to multiplex all devices messages over a single MQTT connection we will add a virtual bridge device to the AWS IoT Core and add it to the Greengrass Group, so it will be the only GreenGrass Aware Device (GGAD) in the group. After that we will add proper Subscriptions to allow message exchange between local Greengrass and cloud AWS IoT Core broker.

  1. Select Devices -> Add your first Device

img

  1. On the next page select Create New Device

img

  1. On next page set the bridge GGAD thing name and type and click Next

img

  1. On device security page select Use defaults img

  2. And on the final page save the device certificate and private key (click on Download these resources as a tar.gz) and click Finish

img

Now the group has one Greengrass aware device that will act as a bridge device:

img

WARNING

After any modification to Greengrass Group, you need to do a new deploy, otherwise new devices, subscriptions and other stuff are not sent to local Greengrass software and Greengrass Discovery RESTful API does not find new added devices.

img

To test the bridge device use the following command:

curl --key cb129e54bc.private.key --cert cb129e54bc.cert.pem https://greengrass-ats.iot.eu-central-1.amazonaws.com:8443/greengrass/discover/thing/demoGGG_Bridge

The result should be similar to

{
  "GGGroups": [
    {
      "GGGroupId": "0267d30c-a639-4a33-94e5-f0aed5a8383f",
	    "Cores": [
	      {
		    "thingArn": "arn:aws:iot:eu-central-1:076081621542:thing/demoGGG_Core",
		    "Connectivity": [
			  {
		      "Id": "AUTOIP_127.0.0.1_0",
			    "HostAddress": "127.0.0.1",
			    "PortNumber": 8883,
			    "Metadata": ""
		    },
			  {
			    "Id": "AUTOIP_172.17.0.2_1",
			    "HostAddress": "172.17.0.2",
			    "PortNumber": 8883,
			    "Metadata": ""
			  }
		  ]
		}
	  ],
	  "CAs": ["-----BEGIN CERTIFICATE-----*****-----END CERTIFICATE-----\n"]
	}
  ]
}

# Connecting with Thingpark

# Bridge topic or device topic ?

Depending of your use case, you need do a choice that impact your architecture. The communication between Thingpark and Greengrass Core (Local), could be done throught one unique topic (Bridge topic) that collect all uplinks of all Thingpark devices, or you can choose a more traditionnal way by using one topic per devices.

# Bridge topic architecture (recommanded)

A bridge topic concentrate all uplinks of all devices on a local Lambda function, you can create your own security rules and dispatch on AWS IoT-Core Cloud all messages that you want see. You control the traffic exchanged with the Cloud. img

Your uplinkTopicPattern should be similar to this : tpx/things/ActilityGreenGrassBridge/uplink

# Device topic architecture

Each device has is own topic. You assume that all of your local devices can communicate with your AWS IoT-Core. If you already use AWS IoT-Core, this behavior is more traditionnal, but not recommanded on a Greengrass architecture, the traffic generated is not really controlled.

img

Your uplinkTopicPattern should be similar to this : tpx/things/{DevEUI}/uplink

# Using REST API

The connection can be created throught REST API by using :

  • POST/connections to create a new Connection instance
  • PUT/connections/{connectionId} to update a Connection instance
  • DELETE/connections/{connectionId} to delete a Connection instance

Note

We follow the REST-full API pattern, when updating configuration properties for a connection resource. Thus, you must also provide the whole configuration again.

Example for creation of a new connection instance :

{
  "connectorId": "actility-aws-iot-greengrass",
  "name": "GreenGrass Core connection",
  "configuration": {
    "region": "eu-central-1",
    "accessKeyId": "I2DGDNWRAKNITFIAR74Q",
    "secretAccessKey": "UKLctg3V/tFORwr9EF8Gxs/ciZlgH5bDNmVwyzlj",
    "awsRootCa": "-----BEGIN CERTIFICATE-----MIIDQTCCAimgAwIBAxxxx-----END CERTIFICATE-----",
    "ggHostName": "127.0.0.1:8883",
    "ggadThingName": "ActilityGreenGrassBridge",
    "ggadCertificateId": "arn:aws:iot:eu-central-1:054281621076:cert/b129xxxx",
    "ggadCertificate": "-----BEGIN CERTIFICATE-----MIIDWTCCAkGgAwIBxxxxxxx-----END CERTIFICATE-----",
    "ggadPrivateKey": "-----BEGIN RSA PRIVATE KEY-----MIIEowxxxxxx-----END RSA PRIVATE KEY-----",
    "deviceType": "ActilityGGADType",
    "uplinkTopicPattern": "tpx/things/ActilityGreenGrassBridge/uplink",
    "downlinkTopicPattern": "tpx/things/ActilityGreenGrassBridge/downlink"
  }
}

WARNING

We recommend doing these steps to generate the inline certificates ggadPrivateKey and ggadCertificate:

ggadPrivateKey:

  1. Inside your greengrass/certs folder, save the .private.key file on a linux machine
  2. Execute the following command: cat cb129e54bc.private.key | sed 's/$/\n/' | tr -d '\n'
  3. Copy and paste the value inside the json payload

ggadCertificate:

  1. Inside your greengrass/certs folder, save the .cert.pem file on a linux machine
  2. Execute the following command: cat cb129e54bc.cert.pem | tr -d '\n'
  3. Copy and paste the value inside the json payload

# Using TPE UI

On ThingPark Enterprise (TPE), you can create your Greengrass connection. img img

# Creation of subscriptions

To allow messages to flow from bridge device to cloud and from cloud to bridge device we need to add 2 Subscriptions and do a new deployment.

  1. Go to Subscriptions and select Add Subscription

img

  1. For uplink path select source bridge device to service IoT Cloud and click Next

img

img

Note

If you use a topic per device (that contain {DevEUI}), you need replace {DevEUI} variable with +
Example: tpx/things/{DevEUI}/uplink become tpx/things/+/uplink

img

  1. On confirmation page press Finish

img

img

We do the same steps to add a Subscription for downlink path, from IoT Cloud Service to bridge device and choose topic filter similar to downlinkTopicPattern tpx/things/+/downlink

img

img

img

img

img

In the end don't forget to do a new Deploy

img

# End to end testing

Now we can test the uplink path.

  1. Go to Test and subscribe to your topic (tpx/things/ActilityGreenGrassBridge/uplink)

img

img

  1. Start the Actility AWS Greengrass connection and wait for devices to send uplinks.

img

The missing devices are automatically created (unless createDevices is set explicit to false in connection config) using the specified deviceType inside connection config and having same thingPrincipal as bridge device.

img

Last Updated: 2/2/2021, 3:45:33 PM

← Connecting to AZURE IoT →