# Onboard your gateways to AWS IoT Core for LoRaWAN If you're using AWS IoT Core for LoRaWAN for the first time, you can add your first LoRaWAN gateway and device by using the console. **Note** If you're using a public network to connect your LoRaWAN devices to the cloud, you can skip onboarding your gateways. For more information, see [Managing LoRaWAN traffic from public networks (Everynet)](iot-lorawan-roaming.md). **Before onboarding your gateway** Before you onboard your gateway to AWS IoT Core for LoRaWAN, we recommend that you: + Use gateways that are qualified for use with AWS IoT Core for LoRaWAN. These gateways connect to AWS IoT Core without any additional configuration settings and have a version 2.0.4 or later of the [ LoRa Basics Station](https://doc.sm.tc/station/) software running on them. For more information, see [Managing gateways with AWS IoT Wireless](lorawan-manage-gateways.md). + Consider the naming convention of the resources that you create so that you can more easily manage them. For more information, see [Describing your AWS IoT Wireless resources](getting-started.md#iotwireless-describe-resources). + Have the configuration parameters that are unique to each gateway ready to enter in advance, which makes entering the data into the console go more smoothly. The wireless gateway configuration parameters that AWS IoT requires to communicate with and manage the gateway include the gateway's EUI and its LoRa frequency band. **Topics** + [Consider frequency band selection and add necessary IAM role](lorawan-rfregion-permissions.md) + [Add a gateway to AWS IoT Core for LoRaWAN](lorawan-onboard-gateway-add.md) + [Connect your LoRaWAN gateway and verify its connection status](lorawan-gateway-connection-status.md) # Consider frequency band selection and add necessary IAM role Before you add your gateway to AWS IoT Core for LoRaWAN, we recommend that you consider the frequency band in which your gateway will be operating and add the necessary IAM role for connecting your gateway to AWS IoT Core for LoRaWAN. **Note** If you're adding your gateway using the console, click **Create role** in the console to create the necessary IAM role so you can then skip these steps. You need to perform these steps only if you're using the CLI to create the gateway. ## Consider selection of LoRa frequency bands for your gateways and device connection AWS IoT Core for LoRaWAN supports EU863-870, US902-928, AU915, and AS923-1 frequency bands, which you can use to connect your gateways and devices that are physically present in countries that support the frequency ranges and characteristics of these bands. The EU863-870 and US902-928 bands are commonly used in Europe and North America, respectively. The AS923-1 band is commonly used in Australia, New Zealand, Japan, and Singapore among other countries. The AU915 is used in Australia and Argentina among other countries. For more information about which frequency band to use in your region or country, see [ LoRaWAN® Regional Parameters](https://lora-alliance.org/resource_hub/rp2-101-lorawan-regional-parameters-2/). LoRa Alliance publishes LoRaWAN specifications and regional parameter documents that are available for download from the LoRa Alliance website. The LoRa Alliance regional parameters help companies decide which frequency band to use in their region or country. AWS IoT Core for LoRaWAN's frequency band implementation follows the recommendation in the regional parameters specification document. These regional parameters are grouped into a set of radio parameters, along with a frequency allocation that is adapted to the Industrial, Scientific, and Medical (ISM) band. We recommend that you work with the compliance teams to ensure that you meet any applicable regulatory requirements. ## Add an IAM role to allow the Configuration and Update Server (CUPS) to manage gateway credentials This procedure describes how to add an IAM role that will allow the Configuration and Update Server (CUPS) to manage gateway credentials. Make sure you perform this procedure before a LoRaWAN gateway tries to connect with AWS IoT Core for LoRaWAN; however, you need to do this only once. **Add the IAM role to allow the Configuration and Update Server (CUPS) to manage gateway credentials** 1. Open the [ Roles hub of the IAM console](https://console.aws.amazon.com/iam/home#/roles) and choose **Create role**. 1. If you think that you might have already added the **IoTWirelessGatewayCertManagerRole** role, in the search bar, enter **IoTWirelessGatewayCertManagerRole**. If you see an **IoTWirelessGatewayCertManagerRole** role in the search results, you have the necessary IAM role. You can leave the procedure now. If the search results are empty, you don't have the necessary IAM role. Continue the procedure to add it. 1. In **Select type of trusted entity**, choose **Another AWS account**. 1. In **Account ID**, enter your AWS account ID, and then choose **Next: Permissions**. 1. In the search box, enter **AWSIoTWirelessGatewayCertManager**. 1. In the list of search results, select the policy named **AWSIoTWirelessGatewayCertManager**. 1. Choose **Next: Tags**, and then choose **Next: Review**. 1. In **Role name**, enter **IoTWirelessGatewayCertManagerRole**, and then choose **Create role**. 1. To edit the new role, in the confirmation message, choose **IoTWirelessGatewayCertManagerRole**. 1. In **Summary**, choose the **Trust relationships** tab, and then choose **Edit trust relationship**. 1. In **Policy Document**, change the `Principal` property to look like this example. ``` "Principal": { "Service": "iotwireless.amazonaws.com" }, ``` After you change the `Principal` property, the complete policy document should look like this example. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "iotwireless.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": {} } ] } ``` 1. To save your changes and exit, choose **Update Trust Policy**. You’ve now created the **IoTWirelessGatewayCertManagerRole**. You won’t need to do this again. If you performed this procedure while you were adding a gateway, you can close this window and the IAM console and return to the AWS IoT console to finish adding the gateway. # Add a gateway to AWS IoT Core for LoRaWAN You can add your gateway to AWS IoT Core for LoRaWAN by using the console or the CLI. Before adding your gateway, we recommend that you consider the factors mentioned in the **Before onboarding your gateway** section of [Onboard your gateways to AWS IoT Core for LoRaWAN](lorawan-onboard-gateways.md). If you're adding your gateway for the first time, we recommend that you use the console. If you want to add your gateway by using the CLI instead, you must have already created the necessary IAM role so that the gateway can connect with AWS IoT Core for LoRaWAN. For information about how to create the role, see [Add an IAM role to allow the Configuration and Update Server (CUPS) to manage gateway credentials](lorawan-rfregion-permissions.md#lorawan-onboard-permissions). ## Add a gateway using the console Navigate to the [AWS IoT Core for LoRaWAN](https://console.aws.amazon.com/iot/home#/wireless/landing) **Intro** page of the AWS IoT console and choose **Get started**, and then choose **Add gateway**. If you've already added a gateway, choose **View gateway** to view the gateway that you added. If you would like to add more gateways, choose **Add gateway**. 1. **Provide gateway details and frequency band information** Use the **Gateway details** section to provide information about the device configuration data such as the Gateway's EUI and the frequency band configuration. + **Gateway's EUI** The EUI (Extended Unique Identifier) of the individual gateway device. The EUI is a 16-digit alphanumeric code, such as `c0ee40ffff29df10`, that uniquely identifies a gateway in your LoRaWAN network. This information is specific to your gateway model and you can find it on your gateway device or in its user manual. **Note** The Gateway's EUI is different from the Wi-Fi MAC address that you may see printed on your gateway device. The EUI follows a EUI-64 standard that uniquely identifies your gateway and therefore cannot be resued in other AWS accounts and regions. + **Frequency band (RFRegion)** The gateway's frequency band. You can choose from `US915`, `EU868`, `AU915`, or `AS923-1`, depending on what your gateway supports and which country or region the gateway is physically connecting from. For more information about the bands, see [Consider selection of LoRa frequency bands for your gateways and device connection](lorawan-rfregion-permissions.md#lorawan-frequency-bands). 1. **Specify your wireless gateway configuration data (optional)** These fields are optional and you can use them to provide additional information about the gateway and it's configuration. + **Name, Description, and Tags for your gateway** The information in these optional fields comes from how you organize and describe the elements in your wireless system. You can assign a **Name** to the gateway, use the **Description** field to provide information about the gateway, and use **Tags** to add key-value pairs of metadata about the gateway. For more information on naming and describing your resources, see [Describing your AWS IoT Wireless resources](getting-started.md#iotwireless-describe-resources). + **LoRaWAN configuration using subbands and filters** Optionally, you can also specify LoRaWAN configuration data such as the subbands that you want to use and filters that can control the flow of traffic. For this tutorial, you can skip these fields. For more information, see [Configure subbands and filtering capabilities of your LoRaWAN gateways](lorawan-subband-filter-configuration.md). 1. **Associate an AWS IoT thing with the gateway** Specify whether to create an AWS IoT thing and associate it with the gateway. Things in AWS IoT can make it easier to search and manage your devices. Associating a thing with your gateway lets the gateway access other AWS IoT Core features. 1. **Create and download the gateway certificate** To authenticate your gateway so that it can securely communicate with AWS IoT, your LoRaWAN gateway must present a private key and certificate to AWS IoT Core for LoRaWAN. Create a **Gateway certificate** so that AWS IoT can verify your gateway's identity by using the X.509 Standard. Click the **Create certificate** button and download the certificate files. You'll use them later to configure your gateway. 1. **Copy the CUPS and LNS endpoints and download certificates** Your LoRaWAN gateway must connect to a CUPS or LNS endpoint when establishing a connection to AWS IoT Core for LoRaWAN. We recommend that you use the CUPS endpoint as it also provides configuration management. To verify the authenticity of AWS IoT Core for LoRaWAN endpoints, your gateway will use a trust certificate for each of the CUPS and LNS endpoints, Click the **Copy** button to copy the CUPS and LNS endpoints. You'll need this information later to configure your gateway. Then click the **Download server trust certificates** button to download the trust certificates for the CUPS and LNS endpoints. 1. **Create the IAM role for the gateway permissions** You need to add an IAM role that allows the Configuration and Update Server (CUPS) to manage gateway credentials. **Note** In this step, you create the **IoTWirelessGatewayCertManager** role. If you have already created this role, you can skip this step. You must do this before a LoRaWAN gateway tries to connect with AWS IoT Core for LoRaWAN; however, you need to do it only once. To create the **IoTWirelessGatewayCertManager** IAM role for your account, click the **Create role** button. If the role already exists, select it from the dropdown list. Click **Submit** to complete the gateway creation. ## Add a gateway by using the API **Note** If you're adding a gateway for the first time by using the API or CLI, you must add the **IoTWirelessGatewayCertManager** IAM role so that the gateway can connect with AWS IoT Core for LoRaWAN. For information about how to create the role, see the following section [Add an IAM role to allow the Configuration and Update Server (CUPS) to manage gateway credentials](lorawan-rfregion-permissions.md#lorawan-onboard-permissions). The following sections show how to add a gateway using the AWS IoT Wireless API operations or the AWS CLI. You first add your gateway and then associate a certificate with the gateway. You can also use the additional API operations, such as to update an existing gateway. **Topics** + [How to add your gateway](#lorawan-gateway-api-add) + [Associate a certificate with your gateway](#lorawan-gateway-cert) + [Additional API operations](#lorawan-gateway-api-list) ### How to add your gateway You can use the AWS CLI to create a wireless gateway by using the [CreateWirelessGateway](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessGateway.html) API operation or the [create-wireless-gateway](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-wireless-gateway.html) CLI command to add your wireless gateway. **Note** If your gateway is communicating with class B LoRaWAN devices, you can also specify certain beaconing parameters when adding the gateway using the `CreateWirelessGateway` API or the `create-wireless-gateway` CLI command. For more information, see [Configure beaconing for your LoRaWAN gateways](lorawan-gateway-beaconing.md). The following example creates a wireless LoRaWAN device gateway. You can also provide an `input.json` file that will contain additional details such as the gateway certificate and provisioning credentials. **Note** You can also perform this procedure with the API by using the methods in the AWS API that correspond to the CLI commands shown here. ``` aws iotwireless create-wireless-gateway \ --lorawan GatewayEui="a1b2c3d4567890ab",RfRegion="US915" \ --name "myFirstLoRaWANGateway" \ --description "Using my first LoRaWAN gateway" --cli-input-json file://input.json ``` ### Associate a certificate with your gateway After you add your gateway to AWS IoT Wireless, it must be associated with a certificate to connect to the CUPS endpoint. To connect to the endpoint, your gateway running LoRa Basics Station requires the following files: + `cups.crt` - The gateway's CUPS certificate that it uses to connect to the CUPS endpoint. + `cups.key` - Private key corresponding to the certificate. + `cups.trust` - The trust certificate of the CUPS endpoint. + `cups.uri` - The CUPS endpoint URI. The following steps show you how to generate a certificate and associate it with your gateway. **Topics** + [Step 1: Generating a gateway certificate](#lorawan-gateway-cert-generate) + [Step 2: Obtaining server trust certificate and CUPS endpoint](#lorawan-gateway-cert-obtain) + [Step 3: Associate the certificate with your gateway](#lorawan-gateway-cert-associate) #### Step 1: Generating a gateway certificate To generate a certificate for your gateway, use the AWS IoT API Reference API action, [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateKeysAndCertificate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateKeysAndCertificate.html), or the AWS CLI command, [create-keys-and-certificate](https://docs.aws.amazon.com/cli/latest/reference/iot/create-keys-and-certificate.html) CLI command. The following command shows an example of generating the certificate, `cups.crt`, and the private key, `cups.key`. ``` aws iot create-keys-and-certificate \ --set-as-active --certificate-pem-outfile "cups.crt" \ --private-key-outfile "cups.key" ``` Running this command generates the certificate and private key, and a certificate ID. The following example shows an output of running this command. ``` { "certificateArn": "arn:aws:iot:us-east-1:123456789012:cert/abc1234d55ef32101a34434bb123cba2a011b2cdefa6bb5cee1a221b4567ab12", "certificateId": "abc1234d55ef32101a34434bb123cba2a011b2cdefa6bb5cee1a221b4567ab12", "certificatePem": "-----BEGIN CERTIFICATE-----\n..\n-----END CERTIFICATE-----\n, "KeyPair": { "PublicKey": "-----BEGIN PUBLIC KEY -----\n..\n----END PUBLIC KEY----\n", "PrivateKey": "----BEGIN RSA PRIVATE KEY----\n..\nEND RSA PRIVATE KEY----\n" } } ``` Store the certificate ID temporarily, as it will be used in the subsequent step to associate your certificate with the gateway. **Note** You must securely store the private key, `cups.key`. If you misplace the private key, rerun the `create-keys-and-certificate` command to generate another certificate. #### Step 2: Obtaining server trust certificate and CUPS endpoint Now that you've generated the certificate and private key, use the [GetServiceEndpoint](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetServiceEndpoint.html) API action or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-service-endpoint](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-service-endpoint) CLI command to obtain the server trust certificate, `cups.trust` and the endpoint URI, `cups.uri`. The following command shows an example of obtaining the server trust certificate and the endpoint URI. When running the command, set the `service-type` parameter to `CUPS`. ``` aws iotwireless get-service-endpoint --service-type CUPS ``` The following shows an output of running the command. ``` { "ServiceType": "CUPS", "ServiceEndpoint": "https://ABCDEFGHIJKLMN.cups.lorawan.us-east-1.amazonaws.com:443", "ServerTrust": "-----BEGIN CERTIFICATE-----\n..\n-----END CERTIFICATE-----\n" } ``` The `ServiceEndpoint` obtained from the response corresponds to the CUPS endpoint, `cups.uri`. **Note** Store the `ServerTrust` certificate in a `.pem` file with the `\n` replaced by new lines. #### Step 3: Associate the certificate with your gateway You must associate the gateway's certificate that you generated with the gateway that you added. AWS IoT Core for LoRaWAN will use this information to identify the certificate that the gateway will use to connect to the CUPS endpoint. To associate the certificate with your gateway, use the [AssociateWirelessGatewaywithCertificate](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_AssociateWirelessGatewaywithCertificate.html) API action or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/associate-wireless-gateway-with-certificate.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/associate-wireless-gateway-with-certificate.html) CLI command. The following command shows an example of associating a certificate with your gateway. ``` aws iotwireless associate-wireless-gateway-with-certificate \ --id \ --iot-certificate-id ``` Running this command returns the `IotCertificateId`, which is the ID of the certificate that you associated with the gateway. The following shows an output of running the command, where the `IotCertificateId` is the ID of the certificate, such as `abc1234d55ef32101a34434bb123cba2a011b2cdefa6bb5cee1a221b4567ab12`. ``` { "IotCertificateId": "" } ``` ### Additional API operations You can use the following API actions to perform the tasks associated with adding, updating, or deleting a LoRaWAN gateway. **AWS IoT Wireless API actions for AWS IoT Core for LoRaWAN gateways** + [GetWirelessGateway](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessGateway.html) + [ListWirelessGateways](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListWirelessGateways.html) + [ UpdateWirelessGateway ](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateWirelessGateway.html) + [DeleteWirelessGateway](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteWirelessGateway.html) For the complete list of the actions and data types available to create and manage AWS IoT Core for LoRaWAN resources, see the [AWS IoT Wireless API reference](https://docs.aws.amazon.com/iot-wireless/latest/apireference/welcome.html). For information about the CLIs that you can use, see [AWS CLI reference](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/index.html). # Connect your LoRaWAN gateway and verify its connection status Before you can check the gateway connection status, you must have already added your gateway and connected it to AWS IoT Core for LoRaWAN. For information about how to add your gateway, see [Add a gateway to AWS IoT Core for LoRaWAN](lorawan-onboard-gateway-add.md). **Note** AWS IoT Core for LoRaWAN supports communication using both the IPv4 and IPv6 address format. To enable IPv6 support for your account-specific CUPS and LNS endpoints, if you've already onboarded your LoRaWAN gateways before December 1st, 2024, you must request IPv6 activation. For more information, see [IPv6 activation for data plane endpoints](wireless-ipv6-access.md#iot-wireless-ipv6-activation). ## Connect your gateway to AWS IoT Core for LoRaWAN After you've added your gateway, connect to the configuration interface of your gateway to enter the configuration information and trust certificates. After adding the gateway's information to AWS IoT Core for LoRaWAN, add some AWS IoT Core for LoRaWAN information to the gateway device. The documentation provided by the gateway's vendor should describe the process for uploading the certificate files to the gateway and configuring the gateway device to communicate with AWS IoT Core for LoRaWAN. **Gateways qualified for use with AWS IoT Core for LoRaWAN** For instructions on how to configure your LoRaWAN gateway, refer to the [ configure gateway device](https://iotwireless.workshop.aws/en/200_gateway/400_configuregateway.html) section of the AWS IoT Core for LoRaWAN workshop. Here, you'll find information about instructions for connecting gateways that are qualified for use with AWS IoT Core for LoRaWAN. **Gateways that support CUPS protocol** The following instructions show how you can connect your gateways that support the CUPS protocol. 1. Upload the following files that you obtained when adding your gateway. + Gateway device certificate and private key files. + Trust certificate file for CUPS endpoint, `cups.trust`. 1. Specify the CUPS endpoint URL that you obtained previously. The endpoint will be of the format `prefix.cups.lorawan.region.amazonaws.com:443`. For details about how to obtain this information, see [Add a gateway to AWS IoT Core for LoRaWAN](lorawan-onboard-gateway-add.md). **Gateways that support LNS protocol** The following instructions show how you can connect your gateways that support the LNS protocol. 1. Upload the following files that you obtained when adding your gateway. + Gateway device certificate and private key files. + Trust certificate file for LNS endpoint, `lns.trust`. 1. Specify the LNS endpoint URL that you obtained previously. The endpoint will be of the format https://`prefix.lns.lorawan.region.amazonaws.com:443`. For details about how to obtain this information, see [Add a gateway to AWS IoT Core for LoRaWAN](lorawan-onboard-gateway-add.md). After that you've connected your gateway to AWS IoT Core for LoRaWAN, you can check the status of your connection and get information about when the last uplink was received by using the console or the API. ## Check gateway connection status using the console To check the connection status using the console, navigate to the [https://console.aws.amazon.com/iot/home#/wireless/gateways](https://console.aws.amazon.com/iot/home#/wireless/gateways) page of the AWS IoT console and choose the gateway you've added. In the **LoRaWAN specific details** section of the Gateway details page, you'll see the connection status and the date and time the last uplink was received. ## Check gateway connection status using the API To check the connection status using the API, use the `GetWirelessGatewayStatistics` API. This API doesn't have a request body and only contains a response body that shows whether the gateway is connected and when the last uplink was received. ``` HTTP/1.1 200 Content-type: application/json { "ConnectionStatus": "Connected", "LastUplinkReceivedAt": "2021-03-24T23:13:08.476015749Z", "WirelessGatewayId": "30cbdcf3-86de-4291-bfab-5bfa2b12bad5" } ``` ## Enable connection status events You can also enable connection status events to receive notications about status updates to your gateway connection. You will be notified when a gateway becomes connected, or when it's disconnected. For more information about these events and how to enable them, see [Enable notifications for LoRaWAN gateway connection status events](iot-lorawan-gateway-events.md).