# Connecting gateways and devices to AWS IoT Core for LoRaWAN AWS IoT Core for LoRaWAN helps you connect and manage wireless LoRaWAN (low-power long-range Wide Area Network) devices and replaces the need for you to develop and operate an LNS. Long range WAN (LoRaWAN) devices and gateways can connect to AWS IoT Core by using AWS IoT Core for LoRaWAN. ## Naming conventions for your devices, gateways, profiles, and destinations Before you get started with AWS IoT Core for LoRaWAN and create the resources, consider the naming convention of your devices, gateways, and destination. AWS IoT Core for LoRaWAN assigns unique IDs to the resources you create for wireless devices, gateways, and profiles; however, you can also give your resources more descriptive names to make it easier to identify them. Before you add devices, gateways, profiles, and destinations to AWS IoT Core for LoRaWAN, consider how you'll name them to make them easier to manage. You can also add tags to the resources you create. Before you add your LoRaWAN devices, consider how you might use tags to identify and manage your AWS IoT Core for LoRaWAN resources. Tags can be modified after you add them. For more information about naming and tagging, see [Describing your AWS IoT Wireless resources](getting-started.md#iotwireless-describe-resources). ## Mapping of device data to service data The data from LoRaWAN wireless devices is often encoded to optimize bandwidth. These encoded messages arrive at AWS IoT Core for LoRaWAN in a format that might not be easily used by other AWS services. AWS IoT Core for LoRaWAN uses AWS IoT rules that can use AWS Lambda functions to process and decode the device messages to a format that other AWS services can use. To transform device data and send it to other AWS services, you need to know: + The format and contents of the data that the wireless devices send. + The service to which you want to send the data. + The format that service requires. Using that information, you can create the AWS IoT rule that performs the conversion and sends the converted data to the AWS services that will use it. ## Using the console to onboard your device and gateway to AWS IoT Core for LoRaWAN You can use the console interface or the API to add your LoRaWAN gateway and devices. If you're using AWS IoT Core for LoRaWAN for the first time, we recommend that you use the console. The console interface is most practical when managing a few AWS IoT Core for LoRaWAN resources at a time. When managing large numbers of AWS IoT Core for LoRaWAN resources, consider creating more automated solutions by using the AWS IoT Wireless API. **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). Much of the data that you enter when configuring AWS IoT Core for LoRaWAN resources is provided by the devices' vendors and is specific to the LoRaWAN specifications they support. The following topics describe how you can describe your AWS IoT Core for LoRaWAN resources and use the console or the API to add your gateways and devices. **Topics** + [Naming conventions for your devices, gateways, profiles, and destinations](#lorawan-naming-convention) + [Mapping of device data to service data](#lorawan-service-device-data) + [Using the console to onboard your device and gateway to AWS IoT Core for LoRaWAN](#lorawan-console) + [Onboard your gateways to AWS IoT Core for LoRaWAN](lorawan-onboard-gateways.md) + [Onboard your devices to AWS IoT Core for LoRaWAN](lorawan-onboard-end-devices.md) # 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). # Onboard your devices to AWS IoT Core for LoRaWAN After you have onboarded your gateway to AWS IoT Core for LoRaWAN and verified its connection status, you can onboard your wireless devices. For information about how to onboard your gateways, see [Onboard your gateways to AWS IoT Core for LoRaWAN](lorawan-onboard-gateways.md). LoRaWAN devices use a LoRaWAN protocol to exchange data with cloud-hosted applications. AWS IoT Core for LoRaWAN supports devices that comply to 1.0.x or 1.1 LoRaWAN specifications standardized by LoRa Alliance. A LoRaWAN device typically contains one or more sensors and actors. The devices send uplink telemetry data through LoRaWAN gateways to AWS IoT Core for LoRaWAN. Cloud-hosted applications can control the sensors by sending downlink commands to LoRaWAN devices through LoRaWAN gateways. **Before onboarding your wireless device** Before you onboard your wireless device to AWS IoT Core for LoRaWAN, you need to have the following information ready in advance: + **LoRaWAN specification and wireless device configuration** Having the configuration parameters that are unique to each device ready to enter in advance makes entering the data into the console go more smoothly. The specific parameters that you need to enter depend on the LoRaWAN specification that the device uses. For the complete listing of its specifications and configuration parameters, see each device's documentation. + **Device name and description (optional)** The information in these optional fields comes from how you organize and describe the elements in your wireless system. For more information about naming and describing your resources, see [Describing your AWS IoT Wireless resources](getting-started.md#iotwireless-describe-resources). + **Device and service profiles** Have some wireless device configuration parameters ready that are shared by many devices and can be stored in AWS IoT Core for LoRaWAN as device and service profiles. The configuration parameters are found in the device's documentation or on the device itself. You'll want to identify a device profile that matches the configuration parameters of the device, or create one if necessary, before you add the device. For more information, see [Add profiles to AWS IoT Core for LoRaWAN](lorawan-define-profiles.md). + **AWS IoT Core for LoRaWAN destination** Each device must be assigned to a destination that will process its messages to send to AWS IoT and other services. The AWS IoT rules that process and send the device messages are specific to the device's message format. To process the messages from the device and send them to the correct service, identify the destination you'll create to use with the device's messages and assign it to the device. **Topics** + [Add your wireless device to AWS IoT Core for LoRaWAN](lorawan-end-devices-add.md) + [Add profiles to AWS IoT Core for LoRaWAN](lorawan-define-profiles.md) + [Add destinations to AWS IoT Core for LoRaWAN](lorawan-create-destinations.md) + [Create rules to process LoRaWAN device messages](lorawan-destination-rules.md) + [Connect your LoRaWAN device and verify its connection status](lorawan-device-connection-status.md) # Add your wireless device to AWS IoT Core for LoRaWAN If you're adding your wireless device for the first time, we recommend that you use 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, choose **Get started**, and then choose **Add device**. If you've already added a device, choose **View device** to view the gateway that you added. If you would like to add more devices, choose **Add device**. Alternatively, you can also add wireless devices from the [ Devices](https://console.aws.amazon.com/iot/home#/wireless/devices) page of the AWS IoT console. ## Add your wireless device specification to AWS IoT Core for LoRaWAN using the console Choose a **Wireless device specification** based on your activation method and the LoRaWAN version. Once selected, your data is encrypted with a key that AWS owns and manages for you. **OTAA and ABP activation modes** Before your LoRaWAN device can send uplink data, you must complete a process called *activation* or *join procedure*. To activate your device, you can either use OTAA (Over the air activation) or ABP (Activation by personalization). ABP doesn't require a join procedure and uses static keys. When you use OTAA, your LoRaWAN device sends a join request and the Network Server can allow the request. We recommend that you use OTAA to activate your device because new session keys are generated for each activation, which makes it more secure. **LoRaWAN version** When you use OTAA, your LoRaWAN device and cloud-hosted applications share the root keys. These root keys depend on whether you're using version v1.0.x or v1.1. v1.0.x has only one root key, **AppKey** (Application Key) whereas v1.1 has two root keys, **AppKey** (Application Key) and **NwkKey** (Network Key). The session keys are derived based on the root keys for each activation. Both the **NwkKey** and **AppKey** are 32-digit hexadecimal values that your wireless vendor provided. **Wireless Device EUIs** After you select the **Wireless device specification**, you see the EUI (Extended Unique Identifier) parameters for the wireless device displayed on the console. You can find this information from the documentation for the device or the wireless vendor. + **DevEUI**: 16-digit hexademical value that is unique to your device and found on the device label or its documentation. + **AppEUI**: 16-digit hexademical value that is unique to the join server and found in the device documentation. In LoRaWAN version v1.1, the **AppEUI** is called as **JoinEUI**. For more information about the unique identifiers, session keys, and root keys, refer to the [ LoRa Alliance](https://lora-alliance.org/about-lorawan) documentation. ## Add your wireless device specification to AWS IoT Core for LoRaWAN by using the API If you're adding a wireless device using the API, you must create your device profile and service profile first before creating the wireless device. You'll use the device profile and service profile ID when creating the wireless device. For information about how to create these profiles using the API, see [Add a device profile by using the API](lorawan-define-profiles.md#lorawan-device-profile-api). The following lists describe the API actions that perform the tasks associated with adding, updating, or deleting a service profile. **AWS IoT Wireless API actions for service profiles** + [CreateWirelessDevice](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html) + [GetWirelessDevice](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessDevice.html) + [ListWirelessDevices](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListWirelessDevices.html) + [ UpdateWirelessDevice](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateWirelessDevice.html) + [DeleteWirelessDevice](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteWirelessDevice.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). **How to use the AWS CLI to create a wireless device** You can use the AWS CLI to create a wireless device by using the [create-wireless-device](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-device-profile.html) command. The following example creates a wireless device by using an input.json file to input the parameters. **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. **Contents of input.json** ``` { "Description": "My LoRaWAN wireless device", "DestinationName": "IoTWirelessDestination", "LoRaWAN": { "DeviceProfileId": "ab0c23d3-b001-45ef-6a01-2bc3de4f5333", "ServiceProfileId": "fe98dc76-cd12-001e-2d34-5550432da100", "OtaaV1_1": { "AppKey": "3f4ca100e2fc675ea123f4eb12c4a012", "JoinEui": "b4c231a359bc2e3d", "NwkKey": "01c3f004a2d6efffe32c4eda14bcd2b4" }, "DevEui": "ac12efc654d23fc2" }, "Name": "SampleIoTWirelessThing", "Type": LoRaWAN } ``` You can provide this file as input to the `create-wireless-device` command. ``` aws iotwireless create-wireless-device \ --cli-input-json file://input.json ``` For information about the CLIs that you can use, see [AWS CLI reference](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/index.html) # Add profiles to AWS IoT Core for LoRaWAN Device and service profiles can be defined to describe common device configurations. These profiles describe configuration parameters that are shared by devices to make it easier to add those devices. AWS IoT Core for LoRaWAN supports device profiles and service profiles. The configuration parameters and the values to enter into these profiles are provided by the device's manufacturer. ## Add device profiles Device profiles define the device capabilities and boot parameters that the network server uses to set the LoRaWAN radio access service. It includes selection of parameters such as LoRa frequency band, LoRa regional parameters version, and MAC version of the device. To learn about the different frequency bands, see [Consider selection of LoRa frequency bands for your gateways and device connection](lorawan-rfregion-permissions.md#lorawan-frequency-bands). ### Add a device profile by using the console If you're adding a wireless device by using the console as described in [Add your wireless device specification to AWS IoT Core for LoRaWAN using the console](lorawan-end-devices-add.md#lorawan-end-device-spec-console), after you've added the wireless device specification, you can add your device profile. Alternatively, you can also add wireless devices from the [ Profiles](https://console.aws.amazon.com/iot/home#/wireless/profiles) page of the AWS IoT console on the **LoRaWAN** tab. You can choose from default device profiles or create a new device profile. We recommend that you use the default device profiles. If your application requires you to create a device profile, provide a **Device profile name**, select the **Frequency band (RfRegion)** that you're using for the device and gateway, and keep the other settings to the default values, unless specified otherwise in the device documentation. ### Add a device profile by using the API If you're adding a wireless device by using the API, you must create your device profile before creating the wireless device. The following lists describe the API actions that perform the tasks associated with adding, updating, or deleting a service profile. **AWS IoT Wireless API actions for service profiles** + [CreateDeviceProfile](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDeviceProfile.html) + [GetDeviceProfile](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetDeviceProfile.html) + [ListDeviceProfiles](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListDeviceProfiles.html) + [DeleteDeviceProfile](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteDeviceProfile.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). **How to use the AWS CLI to create a device profile** You can use the AWS CLI to create a device profile by using the [create-device-profile](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-device-profile.html) command. The following example creates a device profile. ``` aws iotwireless create-device-profile ``` Running this command automatically creates a device profile with an ID that you can use when creating the wireless device. You can now create the service profile using the following API and then create the wireless device by using the device and service profiles. ``` { "Arn": "arn:aws:iotwireless:us-east-1:123456789012:DeviceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d", "Id": "12345678-a1b2-3c45-67d8-e90fa1b2c34d" } ``` For information about the CLIs that you can use, see [AWS CLI reference](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/index.html) ## Add service profiles Service profiles describe the communication parameters the device needs to communicate with the application server. **Note** When creating a service profile, you can specify that you want to use the public network instead of your own private LoRaWAN gateway. For more information, see [Managing LoRaWAN traffic from public networks (Everynet)](iot-lorawan-roaming.md). ### Add a service profile using the console If you're adding a wireless device using the console as described in [Add your wireless device specification to AWS IoT Core for LoRaWAN using the console](lorawan-end-devices-add.md#lorawan-end-device-spec-console), after you've added the device profile, you can add your service profile. Alternatively, you can also add wireless devices from the [ Profiles](https://console.aws.amazon.com/iot/home#/wireless/profiles) page of the AWS IoT console on the **LoRaWAN** tab. We recommend that you leave the setting **AddGWMetaData** enabled so that you'll receive additional gateway metadata for each payload, such as RSSI and SNR for the data transmission. ### Add a service profile using the API If you're adding a wireless device using the API, you must first create your service profile before creating the wireless device. The following lists describe the API actions that perform the tasks associated with adding, updating, or deleting a service profile. **AWS IoT Wireless API actions for service profiles** + [CreateServiceProfile](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateServiceProfile.html) + [GetServiceProfile](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetServiceProfile.html) + [ListServiceProfiles](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListServiceProfiles.html) + [DeleteServiceProfile](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteServiceProfile.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). **How to use the AWS CLI to create a service profile** You can use the AWS CLI to create a service by using the [create-service-profile](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-service-profile.html) command. The following example creates a service profile. ``` aws iotwireless create-service-profile ``` Running this command automatically creates a service profile with an ID that you can use when creating the wireless device. You can now create the wireless device by using the device and service profiles. ``` { "Arn": "arn:aws:iotwireless:us-east-1:123456789012:ServiceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d", "Id": "12345678-a1b2-3c45-67d8-e90fa1b2c34d" } ``` # Add destinations to AWS IoT Core for LoRaWAN AWS IoT Core for LoRaWAN destinations describe the AWS IoT rule that processes a device's data for use by AWS services. Because most LoRaWAN devices don't send data to AWS IoT Core for LoRaWAN in a format that can be used by AWS services, an AWS IoT rule must process it first. The AWS IoT rule contains the SQL statement that interprets the device's data and the topic rule actions that send the result of the SQL statement to the services that will use it. If you're adding your destination for the first time, we recommend that you use the console. ## Add a destination using the console If you're adding a wireless device using the console as described in [Add your wireless device specification to AWS IoT Core for LoRaWAN using the console](lorawan-end-devices-add.md#lorawan-end-device-spec-console), after you've already added the wireless device specification and profiles to AWS IoT Core for LoRaWAN as described previously, you can go ahead and add a destination. Alternatively, you can also add an AWS IoT Core for LoRaWAN destination from the [ Destinations](https://console.aws.amazon.com/iot/home#/wireless/destinations) page of the AWS IoT console. To process a device's data, specify the following fields when creating an AWS IoT Core for LoRaWAN destination, and then choose **Add destination**. + **Destination details** Enter a **Destination name** and an optional description for your destination. + **Rule name** The AWS IoT rule that is configured to evaluate messages sent by your device and process the device's data. The rule name will be mapped to your destination. The destination requires the rule to process the messages that it receives. You can choose for the messages to be processed by either invoking an AWS IoT rule or by publishing to the AWS IoT message broker. + If you choose **Enter a rule name**, enter a name, and then choose **Copy** to copy the rule name that you'll enter when creating the AWS IoT rule. You can either choose **Create rule** to create the rule now or navigate to the [Rules](https://console.aws.amazon.com/iot/home#/create/rule) Hub of the AWS IoT console and create a rule with that name. You can also enter a rule and use the **Advanced** setting to specify a topic name. The topic name is provided during rule invocation and is accessed by using the `topic` expression inside the rule. For more information about AWS IoT rules, see [https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html). + If you choose **Publish to AWS IoT message broker**, enter a topic name. You can then copy the MQTT topic name and multiple subscribers can subscribe to this topic to receive messages published to that topic. For more information, see [https://docs.aws.amazon.com/iot/latest/developerguide/topics.html](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html). For more information about AWS IoT rules for destinations, see [Create rules to process LoRaWAN device messages](lorawan-destination-rules.md). + **Role name** The IAM role that grants the device's data permission to access the rule named in **Rule name**. In the console, you can create a new service role or select an existing service role. If you're creating a new service role, you can either enter a role name (for example, **IoTWirelessDestinationRole**), or leave it blank for AWS IoT Core for LoRaWAN to generate a new role name. AWS IoT Core for LoRaWAN will then automatically create the IAM role with the appropriate permissions on your behalf. For more information about IAM roles, see [Using IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html). ## Add a destination by using the API If you want to add a destination using the CLI instead, you must have already created the rule and IAM role for your destination. For more information about the details that a destination requires in the role, see [Create an IAM role for your destinations](#lorawan-create-destinations-roles). The following list contains the API actions that perform the tasks associated with adding, updating, or deleting a destination. **AWS IoT Wireless API actions for destinations** + [CreateDestination](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDestination.html) + [GetDestination](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetDestination.html) + [ListDestinations](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListDestinations.html) + [ UpdateDestination](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateDestination.html) + [DeleteDestination](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteDestination.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). **How to use the AWS CLI to add a destination** You can use the AWS CLI to add a destination by using the [create-destination](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-destination.html) command. The following example shows how to create a destination by entering a rule name by using `RuleName` as the value for the `expression-type` parameter. If you want to specify a topic name for publishing or subscribing to the message broker, change the `expression-type` parameter's value to `MqttTopic`d. ``` aws iotwireless create-destination \ --name IoTWirelessDestination \ --expression-type RuleName \ --expression IoTWirelessRule \ --role-arn arn:aws:iam::123456789012:role/IoTWirelessDestinationRole ``` Running this command creates a destination with the specified destination name, rule name, and role name. For information about rule and role names for destinations, see [Create rules to process LoRaWAN device messages](lorawan-destination-rules.md) and [Create an IAM role for your destinations](#lorawan-create-destinations-roles). For information about the CLIs that you can use, see [AWS CLI reference](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/index.html). ## Create an IAM role for your destinations AWS IoT Core for LoRaWAN destinations require IAM roles that give AWS IoT Core for LoRaWAN the permissions necessary to send data to the AWS IoT rule. If such a role is not already defined, uou must define it so that it will appear in the list of roles. When you use the console to add a destination, AWS IoT Core for LoRaWAN automatically creates an IAM role for you, as described previously in this topic. When you add a destination using the API or CLI, you must create the IAM role for your destination. **To create an IAM policy for your AWS IoT Core for LoRaWAN destination role** 1. Open the [ Policies hub of the IAM console](https://console.aws.amazon.com/iam/home#/policies). 1. Choose **Create policy**, and choose the **JSON** tab. 1. In the editor, delete any content from the editor and paste this policy document. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:DescribeEndpoint", "iot:Publish" ], "Resource": "*" } ] } ``` 1. Choose **Review policy**, and in **Name**, enter a name for this policy. You'll need this name to use in the next procedure. You can also describe this policy in **Description**, if you want. 1. Choose **Create policy**. **To create an IAM role for an AWS IoT Core for LoRaWAN destination** 1. Open the [ Roles hub of the IAM console](https://console.aws.amazon.com/iam/home#/roles) and choose **Create role**. 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 the name of the IAM policy that you created in the previous procedure. 1. In the search results, check the IAM policy that you created in the previous procedure. 1. Choose **Next: Tags**, and then choose **Next: Review**. 1. In **Role name**, enter the name of this role, and then choose **Create role**. 1. In the confirmation message, choose the name of the role you created to edit the new role. 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**. With this role defined, you can find it in the list of roles when you configure your AWS IoT Core for LoRaWAN destinations. # Create rules to process LoRaWAN device messages AWS IoT rules send device messages to other services. AWS IoT rules can also process the binary messages received from a LoRaWAN device to convert the messages to other formats that can make them easier for other services to use. [AWS IoT Core for LoRaWAN destinations](lorawan-create-destinations.md) associate a wireless device with the rule that processes the device's message data to send to other services. The rule acts on the device's data as soon as AWS IoT Core for LoRaWAN receives it. [AWS IoT Core for LoRaWAN destinations](lorawan-create-destinations.md) can be shared by all devices whose messages have the same data format and that send their data to the same service. ## How AWS IoT rules process device messages How an AWS IoT rule processes a device's message data depends on the service that will receive the data, the format of the device's message data, and the data format that the service requires. Typically, the rule calls an AWS Lambda function to convert the device's message data to the format a service requires, and then sends the result to the service. The following illustration shows how message data is secured and processed as it moves from the wireless device to an AWS service. ![\[Image showing how AWS IoT Core for LoRaWAN data is passed from a wireless device to AWS IoT and other services.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-lorawan-data-flow.png) 1. The LoRaWAN wireless device encrypts its binary messages using AES128 CTR mode before it transmits them. 1. AWS IoT Core for LoRaWAN decrypts the binary message and encodes the decrypted binary message payload as a base64 string. 1. The resulting base64-encoded message is sent as a message payload, that is not formatted as a JSON document, to the AWS IoT rule described in the destination assigned to the device. 1. The AWS IoT rule directs the message data to the service described in the rule's configuration. The encrypted binary payload received from the wireless device is not altered or interpreted by AWS IoT Core for LoRaWAN. The decrypted binary message payload is encoded only as a base64 string. For services to access the data elements in the binary message payload, the data elements must be parsed out of the payload by a function called by the rule. The base64-encoded message payload is an ASCII string, so it could be stored as such to be parsed later. ## Create rules for LoRaWAN devices AWS IoT Core for LoRaWAN uses AWS IoT rules to securely send device messages directly to other AWS services without the need to use the message broker. By removing the message broker from the ingestion path, it reduces costs and optimizes the data flow. For an AWS IoT Core for LoRaWAN rule to send device messages to other AWS services, it requires an AWS IoT Core for LoRaWAN destination and an AWS IoT rule assigned to that destination. The AWS IoT rule must contain a SQL query statement and at least one rule action. Typically, the AWS IoT rule query statement consists of: + A SQL SELECT clause that selects and formats the data from the message payload + A topic filter (the FROM object in the rule query statement) that identifies the messages to use + An optional conditional statement (a SQL WHERE clause) that specifies conditions on which to act Here is an example of a rule query statement: ``` SELECT temperature FROM iot/topic' WHERE temperature > 50 ``` When building AWS IoT rules to process payloads from LoRaWAN devices, you do not have to specify the FROM clause as part of the rule query object. The rule query statement must have the SQL SELECT clause and can optionally have the WHERE clause. If the query statement uses the FROM clause, it is ignored. Here is an example of a rule query statement that can process payloads from LoRaWAN devices: ``` SELECT WirelessDeviceId, WirelessMetadata.LoRaWAN.FPort as FPort, WirelessMetadata.LoRaWAN.DevEui as DevEui, PayloadData ``` In this example, the `PayloadData` is a base64-encoded binary payload sent by your LoRaWAN device. Here is an example rule query statement that can perform a binary decoding of the incoming payload and transform it into a different format such as JSON: ``` SELECT WirelessDeviceId, WirelessMetadata.LoRaWAN.FPort as FPort, WirelessMetadata.LoRaWAN.DevEui as DevEui, aws_lambda("arn:aws:lambda:::function:", { ]"PayloadData":PayloadData, "Fport": WirelessMetadata.LoRaWAN.FPort } ) as decodingoutput ``` For more information on using the SELECT AND WHERE clauses, see [AWS IoT SQL reference](https://docs.aws.amazon.com/iot/latest/developerguide/iot-sql-reference.html). For information about AWS IoT rules and how to create and use them, see [AWS IoT rules](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) and [AWS IoT rules tutorials](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules-tutorial.html). For information about creating and using AWS IoT Core for LoRaWAN destinations, see [Add destinations to AWS IoT Core for LoRaWAN](lorawan-create-destinations.md). For information about using binary message payloads in a rule, see [Binary payloads](https://docs.aws.amazon.com/iot/latest/developerguide/binary-payloads.html). For more information about the data security and encryption used to protect the message payload on its journey, see [Data protection in AWS IoT Wireless](data-protection.md). For a reference architecture that shows a binary decoding and implementation example for IoT rules, see [AWS IoT Core for LoRaWAN Solution Samples on GitHub](https://github.com/aws-samples/aws-iot-core-lorawan/tree/main/transform_binary_payload). # Connect your LoRaWAN device and verify its connection status Before you can check the device connection status, you must have already added your device and connected it to AWS IoT Core for LoRaWAN. For information about how to add your device, see [Add your wireless device to AWS IoT Core for LoRaWAN](lorawan-end-devices-add.md). After you've added your device, refer to your device's user manual to learn how to initiate sending an uplink message from your LoRaWAN device. ## Wireless device destination payload The following code shows the payload received at the destination for your wireless device. It shows a sample payload when using your own private LoRaWAN gateway, and when you use a public network. It also shows the payload format if you exclude the gateway metadata information. The following shows a sample payload. ``` HTTP/1.1 200 Content-type: application/json { "LastUplinkReceivedAt": "2021-03-24T23:13:08.476015749Z", "LoRaWAN": { "DataRate": 5, "DevEui": "647fda0000006420", "Frequency": 868100000, "Gateways": [ { "GatewayEui": "c0ee40ffff29df10", "Rssi": -67, "Snr": 9.75 } ], "WirelessDeviceId": "30cbdcf3-86de-4291-bfab-5bfa2b12bad5" } ``` ### Payload example with private LoRaWAN gateway This example uses a private LoRaWAN gateway to show the gateway metadata information in the uplink message. The metadata consists of the gateway EUI, SNR (signal to noise ratio), and RSSI (Received signal to strength indicator). These values can help you determine the strength of your gateway channel and whether to switch to a stronger channel. ``` { "MessageId": "d8374454-f361-4907-9f3f-ca53233bb281", "WirelessDeviceId": "d7c96c47-6058-46d6-a033-c67d28c2243c", "PayloadData": "wOr7P9SI8tsIgMl0=", "WirelessMetadata": { "LoRaWAN": { "ADR": false, "Bandwidth": 125, "ClassB": false, "CodeRate": "4/5", "DataRate": "0", "DevAddr": "725dd3eb", "DevEui": "ac1f09fffe081943", "FCnt": 5, "FOptLen": 0, "FPort": 1, "Frequency": "868300000", "Gateways": [ { "GatewayEui": "2cf7f11053100080", "Rssi": -34, "Snr": 9.5 } ], "MIC": "9eb0337c", "MType": "UnconfirmedDataUp", "Major": "LoRaWANR1", "Modulation": "LORA", "PolarizationInversion": false, "SpreadingFactor": 12, "Timestamp": "2023-12-01T16:16:11Z" } } } ``` ### Payload example with public network You can also connect to the public network instead of your own private LoRaWAN gateway. The public network is provided and operated as a service directly by Everynet. The following example shows the public LoRaWAN network metadata in the message. The metadata consists of the ID of the gateway and the network provider (Everynet), whether downlink is allowed, and the SNR and RSSI values. For more infrrmation about the public network, see [Managing LoRaWAN traffic from public networks (Everynet)](iot-lorawan-roaming.md). **Note** The uplink message will mention `PublicGateways` to indicate that it's received from the public network and not a private LoRaWAN gateway. ``` { "MessageId": "d8374454-f361-4907-9f3f-ca53233bb281", "WirelessDeviceId": "d7c96c47-6058-46d6-a033-c67d28c2243c", "PayloadData": "wOr7P9SI8tsIgMl0=", "WirelessMetadata": { "LoRaWAN": { "ADR": false, "Bandwidth": 125, "ClassB": false, "CodeRate": "4/5", "DataRate": "0", "DevAddr": "725dd3eb", "DevEui": "ac1f09fffe081943", "FCnt": 5, "FOptLen": 0, "FPort": 1, "Frequency": "868300000", "PublicGateways": [ { "DlAllowed": true, "Id": "3abe094", "ProviderNetId": "0x0000b", "RfRegion": "US915", "Rssi": -12, "Snr": 6.75 } ], "MIC": "9eb0337c", "MType": "UnconfirmedDataUp", "Major": "LoRaWANR1", "Modulation": "LORA", "PolarizationInversion": false, "SpreadingFactor": 12, "Timestamp": "2023-12-01T16:16:11Z" } } } ``` ### Payload example without gateway metadata If you want to exclude the gateway metadata information from your uplink metadata, disable the **AddGwMetadata** parameter when you create the service profile. For information about disabling this parameter, see [Add service profiles](lorawan-define-profiles.md#lorawan-service-profiles). In this case, you won't see the `Gateways` section in the uplink metadata, as illustrated in the following example. ``` { "MessageId": "d8374454-f361-4907-9f3f-ca53233bb281", "WirelessDeviceId": "d7c96c47-6058-46d6-a033-c67d28c2243c", "PayloadData": "wOr7P9SI8tsIgMl0=", "WirelessMetadata": { "LoRaWAN": { "ADR": false, "Bandwidth": 125, "ClassB": false, "CodeRate": "4/5", "DataRate": "0", "DevAddr": "725dd3eb", "DevEui": "ac1f09fffe081943", "FCnt": 5, "FOptLen": 0, "FPort": 1, "Frequency": "868300000", "MIC": "9eb0337c", "MType": "UnconfirmedDataUp", "Major": "LoRaWANR1", "Modulation": "LORA", "PolarizationInversion": false, "SpreadingFactor": 12, "Timestamp": "2023-12-01T16:16:11Z" } } } ``` ## Check device connection status The following sections show you how to check the connection status using the AWS Management Console and the AWS CLI. ### Check device connection status using the console To check the connection status using the console, navigate to the [https://console.aws.amazon.com/iot/home#/wireless/devices](https://console.aws.amazon.com/iot/home#/wireless/devices) page of the AWS IoT console and choose the device you've added. In the **Details** section of the Wireless devices details page, you'll see the date and time the last uplink was received. ### Check device connection status using the API To check the connection status using the API, use the [`GetWirelessDeviceStatistics` API](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessDeviceStatistics.html). This API doesn't have a request body and only contains a response body that shows when the last uplink was received. The response from the API also indicates whether it's received from a public network or a private LoRaWAN gateway. ## Next steps Now that you have connected your device and verified the connection status, you can observe the format of the uplink metadata recieved from the device by using the [ MQTT test client](https://console.aws.amazon.com/iot/home#/test) on the **Test** page of the AWS IoT console. For more information, see [View format of uplink messages sent from LoRaWAN devices](lorawan-uplink-metadata-format.md).