Using AWS IoT Greengrass to provision and connect your LoRaWAN gateways at scale

This implementation is for demonstration purposes only.

With AWS IoT Core for LoRaWAN, customers can now setup a fully managed LoRaWAN network by connecting their own LoRaWAN devices and gateways to AWS IoT Core - without developing or operating a LoRaWAN Network Server (LNS). This repository contains an example AWS IoT Greengrass component to provision and manage your LoRaWAN gateways at scale.

AWS IoT Greengrass components are software modules that you deploy to Greengrass core devices. Components can represent applications, runtime installers, libraries, or any code that you would run on a device.

Once deployed to your LoRaWAN Gateway or groups of LoRaWAN gateways, the component will provision the gateway to AWS IoT Core for LoRaWAN, generate and store all the certificates needed to securely connect to the Configuration and Update Server (CUPS) and the LNS server.

Finally, the component will launch Basics Station to connect the gateway to AWS IoT Core for LoRaWAN.

This component has been developed for Raspberry Pi based gateways and tested with the RAK7246 and the RAK7248

Solution architecture

Prerequisites

A Greengrass Version 2 compatible LoRaWAN Gateway. This component has been developed for Raspberry Pi based gateways and tested with the RAK7246 and the RAK7248
To deploy this component, you first need to install AWS IoT Greengrass on your LoRaWAN gateway(s).
Python 3.7 or later installed on your development computer.
AWS Command Line Interface (AWS CLI) installed and configured with credentials on your development computer.
A Basics Station executable named station compiled for your target platform (your LoRaWAN gateways)
Create the IoTWirelessGatewayCertManagerRole to allow the Configuration and Update Server (CUPS) to manage gateway credentials. Make sure you perform this procedure before deploying the component; however, you need to do this only once. This procedure is explained in the video Getting Started with AWS IoT Core for LoRaWAN

Getting Started

This implementation is for demonstration purposes only.

1. Create the artifact for the component

Every Greengrass component is composed of a recipe and artifacts. Artifacts can include scripts, compiled code, static resources, and any other files that a component consumes.

To deploy the component, you need to provide an artifact as an archive file named ggbasics.zip which includes:

The station.conf configuration file. Basics Station requires a configuration file named station.conf, which contains settings for the configuration of the LoRaWAN gateway itself and the configuration of the radio concentrator boards. If you dont' use the one provided in the folder artifacts, make sure to add the field "routerid": "" in the "station_conf"section of your station.conf file.
A Basics Station executable named station compiled for your target platform (your LoRaWAN gateways).
The python script named main.py provided in the artifacts folder. This scripts will provision the LoRaWAN gateway to AWS IoT Core for LoRaWAN.
The reset_gw.shscript that will reset the LoRa concentrator before running Basics Station. This is done to prevent the LoRa concentrator to stay in an Error state. You need to check if the GPIO Pins used in the script suit your Gateway.
A folder dependencies in which the AWS SDK for Python (Boto3) is installed.

Add the Basics Station executable named station compiled for your target platform in the artifact folder and then compress the content of the artifact folder in an archive named ggbasics.zip.

Make sure to compress the content of the folder and not the folder itself.

Before proceeding, you must have a ggbasics.zip archive that contains the following folder and files:

|___station.conf # Configuration file
|___station # Basics Station executable  
|___main.py # Python script to provision the gateway in AWS IoT Core for LoRaWAN
|___reset_gw.sh # Shell script to reset the LoRa concentrator 
|___dependencies # folder with the AWS SDK for Python (Boto3) installed
    |___boto3
    |___*

2. Create an S3 bucket to host your AWS IoT Greengrass component artifacts

Now that you have your artifact ready, you need to create an Amazon S3 bucket (if you don't have one already) to host your AWS IoT Greengrass component artifacts.

Run the following command to create a bucket with your AWS account ID and AWS Region to use a unique bucket name.

Replace 123456789012 with your AWS account ID and awsregion with the AWS Region that you use to provision your gateways.

Make sure that AWS IoT Core for LoRaWAN is available in the region you choose.

aws s3 mb s3://greengrass-component-artifacts-123456789012-awsregion

The command outputs the following information if the request succeeds.

make_bucket: greengrass-component-artifacts-123456789012-awsregion

3. Upload the artifact in your S3 bucket

upload the artifact ggbasics.zip to the Amazon S3 bucket you created in the folder artifacts with the following command.

aws s3 cp ggbasics.zip s3://REPLACE_WITH_YOUR_S3_BUCKET/artifacts/

The command outputs a line that starts with upload: if the request succeeds.

4. Allow the core device to access component artifacts

Allow the Greengrass core device to access component artifacts in this Amazon S3 bucket.

Each core device has a core device IAM role that allows it to interact with AWS IoT and send logs to the AWS Cloud.

You can find this role in the AWS IoT Console, Secure, Role Aliases.

This device role doesn't allow access to Amazon S3 buckets by default, so you must create and attach a policy that allows the core device to retrieve component artifacts from the S3 bucket.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": "arn:aws:s3:::greengrass-component-artifacts-123456789012-awsregion/*"
    }
  ]
}

Then you need to create another policy that authorizes the component to perform the action in IoT and IoTWireless and attach it to the same role.

Your policy needs the following authorizations.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "LorawanGGv2ComponentProvisioning",
            "Effect": "Allow",
            "Action": [
                "iot:CreateKeysAndCertificate",
                "iotwireless:GetWirelessGateway",
                "iotwireless:AssociateWirelessGatewayWithCertificate",
                "iotwireless:GetServiceEndpoint",
                "iotwireless:CreateWirelessGateway"
            ],
            "Resource": "*"
        }
    ]
}

5. Create a component resource in AWS IoT Greengrass

Replace in the recipe recipe.yaml the artifact URI with the artifact's Amazon S3 URI.

Your script artifact's Amazon S3 URI is the URI that you upload the artifact to in the previous step. This URI should look similar to the following example:

s3://greengrass-component-artifacts-123456789012-awsregion/artifacts/ggbasics.zip

The Amazon S3 URI is composed of the bucket name and the path to the artifact object in the bucket.

Configure the LoRa region for your gateways in the LoraRegion parameter.

Create a component resource in AWS IoT Greengrass from the recipe recipe.yaml.

Run the following command to create the component from the recipe, which you provide as a binary file.

aws greengrassv2 create-component-version --inline-recipe fileb://recipe.yaml

The response looks similar to the following example if the request succeeds.

{
    "arn": "arn:aws:greengrass:eu-west-1:123456789012:components:abenfat.lorawan.ggbasics:versions:1.0.0",
    "componentName": "abenfat.lorawan.ggbasics",
    "componentVersion": "1.0.0",
    "creationTimestamp": "2021-07-23T17:04:15.504000+02:00",
    "status": {
        "componentState": "REQUESTED",
        "message": "NONE",
        "errors": {}
    }
}

The abenfat.lorawan.ggbasics component is now available in AWS IoT Greengrass and you can deploy it to your AWS IoT Greengrass core devices.

6. Deploy the component

Before deploying the component, make sure you don't have already your gateway(s) registered to AWS IoT Core for LoRaWAN

With AWS IoT Greengrass, you can deploy components to individual devices or groups of devices. You specify which components to deploy and the configuration update to deploy for each component.

In the navigation pane of the AWS IoT console, choose Greengrass, then choose Components.

you should see the component in the list My Components.

Choose the component, and choose Deploy. If there is an existing deployment that targets your group of gateways, you can add the component to the existing deployment, otherwise you can create a new deployment.

Select the existing deployment and choose Next. Then choose Next again. In the Select components page, make sure you have selected the components you want to deploy and choose Next.

Then choose Next again.

In the Configure advanced settings, leave the default settings and then choose Next.

Finally, choose Deploy.

The deployment can take several minutes to complete. You can check in the Greengrass Core device the component logs to check the deployment:

sudo tail -f /greengrass/v2/logs/abenfat.lorawan.ggbasics.log

You can check that your gateways have been provisioned!

aws-samples/aws-iot-greengrass-component-lorawan-provisioning