# AWS IoT Core for LoRaWAN AWS IoT Core for LoRaWAN is a fully managed LoRaWAN network server (LNS) that provides gateway management using the Configuration and Update Server (CUPS) and Firmware Updates Over-The-Air (FUOTA) capabilities. You can replace your private LNS with AWS IoT Core for LoRaWAN and connect your Long Range Wide Area Network (LoRaWAN) devices and gateways to AWS IoT Core. By doing so, you'll reduce the maintenance, operational costs, setup time, and overhead costs. **Note** AWS IoT Core for LoRaWAN supports communication using both the IPv4 and IPv6 address format. See [AWS services that support IPv6](https://docs.aws.amazon.com/general/latest/gr/aws-ipv6-support.html#ipv6-service-support). ## Introduction LoRaWAN devices are long-range, low-power, battery-operated devices that use the LoRaWAN protocol to operate in a license-free radio spectrum. LoRaWAN is a Low Power Wide Area Network (LPWAN) communication protocol that is built on LoRa. LoRa is the physical layer protocol that enables low power, wide-area communication between devices. To connect your LoRaWAN devices to AWS IoT, you must use a LoRaWAN gateway. The gateway acts as a bridge to connect your device to AWS IoT Core for LoRaWAN and to exchange messages. AWS IoT Core for LoRaWAN uses the AWS IoT rules engine to route the messages from your LoRaWAN devices to other AWS IoT services. To reduce development effort and quickly onboard your devices to AWS IoT Core for LoRaWAN, we recommend that you use LoRaWAN-certified end devices. For more information, see the [AWS IoT Core for LoRaWAN product overview](https://aws.amazon.com/iot-core/lorawan) page. For information about getting your devices LoRaWAN certified, see [Certifying LoRaWAN products](https://lora-alliance.org/lorawan-certification/). ## Features of AWS IoT Core for LoRaWAN With AWS IoT Core for LoRaWAN, you can: + Onboard and connect LoRaWAN devices and gateways to AWS IoT without the need to set up and manage a private LNS. + Connect LoRaWAN devices that comply to 1.0.x or 1.1 LoRaWAN specifications standardized by LoRa Alliance. These devices can operate in class A, class B, or class C mode. + Use LoRaWAN gateways that support LoRa Basics Station version 2.0.4 or later. All gateways that are qualified for AWS IoT Core for LoRaWAN run a compatible version of LoRa Basics Station. + Connect your LoRaWAN devices to the cloud using publicly available LoRaWAN networks, which reduces the time to deployment, and eliminates the need for managing a private LoRaWAN network, thereby saving time and cost. + Monitor signal strength, bandwidth, and spreading factor by using AWS IoT Core for LoRaWAN's adaptive data rate, and optimize the data rate if needed. You can also use network analyzer to monitor your LoRaWAN resources in real-time. + Update LoRaWAN gateways' firmware using the CUPS service and the firmware of LoRaWAN devices using Firmware Updates Over-The-Air (FUOTA). ## Accessing AWS IoT Core for LoRaWAN You can quickly onboard your LoRaWAN devices and gateways to AWS IoT Core for LoRaWAN by using the console or the AWS IoT Wireless API. **Using the console** To onboard your LoRaWAN devices and gateways by using the AWS Management Console, sign in to the AWS Management Console and navigate to the [AWS IoT Core for LoRaWAN](https://console.aws.amazon.com/iot/home#/wireless/landing) page in the AWS IoT console. You can then use the **Intro** section to add your gateways and devices to AWS IoT Core for LoRaWAN. For more information, see [Using the console to onboard your device and gateway to AWS IoT Core for LoRaWAN](lorawan-getting-started.md#lorawan-console). **Using the API or CLI** You can onboard both LoRaWAN and Sidewalk devices by using the [AWS IoT Wireless](https://docs.aws.amazon.com/iot-wireless/latest/apireference/) API. The AWS IoT Wireless API that AWS IoT Core for LoRaWAN is built on is supported by the AWS SDK. For more information, see [AWS SDKs and Toolkits](https://aws.amazon.com/developer/tools/). You can use the AWS CLI to run commands for onboarding and managing your LoRaWAN gateways and devices. For more information, see [AWS IoT Wireless CLI reference](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/index.html). ## AWS IoT Core for LoRaWAN Regions and endpoints AWS IoT Core for LoRaWAN provides support for control plane and data plane API endpoints that are specific to your AWS Region. The data plane API endpoints are specific to your AWS account and AWS Region. For more information about the AWS IoT Core for LoRaWAN endpoints, see [AWS IoT Core for LoRaWAN Endpoints](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#iot-wireless_region) in the *AWS General Reference*. For more secure communication between your devices and AWS IoT, you can connect your devices to AWS IoT Core for LoRaWAN through AWS PrivateLink in your virtual private cloud (VPC), instead of connecting over the public internet. For more information, see [AWS IoT Core for LoRaWAN and interface VPC endpoints (AWS PrivateLink)](vpc-interface-endpoints.md). AWS IoT Core for LoRaWAN has quotas that apply to device data that is transmitted between the devices and the maximum TPS for the AWS IoT Wireless API operations. For more information, see [AWS IoT Core for LoRaWAN quotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#wireless-limits) in the *AWS General Reference*. ## AWS IoT Core for LoRaWAN pricing If you're a new customer, when you sign up for AWS, you can get started with AWS IoT Core for LoRaWAN for free by using the [AWS Free Tier](https://aws.amazon.com/free/). With AWS IoT Core for LoRaWAN, you only pay for what you use. For more information about general product overview and pricing, see [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/). # What is AWS IoT Core for LoRaWAN? AWS IoT Core for LoRaWAN replaces a private LoRaWAN network server (LNS) by connecting your LoRaWAN devices and gateways to AWS. Using the AWS IoT rules engine, you can route messages received from LoRaWAN devices, where they can be formatted and sent to other AWS IoT services. To secure device communications with AWS IoT, AWS IoT Core for LoRaWAN uses X.509 certificates. AWS IoT Core for LoRaWAN manages the service and device policies that AWS IoT Core requires to communicate with the LoRaWAN gateways and devices. AWS IoT Core for LoRaWAN also manages the destinations that describe the AWS IoT rules that send device data to other services. The following topics will provide more information about the LoRaWAN technology and AWS IoT Core for LoRaWAN. **Topics** + [ ## What is LoRaWAN? ](#what-is-lorawan) + [ ## How AWS IoT Core for LoRaWAN works ](#how-iot-lorawan-works) + [ ## Get started using AWS IoT Core for LoRaWAN ](#lorawan-get-started-resources) + [ ## AWS IoT Core for LoRaWAN resources ](#iot-lorawan-resources) ## What is LoRaWAN? The [LoRa Alliance](https://lora-alliance.org/about-lorawan) describes LoRaWAN as, *"a Low Power, Wide Area (LPWA) networking protocol designed to wirelessly connect battery operated ‘things’ to the internet in regional, national or global networks, and targets key Internet of Things (IoT) requirements such as bi-directional communication, end-to-end security, mobility and localization services."*. **Topics** + [ ### LoRa and LoRaWAN ](#lora-and-lorawan) + [ ### Characteristics of LoRaWAN technology ](#lorawan-characteristics) + [ ### LoRaWAN protocol versions ](#lorawan-versions) + [ ### Learn more about LoRaWAN ](#lorawan-learn-more) ### LoRa and LoRaWAN The LoRaWAN protocol is a Low Power Wide Area Networking (LPWAN) communication protocol that functions on LoRa. LoRaWAN has been recognized as an international standard for low power wide area networking. For more information, see [LoRAWAN formally recognized as ITU internationl standard](https://lora-alliance.org/lora-alliance-press-release/lorawan-formally-recognized-as-itu-international-standard-for-low-power-wide-area-networking/). The LoRaWAN specification is open so anyone can set up and operate a LoRa network. LoRa is a wireless audio frequency technology that operates in a license-free radio frequency spectrum. LoRa is a physical layer protocol that uses spread spectrum modulation and supports long-range communication at the cost of a narrow bandwidth. It uses a narrow band waveform with a central frequency to send data, which makes it robust to interference. ### Characteristics of LoRaWAN technology + Long range communication up to 10 miles in line of sight. + Long battery duration of up to 10 years. For enhanced battery life, you can operate your devices in class A or class B mode, which requires increased downlink latency. + Low cost for devices and maintenance. + License-free radio spectrum but region-specific regulations apply. + Low power but has a limited payload size of 51 bytes to 241 bytes depending on the data rate. The data rate can be 0,3 Kbit/s – 27 Kbit/s data rate with a 222 maximal payload size. ### LoRaWAN protocol versions LoRa Alliance specifies the LoRaWAN protocol using LoRaWAN specification documents. To account for the region-specific regulations, the LoRa Alliance also publishes regional parameter documents. For more information, see [LoRaWAN regional parameters and specifications](https://lora-alliance.org/resource_hub/rp2-102-lorawan-regional-parameters/). The initial release of LoRaWAN is version 1.0. Additional versions released are 1.0.1, 1.0.2, 1.0.3, 1.0.4, and 1.1. Versions 1.0.1-1.0.4 are commonly referred to as 1.0.x. ### Learn more about LoRaWAN The following links contain helpful information about the LoRaWAN technology and about LoRa Basics Station, which is the software that runs on your LoRaWAN gateways for connecting end devices to AWS IoT Core for LoRaWAN. + **[LoRaWAN recognized as ITU International Standard](https://lora-alliance.org/lora-alliance-press-release/lorawan-formally-recognized-as-itu-international-standard-for-low-power-wide-area-networking/)** LoRaWAN has been formally documented as an international standard by ITU for low power wide area networking. The standard is titled Recommendation ITU-T Y.4480 “Low power protocol for wide area wireless networks”. + **[The Things Fundamentals on LoRaWAN](https://www.thethingsnetwork.org/docs/lorawan/)** The Things Fundamentals on LoRaWAN contains an introductory video that covers the fundamentals of LoRaWAN and a series of chapters that'll help you learn about LoRa and LoRaWAN. + **[What is LoRaWAN](https://lora-alliance.org/resource_hub/what-is-lorawan/)** LoRa Alliance provides a technical overview of LoRa and LoRaWAN, including a summary of the LoRaWAN specifications in different Regions. + **[LoRa Basics Station](https://lora-developers.semtech.com/resources/tools/lora-basics/)** Semtech Corporation provides helpful concepts about LoRa basics for gateways and end nodes. LoRa Basics Station, an open source software that runs on your LoRaWAN gateway, is maintained and distributed through Semtech Corporation's [ GitHub](https://github.com/lorabasics/basicstation) repository. You can also learn about the LNS and CUPS protocols that describe how to exchange LoRaWAN data and perform configuration updates. + **[LoRaWAN regional parameters and specifications](https://lora-alliance.org/resource_hub/rp2-102-lorawan-regional-parameters/)** RP002-1.0.2 document includes support for all versions of the LoRaWAN Layer 2 specification.It includes information about the LoRaWAN specifications and regional parameters, and the different LoRaWAN versions. ## How AWS IoT Core for LoRaWAN works The LoRaWAN network architecture is deployed in a star of stars topology in which gateways relay information between end devices and the LoRaWAN network server (LNS). The following shows how a LoRaWAN device interacts with AWS IoT Core for LoRaWAN. It also shows how AWS IoT Core for LoRaWAN acts as an LNS and communicates with other AWS services in the AWS Cloud. ![\[Image showing how AWS IoT Core provides device endpoints to connect IoT devices to AWS IoT and service endpoints to connect apps and other services to AWS IoT Core.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-lorawan-how-it-works.png) LoRaWAN devices communicate with AWS IoT Core through LoRaWAN gateways. AWS IoT Core for LoRaWAN manages the service and device policies that AWS IoT Core requires to manage and communicate with the LoRaWAN gateways and devices. AWS IoT Core for LoRaWAN also manages the destinations that describe the AWS IoT rules that send device data to other services. ## Get started using AWS IoT Core for LoRaWAN The following steps show an overview of how you can get started using AWS IoT Core for LoRaWAN. 1. **Select the wireless devices and LoRaWAN gateways that you'll need.** The [AWS Partner Device Catalog](https://devices.amazonaws.com/search?page=1&sv=iotclorawan) contains gateways and developer kits that are qualified for use with AWS IoT Core for LoRaWAN. For more information, see [Using qualified gateways from the AWS Partner Device Catalog](lorawan-manage-gateways.md#lorawan-qualified-gateways). 1. **Add your wireless devices and LoRaWAN gateways to AWS IoT Core for LoRaWAN.** [Connecting gateways and devices to AWS IoT Core for LoRaWAN](lorawan-getting-started.md) gives you information about how to describe your resources and add your wireless devices and LoRaWAN gateways to AWS IoT Core for LoRaWAN. You'll also learn how to configure the other AWS IoT Core for LoRaWAN resources that you'll need to manage these devices and send their data to AWS services. 1. **Complete your AWS IoT Core for LoRaWAN solution.** Start with [our sample AWS IoT Core for LoRaWAN solution](https://github.com/aws-samples/aws-iot-core-lorawan) and make it yours. ## AWS IoT Core for LoRaWAN resources The following resources will help you learn more about AWS IoT Core for LoRaWAN and how to get started. + **[Getting Started with AWS IoT Core for LoRaWAN](https://www.youtube.com/watch?v=6-ZrdRjqdTk/)** The following video describes how AWS IoT Core for LoRaWAN works and walks you through the process of adding LoRaWAN gateways from the AWS Management Console. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/6-ZrdRjqdTk/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/6-ZrdRjqdTk) + **[AWS IoT Core for LoRaWAN workshop](https://iotwireless.workshop.aws/en/)** The workshop covers fundamentals of LoRaWAN technology and its implementation with AWS IoT Core for LoRaWAN. You can also use the workshop to walk through labs that show how to connect your gateway and device to AWS IoT Core for LoRaWAN for building a sample IoT solution. + **[Implementing Low-Power Wide-Area Network (LPWAN) Solutions with AWS IoT](https://d1.awsstatic.com/whitepapers/LPWAN-connectivity-with-AWS-IoT.pdf)** This paper provides you with a decision framework to help you decide if LPWAN is the right choice for your IoT use case, provides an overview of LPWAN connectivity technologies and their capabilities, and provides implementation guidelines. # 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). # Configuring position of wireless resources with AWS IoT Core for LoRaWAN | | | --- | | Before using this feature, note that the chosen third party provider for resolving position information for LoRaWAN devices relies on data feeds and data sets provided or maintained by the International GNSS Service (IGS), EarthData via NASA, or other third-parties. These data feeds and data sets are Third-Party Content (as defined in the Customer Agreement) and provided on an as-is basis. For more information, see [AWS Service Terms](https://aws.amazon.com/service-terms). | You can use AWS IoT Core for LoRaWAN to specify your static position data, or activate positioning to identify the position of your device in real time using third-party solvers. You can add or update the position information for either LoRaWAN devices or gateways, or both. You specify the position information either when adding your device or gateway to AWS IoT Core for LoRaWAN, or when editing the configuration details of your device or gateway. The position information is specified as a [GeoJSON](https://geojson.org/) payload. The GeoJSON format is a format that's used to encode geographic data structures. The payload contains the latitude and longitude co-ordinates of your device location, that are based on the [ World Geodetic System coordinate system (WGS84)](https://gisgeography.com/wgs84-world-geodetic-system/). After the solvers compute the position of your resource, if you have Amazon Location Service, you can activate an Amazon Location map where the position of your resource will be displayed. Using the position data, you can: + Activate positioning to identify and obtain the position of your LoRaWAN devices. + Track and monitor the position of your gateways and devices. + Define AWS IoT rules that process any updates to the position data and routes it to other AWS services. For a list of rule actions, see [AWS IoT rule actions](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html) in the *AWS IoT developer guide*. + Create alerts and receive notifications to devices in case of any unusual activity by using the position data and Amazon SNS. ## How positioning works for LoRaWAN devices You can activate positioning to identify the position of your devices using third-party Wi-Fi and GNSS solvers. This information can be used to track and monitor your device. The following steps show you how to activate positioning and view the position information for LoRaWAN devices. **Note** The third-party solvers can only be used with LoRaWAN devices that have the [LoRa Edge](https://www.semtech.com/products/wireless-rf/lora-edge) chip. It can't be used with LoRaWAN gateways. For gateways, you can still specify the static position information and identify the location on an Amazon Location map. 1. **Add your device** Before you activate positioning, first add your device to AWS IoT Core for LoRaWAN. The LoRaWAN device must have the LoRa Edge chipset, which is an ultra-low power platform that integrates a long range LoRa transceiver, multi-constellation GNSS scanner, and passive Wi-Fi MAC scanner targeting geolocation applications. 1. **Activate positioning** To obtain the real-time position of your devices, activate positioning. When your LoRaWAN device sends an uplink message, the Wi-Fi and GNSS scan data contained in the message is sent to AWS IoT Core for LoRaWAN using the geolocation frame port. 1. **Retrieve position information** Retrieve the estimated device position from the solvers computed based on the scan results from the transceivers. If the position information was computed using both Wi-Fi and GNSS scan results, AWS IoT Core for LoRaWAN selects the estimated position that has the higher accuracy. 1. **View position information** After the solver computes the position information, it will also provide the accuracy information which indicates the difference between the position computed by the solvers and the static position information that you entered. You can also view the device location on an Amazon Location map. **Note** As solvers can't be used for LoRaWAN gateways, the accuracy information will be reported as `0.0`. For more information about the uplink message format and the frequency ports that are used for the positioning solver, see [Uplink message from AWS IoT Core for LoRaWAN to rules engine](lorawan-location-devices.md#lorawan-location-devices-uplink). ## Overview of positioning workflow The following diagram shows how AWS IoT Core for LoRaWAN stores and updates the position information of your devices and gateways. ![\[Image showing how AWS IoT Core for LoRaWAN can use your static position data and raw data to compute the position in real time.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-lorawan-lms-architecture.png) 1. **Specify static position of your resource** Specify the static position information of your device or gateway as a GeoJSON payload, using the latitude and longitude coordinates. You can also specify an optional altitude coordinate. These coordinates are based on the WGS84 coordinate system. For more information, see [ World Geodetic System (WGS84)](https://gisgeography.com/wgs84-world-geodetic-system/). 1. **Activate positioning for devices** If you're using LoRaWAN devices that have the LoRa Edge chip, you can optionally activate positioning to track your device position in real time. When your device sends an uplink message, the GNSS and Wi-Fi scan data is sent to AWS IoT Core for LoRaWAN using the geolocation frame port. The solvers then use this information to resolve the device position. 1. **Add a destination to route position data** You can add a destination that describes the IoT rule for processing the device data and route the updated position information to AWS IoT Core for LoRaWAN. You can also view the last known position of your resource on an Amazon Location map. ## Configuring your resource position You can configure the position of your resource using the AWS Management Console, the AWS IoT Wireless API, or the AWS CLI. If your devices have the LoRa Edge chip, you can activate positioning to compute the real-time position information. For your gateways, you can still enter the static position coordinates and use Amazon Location to track the gateway position on an Amazon Location map. **Topics** + [ ## How positioning works for LoRaWAN devices ](#lorawan-location-solver) + [ ## Overview of positioning workflow ](#lorawan-location-workflow) + [ ## Configuring your resource position ](#lorawan-location-how) + [ # Configuring the position of LoRaWAN gateways ](lorawan-location-gateways.md) + [ # Configuring position of LoRaWAN devices ](lorawan-location-devices.md) # Configuring the position of LoRaWAN gateways When you add your gateway to AWS IoT Core for LoRaWAN, you can specify the static position data. If you've activated Amazon Location Service maps, the position data is displayed on an Amazon Location map. **Note** The third-party solvers can't be used with LoRaWAN gateways. For gateways, you can still specify the static position coordinates. When solvers aren't used to compute the position, such as in the case of gateways, the accuracy information will be reported as `0.0`. You can configure the gateway position using the AWS Management Console, the AWS IoT Wireless API, or the AWS CLI. ## Configuring position of your gateway using the console To configure the position of your gateway resources by using the AWS Management Console, first sign in to the console and then go to the [https://console.aws.amazon.com/iot/home#/wireless/gateways](https://console.aws.amazon.com/iot/home#/wireless/gateways) hub page of the AWS IoT console. **Add position information** To add a position configuration for your gateway 1. In the **Gateways** hub page, choose **Add gateway**. 1. Enter the gateway's EUI, frequency band (RFRegion), and any additional gateway details and LoRaWAN configuration information. For more information, see [Add a gateway using the console](lorawan-onboard-gateway-add.md#lorawan-onboard-gateway-console). 1. Go to the **Position information - Optional** section, and enter the position information for your gateway using the latitude and longitude coordinates, and an optional altitude coordinate. The position information is based on the WGS84 coordinate system. **View gateway's position** After you've configured your gateway's position, AWS IoT Core for LoRaWAN creates an Amazon Location map called `iotwireless.map`. You can see this map in the details page of your gateway on the **Position** tab. Based on the position coordinates that you specified, the position of your gateway will be displayed as a marker on the map. You can zoom in or zoom out to clearly view the position of your gateway on the map. On the **Position** tab, you'll also see the accuracy information and the timestamp at which your gateway's position was determined. **Note** If you don't have Amazon Location Service maps installed, you'll see a message indicating that you must use Amazon Location Service to access the map and view the gateway position. Using Amazon Location Service maps may incur additional charges to your AWS account. For more information, see [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/). The map, `iotwireless.map`, acts as a source of map data which is accessed using `Get` API operations, such as [https://docs.aws.amazon.com/location-maps/latest/APIReference/API_GetMapTile.html](https://docs.aws.amazon.com/location-maps/latest/APIReference/API_GetMapTile.html). For information about `Get` APIs used with maps, see [Amazon Location Service API reference](https://docs.aws.amazon.com/location-maps/latest/APIReference/Welcome.html). To get additional details about this map, go to the Amazon Location Service console, choose **maps**, and then choose [iotwireless.map](https://console.aws.amazon.com/location/maps/home#/describe/iotwireless.map). For more information, see [Maps](https://docs.aws.amazon.com/location/latest/developerguide/map-concepts.html) in the *Amazon Location Service developer guide*. **Update gateway's position configuration** To change the gateway's position configuration, in the gateway details page, choose **Edit** and then update the position information and the destination. **Note** Information about historical position data isn't available. When you update the gateway's position coordinates, it overwrites the previously reported position data. After you've updated the position, in the **Position** tab of the gateway details, you'll see the new position information. The change in timestamp indicates that it corresponds to the last known position of the gateway. ## Configure position of your gateway using the API You can specify the position information and configure the gateway position using the AWS IoT Wireless API or the AWS CLI. **Important** The API actions [ UpdatePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdatePosition.html), [GetPosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPosition.html), [PutPositionConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_PutPositionConfiguration.html), [GetPositionConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionConfiguration.html), and [ListPositionConfigurations](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListPositionConfigurations.html) are no longer supported. Calls to update and retrieve the position information should use the [GetResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetResourcePosition.html) and [UpdateResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateResourcePosition.html) API operations instead. ### Add position information To add the static position information for a given wireless gateway, specify the coordinates using the [UpdateResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateResourcePosition.html) API operation or the [update-resource-position](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-resource-position.html) CLI command. Specify `WirelessGateway` as the `ResourceType`, the ID of the wireless gateway to be updated as the `ResourceIdentifier`, and the position information as a GeoJSON payload. ``` aws iotwireless update-resource-position \ --resource-type WirelessGateway \ --resource-id "12345678-a1b2-3c45-67d8-e90fa1b2c34d" \ --cli-input-json file://gatewayposition.json ``` The following shows the contents of the `gatewayposition.json` file. **Contents of gatewayposition.json** ``` { "type": "Point", "coordinates": [33.3318, -22.2155, 13.123], "properties": { "timestamp": "2018-11-30T18:35:24Z" } } ``` Running this command doesn't produce any output. To see the position information that you specified, use the `GetResourcePosition` API operation. ### Get position information To get the position information for a given wireless gateway, use the [ GetResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetResourcePosition.html) API operation or the [get-resource-position](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-position.html) CLI command. Specify `WirelessGateway` as the `resourceType` and provide the ID of the wireless gateway as the `resourceIdentifier`. ``` aws iotwireless get-resource-position \ --resource-type WirelessGateway \ --resource-id "12345678-a1b2-3c45-67d8-e90fa1b2c34d" ``` Running this command displays the position information of your wireless gateway as a GeoJSON payload. You'll see information about the position coordinates, the type of position information, and additional properties, such as the timestamp which corresponds to the last known position of the gateway. ``` { { "type": "Point", "coordinates": [33.3318,-22.2155,13.123], "properties": { "timestamp": "2018-11-30T18:35:24Z" } } } ``` # Configuring position of LoRaWAN devices When you add your device to AWS IoT Core for LoRaWAN, you can specify the static position information, optionally activate positioning, and specify a destination. The destination describes the IoT rule that processes the device's position information and routes the updated position to Amazon Location Service. After you configure your device position, the position data is displayed on an Amazon Location map with the accuracy information, and the destination that you specified. You can configure the position of your device using the AWS Management Console, the AWS IoT Wireless API, or the AWS CLI. ## Frame ports and format of uplink messages If you activate positioning, you must specify the geolocation frame port for communicating the Wi-Fi and GNSS scan data from the device to AWS IoT Core for LoRaWAN. The position information is communicated to AWS IoT Core for LoRaWAN using this frame port. The LoRaWAN specification provides a data delivery field (FRMPayload) and a Port field (FPort) to distinguish between different types of messages. To communicate the position information, you can specify a value anywhere between 1 and 223 for the frame port. FPort 0 is reserved for MAC messages, FPort 224 is reserved for MAC compliance testing, and ports 225-255 are reserved for future standardized application extensions. ### Uplink message from AWS IoT Core for LoRaWAN to rules engine When you add a destination, it creates an AWS IoT rule to route the data to Amazon Location Service using the rules engine. The updated position information is then displayed on an Amazon Location map. If you haven't activated positioning, the destination routes the position data when you update the static position coordinates of your device. The following code shows the format of the uplink message sent from AWS IoT Core for LoRaWAN with the position information, accuracy, solver configuration, and the wireless metadata. The fields highlighted below are optional. If there's no vertical accuracy information, the value is `null`. ``` { // Position configuration parameters for given wireless device "WirelessDeviceId": "5b58245e-146c-4c30-9703-0ca942e3ff35", // Position information for a device in GeoJSON format. Altitude // is optional. If no vertical accuracy information is available // or positioning isn't activated, the value is set to null. // The position information coordinates are listed in the order // [longitude, latitude, altitude]. "coordinates": [33.33000183105469, -22.219999313354492, 99.0], "type": "Point", "properties": { "horizontalAccuracy": number, "verticalAccuracy": number", "timestamp": "2022-08-19T03:08:35.061Z" }, //Parameters controlled by AWS IoT Core for LoRaWAN "WirelessMetadata": { "LoRaWAN": { "ADR": false, "Bandwidth": 125, "ClassB": false, "CodeRate": "4/5", "DataRate": "0", "DevAddr": "00b96cd4", "DevEui": "58a0cb000202c99", "FOptLen": 2, "FCnt": 1, "Fport": 136, "Frequency": "868100000", "Gateways": [ { "GatewayEui": "80029cfffe5cf1cc", "Snr": -29, "Rssi": 9.75 } ], "MIC": "7255cb07", "MType": "UnconfirmedDataUp", "Major": "LoRaWANR1", "Modulation": "LORA", "PolarizationInversion": false, "SpreadingFactor": 12, "Timestamp": "2021-05-03T03:24:29Z" } } } ``` ## Configuring position of your devices using the console To configure and manage the position of your devices by using the AWS Management Console, first sign in to the console and then go to the [https://console.aws.amazon.com/iot/home#/wireless/devices](https://console.aws.amazon.com/iot/home#/wireless/devices) hub page of the AWS IoT console. **Add position information** To add position information for your device: 1. In the ** Devices** hub page, choose **Add wireless device**. 1. Enter the wireless device specification, device and service profiles, and the destination that defines the IoT rule for routing the data to other AWS services. For more information, see [Onboard your devices to AWS IoT Core for LoRaWAN](lorawan-onboard-end-devices.md). 1. Enter the position information, optionally activate geolocation, and specify a position data destination that you want to use for routing messages. + **Position information** Specify the position data for your device using the latitude and longitude coordinates, and an optional altitude coordinate. The position information is based on the WGS84 coordinate system. + **Geolocation** Activate positioning if you want AWS IoT Core for LoRaWAN to use geolocation for computing the device position. It uses third-party GNSS and Wi-Fi solvers to identify the position of your device in real time. To enter the geolocation information, choose **Activate positioning**, and enter the geolocation frame port for communicating the GNSS and Wi-Fi scan data to AWS IoT Core for LoRaWAN. You'll see default FPorts populated for your reference. However, you can choose a different value anywhere between 1 and 223. + **Position data destination** Choose a destination to describe the AWS IoT rule that processes the device's position data and forwards it to AWS IoT Core for LoRaWAN. Use this destination only to route position data. It must be different from the destination that you use for routing device data to other AWS services. **View device's position configuration** After you've configured your device's position, AWS IoT Core for LoRaWAN creates an Amazon Location map called `iotwireless.map`. You can see this map in the details page of your device on the **Position** tab. Based on the position coordinates that you specified or the position computed by the third-party solvers, the position of your device will be displayed as a marker on the map. You can zoom in or zoom out to clearly view the position of your device on the map. In the device's details page, on the **Position** tab, you'll also see the accuracy information, the timestamp at which your device's position was determined, and the position data destination that you specified. **Note** If you haven't activated Amazon Location Service maps, you'll see a message indicating that you'll have to use Amazon Location Service to access the map and view the position. Using Amazon Location Service maps may incur additional charges to your AWS account. For more information, see [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/). The map, `iotwireless.map`, acts as a source of map data which is accessed using `Get` API operations, such as [https://docs.aws.amazon.com/location-maps/latest/APIReference/API_GetMapTile.html](https://docs.aws.amazon.com/location-maps/latest/APIReference/API_GetMapTile.html). For information about `Get` APIs used with maps, see [Amazon Location Service API reference](https://docs.aws.amazon.com/location-maps/latest/APIReference/Welcome.html). To get additional details about this map, go to the Amazon Location Service console, choose **maps**, and then choose [iotwireless.map](https://console.aws.amazon.com/location/maps/home#/describe/iotwireless.map). For more information, see [Maps](https://docs.aws.amazon.com/location/latest/developerguide/map-concepts.html) in the *Amazon Location Service developer guide*. **Update device's position configuration** To change the device's position configuration, in the device details page, choose **Edit** and then update the position information, any geolocation settings, and the destination. **Note** Information about historical position data isn't available. When you update the device's position coordinates, it overwrites the previously reported position data. After you've updated the position, in the **Position** tab of the device details, you'll see the new position information. The change in timestamp indicates that it corresponds to the last known position of the device. ## Configure device position using the API **Note** For Bluetooth Low Energy based location, AWS IoT returns location coordinates based on the approximate location of nearby Sidewalk Gateways that are connected to Amazon Sidewalk and have the Community Finding feature enabled. Gateway Location Data is AWS Content and is provided to you solely for the purpose of assisting you in locating your devices that are connected to Amazon Sidewalk, and you must only use the data for that purpose. You must only use and access location data via the interface and functionality that we generally make available to you, and you must not attempt to re-identify, reverse engineer, or re-map any Gateway location data provided by us to you. You can specify the position information, configure the device position, and activate optional geolocation using the AWS IoT Wireless API or the AWS CLI. **Important** The API actions [ UpdatePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdatePosition.html), [GetPosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPosition.html), [PutPositionConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_PutPositionConfiguration.html), [GetPositionConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionConfiguration.html), and [ListPositionConfigurations](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListPositionConfigurations.html) are no longer supported. Calls to update and retrieve the position information should use the [GetResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetResourcePosition.html) and [UpdateResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateResourcePosition.html) API operations instead. ### Add position information and configuration To add the position information for a given wireless device, specify the coordinates using the [ UpdateResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateResourcePosition.html) API operation or the [update-resource-position](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-resource-position.html) CLI command. Specify `WirelessDevice` as the `ResourceType`, the ID of the wireless device to be updated as the `ResourceIdentifier`, and the position information. ``` aws iotwireless update-resource-position \ --resource-type WirelessDevice \ --resource-id "1ffd32c8-8130-4194-96df-622f072a315f" \ --position [33.33, -33.33, 10.0] ``` The following shows the contents of the `deviceposition.json` file. To specify the FPort values for sending the geolocation data, use the [Positioning](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_Positioning.html) object with the [CreateWirelessDevice](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html) and [UpdateWirelessDevice](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateWirelessDevice.html) API operations. **Contents of deviceposition.json** ``` { "type": "Point", "coordinates": [33.3318, -22.2155, 13.123], "properties": { "verticalAccuracy": 707, "horizontalAccuracy": "timestamp": "2018-11-30T18:35:24Z" } } ``` Running this command doesn't produce any output. To see the position information that you specified, use the `GetResourcePosition` API operation. ### Get position information and configuration To get the position information for a given wireless device, use the [ GetResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetResourcePosition.html) API or the [get-resource-position](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-resource-position.html) CLI command. Specify `WirelessDevice` as the `resourceType` and provide the ID of the wireless device as the `resourceIdentifier`. ``` aws iotwireless get-resource-position \ --resource-type WirelessDevice \ --resource-id "1ffd32c8-8130-4194-96df-622f072a315f" ``` Running this command displays the position information of your wireless device as a GeoJSON payload. You'll see information about the position coordinates, the location type, and properties which can include the accuracy information and the timestamp which corresponds to the last known position of the device. ``` { "type": "Point", "coordinates": [33.3318, -22.2155, 13.123], "properties": { "verticalAccuracy": 707, "horizontalAccuracy": 389, "horizontalConfidenceLevel": 0.68, "verticalConfidenceLevel": 0.68, "timestamp": "2018-11-30T18:35:24Z" } } ``` # Managing gateways with AWS IoT Wireless Following are some important considerations when using your gateways with AWS IoT Core for LoRaWAN. For information about how to add your gateway to AWS IoT Core for LoRaWAN, see [Onboard your gateways to AWS IoT Core for LoRaWAN](lorawan-onboard-gateways.md). ## LoRa Basics Station software requirement To connect to AWS IoT Core for LoRaWAN, your LoRaWAN gateway must have software called [LoRa Basics Station](https://doc.sm.tc/station/) running on it. LoRa Basics Station is an open source software that is maintained by Semtech Corporation and distributed by their [GitHub](https://github.com/lorabasics/basicstation) repository. AWS IoT Core for LoRaWAN supports LoRa Basics Station version 2.0.4 and later. The latest version is 2.0.6. ## Using qualified gateways from the AWS Partner Device Catalog The [AWS Partner Device Catalog](https://devices.amazonaws.com/search?page=1&sv=iotclorawan) contains gateways and developer kits that are qualified for use with AWS IoT Core for LoRaWAN. We recommend that you use these qualified gateways because you don't have to modify the embedding software for connecting the gateways to AWS IoT Core. These gateways already have a version of the BasicStation software compatible with AWS IoT Core for LoRaWAN. **Note** If you have a gateway that is not listed in the Partner Catalog as a qualified gateway with AWS IoT Core for LoRaWAN, you might still be able to use it if the gateway is running LoRa Basics Station software with version 2.0.4 and later. Make sure that you use **TLS Server and Client Authentication** for authenticating your LoRaWAN gateway. ## Using CUPS and LNS protocols LoRa Basics Station software contains two sub protocols for connecting gateways to network servers, LoRaWAN Network Server (LNS) and Configuration and Update Server (CUPS) protocols. The LNS protocol establishes a data connection between a LoRa Basics Station compatible gateway and a network server. LoRa uplink and downlink messages are exchanged through this data connection over secure WebSockets. The CUPS protocol enables credentials management, and remote configuration and firmware update of gateways. AWS IoT Core for LoRaWAN provides both LNS and CUPS endpoints for LoRaWAN data ingestion and remote gateway management respectively. For more information, see [LNS protocol](https://doc.sm.tc/station/tcproto.html) and [CUPS protocol](https://doc.sm.tc/station/cupsproto.html). **Topics** + [ ## LoRa Basics Station software requirement ](#lorawan-lora-basics-station) + [ ## Using qualified gateways from the AWS Partner Device Catalog ](#lorawan-qualified-gateways) + [ ## Using CUPS and LNS protocols ](#lorawan-cups-lns-protocols) + [ # Configure beaconing for your LoRaWAN gateways ](lorawan-gateway-beaconing.md) + [ # Configure subbands and filtering capabilities of your LoRaWAN gateways ](lorawan-subband-filter-configuration.md) + [ # Choosing gateways to receive the LoRaWAN downlink data traffic ](lorawan-gateway-participate.md) + [ # Update gateway firmware using CUPS service with AWS IoT Core for LoRaWAN ](lorawan-update-firmware.md) # Configure beaconing for your LoRaWAN gateways If you onboard class B wireless devices to AWS IoT Core for LoRaWAN, the devices receive downlink messages in scheduled time slots. The devices open these slots based on time-synchronized beacons that are transmitted by the gateway. For your gateways to transmit these time-synchronous beacons, you can use AWS IoT Core for LoRaWAN to configure certain beaconing-related parameters for the gateways. To configure these beaconing parameters, your gateway must be running LoRa Basics Station software version 2.0.6. See [Using qualified gateways from the AWS Partner Device Catalog](lorawan-manage-gateways.md#lorawan-qualified-gateways). ## How to configure the beaconing parameters **Note** You only need to configure the beaconing parameters for your gateway if it's communicating with a class B wireless device. You configure the beaconing parameters when adding your gateway to AWS IoT Core for LoRaWAN using the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessGateway.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessGateway.html) API operation. When you invoke the API operation, specify the following parameters using the `Beaconing` object for your gateways. After you configure the parameters, the gateways will send the beacons to your devices at a 128-second interval. + `DataRate`: The data rate for the gateways that are transmitting the beacons. + `Frequencies`: The list of frequencies for the gateways to transmit the beacons. The following example shows how you configure these parameters for the gateway. The `input.json` file will contain additional details, such as the gateway certificate and provisioning credentials. For more information about adding your gateway to AWS IoT Core for LoRaWAN using the `CreateWirelessGateway` API operation, see [Add a gateway by using the API](lorawan-onboard-gateway-add.md#lorawan-onboard-gateway-api). **Note** The beaconing parameters aren't available when you add your gateway to AWS IoT Core for LoRaWAN using the AWS IoT console. ``` aws iotwireless create-wireless-gateway \ --name "myLoRaWANGateway" \ --cli-input-json file://input.json ``` The following shows the contents of the `input.json` file. **Contents of input.json** ``` { "Description": "My LoRaWAN gateway", "LoRaWAN": { "Beaconing": { "DataRate": 8, "Frequencies": [923300000,923900000] }, "GatewayEui": "a1b2c3d4567890ab", "RfRegion": US915, "JoinEuiFilters": [ ["0000000000000001", "00000000000000ff"], ["000000000000ff00", "000000000000ffff"] ], "NetIdFilters": ["000000", "000001"], "RfRegion": "US915", "SubBands": [2] } } ``` The following code shows a sample output of running this command. ``` { "Arn": "arn:aws:iotwireless:us-east-1:400232685877aa:WirelessGateway/a01b2c34-d44e-567f-abcd-0123e445663a", "Id": a01b2c34-d44e-567f-abcd-0123e445663a" } ``` ## Get information about the beaconing parameters You can get information about the beaconing parameters for your gateway using the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessGateway.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessGateway.html) API operation. **Note** If a gateway has already been onboarded, you can't use the `UpdateWirelessGateway` API operation to configure the beaconing parameters. To configure the parameters, you must delete the gateway and then specify the parameters when adding your gateway using the `CreateWirelessGateway` API operation. ``` aws iotwireless get-wireless-gateway \ --identifier "12345678-a1b2-3c45-67d8-e90fa1b2c34d" \ --identifier-type WirelessGatewayId ``` Running this command returns information about your gateway and the beaconing parameters. # Configure subbands and filtering capabilities of your LoRaWAN gateways LoRaWAN gateways run a [LoRa Basics Station](https://doc.sm.tc/station/) software that enables the gateways to connect to AWS IoT Core for LoRaWAN. To connect to AWS IoT Core for LoRaWAN, your LoRa gateway first queries the CUPS server for the LNS endpoint, and then establishes a WebSockets data connection with that endpoint. After the connection is established, uplink and downlink frames can be exchanged through that connection. ## Filtering of LoRa data frames received by gateway After your LoRaWAN gateway establishes a connection to the endpoint, AWS IoT Core for LoRaWAN responds with a `router_config` message that specifies a set of parameters for the LoRa gateway's configuration, including filtering parameters `NetID` and `JoinEui`. For more information about `router_config` and how a connection is established with the LoRaWAN Network Server (LNS), see [LNS protocol](https://doc.sm.tc/station/tcproto.html). ``` { "msgtype" : "router_config" "NetID" : [ INT, .. ] "JoinEui" : [ [INT,INT], .. ] // ranges: beg,end inclusive "region" : STRING // e.g. "EU863", "US902", .. "hwspec" : STRING "freq_range" : [ INT, INT ] // min, max (hz) "DRs" : [ [INT,INT,INT], .. ] // sf,bw,dnonly "sx1301_conf": [ SX1301CONF, .. ] "nocca" : BOOL "nodc" : BOOL "nodwell" : BOOL } ``` The gateways carry LoRaWAN device data to and from LNS usually over high-bandwidth networks like Wi-Fi, Ethernet, or Cellular. The gateways usually pick up all messages and pass through the traffic that comes to it to AWS IoT Core for LoRaWAN. However, you can configure the gateways to filter some of the device data traffic, which helps conserve bandwidth usage and reduces the traffic flow between the gateway and LNS. To configure your LoRa gateway to filter the data frames, you can use the parameters `NetID` and `JoinEui` in the `router_config` message. `NetID` is a list of NetID values that are accepted. Any LoRa data frame carrying a data frame other than those listed will be dropped. `JoinEui` is a list of pairs of integer values encoding ranges of JoinEUI values. Join request frames will be dropped by the gateway unless the field `JoinEui` in the message is within the range [BegEui,EndEui]. ## Frequency channels and subbands For US915 and AU915 RF regions, wireless devices have choices of 64 125KHz and 8 500KHz uplink channels to access the LoRaWAN networks using the LoRa gateways. The uplink frequency channels are divided into 8 subbands, each with 8 125KHz channels and one 500KHz channel. For each regular gateway in AU915 region, one or more subbands will be supported. Some wireless devices can't hop between subbands and use the frequency channels in only one subband when connected to AWS IoT Core for LoRaWAN. For the uplink packets from those devices to be transmitted, configure the LoRa gateways to use that particular subband. For gateways in other RF regions, such as EU868, this configuration is not required. ## Configure your gateway to use filtering and subbands using the console You can configure your gateway to use a particular subband and also enable the capability to filter the LoRa data frames. To specify these parameters using the console: 1. Navigate to the [AWS IoT Core for LoRaWAN](https://console.aws.amazon.com/iot/home#/wireless/gateways) **Gateways** page of the AWS IoT console and choose **Add gateway**. 1. Specify the gateway details such as the **Gateway's Eui**, **Frequency band (RFRegion)** and an optional **Name** and **Description**, and choose whether to associate an AWS IoT thing to your gateway. For more information about how to add a gateway, see [Add a gateway using the console](lorawan-onboard-gateway-add.md#lorawan-onboard-gateway-console). 1. In the **LoRaWAN configuration** section, you can specify the subbands and filtering information. + `SubBands`: To add a subband, choose **Add SubBand** and specify a list of integer values that indicate which subbands are supported by the gateway. The `SubBands` parameter can only be configured in the `RfRegion` US915 and AU915 and must have values in the range `[1,8]` within one of these supported regions. + `NetIdFilters`: To filter uplink frames, choose **Add NetId** and specify a list of string values that the gateway uses. The NetID of the incoming uplink frame from the wireless device must match at least one of the listed values, otherwise the frame is dropped. + `JoinEuiFilters`: Choose **Add JoinEui range** and specify a list of pairs of string values that a gateway uses to filter LoRa frames. The JoinEUI value specified as part of the join request from the wireless device must be within the range of at least one of the JoinEuiRange values, each listed as a pair of [BegEui, EndEui], otherwise the frame is dropped. 1. You can then continue to configure your gateway by following the instructions described in [Add a gateway using the console](lorawan-onboard-gateway-add.md#lorawan-onboard-gateway-console). After you've added a gateway, in the [AWS IoT Core for LoRaWAN](https://console.aws.amazon.com/iot/home#/wireless/gateways) **Gateways** page of the AWS IoT console, if you select the gateway that you've added, you can see the `SubBands` and filters `NetIdFilters` and `JoinEuiFilters` in the **LoRaWAN specific details** section of the Gateway details page. ## Configure your gateway to use filtering and subbands using the API You can use the [CreateWirelessGateway](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessGateway.html) API that you use to create a gateway to configure the subbands you want to use and enable the filtering capability. Using the `CreateWirelessGateway` API, you can specify the subbands and filters as part of the gateway configuration information that you provide using the `LoRaWAN` field. The following shows the request token that includes this information. ``` POST /wireless-gateways HTTP/1.1 Content-type: application/json { "Arn": "arn:aws:iotwireless:us-east-1:400232685877aa:WirelessGateway/ a11e3d21-e44c-471c-afca-6716c228336a", "Description": "Using my first LoRaWAN gateway", "LoRaWAN": { "GatewayEui": "a1b2c3d4567890ab", "JoinEuiFilters": [ ["0000000000000001", "00000000000000ff"], ["000000000000ff00", "000000000000ffff"] ], "NetIdFilters": ["000000", "000001"], "RfRegion": "US915", "SubBands": [2] }, "Name": "myFirstLoRaWANGateway" "ThingArn": null, "ThingName": null } ``` You can also use the [UpdateWirelessGateway](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateWirelessGateway.html) API to update the filters but not the subbands. If the `JoinEuiFilters` and `NetIdfilters` values are null, it means there is no update for the fields. If the values aren't null and empty lists are included, then the update is applied. To get the values of the fields that you specified, use the [GetWirelessGateway](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessGateway.html) API. # Choosing gateways to receive the LoRaWAN downlink data traffic When you send a downlink message from AWS IoT Core for LoRaWAN to your device, you can choose the gateways you want to use for the downlink data traffic. You can specify an individual gateway or choose from a list of gateways to receive the downlink traffic. **Note** This feature is different from the participating gateways feature that you can use for multicast downlink from AWS IoT Core for LoRaWAN to devices in your multicast group. For more information, see [Choose participating gateways to receive multicast downlink messages](lorawan-multicast-choose-gateways.md) ## How to specify the gateway list You can specify an individual gateway or the list of gateways to use when sending a downlink message from AWS IoT Core for LoRaWAN to your device using the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToWirelessDevice.html) API operation. When you invoke the API operation, specify the following parameters using the `ParticipatingGateways` object for your gateways. **Note** The list of gateways you want to use isn't available in the AWS IoT console. You can specify this list of gateways to use only when using the `SendDataToWirelessDevice` API operation or the CLI. + `DownlinkMode`: Indicates whether to send the downlink message in sequential mode or concurrent mode. For class A devices, specify `UsingUplinkGateway` to use only the chosen gateways from the previous uplink message transmission. + `GatewayList`: The list of gateways that you want to use for sending the downlink data traffic. The downlink payload will be sent to the specified gateways with the specified frequency. This is indicated using a list of `GatewayListItem` objects, that consists of `GatewayId` and `DownlinkFrequency` pairs. + `TransmissionInterval`: The duration of time for which AWS IoT Core for LoRaWAN will wait before transmitting the payload to the next gateway. **Note** You can specify this list of gateways to use only when sending the downlink message to a class B or a class C wireless device. If you use a class A device, the gateway that you chose when sending the uplink message will be used when a downlink message is sent to the device. The following example shows how you specify these parameters for the gateway. The `input.json` file will contain additional details. For more information about sending a downlink message using the `SendDataToWirelessDevice` API operation, see [Perform downlink queue operations by using the API](lorawan-downlink-queue.md#lorawan-downlink-queue-api). **Note** The parameters for specifying the list of participating gateways aren't available when you send a downlink message from AWS IoT Core for LoRaWAN using the AWS IoT console. ``` aws iotwireless send-data-to-wireless-device \ --id "11aa5eae-2f56-4b8e-a023-b28d98494e49" \ --transmit-mode "1" \ --payload-data "SGVsbG8gVG8gRGV2c2lt" \ --cli-input-json file://input.json ``` The following shows the contents of the `input.json` file. **Contents of input.json** ``` { "WirelessMetadata": { "LoRaWAN": { "FPort": "1", "ParticipatingGateways": { "DownlinkMode": "SEQUENTIAL", "TransmissionInterval": 1200, "GatewayList": [ { "DownlinkFrequency": 100000000, "GatewayID": a01b2c34-d44e-567f-abcd-0123e445663a }, { "DownlinkFrequency": 100000101, "GatewayID": 12345678-a1b2-3c45-67d8-e90fa1b2c34d } ] } } } } ``` The output of running this command generates a `MessageId` for the downlink message. In some cases, even if you receive the `MessageId`, packets can get dropped. For more information about how you can resolve the error, see [Troubleshoot downlink message queue errors](lorawan-downlink-queue.md#lorawan-downlink-queue-troubleshoot). ``` { MessageId: "6011dd36-0043d6eb-0072-0008" } ``` ## Get information about the list of participating gateways You can get information about the list of gateways that are participating in receiving the downlink message by listing messages in the downlink queue. To list messages, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListQueuedMessages.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListQueuedMessages.html) API. ``` aws iotwireless list-queued-messages \ --wireless-device-type "LoRaWAN" ``` Running this command returns information about the messages in the queue and their parameters. # Update gateway firmware using CUPS service with AWS IoT Core for LoRaWAN The [LoRa Basics Station](https://doc.sm.tc/station/) software that runs on your gateway provides credential management and firmware update interface using the Configuration and Update Server (CUPS) protocol. The CUPS protocol is an efficient mechanism that provides secure firmware update delivery with ECDSA signatures. It enables over-the-air (OTA) firmware updates, allowing you to remotely manage and upgrade the software on your LoRaWAN gateways without physically accessing them. You'll have to frequently update your gateway's firmware. You can use the CUPS service with AWS IoT Core for LoRaWAN to provide firmware updates to the gateway where the updates can also be signed. To update the gateway's firmware, you can use the SDK, CLI, or the console. With CUPS, you can upload the firmware file to an Amazon Simple Storage Service bucket, sign them with a private key, and schedule the updates to be delivered to your gateways with AWS IoT Core for LoRaWAN. ## Pre-requisites Before you can update the firmware of your LoRaWAN gateway, your gateway must have established a CUPS connection to the cloud. If you had previously connected your gateway, verify that your gateway is still connected before updating the gateway firmware. For information about onboarding and connecting your LoRaWAN gateway to AWS IoT Core for LoRaWAN, see [Onboard your gateways to AWS IoT Core for LoRaWAN](lorawan-onboard-gateways.md). ## Firmware update process The firmware update process involves the following steps. 1. Upload the firmware file to an Amazon Simple Storage Service (S3) bucket. 1. Generate a signature key pair and sign the firmware update file with the private key. **Note** To perform this step, make sure that the private key is present in the gateway. 1. Schedule the firmware update job, specifying the signed firmware file, the devices to be updated, and other configuration options. The firmware update is then securely delivered to the targeted gateways using the CUPS protocol. If the update was signed, the gateways can then verify the authenticity and integrity of the update using the provided signature, which ensures a secure and reliable firmware update process. The update process takes about 45 minutes to complete. It can take longer if you're setting up your gateway for the first time to connect to AWS IoT Core for LoRaWAN. Gateway manufacturers usually provide their own firmware update files and signatures so you can use that for the firmware update. If you don't have the firmware update files, see [(Optional) Generate the firmware update file and signature](lorawan-script-fwupdate-sigkey.md) for an example that you can use to adapt to your application. + If you're using the AWS Management Console to schedule and run the firmware update, proceed to [Schedule and run gateway firmware update task](lorawan-schedule-firmware-update.md). + If you're using the AWS CLI to schedule and run the firmware update, first proceed to [Upload the firmware file to an Amazon S3 bucket and add an IAM role](lorawan-upload-firmware-s3bucket.md) to upload your firmware file to Amazon S3 and grant AWS IoT Core for LoRaWAN permissions to access the file on your behalf. **Topics** + [ ## Pre-requisites ](#lorawan-update-firmware-prereq) + [ ## Firmware update process ](#lorawan-update-firmware-process) + [ # (Optional) Generate the firmware update file and signature ](lorawan-script-fwupdate-sigkey.md) + [ # Upload the firmware file to an Amazon S3 bucket and add an IAM role ](lorawan-upload-firmware-s3bucket.md) + [ # Schedule and run gateway firmware update task ](lorawan-schedule-firmware-update.md) # (Optional) Generate the firmware update file and signature The steps in this procedure are optional and depend on the gateway you're using. Gateway manufacturers provide their own firmware update in the form of an update file or a script and Basics Station runs this script in the background. In this case, you'll most likely find the firmware update file in the release notes of the gateway you're using. You can then use that update file or script instead and proceed to [Upload the firmware file to an Amazon S3 bucket and add an IAM role](lorawan-upload-firmware-s3bucket.md). If you don't have this script, following shows the commands to run for generating the firmware update file. The updates can also be signed to ensure that the code was not altered or corrupted and the devices run code that's published only by trusted authors. **Topics** + [ ## Generate the firmware update file ](#lorawan-firmware-update-script) + [ ## Generate signature for the firmware update ](#lorawan-generate-signature-fwupdate) + [ ## Review the next steps ](#lorawan-fwupdate-sigkey-next-steps) ## Generate the firmware update file The LoRa Basics Station software running on the gateway is capable of receiving firmware updates in the CUPS response. If you don't have a script provided by the manufacturer, refer to the following firmware update script that is written for the Raspberry Pi based RAKWireless Gateway. We have a base script and the new station binary, version file, and `station.conf` are attached to it. **Note** The script is specific to the RAKWireless Gateway, so you'll have to adapt it to your application depending on the gateway you're using. **Base script** Following shows a sample base script for the Raspberry Pi based RAKWireless Gateway. You can save the following commands in a file `base.sh` and then run the script in the terminal on the Raspberry Pi's web browser. ``` *#!/bin/bash* execution_folder=/home/pi/Documents/basicstation/examples/aws_lorawan station_path="$execution_folder/station" version_path="$execution_folder/version.txt" station_conf_path="$execution_folder/station_conf" # Function to find the Basics Station binary at the end of this script # and store it in the station path function prepare_station() { match=$(grep --text --line-number '^STATION:$' $0 | cut -d ':' -f 1) payload_start=$((match + 1)) match_end=$(grep --text --line-number '^END_STATION:$' $0 | cut -d ':' -f 1) payload_end=$((match_end - 1)) lines=$(($payload_end-$payload_start+1)) head -n $payload_end $0 | tail -n $lines > $station_path } # Function to find the version.txt at the end of this script # and store it in the location for version.txt function prepare_version() { match=$(grep --text --line-number '^VERSION:$' $0 | cut -d ':' -f 1) payload_start=$((match + 1)) match_end=$(grep --text --line-number '^END_VERSION:$' $0 | cut -d ':' -f 1) payload_end=$((match_end - 1)) lines=$(($payload_end-$payload_start+1)) head -n $payload_end $0 | tail -n $lines > $version_path } # Function to find the version.txt at the end of this script # and store it in the location for version.txt function prepare_station_conf() { match=$(grep --text --line-number '^CONF:$' $0 | cut -d ':' -f 1) payload_start=$((match + 1)) match_end=$(grep --text --line-number '^END_CONF:$' $0 | cut -d ':' -f 1) payload_end=$((match_end - 1)) lines=$(($payload_end-$payload_start+1)) head -n $payload_end $0 | tail -n $lines > $station_conf_path } # Stop the currently running Basics station so that it can be overwritten # by the new one killall station # Store the different files prepare_station prepare_versionp prepare_station_conf # Provide execute permission for Basics station binary chmod +x $station_path # Remove update.bin so that it is not read again next time Basics station starts rm -f /tmp/update.bin # Exit so that rest of this script which has binaries attached does not get executed exit 0 ``` **Add payload script** To the base script, we append the Basics Station binary, the version.txt that identifies the version to update to, and `station.conf` in a script called `addpayload.sh`. Then, run this script. ``` *#!/bin/bash * base.sh > fwstation # Add station echo "STATION:" >> fwstation cat $1 >> fwstation echo "" >> fwstation echo "END_STATION:" >> fwstation # Add version.txt echo "VERSION:" >> fwstation cat $2 >> fwstation echo "" >> fwstation echo "END_VERSION:" >> fwstation # Add station.conf echo "CONF:" >> fwstation cat $3 >> fwstation echo "END_CONF:" >> fwstation # executable chmod +x fwstation ``` After you've run these scripts, you can run the following command in the terminal to generate the firmware update file, `fwstation`. ``` $ ./addpayload.sh station version.txt station.conf ``` ## Generate signature for the firmware update The LoRa Basics Station software provides signed firmware updates with ECDSA signatures. To support signed updates, you'll need: + A signature that must be generated by an ECDSA private key and less than 128 bytes. + The private key that is used for the signature and must be stored in the gateway with file name of the format `sig-%d.key`. We recommend using the file name `sig-0.key`. + A 32-bit CRC over the private key. The signature and CRC will be passed to the AWS IoT Core for LoRaWAN APIs. To generate the previous files, you can use the following script `gen.sh` that is inspired by the [ basicstation](https://github.com/lorabasics/basicstation/blob/master/examples/cups/prep.sh) example in the GitHub repository. ``` *#!/bin/bash *function ecdsaKey() { # Key not password protected for simplicity openssl ecparam -name prime256v1 -genkey | openssl ec -out $1 } # Generate ECDSA key ecdsaKey sig-0.prime256v1.pem # Generate public key openssl ec -in sig-0.prime256v1.pem -pubout -out sig-0.prime256v1.pub # Generate signature private key openssl ec -in sig-0.prime256v1.pub -inform PEM -outform DER -pubin | tail -c 64 > sig-0.key # Generate signature openssl dgst -sha512 -sign sig-0.prime256v1.pem $1 > sig-0.signature # Convert signature to base64 openssl enc -base64 -in sig-0.signature -out sig-0.signature.base64 # Print the crc crc_res=$(crc32 sig-0.key)printf "The crc for the private key=%d\n" $((16#$crc_res)) # Remove the generated files which won't be needed later rm -rf sig-0.prime256v1.pem sig-0.signature sig-0.prime256v1.pub ``` The private key generated by the script should be saved into the gateway. The key file is in binary format. ``` ./gen_sig.sh fwstation read EC key writing EC key read EC key writing EC key read EC key writing EC key The crc for the private key=3434210794 $ cat sig-0.signature.base64 MEQCIDPY/p2ssgXIPNCOgZr+NzeTLpX+WfBo5tYWbh5pQWN3AiBROen+XlIdMScv AsfVfU/ZScJCalkVNZh4esyS8mNIgA== $ ls sig-0.key sig-0.key $ scp sig-0.key pi@192.168.1.11:/home/pi/Documents/basicstation/examples/iotwireless ``` ## Review the next steps Now that you have generated the firmware and signature. you can proceed to update the gateway firmware. + If you're using the AWS Management Console to schedule and run the firmware update, proceed to [Schedule and run gateway firmware update task](lorawan-schedule-firmware-update.md). + If you're using the AWS CLI to schedule and run the firmware update, first proceed to [Upload the firmware file to an Amazon S3 bucket and add an IAM role](lorawan-upload-firmware-s3bucket.md) to upload your firmware file, `fwstation`, to an Amazon S3 bucket. Then, grant AWS IoT Core for LoRaWAN permissions to access the file on your behalf. # Upload the firmware file to an Amazon S3 bucket and add an IAM role **Note** You'll need to perform these steps only if you're using the AWS CLI to create a wireless gateway task definition and perform the update. If you're using the AWS Management Console, you can skip these steps and proceed to [Schedule and run gateway firmware update task](lorawan-schedule-firmware-update.md). You can use Amazon S3 to create a *bucket*, which is a container that can store your firmware update file. You can upload your file to the S3 bucket and add an IAM role that allows the CUPS server to read your update file from the bucket. For more information about Amazon S3, see [ Getting started with Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html). The firmware update file that you want to upload depends on the gateway you're using. If you followed a procedure similar to the one described in [(Optional) Generate the firmware update file and signature](lorawan-script-fwupdate-sigkey.md), you'll upload the `fwstation` file generated by running the scripts. **Topics** + [ ## Create an Amazon S3 bucket and upload the update file ](#lorawan-create-s3-bucket) + [ ## Create an IAM role with permissions to read the S3 bucket ](#lorawan-s3-iam-permissions) + [ ## Review the next steps ](#lorawan-s3iam-next-steps) ## Create an Amazon S3 bucket and upload the update file You'll create an Amazon S3 bucket by using the AWS Management Console and then upload your firmware update file into the bucket. **Create an S3 bucket** To create an S3 bucket, sign in to the [Amazon S3 console](https://console.aws.amazon.com/s3/home#) and choose **Create bucket**. Then perform the following steps: **Note** Make sure you selected the same AWS Region as the one you used to create your LoRaWAN gateway and device. 1. Enter a unique and meaningful name for the **Bucket name**, (for example, `iotwirelessfwupdate`). For recommended naming convention for your bucket, see [Bucket naming rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html). 1. Verify the following settings for your Amazon S3 bucket, and then choose **Create bucket**. + Make sure that the **Block all public access** setting is selected so that your bucket uses the default permissions. + Choose **Enable** for **Bucket versioning** which will help you keep multiple versions of the firmware update file in the same bucket. + Choose **Server-side encryption** and make sure that it is set to **Disable**. **Upload your firmware update file** You can now see your bucket in the list of Buckets displayed in the AWS Management Console. Choose your bucket and then choose **Upload** to upload your file and complete the following steps. 1. Choose **Add file** and then upload the firmware update file. If you followed the procedure described in [(Optional) Generate the firmware update file and signature](lorawan-script-fwupdate-sigkey.md), you'll upload the `fwstation` file, otherwise upload the file provided by your gateway manufacturer. 1. Make sure all settings are set to their default. Make sure that **Predefined ACLs** is set to **private** and choose **Upload** to upload your file. 1. Copy the S3 URI of the file you uploaded. Choose your bucket and you'll see the file you uploaded displayed in the list of **Objects**. Choose your file and then choose **Copy S3 URI**. The URI will be something like: `s3://iotwirelessfwupdate/fwstation` if you named your bucket similar to the example described previously (`fwstation`). You'll use the S3 URI when creating the IAM role. ## Create an IAM role with permissions to read the S3 bucket You'll now create an IAM role and policy that will give CUPS the permission to read your firmware update file from the S3 bucket. **Create an IAM policy for your role** To create an IAM policy for your AWS IoT Core for LoRaWAN destination role, open the [Policies hub of the IAM console](https://console.aws.amazon.com/iam/home#/policies) and then complete the following steps: 1. Choose **Create policy**, and choose the **JSON** tab. 1. Delete any content from the editor and paste this policy document. The policy provides permissions to access the `iotwireless` bucket and the firmware update file, `fwstation`, stored inside an object. **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "s3:ListBucketVersions", "s3:ListBucket", "s3:GetObject" ], "Resource": [ "arn:aws:s3:::iotwirelessfwupdate/fwstation", "arn:aws:s3:::iotwirelessfwupdate" ] } ] } ``` 1. Choose **Review policy**, and in **Name**, enter a name for this policy (for example, `IoTWirelessFwUpdatePolicy`). You'll need this name to use in the next procedure. 1. Choose **Create policy**. **Create an IAM role with the attached policy** You'll now create an IAM role and attach the policy created previously for accessing the S3 bucket. Open the [Roles hub of the IAM console](https://console.aws.amazon.com/iam/home#/roles) and choose **Create role**, and then complete the following steps: 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. Check the IAM policy (for example, `IoTWirelessFwUpdatePolicy`) you created earlier in the search results and choose it. 1. Choose **Next: Tags**, and then choose **Next: Review**. 1. In **Role name**, enter the name of this role (for example, `IoTWirelessFwUpdateRole`), and then choose **Create role**. **Edit trust relationship of the IAM role** In the confirmation message displayed after you ran the previous step, choose the name of the role you created to edit it. You'll edit the role to add the following trust relationship. 1. In the **Summary** section of the role you created, 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**. 1. Obtain the ARN for your role. Choose your IAM role and in the Summary section, you'll see a **Role ARN**, such as `arn:aws:iam::123456789012:role/IoTWirelessFwUpdateRole`. Copy this **Role ARN**. ## Review the next steps Now that you have created the S3 bucket and an IAM role that allows the CUPS server to read the S3 bucket, go to the next topic to schedule and run the firmware update. Keep the **S3 URI** and **Role ARN** that you copied previously so that you can enter them to create a task definition that will be run to perform the firmware update. # Schedule and run gateway firmware update task If you have the firmware update file and signature, you can schedule and run the task definition to update the gateway firmware, as described in this page. If you don't have the firmware update files, see [(Optional) Generate the firmware update file and signature](lorawan-script-fwupdate-sigkey.md) for an example that you can use to adapt to your application. The following steps show you how to create a wireless gateway task definition to update the gateway firmware. **Topics** + [ ## What's a wireless gateway task definition? ](#lorawan-firmware-task-definition) + [ ## Get the current firmware version running on your gateway ](#lorawan-gateway-current-version) + [ ## Schedule gateway firmware update using a task definition ](#lorawan-create-task-definition) + [ ## Run the firmware update task and track progress ](#lorawan-run-fwupdate-task) ## What's a wireless gateway task definition? To update the gateway firmware, you create a task definition. You can use the task definition to include details about the firmware update and define the update. AWS IoT Core for LoRaWAN provides a firmware update based on information from the following three fields associated with the gateway. + **LoRa Basics Station** The version and build time of the Basics Station software. To identify this information, you can also generate it by using the Basics Station software that is being run by your gateway (for example, `2.0.5(rpi/std) 2021-03-09 03:45:09`). + **Package version** The firmware version, specified by the file `version.txt` in the gateway. While this information might not be present in the gateway, you must specify this field as it provides a way to define your firmware version (for example, `1.0.0`). + **Gateway platform model** The platform or model that is being used by the gateway (for example, Linux). ## Get the current firmware version running on your gateway To determine your gateway's eligibility for a firmware update, the CUPS server checks all three fields, **LoRa Basics Station**, **Package version**, and **Gateway platform model**, for a match when the gateway presents them during a CUPS request. These fields are stored as part of the current version of a wireless gateway task definition. You can determine the current firmware version running on the gateway from the console or the CLI. ### Get the current firmware version (console) When you use the AWS Management Console, you can obtain the firmware version from the details page of the gateway for which you're retrieving this information. 1. Go to the [Gateways hub](https://console.aws.amazon.com/iot/home#/wireless/gateways) page of the AWS IoT console and choose the gateway for which you're retrieving this information. 1. Go to the **Firmware** tab in the details page of the gateway to see the current firmware version and the status information that indicates whether a firmware update is pending. ### Get the current firmware version (CLI) When you use the AWS IoT Wireless API or the AWS CLI, you can obtain this information using the `CurrentVersion` field that's stored as part of the task definition. The following steps use the CLI to demonstrate how you can get this information. 1. **Obtain wireless gateway ID** First, obtain the unique identifier of the gateway for which you want to retrieve the current firmware version. If you've already provisioned a gateway, you can get information about the gateway using the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessGateway.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessGateway.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-wireless-gateway.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-wireless-gateway.html) CLI command. ``` aws iotwireless get-wireless-gateway \ --identifier 5a11b0a85a11b0a8 \ --identifier-type GatewayEui ``` Following shows a sample output for the command. ``` { "Name": "Raspberry pi", "Id": "1352172b-0602-4b40-896f-54da9ed16b57", "Description": "Raspberry pi", "LoRaWAN": { "GatewayEui": "5a11b0a85a11b0a8", "RfRegion": "US915" }, "Arn": "arn:aws:iotwireless:us-east-1:231894231068:WirelessGateway/1352172b-0602-4b40-896f-54da9ed16b57" } ``` 1. **Get gateway firmware version** Using the wireless gateway ID reported by the `get-wireless-gateway` command, you can use the [get-wireless-gateway-firmware-information](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-wireless-gateway-firmware-information.html) command to get the `CurrentVersion`. ``` aws iotwireless get-wireless-gateway-firmware-information \ --id "3039b406-5cc9-4307-925b-9948c63da25b" ``` Following shows a sample output for the command, with information from all three fields displayed by the `CurrentVersion`. ``` { "LoRaWAN": { "CurrentVersion": { "PackageVersion": "1.0.0", "Model": "rpi", "Station": "2.0.5(rpi/std) 2021-03-09 03:45:09" } } } ``` ## Schedule gateway firmware update using a task definition Now that you've verified the eligibility of the firmware update, you can schedule a firmware update task using a wireless gateway task definition and then run the update. To update the gateway firmware, you'll need a wireless gateway task definition. You can use the AWS IoT console or the AWS CLI to update the gateway firmware. ### Schedule gateway firmware update using a task definition (console) To schedule a firmware update task from the console: 1. Go to the [Gateways hub](https://console.aws.amazon.com/iot/home#/wireless/gateways) page of the AWS IoT console and choose the gateway for which you're updating the firmware. 1. Go to the **Firmware** tab in the details page of the gateway and choose **Update firmware**. 1. Create a wireless gateway task, or choose an existing task definition if you have already created one. If you have already created a task definition, choose **Use an existing task**. Information about the task definition will appear here, such as the **Package version**, the location for the firmware file in Amazon S3, and the status of the update. You can review the information and then choose **Update firmware**. #### Create a gateway task definition If you're creating a new task definition, you'll need to perform the steps described below to specify the location to your firmware file in Amazon S3, and the IAM role that grants AWS IoT Core for LoRaWAN permission to access the file and perform the update. In the **Update firmware** page of the console, choose **Create a new task**, and then perform the following steps. 1. **Specify firmware file and location in Amazon S3** You can use an Amazon Simple Storage Service bucket to store the firmware update files. Specify the location to your firmware file in Amazon S3, and provide the IAM role that grants AWS IoT Core for LoRaWAN permission to access the file and perform the update. + If you have already uploaded the file to Amazon S3, choose **Select an existing firmware file**. You can then **Browse S3** and provide the S3 URI to the file. + If you haven't already uploaded the file to Amazon S3, choose **Upload a new firmware file**. You can then upload the firmware file and **Browse S3** to choose the Amazon S3 bucket where the file will be uploaded. 1. **(Optional) Provide additional firmware verification settings** Optionally, if your firmware update was signed, you can use the additional settings to specify the update signature and CRC. These settings can be used to verify the authenticity and integrity of the signed update. It also ensures that the code was not corrupted or altered, and the devices run code that's published only by trusted authors. The update signature and CRC will be passed to AWS IoT Core for LoRaWAN when updating the firmware using CUPS. 1. **(Optional) Provide additional setting to automatically create update tasks** Optionally, we recommend that you choose to specify automatic creation of tasks for all gateways by using the `Auto create tasks and update all like gateways` parameter. This parameter applies to any gateway that has a match for all three parameters mentioned previously in [What's a wireless gateway task definition?](#lorawan-firmware-task-definition). If this parameter is disabled, the parameters have to be manually assigned to the gateway. 1. **Permissions to access the bucket** You can either create a new service role or choose an existing role to allow AWS IoT Core for LoRaWAN to access the firmware update file in the Amazon S3 bucket on your behalf. To create a new role, you can enter a role name or leave it blank for a random name to be generated automatically. To view the policy permissions that grant access to the Amazon S3 bucket, choose **View policy permissions**. ### Schedule gateway firmware update using a task definition (CLI) You can create the wireless gateway task definition by using the AWS IoT Wireless API or the AWS CLI. The following steps show how to create the task definition using the CLI. **Note** When you create the task definition, we recommend that you specify automatic creation of tasks by using the `AutoCreateTasks` parameter. This parameter applies to any gateway that has a match for all three parameters mentioned previously in [What's a wireless gateway task definition?](#lorawan-firmware-task-definition). If this parameter is disabled, the parameters have to be manually assigned to the gateway. #### Pre-requisites Before you use the AWS CLI to update the firmware, you must have uploaded the firmware file to an Amazon S3 bucket, and created an IAM role that grants AWS IoT Core for LoRaWAN permission to access the file in the Amazon S3 bucket for performing the update. If you've already uploaded the firmware file and the IAM role, proceed to [Run firmware update task](#lorawan-create-task-definition-cli-run) to run the firmware update task. If you haven't already uploaded the firmware file and specified the IAM role, perform the steps described in [Upload the firmware file to an Amazon S3 bucket and add an IAM role](lorawan-upload-firmware-s3bucket.md)8 and then run the firmware update task. #### Run firmware update task To run the firmware update task, perform the following steps. 1. **Specify the input parameters for the update task** Create a file, `input.json`, that'll contain the information to pass to the `CreateWirelessGatewayTaskDefinition` API. In the `input.json` file, provide the following information that you obtained earlier: + **UpdateDataSource** Provide the link to your object containing the firmware update file that you uploaded to the S3 bucket. (for example, `s3://iotwirelessfwupdate/fwstation`. + **UpdateDataRole** Provide the link to the Role ARN for the IAM role that you created, which provides permissions to read the S3 bucket. (for example, `arn:aws:iam::123456789012:role/IoTWirelessFwUpdateRole`. + **SigKeyCRC and UpdateSignature** This information might be provided by your gateway manufacturer, but if you followed the procedure described in [(Optional) Generate the firmware update file and signature](lorawan-script-fwupdate-sigkey.md), you'll find this information when generating the signature. + **CurrentVersion** Provide the `CurrentVersion` output that you obtained previously by running the `get-wireless-gateway-firmware-information ` command. ``` cat input.json ``` Following shows the contents of the `input.json` file. ``` { "AutoCreateTasks": true, "Name": "FirmwareUpdate", "Update": { "UpdateDataSource" : "s3://iotwirelessfwupdate/fwstation", "UpdateDataRole" : "arn:aws:iam::123456789012:role/IoTWirelessFwUpdateRole", "LoRaWAN" : { "SigKeyCrc": 3434210794, "UpdateSignature": "MEQCIDPY/p2ssgXIPNCOgZr+NzeTLpX+WfBo5tYWbh5pQWN3AiBROen+XlIdMScvAsfVfU/ZScJCalkVNZh4esyS8mNIgA==", "CurrentVersion" : { "PackageVersion": "1.0.0", "Model": "rpi", "Station": "2.0.5(rpi/std) 2021-03-09 03:45:09" } } } } ``` 1. **Create the gateway task definition** Pass the `input.json` file to the [create-wireless-gateway-task-definition](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-wireless-gateway-task-definition.html) command to create the task definition. ``` aws iotwireless create-wireless-gateway-task-definition \ --cli-input-json file://input.json ``` Following shows the output of the command. ``` { "Id": "4ac46ff4-efc5-44fd-9def-e8517077bb12", "Arn": "arn:aws:iotwireless:us-east-1:231894231068:WirelessGatewayTaskDefinition/4ac46ff4-efc5-44fd-9def-e8517077bb12" } ``` ## Run the firmware update task and track progress The gateway is ready to receive the firmware update and, once powered on, it connects to the CUPS server. When the CUPS server finds a match in the version of the gateway, it schedules a firmware update. A task is a task definition in process. The firmware update task starts as soon as a matching gateway for the update is found by the CUPS server. You can track the progress of the update task on the gateway from the console or the CLI. ### Run update task and track progress (console) When you use the AWS Management Console, you can track the progress of the firmware update from the details page of the gateway for which you're retrieving this information. Go to the [Gateways hub](https://console.aws.amazon.com/iot/home#/wireless/gateways) page, choose the gateway for which you're tracking the update, and then go to the **Firmware** tab to see the update status. If the firmware update fails the first time, you'll see a status of **Retrying**, and the gateway sends the same request. If the CUPS server is unable to connect to the gateway after a second retry, it will show a status of **FAILED**. ### Run update task and track progress (CLI) You can track the progress of the task by using the `GetWirelessGatewayTask` API. When you run the [get-wireless-gateway-task](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-wireless-gateway-task.html) command the first time, it will show the task status as `IN_PROGRESS`. ``` aws iotwireless get-wireless-gateway-task \ --id 1352172b-0602-4b40-896f-54da9ed16b57 ``` Following shows the output of the command. ``` { "WirelessGatewayId": "1352172b-0602-4b40-896f-54da9ed16b57", "WirelessGatewayTaskDefinitionId": "ec11f9e7-b037-4fcc-aa60-a43b839f5de3", "LastUplinkReceivedAt": "2021-03-12T09:56:12.047Z", "TaskCreatedAt": "2021-03-12T09:56:12.047Z", "Status": "IN_PROGRESS" } ``` When you run the command the next time, if the firmware update takes effect, it will show the updated fields, `Package`, `Version`, and `Model` and the task status changes to `COMPLETED`. ``` aws iotwireless get-wireless-gateway-task \ --id 1352172b-0602-4b40-896f-54da9ed16b57 ``` Following shows the output of the command. ``` { "WirelessGatewayId": "1352172b-0602-4b40-896f-54da9ed16b57", "WirelessGatewayTaskDefinitionId": "ec11f9e7-b037-4fcc-aa60-a43b839f5de3", "LastUplinkReceivedAt": "2021-03-12T09:56:12.047Z", "TaskCreatedAt": "2021-03-12T09:56:12.047Z", "Status": "COMPLETED" } ``` In this example, we showed you the firmware update using the Raspberry Pi based RAKWireless gateway. The firmware update script stops the running BasicStation to store the updated `Package`, `Version`, and `Model` fields so BasicStation will have to be restarted. ``` 2021-03-12 09:56:13.108 [CUP:INFO] CUPS provided update.bin 2021-03-12 09:56:13.108 [CUP:INFO] CUPS provided signature len=70 keycrc=37316C36 2021-03-12 09:56:13.148 [CUP:INFO] ECDSA key#0 -> VERIFIED 2021-03-12 09:56:13.148 [CUP:INFO] Running update.bin as background process 2021-03-12 09:56:13.149 [SYS:VERB] /tmp/update.bin: Forked, waiting... 2021-03-12 09:56:13.151 [SYS:INFO] Process /tmp/update.bin (pid=6873) completed 2021-03-12 09:56:13.152 [CUP:INFO] Interaction with CUPS done - next regular check in 10s ``` If the firmware update fails, you see a status of `FIRST_RETRY` from the CUPS server, and the gateway sends the same request. If the CUPS server is unable to connect to the gateway after a `SECOND_RETRY`, it will show a status of `FAILED`. After the previous task was `COMPLETED` or `FAILED`, delete the old task by using the [delete-wireless-gateway-task](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/delete-wireless-gateway-task.html) command before starting a new one. ``` aws iotwireless delete-wireless-gateway-task \ --id 1352172b-0602-4b40-896f-54da9ed16b57 ``` # Managing devices with AWS IoT Core for LoRaWAN Following are some important considerations when using your devices with AWS IoT Core for LoRaWAN. For information about how to add your device to AWS IoT Core for LoRaWAN, see [Onboard your devices to AWS IoT Core for LoRaWAN](lorawan-onboard-end-devices.md). ## Device considerations When selecting a device that you want to use for communicating with AWS IoT Core for LoRaWAN, consider the following. + Available sensors + Battery capacity + Energy consumption + Cost + Antenna type and transmission range ## Using devices with gateways qualified for AWS IoT Core for LoRaWAN The devices that you use can be paired with wireless gateways that are qualified for use with AWS IoT Core for LoRaWAN. You can find these gateways and developer kits in the [AWS Partner Device Catalog](https://devices.amazonaws.com/search?page=1&sv=iotclorawan). We also recommend that you consider proximity of these devices to your gateways. For more information, see [Using qualified gateways from the AWS Partner Device Catalog](lorawan-manage-gateways.md#lorawan-qualified-gateways). ## LoRaWAN version AWS IoT Core for LoRaWAN supports all devices that comply to 1.0.x or 1.1 LoRaWAN specifications standardized by LoRa Alliance. ## 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). We recommend that you use OTAA to activate your device because new session keys are generated for each activation, which makes it more secure. Your wireless device specification is based on the LoRaWAN version and activation mode, which determines the root keys and session keys generated for each activation. For more information, see [Add your wireless device specification to AWS IoT Core for LoRaWAN using the console](lorawan-end-devices-add.md#lorawan-end-device-spec-console). ## Device classes LoRaWAN devices can send uplink messages at any time. Listening to downlink messages consumes battery capacity and reduces battery duration. The LoRaWAN protocol specifies three classes of LoRaWAN devices. + Class A devices sleep most of the time and listen for downlink messages only for a short period of time. These devices are mostly battery-powered sensors with a battery lifetime of up to 10 years. + Class B devices can receive messages in scheduled downlink slots. These devices are mostly battery-powered actuators. + Class C devices never sleep and continuously listen to incoming messages and so there isn't much delay in receiving the messages. These devices are mostly mains-powered actuators. For more information about these wireless device considerations, refer to the resources mentioned in [Learn more about LoRaWAN](what-is-iot-lorawan.md#lorawan-learn-more). **Topics** + [ ## Device considerations ](#lorawan-devices-criteria) + [ ## Using devices with gateways qualified for AWS IoT Core for LoRaWAN ](#lorawan-devices-qualified-gateways) + [ ## LoRaWAN version ](#lorawan-lorawan-version) + [ ## Activation modes ](#lorawan-activation-modes) + [ ## Device classes ](#lorawan-device-classes) + [ # Using adaptive data rate (ADR) with AWS IoT Core for LoRaWAN ](iot-lorawan-adr.md) + [ # View format of uplink messages sent from LoRaWAN devices ](lorawan-uplink-metadata-format.md) + [ # Queue downlink messages to send to LoRaWAN devices ](lorawan-downlink-queue.md) + [ # Managing LoRaWAN traffic from public networks (Everynet) ](iot-lorawan-roaming.md) # Using adaptive data rate (ADR) with AWS IoT Core for LoRaWAN To optimize the device transmission power consumption while making sure that messages from the end devices are received at the gateways, AWS IoT Core for LoRaWAN uses adaptive data rate. Adaptive data rate instructs the end devices to optimize the data rate, transmission power, and the number of retransmissions while attempting to reduce the error rate of the packets received at the gateways. For example, if your end device is located close to the gateways, adaptive data rate reduces the transmission power and increases the data rate. **Topics** + [ ## How adaptive data rate (ADR) works ](#iot-lorawan-adr-algorithm) + [ ## Configure data rate limits (CLI) ](#iot-lorawan-adr-use) ## How adaptive data rate (ADR) works To enable ADR, your device must set the ADR bit in the frame header. Once the ADR bit is set, AWS IoT Core for LoRaWAN sends the `LinkADRReq` MAC command and your devices respond with the `LinkADRAns` command which includes the ACK status of the ADR command. Once your devices ACK the ADR command, it will then follow the ADR instructions from AWS IoT Core for LoRaWAN and adjust the transmission parameter values for optimal data rate. The AWS IoT Core for LoRaWAN ADR algorithm uses the SINR information in the uplink metadata history to determine the optimal transmission power and data rate to use for the devices. The algorithm uses the 20 most recent uplink messages that start once the ADR bit is set in the frame header. To determine the number of retransmissions, it uses the packet error rate (PER), which is a percentage of the total number of packets that are lost. When you use this algorithm, you can only control the range of data rates, that is, the minimum and maximum limits for the data rates. ## Configure data rate limits (CLI) By default, AWS IoT Core for LoRaWAN will perform ADR when you set the ADR bit in the frame header of your LoRaWAN device. You can control the minimum and maximum limits for the data rate when creating a service profile for your LoRaWAN devices using the AWS IoT Wireless API operation [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateServiceProfile.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateServiceProfile.html), or the AWS CLI command, [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-service-profile.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-service-profile.html). To specify the minimum and maximum limits for the data rate, use the `DrMin` and `DrMax` parameters with the `CreateServiceProfile` API operation. The default minimum and maximum data rate limits are 0 and 15. For example, the following CLI command sets a minimum data rate limit of 3 and a maximum limit of 12. To specify the minimum and maximum limits for the transmit power range of LoRaWAN devices, use the `TxPowerIndexMin` and `TxPowerIndexMax` parameters with the `CreateServiceProfile` API operation. The default minimum and maximum power ranges are 0 and 15. The following following CLI command sets a minimum Transmit Power Index of 3 and a maximum of 12. **Note** Regional parameters override service profile settings for minimum and maximum Transmit Power Index (`TxPowerIndexMin` and `TxPowerIndexMax`). For example, if you set `TxPowerIndexMin` to 14 for a device that operates in the US915 Band, the configuration you set won't be applied. To learn more about regional parameters, see [RP002-1.0.4 Regional Parameters](https://resources.lora-alliance.org/technical-specifications/rp002-1-0-4-regional-parameters). To specify the minimum and maximum number of transmissions, use the `NbTransMin` and `NbTransMax` parameters with the `CreateServiceProfile` API operation. The default minimum and maximum number of transmissions is 0 and 3. ``` aws iotwireless create-service-profile \ --lorawan DrMin=3,DrMax=12,TxPowerIndexMin=3,TxPowerIndexMax=12,NbTransMin=1,NbTransMax=4 ``` Running this command generates an ID and an Amazon Resource Name (ARN) for the service profile. ``` { "Arn": "arn:aws:iotwireless:us-east-1:123456789012:ServiceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d", "Id": "12345678-a1b2-3c45-67d8-e90fa1b2c34d" } ``` You can get the values of the parameters specified using the AWS IoT Wireless API operation [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetServiceProfile.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetServiceProfile.html), or the AWS CLI command, [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-service-profile.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-service-profile.html). ``` aws iotwireless get-service-profile --id "12345678-a1b2-3c45-67d8-e90fa1b2c34d" ``` Running this command generates the values for the service profile parameters. ``` { "Arn": "arn:aws:iotwireless:us-east-1:651419225604:ServiceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d", "Id": "12345678-a1b2-3c45-67d8-e90fa1b2c34d", "LoRaWAN": { "AddGwMetadata": false, "DrMax": 12, "DrMin": 3, "NbTransMax": 4, "NbTransMin": 1, "PrAllowed": false, "RaAllowed": false, "TxPowerIndexMax": 12, "TxPowerIndexMin": 3 } } ``` If you've created multiple profiles, you can use the API operation, [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListServiceProfiles.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListServiceProfiles.html), or the AWS CLI command, [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-service-profiles.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-service-profiles.html) to list the service profiles in your AWS account, and then use the `GetServiceProfile` API or the `get-service-profile` CLI command to retrieve the service profile for which you customized the data rate limits. # View format of uplink messages sent from LoRaWAN devices To faciliate seamless connection between your LoRaWAN devices and the cloud, you can use AWS IoT Core for LoRaWAN. The AWS IoT Core for LoRaWAN service provides secure and reliable data exchange between your LoRaWAN devices and AWS IoT Core. It acts as a bridge, translating the LoRaWAN protocol into MQTT messages that can be seamlessly ingested by AWS IoT Core. You can use this capability in applications, such as real-time data processing, device state management, and integration with other AWS services. After you've connected your LoRaWAN device to AWS IoT Core for LoRaWAN, your devices can start sending messages to the cloud. Uplink messages are messages that are sent from your device and received by AWS IoT Core for LoRaWAN. Your LoRaWAN devices can send uplink messages at any time, which are then forwarded to other AWS services and cloud-hosted applications. Messages that are sent from AWS IoT Core for LoRaWAN and other AWS services and applications to your devices are called downlink messages. This topic shows how you can observe the format of the uplink message that you'll receive from your wireless device. ## Before you can observe the uplink messages You must have onboarded your wireless device and connected your device to AWS IoT so that it can transmit and receive data. For information about onboarding your device to AWS IoT Core for LoRaWAN, see [Onboard your devices to AWS IoT Core for LoRaWAN](lorawan-onboard-end-devices.md). ## What do the uplink messages contain? LoRaWAN devices connect to AWS IoT Core for LoRaWAN by using LoRaWAN gateways. The uplink message that you receive from the device will contain the following information. + Payload data that corresponds to the encrypted payload message that is sent from the wireless device. + Wireless metadata that includes: + Device information such as DevEui, the data rate, and the frequency channel in which the device is operating. + Optional additional parameters and the gateway information for gateways that are connected to the device. The gateway parameters include the gateway's EUI, the SNR, and RSSi. By using the wireless metadata, you can obtain useful information about the wireless device and the data that is transmitted between your device and AWS IoT. For example, you can use the `AckedMessageId` parameter to check whether the last confirmed downlink message has been received by the device. Optionally, if you choose to include the gateway information, you can identify whether you want to switch to a stronger gateway channel that's closer to your device. ## How to observe the uplink messages? After you've onboarded your device, you can use the [MQTT test client](https://console.aws.amazon.com/iot/home#/test) on the **Test** page of the AWS IoT console to subscribe to the topic that you specified when creating your destination. You'll start to see messages after your device is connected and starts sending payload data. This diagram identifies the key elements in a LoRaWAN system connected to AWS IoT Core for LoRaWAN, which shows the primary data plane and how data flows through the system. ![\[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) When the wireless device starts sending uplink data, AWS IoT Core for LoRaWAN wraps the wireless metadata information with the payload and then sends it to your AWS applications. ## Uplink message examples The following examples show the format of the uplink message received from your device. The format includes the gateway metadata that varies depending on whether you're using the public network, or your own private LoRaWAN gateway that you onboarded to AWS IoT Core for LoRaWAN. ### Uplink message 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. In the metadata, the field: + `Battery` indicates the battery level reported by the device. It ranges from 0 to 255. 0 indicates that the device is connected to an external power source. 1 and 254 are the minimum and maximum battery levels. A value of 255 indicates that the device cannot measure the battery level. + `Margin` represents the demodulation SNR (signal-to-noise ratio) in dB rounded to the nearest integer value. It ranges from -32 to \$131. ``` { "WirelessDeviceId": "5b58245e-146c-4c30-9703-0ca942e3ff35", "PayloadData": "Cc48AAAAAAAAAAA=", "WirelessMetadata": { "LoRaWAN": { "ADR": false, "Bandwidth": 125, "ClassB": false, "CodeRate": "4/5", "DataRate": "0", "DevAddr": "00b96cd4", "DevEui": "58a0cb000202c99", "FOptLen": 2, "FCnt": 1, "Fport": 136, "Frequency": "868100000", "Battery": 210, "Margin": -6, "Gateways": [ { "GatewayEui": "80029cfffe5cf1cc", "Snr": -29, "Rssi": 9.75 } ], "MIC": "7255cb07", "MType": "UnconfirmedDataUp", "Major": "LoRaWANR1", "Modulation": "LORA", "PolarizationInversion": false, "SpreadingFactor": 12, "Timestamp": "2021-05-03T03:24:29Z" } } } ``` ### Uplink message 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 uplink 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. ``` { "WirelessDeviceId": "5b58245e-146c-4c30-9703-0ca942e3ff35", "PayloadData": "Cc48AAAAAAAAAAA=", "WirelessMetadata": { "LoRaWAN": { "ADR": false, "Bandwidth": 125, "ClassB": false, "CodeRate": "4/5", "DataRate": "0", "DevAddr": "00b96cd4", "DevEui": "58a0cb000202c99", "FOptLen": 2, "FCnt": 1, "Fport": 136, "Frequency": "868100000", "PublicGateways": [ { "DlAllowed": true, "Id": "0x3abe094", "ProviderNetId": "0x0000b", "RfRegion": "US915", "Rssi": -12, "Snr": 6.75 } ], "MIC": "7255cb07", "MType": "UnconfirmedDataUp", "Major": "LoRaWANR1", "Modulation": "LORA", "PolarizationInversion": false, "SpreadingFactor": 12, "Timestamp": "2021-05-03T03:24:29Z" } } } ``` ### Uplink message 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. ``` { "WirelessDeviceId": "0d9a439b-e77a-4573-a791-49d5c0f4db95", "PayloadData": "AAAAAAAA8=", "WirelessMetadata": { "LoRaWAN": { "ClassB": false, "CodeRate": "4/5", "DataRate": "1", "DevAddr": "01920f27", "DevEui": "ffffff10000163b0", "FCnt": 1, "FPort": 5, "Battery": 125, "Margin": -12, "Timestamp": "2021-04-29T05:19:43.646Z" } } } ``` # Queue downlink messages to send to LoRaWAN devices Cloud-hosted applications and other AWS services can send downlink messages to your wireless devices. Downlink messages are messages that are sent from AWS IoT Core for LoRaWAN to your wireless device. You can schedule and send downlink messages for each device that you've onboarded to AWS IoT Core for LoRaWAN. If you have multiple devices for which you want to send a downlink message, you can use a multicast group. Devices in a multicast group share the same multicast address, which is then distributed to an entire group of recipient devices. For more information, see [Create multicast groups to send a downlink payload to multiple devices](lorawan-multicast-groups.md). ## How a downlink message queue works The device class of your LoRaWAN device determines how the messages in your queue are sent to the device. Class A devices send an uplink message to AWS IoT Core for LoRaWAN to indicate that the device is available to receive downlink messages. Class B devices can receive messages at regular downlink slots. Class C devices can receive downlink messages at any time. For more information about device classes, see [Device classes](lorawan-manage-end-devices.md#lorawan-device-classes). The following shows how messages are queued and sent to your class A devices. 1. AWS IoT Core for LoRaWAN buffers the downlink message that you added to the queue with the frame port, payload data, and the acknowledge mode parameters that you specified by using the AWS IoT console or the AWS IoT Wireless API. 1. Your LoRaWAN device sends an uplink message to indicate that it's online and can start receiving downlink messages. 1. If you added more than one downlink message to the queue, AWS IoT Core for LoRaWAN sends the first downlink message in the queue to your device with the acknowledge (ACK) flag set. 1. Your device either sends an uplink message to AWS IoT Core for LoRaWAN immediately, or it sleeps until the next uplink message and includes the ACK flag in the message. 1. When AWS IoT Core for LoRaWAN receives the uplink message with the ACK flag, it clears the downlink message from the queue, indicating that your device has successfully received the downlink message. If the ACK flag is missing from the uplink message after checking three times, the message is discarded. ## Perform downlink queue operations by using the console You can use the AWS Management Console to queue downlink messages and clear individual messages, or the entire queue, as needed. For class A devices, after an uplink is received from the device to indicate that it's online, the queued messages are then sent to the device. After the message is sent, it's automatically cleared from the queue. **Queue downlink messages** To create a downlink message queue 1. Go to the [Devices hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/wireless/devices) and choose the device for which you want to queue downlink messages. 1. In the **Downlink messages** section of the device details page, choose **Queue downlink messages**. 1. Specify the following parameters to configure your downlink message: + **FPort**: Choose the frame port for the device to communicate with AWS IoT Core for LoRaWAN. + **Payload**: Specify the payload message that you want to send to your device. The maximum payload size is 242 bytes. If adaptive data rate (ADR) is enabled, AWS IoT Core for LoRaWAN uses it to choose the optimal data rate for your payload size. You can further optimize the data rate as needed. + **Acknowledge mode**: Confirm whether your device has received the downlink message. If a message requires this mode, you'll see an uplink message with the ACK flag in your data stream, and the message will be cleared from the queue. 1. To add your downlink message to the queue, choose **Submit**. Your downlink message has now been added to the queue. If you don't see your message or you receive an error, you can troubleshoot the error as described in [Troubleshoot downlink message queue errors](#lorawan-downlink-queue-troubleshoot). **Note** After your downlink message has been added to the queue, you can no longer edit the parameters **FPort**, **Payload**, and **Acknowledge mode**. To send a downlink message with different values for these parameters, you can delete this message and queue a new downlink message with the updated parameter values. The queue lists the downlink messages you've added. To see the payload for the uplink and downlink messages that are exchanged between your devices and AWS IoT Core for LoRaWAN, you can use network analyzer. For more information, see [Monitoring of LoRaWAN resources using network analyzer](network-analyzer-overview.md). **List downlink message queue** The downlink message that you created is added to the queue. Each subsequent downlink message is added to the queue after this message. You can see a list of downlink messages in the **Downlink messages** section of the device details page. After an uplink is received, the messages are sent to the device. After a downlink message has been received by your device, it will be removed from the queue. The next message then moves up in the queue to be sent to your device. **Delete individual downlink messages or clear entire queue** Each downlink message is cleared from the queue automatically after it's sent to your device. You can also delete individual messages or clear the entire downlink queue. These actions can't be undone. + If you find messages in the queue that you don't want to send, choose the messages and choose **Delete**. + If you don't want to send any messages from the queue to your device, you can clear the entire queue by choosing **Clear downlink queue**. ## Perform downlink queue operations by using the API You can use the AWS IoT Wireless API to queue downlink messages and clear individual messages, or the entire queue, as needed. **Queue downlink messages** To create a downlink message queue, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToWirelessDevice.html) API operation or the [cli/latest/reference/iotwireless/send-data-to-wireless-device.html](cli/latest/reference/iotwireless/send-data-to-wireless-device.html) CLI command. ``` aws iotwireless send-data-to-wireless-device \ --id "11aa5eae-2f56-4b8e-a023-b28d98494e49" \ --transmit-mode "1" \ --payload-data "SGVsbG8gVG8gRGV2c2lt" \ --wireless-metadata LoRaWAN={FPort=1} ``` The output of running this command generates a `MessageId` for the downlink message. In some cases, even if you receive the `MessageId`, packets can get dropped. For more information about how you can resolve the error, see [Troubleshoot downlink message queue errors](#lorawan-downlink-queue-troubleshoot). ``` { MessageId: "6011dd36-0043d6eb-0072-0008" } ``` **List downlink messages in the queue** To list all downlink messages in the queue, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListQueuedMessages.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListQueuedMessages.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-queued-messages.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-queued-messages.html) CLI command. ``` aws iotwireless list-queued-messages ``` By default, a maximum of 10 downlink messages are displayed when running this command. **Remove individual downlink messages or clear entire queue** To remove individual messages from the queue or to clear the entire queue, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteQueuedMessages.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteQueuedMessages.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/delete-queued-messages.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/delete-queued-messages.html) CLI command. + To remove individual messages, provide the `messageID` for messages you want to remove for your wireless device, specified by the `wirelessDeviceId`. + To clear the entire downlink queue, specify `messageID` as `*` for your wireless device, specified by the `wirelessDeviceId`. ## Troubleshoot downlink message queue errors Here are some things to check if you're not seeing the expected results: + **Downlink messages don't appear in the AWS IoT console** If you don't see your downlink message in the queue after adding it as described in [Perform downlink queue operations by using the console](#lorawan-downlink-queue-console), it might be because your device hasn't completed a process called *activation* or *join procedure*. This procedure is completed when your device onboards with AWS IoT Core for LoRaWAN. For more information, see [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 onboarding your device to AWS IoT Core for LoRaWAN, you can monitor your device to check whether join and rejoin succeeded by using the network analyzer or Amazon CloudWatch. For more information, see [Monitoring tools](monitoring-cloudwatch.md#monitoring-tools). + **Missing downlink message packets when using the API** When you use the `SendDataToWirelessDevice` API operation, the API returns a unique `MessageId`. However, it can't confirm whether your LoRaWAN device has received the downlink message. The downlink packets can get dropped in cases such as when your device hasn't completed the join procedure. For more information about how to resolve this error, see the previous section. + **Missing ARN error when sending downlink message** When sending a downlink message to your device from the queue, you can receive a missing Amazon Resource Name (ARN) error. This error might occur because the destination hasn't been specified correctly for the device that's receiving the downlink message. To resolve this error, check the destination details for your device. # Managing LoRaWAN traffic from public networks (Everynet) You can connect your LoRaWAN devices to the cloud in minutes by using publicly available LoRaWAN networks. AWS IoT Core for LoRaWAN now supports Everynet’s network coverage in the US, UK, Ireland, and Spain. When using the public network, you'll be charged a public network connectivity charge for each device every month. The pricing applies to all AWS Regions where public network connectivity is offered. For information about pricing for this feature, see the [AWS IoT Core pricing page](https://aws.amazon.com//iot-core/pricing/). **Important** The public network is operated and provided as a service directly by Everynet. Before using this feature, see the applicable [AWS Service Terms](https://aws.amazon.com/service-terms/). In addition, if you use a public network through AWS IoT Core for LoRaWAN, certain LoRaWAN device information such as `DevEUI` and `JoinEUI` will be replicated across regions where AWS IoT Core for LoRaWAN is available. AWS IoT Core for LoRaWAN supports the public LoRaWAN network according to the LoRa Alliance specification for roaming, as described in [LoRaWAN Backend Interfaces 1.0 Specification](https://lora-alliance.org/wp-content/uploads/2020/11/lorawantm-backend-interfaces-v1.0.pdf). The public network capability can be used to connect your end devices that are outside the home network. To support this capability, AWS IoT Core for LoRaWAN partners with Everynet to offer extended radio coverage. ## Benefits of using a public LoRaWAN network Your LoRaWAN devices can use a public network to connect to the cloud, which reduces the time to deployment, and reduces the time and cost that are required to maintain a private LoRaWAN network. By using a public LoRaWAN network, you'll receive benefits such as coverage extension, running core without radio network, and coverage densification. This feature can be used to: + Provide coverage to devices when they move out of their home network, such as *Device A* in figure shown in the [Public LoRaWAN network support architecture](lorawan-roaming-works.md#lorawan-roaming-architecture) section. + Extend coverage to devices that don't have a LoRa gateway to connect to, such as *Device B* in figure shown in the [Public LoRaWAN network support architecture](lorawan-roaming-works.md#lorawan-roaming-architecture) section. The device can then use the gateway provided by the partner to connect to the home network. Your LoRaWAN devices can use a public network to connect to the cloud using the roaming feature, which reduces the time to deployment, and reduces the time and cost that are required to maintain a private LoRaWAN network. The following sections describe the public network support architecture, how public LoRaWAN network support works, and how to use this feature. **Topics** + [ ## Benefits of using a public LoRaWAN network ](#lorawan-roaming-benefits) + [ # How LoRaWAN public network support works ](lorawan-roaming-works.md) + [ # How to use AWS IoT Core for LoRaWAN public network support ](lorawan-roaming-use.md) # How LoRaWAN public network support works AWS IoT Core for LoRaWAN supports the passive roaming feature, according to the LoRa Alliance specification. With passive roaming, the roaming process is entirely transparent to the end device. End devices that roam outside the home network can connect to gateways in that network and exchange uplink and downlink data using the application server. The devices stay connected to the home network throughout the entire roaming process. **Note** AWS IoT Core for LoRaWAN supports only the stateless feature of passive roaming. Handover roaming is not supported. In handover roaming, your device will switch to a different carrier when it travels outside the home network. **Topics** + [ ## Public LoRaWAN network concepts ](#lorawan-roaming-concepts) + [ ## Public LoRaWAN network support architecture ](#lorawan-roaming-architecture) ## Public LoRaWAN network concepts The following concepts are used by the public network feature supported by AWS IoT Core for LoRaWAN. **LoRaWAN network server (LNS)** An LNS is a standalone private server that can run on your premises or can be a cloud-based service. AWS IoT Core for LoRaWAN is an LNS that offers services on the cloud. **Home network server (hNS)** The home network is the network that the device belongs to. The home network server (hNS) is an LNS where AWS IoT Core for LoRaWAN stores the provisioning data of the device, such as the `DevEUI`, `AppEUI`, and session keys. **Visited network server (vNS)** The visited network is the network that the device gets coverage from when it leaves the home network. The visited network server (vNS) is an LNS that has a business and technical agreement with the hNS for being able to serve the end device. AWS partner, Everynet, acts as the visited network to provide coverage. **Serving network server (sNS)** The serving network server (sNS) is an LNS that handles the MAC commands for the device. There can be only one sNS for one LoRa session. **Forwarding network server (fNS)** The forwarding network server (fNS) is an LNS that manages the radio gateways. There can be zero or more fNS involved in one LoRa session. This network server manages the forwarding of data packets that are received from the device to the home network. ## Public LoRaWAN network support architecture The following architecture diagram shows how AWS IoT Core for LoRaWAN partners with Everynet to provide public network connectivity. In this case, *Device A* is connected to the hNS (home network server) provided by AWS IoT Core for LoRaWAN through a LoRa gateway. When Device A moves out of the home network, it enters a visited network, and is covered by the visited network server (vNS) provided by Everynet. The vNS also extends coverage to *Device B* which doesn't have a LoRa gateway to connect to. You can view the public network coverage information in the AWS IoT console as described in the following section. ![\[Image showing how AWS IoT Core for LoRaWAN supports roaming to support devices that move out of home network, and to extend coverage to devices that don't have a gateway to connect to.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-lorawan-roaming-architecture.png) AWS IoT Core for LoRaWAN uses a roaming hub functionality, in accordance with the [LoRa Alliance LoRaWAN Roaming Hub Technical Recommendation](https://lora-alliance.org/wp-content/uploads/2022/01/TR010-1.0.0-LoRaWAN-Roaming-Hub.pdf). The roaming hub provides an endpoint for Everynet to route the traffic received from the end device. In this case, Everynet acts as a forwarding network server (fNS) to forward the traffic received from the device. It uses an HTTP RESTful API, as defined by the LoRa Alliance specification. **Note** If your device moves from its home network and enters a location where both your home network and Everynet can offer coverage, it uses first-come-first-serve policy to determine whether to connect to your LoRa gateway, or to Everynet's gateway. When visiting a public network, the hNS and serving network server (sNS) are separated. Uplink and downlink packets are then exchanged between the sNS and hNS. # How to use AWS IoT Core for LoRaWAN public network support To use Everynet's public network support, you enable certain roaming parameters when creating the service profile. In this beta release, these parameters are available when you use the AWS IoT Wireless API, or the AWS CLI. The following sections show the parameters you must enable, and how to enable public network using the AWS CLI. **Note** You can enable public network support only when creating a new service profile. You can't update an existing profile to enable public network using these parameters. **Topics** + [ ## Roaming parameters ](#lorawan-roaming-parameters) + [ ## Enable public network support for devices ](#lorawan-roaming-enable) + [ ## View coverage information ](#lorawan-roaming-coverage) ## Roaming parameters Specify the following parameters when creating a service profile for your device. Specify these parameters when adding a service profile from the [Profiles](https://console.aws.amazon.com/iot/home#/wireless/profiles) hub of the AWS IoT console, or using the AWS IoT Wireless API operation, [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateServiceProfile.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateServiceProfile.html), or the AWS CLI command, [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-service-profile.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-service-profile.html). **Note** AWS IoT Core for LoRaWAN does not support handover roaming. When creating the service profile, you can't enable the `HrAllowed` parameter that specifies whether to use handover roaming. + Roaming activation allowed (`RaAllowed`): This parameter specifies whether to enable roaming activation. Roaming activation enables an end device to activate under the coverage of a vNS. When using the roaming feature, `RaAllowed` must be set to `true`. + Passive roaming allowed (`PrAllowed`): This parameter specifies whether to enable passive roaming. When using the roaming feature, `PrAllowed` must be set to `true`. ## Enable public network support for devices To enable public LoRaWAN network support on your devices, run the following procedure. **Note** You can enable the public network capability only for OTAA devices. This feature is not supported for devices that use ABP as the activation method. 1. **Create service profile with roaming parameters** Create a service profile by enabling the roaming parameters. **Note** When you create a device profile for the device that you'll associate with this service profile, we recommend that you specify a large value for the `RxDelay1` parameter, at least greater than 2s. + **Using the AWS IoT console** Go to the [Profiles](https://console.aws.amazon.com/iot/home#/wireless/profiles) hub of the AWS IoT console and choose **Add service profile**. When creating the profile, choose **Enable public network**. + **Using the AWS IoT Wireless API** To enable roaming when creating a service profile, use the [CreateServiceProfile](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateServiceProfile.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-service-profile.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-service-profile.html) CLI command, as shown in example below. ``` aws iotwireless create-service-profile \ --region us-east-1 \ --name roamingprofile1 \ --lorawan '{"AddGwMetadata":true,"PrAllowed":true,"RaAllowed":true}' ``` Running this command returns the ARN and ID of the service profile as output. ``` { "Arn": "arn:aws:iotwireless:us-east-1:123456789012:ServiceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d", "Id": "12345678-a1b2-3c45-67d8-e90fa1b2c34d" } ``` 1. **Check roaming parameters in service profile** To check the roaming parameters that you specified, you can view the service profile in the console, or using the `get-service-profile` CLI command, as shown in example below. + **Using the AWS IoT console** Go to the [Profiles](https://console.aws.amazon.com/iot/home#/wireless/profiles) hub of the AWS IoT console and choose the profile that you created. In the **Profile configuration** tab of the details page, you'll see **RaAllowed** and **PrAllowed** set to `true`. + **Using the AWS IoT Wireless API** To view the roaming parameters that you enabled, use the [GetServiceProfile](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetServiceProfile.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-service-profile.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-service-profile.html) CLI command, as shown in example below. ``` aws iotwireless get-service-profile \ --region us-east-1 \ --id 12345678-a1b2-3c45-67d8-e90fa1b2c34d ``` Running this command returns the service profile details as output, including the values for roaming parameters, `RaAllowed` and `PrAllowed`. ``` { "Arn": "arn:aws:iotwireless:us-east-1:123456789012:ServiceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d", "Id": "12345678-a1b2-3c45-67d8-e90fa1b2c34d", "Name": "roamingprofile1" "LoRaWAN": { "UlRate": 60, "UlBucketSize": 4096, "DlRate": 60, "DlBucketSize": 4096, "AddGwMetadata": true, "DevStatusReqFreq": 24, "ReportDevStatusBattery": false, "ReportDevStatusMargin": false, "DrMin": 0, "DrMax": 15, "PrAllowed": true, "RaAllowed": true, "NwkGeoLoc": false, "TargetPer": 5, "MinGwDiversity": 1 } } ``` 1. **Attach service profile to devices** Attach the service profile that you created with the roaming parameters to your end devices. You can also create a device profile and add a destination for your wireless devices. You'll use this destination to route uplink messages that are sent from your device. For more information about creating device profiles and a destination, see [Add device profiles](lorawan-define-profiles.md#lorawan-device-profiles) and [Add destinations to AWS IoT Core for LoRaWAN](lorawan-create-destinations.md). + **Onboarding new devices** If you haven't already onboarded your devices, you specify this service profile to be used when adding your device to AWS IoT Core for LoRaWAN. The following command shows how you can use the `create-wireless-device` CLI command to add a device using the ID of the service profile that you created. For information about adding the service profile using the console, see [Add your wireless device specification to AWS IoT Core for LoRaWAN using the console](lorawan-end-devices-add.md#lorawan-end-device-spec-console). ``` aws iotwireless create-wireless-device --cli-input-json file://createdevice.json ``` The following shows the contents of the file *`createdevice.json`*. **Contents of createdevice.json** ``` { "Name": "DeviceA", "Type": LoRaWAN, "DestinationName": "RoamingDestination1", "LoRaWAN": { "DeviceProfileId": "ab0c23d3-b001-45ef-6a01-2bc3de4f5333", "ServiceProfileId": "12345678-a1b2-3c45-67d8-e90fa1b2c34d", "OtaaV1_1": { "AppKey": "3f4ca100e2fc675ea123f4eb12c4a012", "JoinEui": "b4c231a359bc2e3d", "NwkKey": "01c3f004a2d6efffe32c4eda14bcd2b4" }, "DevEui": "ac12efc654d23fc2" }, } ``` The output of running this command produces the ARN and ID of the wireless device as output. ``` { "Arn": "arn:aws:iotwireless:us-east-1:123456789012:WirelessDevice/1ffd32c8-8130-4194-96df-622f072a315f", "Id": "1ffd32c8-8130-4194-96df-622f072a315f" } ``` + **Updating existing devices** If you have already onboarded your devices, you can update your existing wireless devices to use this service profile. The following command shows how you can use the `update-wireless-device` CLI command to update a device using the ID of the service profile that you created. ``` aws iotwireless update-wireless-device \ --id "1ffd32c8-8130-4194-96df-622f072a315f" \ --service-profile-id "12345678-a1b2-3c45-67d8-e90fa1b2c34d" \ --description "Using roaming service profile A" ``` This command doesn't produce any output. You can use the `GetWirelessDevice` API or the `get-wireless-device` CLI command to get the updated information. 1. **Connect device to cloud using Everynet** As roaming has been enabled, your device must now perform a join to obtain a new `DevAddr`. If you're using OTAA, your LoRaWAN device sends a join request and the Network Server can allow the request. It can then connect to the AWS Cloud using the network coverage provided by Everynet. For instructions on how to perform the activation procedure or join for your device, see the device documentation. **Note** You can enable the roaming capability and connect to the public network only for devices that use OTAA as the activation method. ABP devices aren't supported. For instructions on how to perform the activation procedure or join for your device, see the device documentation. See [Activation modes](lorawan-manage-end-devices.md#lorawan-activation-modes). To disable the roaming capability for your devices, you can disassociate the devices from this service profile, and then associate them with another service profile that has the roaming parameters set to `false`. After switching to this service profile, your devices must perform another join so that they don't continue running on the public network. 1. **Exchange uplink and downlink messages** After your device has joined to AWS IoT Core for LoRaWAN, you can start exchanging messages between your device and the Cloud. + **View uplink messages** When you send uplink messages from your devices, AWS IoT Core for LoRaWAN delivers these messages to your AWS account using the destination that you configured earlier. These messages will be sent from your device to the Cloud over Everynet's network. You can use either view the messages using the AWS IoT rule name or use the MQTT client to subscribe to the MQTT topic that was specified when creating the destination. For more information about the rule name and other destination details that you specify, see [Add a destination using the console](lorawan-create-destinations.md#lorawan-create-destination-console). For more information about viewing uplink message and the format, see [View format of uplink messages sent from LoRaWAN devices](lorawan-uplink-metadata-format.md). + **Send downlink messages** You can queue and send downlink messages to your devices from the console, or by using the AWS IoT Wireless API command, `SendDataToWirelessDevice`, or the AWS CLI command, `send-data-to-wireless-device`. For information about queuing and sending downlink messages, see [Queue downlink messages to send to LoRaWAN devices](lorawan-downlink-queue.md). The following code shows an example of how you can send a downlink message using the `send-data-to-wireless-device` CLI command. You specify the ID of the wireless device to receive the data, the payload, whether to use the acknowledge mode, and the wireless metadata. ``` aws iotwireless send-data-to-wireless-device \ --id "1ffd32c8-8130-4194-96df-622f072a315f" \ --transmit-mode "1" \ --payload-data "SGVsbG8gVG8gRGV2c2lt" \ --wireless-metadata LoRaWAN={FPort=1} ``` The output of running this command generates a `MessageId` for the downlink message. **Note** In some cases, even if you receive the `MessageId`, packets can get dropped. For information about troubleshooting such scenarios and resolving them, see [Troubleshoot downlink message queue errors](lorawan-downlink-queue.md#lorawan-downlink-queue-troubleshoot). ``` { MessageId: "6011dd36-0043d6eb-0072-0008" } ``` ## View coverage information After you've enabled the public network, you can view the network coverage information in the AWS IoT console. Go to the [https://console.aws.amazon.com/iot/home#/wireless/network-coverage](https://console.aws.amazon.com/iot/home#/wireless/network-coverage) hub of the AWS IoT console and then search for locations to see the coverage information of your devices on the map. **Note** This feature uses the Amazon Location Service to display the coverage information of your devices on an Amazon Location map. Before using Amazon Location maps, review the Terms and Conditions for Amazon Location Service. Note that AWS may transmit your API queries to your chosen third party data provider, which may be outside of the AWS Region that you are currently using. For more information, see [AWS Service Terms](https://aws.amazon.com/service-terms/). # Perform firmware update over-the-air (FUOTA) for LoRaWAN devices and multicast groups Efficient firmware updates are crucial for maintaining the performance and security of IoT devices in the field. AWS IoT Core for LoRaWAN supports multicast firmware over-the-air (FUOTA) update feature that streamlines the process of updating firmware on multiple LoRaWAN devices simultaneously. Multicast FUOTA uses the multicast capabilities of the LoRaWAN protocol, and distributes firmware updates to groups of devices without the need for individual unicast transmissions. Using multicast FUOTA, you can significantly reduce the time and bandwidth required for firmware updates, ensuring your IoT deployments remain up-to-date and secure. You can perform firmware update over-the-air to update the device firmware of a single LoRaWAN device or a group of devices. To update the device firmware or to send a downlink payload to multiple devices, create a multicast group. Using multicast, a source can send data to a single multicast group, which is then distributed to a group of recipient devices. AWS IoT Core for LoRaWAN's support for FUOTA and multicast groups is based on the [LoRa Alliance's](https://lora-alliance.org/about-lorawan) following specifications: + LoRaWAN Remote Multicast Setup Specification v1.0.0 + LoRaWAN Fragmented Data Block Transportation Specification v1.0.0 + LoRaWAN Application Layer Clock Synchronization Specification v1.0.0 **Note** AWS IoT Core for LoRaWAN automatically performs the clock synchronization according to the LoRa Alliance specification. It uses the function `AppTimeReq` to reply the server-side time to the devices that request it using ClockSync signaling. The following topics show how to create multicast groups and perform FUOTA. **Topics** + [ # Prepare devices for multicast and FUOTA configuration ](lorawan-prepare-devices-multicast.md) + [ # Create multicast groups to send a downlink payload to multiple devices ](lorawan-multicast-groups.md) + [ # Firmware update over-the-air (FUOTA) for AWS IoT Core for LoRaWAN ](lorawan-mc-fuota-overview.md) # Prepare devices for multicast and FUOTA configuration When you add your wireless device to AWS IoT Core for LoRaWAN, you can prepare your wireless device for multicast setup and FUOTA configuration by using the console or the CLI. If you're performing this configuration for the first time, we recommend that you use the console. To manage your multicast group and add or remove a number of devices from your group, we recommend using the CLI to manage a large number of resources. ## GenAppKey and FPorts When you add your wireless device, before you can add your devices to multicast groups or perform FUOTA, configure the following parameters. Before you configure these parameters, make sure that your devices support FUOTA and multicast and your wireless device specification is either `OTAA v1.1` or `OTAAv1.0.x`. + `GenAppKey`: For devices that support the LoRaWAN version 1.0.x and to use multicast groups, the `GenAppKey` is the device-specific root key from which the session keys for your multicast group are derived. **Note** For LoRaWAN devices that use the wireless specification `OTAA v1.1`, the `AppKey` is used for the same purpose as the `GenAppKey`. To set up the parameters to initiate the data transfer, AWS IoT Core for LoRaWAN distributes session keys with the end devices. For more information about LoRaWAN versions, see [LoRaWAN version](lorawan-manage-end-devices.md#lorawan-lorawan-version). **Note** AWS IoT Core for LoRaWAN stores the `GenAppKey` information that you provide in an encrypted format. + `FPorts`: According to the LoRaWAN specifications for FUOTA and multicast groups, AWS IoT Core for LoRaWAN assigns the default values for the following fields of the `FPorts` parameter. If you have already assigned any of the following `FPort` values, then you can choose a different value that is available, from 1 to 223. + `Multicast`: 200 This `FPort` value is used for multicast groups. + `FUOTA`: 201 This `FPort` value is used for FUOTA. + `ClockSync`: 202 This `FPort` value is used for the clock synchronization. ## Device profiles for multicast and FUOTA At the start of a multicast session, a class B or class C distribution window is used to send the downlink message to the devices in your group. The devices that you add for multicast and FUOTA must support class B or class C modes of operation. Depending on the device class that your device supports, choose a device profile for your device that has either or both class B or class C modes enabled. For information about device profiles, see [Add profiles to AWS IoT Core for LoRaWAN](lorawan-define-profiles.md). ## Prepare devices for multicast and FUOTA by using the console To specify the FPorts and GenAppKey parameters for multicast setup and FUOTA by using the console: 1. Navigate to the [Devices hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/wireless/devices) and choose **Add wireless device**. 1. Choose the **Wireless device specification**. Your device must use OTAA for device activation. When you choose OTAA v1.0.x or OTAA v1.1, a **FUOTA configuration-Optional** section appears. 1. Enter the EUI (Extended Unique Identifier) parameters for your wireless device. 1. Expand the **FUOTA configuration-Optional** section and then choose **This device supports firmware updates over the air (FUOTA)**. You can now enter the **FPort** values for multicast, FUOTA, and clock sync. If you chose `OTAA v1.0.x` for the wireless device specification, enter the **GenAppKey**. 1. Add your device to AWS IoT Core for LoRaWAN by choosing your profiles and a destination for routing messages. For the device profile linked to the device, make sure you select one or both **Supports Class B** or **Supports Class C** modes. **Note** To specify the FUOTA configuration parameters, you must use the [Devices hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/wireless/devices). These parameters don't appear if you onboard your devices by using the **Intro** page of the AWS IoT console. For more information about the wireless device specification and onboarding your device, see [Add your wireless device to AWS IoT Core for LoRaWAN](lorawan-end-devices-add.md). **Note** You can specify these parameters only when you create the wireless device. You can't change or specify parameters when you update an existing device. ## Prepare devices for multicast and FUOTA by using the API To use multicast groups or to perform FUOTA, configure these parameters by using the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-wireless-device.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-wireless-device.html) CLI command. In addition to specifying the application key and FPorts parameters, make sure that the device profile that's linked to the device supports one or both class B or class C modes. You can provide an `input.json` file as input to the `create-wireless-device` command. ``` aws iotwireless create-wireless-device \ --cli-input-json file://input.json ``` where: **Contents of input.json** ``` { "Description": "My LoRaWAN wireless device" "DestinationName": "IoTWirelessDestination" "LoRaWAN": { "DeviceProfileId": "ab0c23d3-b001-45ef-6a01-2bc3de4f5333", "ServiceProfileId": "fe98dc76-cd12-001e-2d34-5550432da100", "FPorts": { "ClockSync": 202, "Fuota": 201, "Multicast": 200 }, "OtaaV1_0_x": { "AppKey": "3f4ca100e2fc675ea123f4eb12c4a012", "AppEui": "b4c231a359bc2e3d", "GenAppKey": "01c3f004a2d6efffe32c4eda14bcd2b4" }, "DevEui": "ac12efc654d23fc2" }, "Name": "SampleIoTWirelessThing" "Type": LoRaWAN } ``` For information about the CLI commands that you can use, see [AWS CLI reference](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/index.html). **Note** After you specify the values of these parameters, you can't update them by using the `UpdateWirelessDevice` API operation. Instead, you can create a new device with the values for the parameters `GenAppKey` and `FPorts`. To get information about the values specified for these parameters, you can use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessDevice.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-wireless-device.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-wireless-device.html) CLI command. ## Next steps After you've configured the parameters, you can create multicast groups and FUOTA tasks to send downlink payload or update the firmware of your LoRaWAN devices. + For information about creating multicast groups, see [Create multicast groups and add devices to the group](lorawan-create-multicast-groups.md). + For information about creating FUOTA tasks, see [Create FUOTA task and provide firmware image](lorawan-fuota-create-task.md). # Create multicast groups to send a downlink payload to multiple devices To send a downlink payload to multiple devices, create a multicast group. Using multicast, a source can send data to a single multicast address, which is then distributed to an entire group of recipient devices. Devices in a multicast group share the same multicast address, session keys, and frame counter. By using the same session keys, devices in a multicast group can decrypt the message when a downlink transmission is initiated. A multicast group only supports downlink. It doesn't confirm whether the downlink payload has been received by the devices. With AWS IoT Core for LoRaWAN's multicast groups, you can: + Filter your list of devices by using the device profile, RFRegion, or device class, and then add these devices to a multicast group. + Schedule and send one or more downlink payload messages to devices in a multicast group, within a 48-hour distribution window. + Have devices temporarily switch to Class B or class C mode at the start of your multicast session for receiving the downlink message. + Monitor your multicast group setup and the state of its devices, and also troubleshoot any issues. + Use Firmware Updates-Over-The-Air (FUOTA) to securely deploy firmware updates to devices in a multicast group. The following video describes how AWS IoT Core for LoRaWAN multicast groups can be created and walks you through the process of adding a device to the group and schedule a downlink message to the group. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/LcCR-1eKX1w/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/LcCR-1eKX1w) The following shows how to create your multicast group and schedule a downlink message. **Topics** + [ # Create multicast groups and add devices to the group ](lorawan-create-multicast-groups.md) + [ # Choose participating gateways to receive multicast downlink messages ](lorawan-multicast-choose-gateways.md) + [ # Monitor and troubleshoot your multicast groups ](lorawan-multicast-status.md) + [ # Schedule a downlink message for your multicast group ](lorawan-multicast-schedule-downlink.md) # Create multicast groups and add devices to the group You can create multicast groups by using the console or the CLI. If you're creating your multicast group for the first time, we recommend that you use the console to add your multicast group. When you want to manage your multicast group and add or remove devices from your group, you can use the CLI. After exchanging signaling with the end devices you added, AWS IoT Core for LoRaWAN establishes the shared keys with the end devices and sets up the parameters for the data transfer. ## Prerequisites Before you can create multicast groups and add devices to the group: + Prepare your devices for multicast and FUOTA setup by specifying the FUOTA configuration parameters `GenAppKey` and `FPorts`. For more information, see [Prepare devices for multicast and FUOTA configuration](lorawan-prepare-devices-multicast.md). + Check whether the devices support class B or class C modes of operation. Depending on the device class that your device supports, choose a device profile that has one or both **Supports Class B** or **Supports Class C** modes enabled. For information about device profiles, see [Add profiles to AWS IoT Core for LoRaWAN](lorawan-define-profiles.md). At the start of the multicast session, a class B or class C distribution window is used to send downlink messages to the devices in your group. ## Create multicast groups by using the console To create multicast groups by using the console, go to the [Multicast groups](https://console.aws.amazon.com/iot/home#/wireless/multicastGroups) page of the AWS IoT console and choose **Create multicast group**. 1. **Create a multicast group** To create your multicast group, specify the multicast properties and tags for your group. 1. **Specify multicast properties** To specify multicast properties, enter the following information for your multicast group. + **Name**: Enter a unique name for your multicast group. The name must contain only letters, numbers, hyphens, and underscores. It can't contain spaces. + **Description**: You can provide an optional description for your multicast group. The description length can be up to 2,048 characters. 1. **Tags for multicast group** You can optionally provide any key-value pairs as **Tags** for your multicast group. To continue creating your multicast group, choose **Next**. 1. **Add devices to a multicast group** You can add individual devices or a group of devices to your multicast group. To add devices: 1. **Specify RFRegion** Specify the **RFRegion** or frequency band for your multicast group. The **RFRegion** for your multicast group must match the **RFRegion** of devices that you add to the multicast group. For more information about the **RFRegion**, see [Consider selection of LoRa frequency bands for your gateways and device connection](lorawan-rfregion-permissions.md#lorawan-frequency-bands). 1. **Select a multicast device class** Choose whether you want devices in the multicast group to switch to a class B or class C mode at the start of the multicast session. A class B session can receive downlink messages at regular downlink slots and a class C session can receive downlink messages at anytime. 1. **Choose your devices to add to the group** Choose whether you want to add devices individually or in bulk to the multicast group. + To add devices individually, enter the wireless device ID of each device that you want to add to your group. + To add devices in bulk, you can filter the devices you want to add by device profile or tags. For device profile, you can add devices with a profile that supports class B, class C, or both device classes. 1. **(Optional) Choose participating gateways** Optionally, you can choose the gateways that you want to use for receiving the downlink message and the transmission interval between them. For more information, see [Choose participating gateways to receive multicast downlink messages](lorawan-multicast-choose-gateways.md). 1. To create your multicast group, choose **Create**. The multicast group details and the devices you added appear in the group. For information about the status of the multicast group and your devices and for troubleshooting any issues, see [Monitor and troubleshoot your multicast groups](lorawan-multicast-status.md). After creating a multicast group, you can choose **Action** to edit, delete, or add devices to the multicast group. After you've added the devices, you can schedule a session for the downlink payload to be sent to the devices in your group. ## Create multicast groups by using the API To create multicast groups and add devices to the group by using the API: 1. **Create a multicast group** To create your multicast group, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateMulticastGroup.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateMulticastGroup.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-multicast-group.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-multicast-group.html) CLI command. You can provide an `input.json` file as input to the `create-multicast-group` command. **Note** When creating a multicast group, you can optionally specify the gateways that you want to use for receiving the multicast downlink message using the `ParticipatingGateways` parameter. For more information, see [Choose participating gateways to receive multicast downlink messages](lorawan-multicast-choose-gateways.md). ``` aws iotwireless create-multicast-group \ --cli-input-json file://input.json ``` where: **Contents of input.json** ``` { "Description": "Multicast group to send downlink payload and perform FUOTA.", "LoRaWAN": { "DlClass": "ClassB", "RfRegion": "US915" }, "Name": "MC_group_FUOTA" } ``` After you create your multicast group, you can use the following API operations or CLI commands to update, delete, or get information about your multicast groups. + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateMulticastGroup](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateMulticastGroup) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-multicast-group.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-multicast-group.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateMulticastGroup](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateMulticastGroup) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-multicast-group.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-multicast-group.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListMulticastGroups](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListMulticastGroups) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-multicast-groups.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-multicast-groups.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteMulticastGroup](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteMulticastGroup) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/delete-multicast-group.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/delete-multicast-group.html) 1. **Add devices to a multicast group** You can add devices to your multicast group individually or in bulk. + To add devices in bulk to your multicast group, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartBulkAssociateWirelessDeviceWithMulticastGroup.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartBulkAssociateWirelessDeviceWithMulticastGroup.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-bulk-associate-wireless-device-with-multicast-group.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-bulk-associate-wireless-device-with-multicast-group.html) CLI command. To filter the devices you want to associate in bulk to your multicast group, provide a query string. The following shows how you can add a group of devices that has a device profile with the specified ID linked to it. ``` aws iotwireless start-bulk-associate-wireless-device-with-multicast-group \ --id "12abd34e-5f67-89c2-9293-593b1bd862e0" \ --cli-input-json file://input.json ``` where: **Contents of input.json** ``` { "QueryString":"DeviceProfileName: MyWirelessDevice AND DeviceProfileId: d6d8ef8e-7045-496d-b3f4-ebcaa1d564bf", "Tags": [ { "Key": "Multicast", "Value": "ClassB" } ] } ``` Here, `multicast-groups/d6d8ef8e-7045-496d-b3f4-ebcaa1d564bf/bulk` is the URL that's used to associate devices with the group. + To add devices individually to your multicast group, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_AssociateWirelessDeviceWithMulticastGroup.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_AssociateWirelessDeviceWithMulticastGroup.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/associate-wireless-device-with-multicast-group.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/associate-wireless-device-with-multicast-group.html) CLI. Provide the wireless device ID for each device you want to add to your group. ``` aws iotwireless associate-wireless-device-with-multicast-group \ --id "12abd34e-5f67-89c2-9293-593b1bd862e0" \ --wireless-device-id "ab0c23d3-b001-45ef-6a01-2bc3de4f5333" ``` After you create your multicast group, you can use the following API operations or CLI commands to get information about your multicast group or to disassociate devices. + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DisassociateWirelessDeviceFromMulticastGroup.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DisassociateWirelessDeviceFromMulticastGroup.html) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/disassociate-wireless-device-from-multicast-group.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/disassociate-wireless-device-from-multicast-group.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartBulkDisassociateWirelessDeviceFromMulticastGroup.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartBulkDisassociateWirelessDeviceFromMulticastGroup.html) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-bulk-disassociate-wireless-device-from-multicast-group.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-bulk-disassociate-wireless-device-from-multicast-group.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListWirelessDevices](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListWirelessDevices) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-wireless-devices.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-wireless-devices.html) **Note** The `ListWirelessDevices` API operation can be used to list wireless devices in general, and wireless devices that are associated with a multicast group or a FUOTA task. To list wireless devices associated with a multicast group, use the `ListWirelessDevices` API operation with `MulticastGroupID` as the filter. To list wireless devices associated with a FUOTA task, use the `ListWirelessDevices` API operation with `FuotaTaskID` as the filter. ## Next steps After you've created a multicast group and added devices, you can continue adding devices and monitor the status of the multicast group and your devices. If your devices have been added successfully to the group, you can configure and schedule a downlink message to be sent to the devices. Before you can send a downlink message, your devices' status must be **Multicast setup ready**. After you schedule a downlink message, the status changes to **Session attempting**. For more information, see [Schedule a downlink message for your multicast group](lorawan-multicast-schedule-downlink.md). If you want to update the firmware of the devices in the multicast group, you can perform Firmware Updates Over-The-Air (FUOTA) with AWS IoT Core for LoRaWAN. For more information, see [Firmware update over-the-air (FUOTA) for AWS IoT Core for LoRaWAN](lorawan-mc-fuota-overview.md). If your devices weren't added or if you see an error in the multicast group or device statuses, you can hover over the error to get more information and resolve it. If you still see an error, for information about how to troubleshoot and resolve the issue, see [Monitor and troubleshoot your multicast groups](lorawan-multicast-status.md). # Choose participating gateways to receive multicast downlink messages A multicast group that consists of multiple devices can have the devices associated with multiple gateways. When a downlink message is sent to the multicast group, it will be sent to all the gateways that are associated with the devices in the group. This can potentially lead to the message that the device receives getting corrupted, such as when a device is in the vicinity of two gateways and receives the same multicast downlink from both gateways at the same time. ![\[Image showing how a multicast downlink message from AWS IoT Core for LoRaWAN can get corrupted to the device.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-lorawan-multicast-gateways.png) To avoid this message corruption, you can specify the gateways that you want to use for receiving the downlink message and the transmission interval between them. To provide this information, use the following fields using the console or CLI. **Note** This feature is different from the participating gateways feature that you can use for general downlink data traffic from AWS IoT Core for LoRaWAN to your device. For more information, see [Choosing gateways to receive the LoRaWAN downlink data traffic](lorawan-gateway-participate.md). + **Gateway list** The list of gateways that you want to use for sending the multicast downlink message. Each downlink message will be sent to all the gateways in the list in the order that you provided them. If the gateway list is empty, then AWS IoT Core for LoRaWAN will use the gateways that were used for the most recent uplink message from the device. + **Transmission interval** The time duration in milliseconds for which AWS IoT Core for LoRaWAN will wait before transmitting the multicast payload to the next gateway in the list. **Note** If you are performing FUOTA for a multicast group for which you added participating gateways when creating the group, make sure that the fragment interval is less than or equal to the transmission interval for the gateways. ## Choose gateways for multicast downlink (console) In the AWS IoT console, you can choose the gateways that you want to use for receiving the multicast downlink message when creating the multicast group and adding your devices to the groups. For information about creating a group, see [Create multicast groups and add devices to the group](lorawan-create-multicast-groups.md). 1. Go to the [Multicast groups](https://console.aws.amazon.com/iot/home#/wireless/multicastGroups) page of the AWS IoT console and choose **Create multicast group**. 1. Specify a name for the multicast group, and optionally provide a description and tags for your group. 1. Choose **Next** to add devices to your multicast group. 1. Specify the RFRegion, and whether to add devices individually using their Device ID, or in bulk using their device profile. 1. Add the gateways that you want to use for receiving the downlink message using their Gateway ID, and the transmission interval. 1. Choose **Create** to create the multicast group. ## Choose gateways for multicast downlink (CLI) To specify the gateways for receiving the downlink messages, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateMulticastGroup.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateMulticastGroup.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-multicast-group.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-multicast-group.html) CLI command. ``` aws iotwireless create-multicast-group \ --name "MC_group_FUOTA" \ --cli-input-json file://input.json ``` The following shows the contents of the *`input.json`* file. **Contents of *`input.json`*** ``` { "LoRaWAN": { "DlClass": "ClassB", "ParticipatingGateways": { "GatewayList": [ "a01b2c34-d44e-567f-abcd-0123e445663a", "12345678-a1b2-3c45-67d8-e90fa1b2c34d" ], "TransmissionInterval": 1200 }, "RfRegion": "US915" } } ``` In this example, the downlink message will be sent to the gateway with ID `a01b2c34-d44e-567f-abcd-0123e445663a`, and the same message will then be sent to the gateway with ID `12345678-a1b2-3c45-67d8-e90fa1b2c34d` after 1200 ms. ## Next steps After you've chosen the gateways to use, you can add devices to the multicast group and proceed to schedule a multicast session. For more information, see [Schedule a downlink message for your multicast group](lorawan-multicast-schedule-downlink.md). If you want to update the firmware of the devices in the multicast group, you can perform Firmware Updates Over-The-Air (FUOTA) with AWS IoT Core for LoRaWAN. In this case, as the FUOTA uses this multicast group, the FUOTA message will be sent to the gateways in the list that you specified. For more information about FUOTA, see [Firmware update over-the-air (FUOTA) for AWS IoT Core for LoRaWAN](lorawan-mc-fuota-overview.md). # Monitor and troubleshoot your multicast groups After you've added devices and created your multicast group, open the AWS Management Console. Navigate to the [Multicast groups](https://console.aws.amazon.com/iot/home#/wireless/multicastGroups) page of the AWS IoT console and choose the multicast group you created to view its details. You'll see information about the multicast group, the number of devices that have been added, and device status details. You can use the status information to track progress of your multicast session and troubleshoot any errors. ## Multicast group status Your multicast group can have one of the following status messages displayed in the AWS Management Console. + **Pending** This status indicates that you've created a multicast group but it doesn't yet have a multicast session. You'll see this status message displayed when your group has been created. During this time, you can update your multicast group, and associate or disassociate devices with your group. After the status changes from **Pending**, additional devices can't be added to the group. + **Session attempting** After your devices have been added successfully to the multicast group, when your group has a scheduled multicast session, you'll see this status message displayed. During this time, you can't update or add devices to your multicast group. If you cancel your multicast session, the group status changes to **Pending**. + **In session** When it's the earliest session time for your multicast session, you'll see this status message displayed. A multicast group also continues to be in this state when it's associated with a FUOTA task that has an ongoing firmware update session. If you don't have an associated FUOTA task in session, and if the multicast session is canceled because the session time exceeded the time out or you canceled your multicast session, the group status changes to **Pending**. + **Delete waiting** If you delete your multicast group, its group status changes to **Delete waiting**. Deletions are permanent and can't be undone. This action can take time and the group status will be **Delete\$1Waiting** until the multicast group has been deleted. After your multicast group enters this state, it can't transition to one of the other states. ## Status of devices in multicast group The devices in your multicast group can have one of the following status messages displayed in the AWS Management Console. You can hover over each status message to get more information about what it indicates. + **Package attempting** After your devices have been associated with the multicast group, the device status is **Package attempting**. This status indicates that AWS IoT Core for LoRaWAN has not yet confirmed whether the device supports multicast setup and operation. + **Package unsupported** After your devices have been associated with the multicast group, AWS IoT Core for LoRaWAN checks whether your device's firmware is capable of multicast setup and operation. If your device doesn't have the supported multicast package, its status is **Package unsupported**. To resolve the error, check whether your device's firmware is capable of multicast setup and operation. + **Multicast setup attempting** If the devices associated with your multicast group are capable of multicast setup and operation, the status is **Multicast setup attempting**. This status indicates that the device hasn't completed the multicast setup yet. + **Multicast setup ready** Your device has completed the multicast setup and has been added to the multicast group. This status indicates that the devices are ready for a multicast session and a downlink message can be sent to those devices. The status also indicates when you can use FUOTA to update the firmware of the devices in the group. + **Session attempting** A multicast session has been scheduled for the devices in your multicast group. At the start of a multicast group session, the device status is **Session attempting**, and requests are sent for whether a class B or class C distribution window can be initiated for the session. If the time it takes to set up the multicast session exceeds the timeout or if you cancel the multicast session, the status changes to **Multicast setup done**. + **In session** This status indicates that a class B or class C distribution window has been initiated and your device has an ongoing multicast session. During this time, downlink messages can be sent from AWS IoT Core for LoRaWAN to devices in the multicast group. If you update your session time, it overrides the current session and the status changes to **Session attempting**. When the session time ends or if you cancel the multicast session, the status changes to **Multicast setup ready**. ## Next steps Now that you've learned the different statuses of your multicast group and the devices in your group, and how you can troubleshoot any issues such as when a device is not capable of multicast setup, you can schedule a downlink message to be sent to the devices and your multicast group will be in **In session**. For information about scheduling a downlink message, see [Schedule a downlink message for your multicast group](lorawan-multicast-schedule-downlink.md). # Schedule a downlink message for your multicast group After you've successfully added devices to your multicast group, you can start a multicast session and configure a downlink message to be sent to those devices. The downlink message must be scheduled within 48 hours and the start time for the multicast must be at least 30 minutes later than the current time. **Note** Devices in a multicast group can't acknowledge when a downlink message has been received. ## Prerequisites Before you can send a downlink message, you must have created a multicast group and successfully added devices to the group for which you want to send a downlink message. You can't add more devices after a start time has been scheduled for your multicast session. For more information, see [Create multicast groups and add devices to the group](lorawan-create-multicast-groups.md). If any of the devices weren't added successfully, the multicast group and device status will contain information to help you resolve the errors. If the errors still persist, for information about troubleshooting these errors, see [Monitor and troubleshoot your multicast groups](lorawan-multicast-status.md). ## Schedule a downlink message by using the console To send a downlink message by using the console, go to the [Multicast groups](https://console.aws.amazon.com/iot/home#/wireless/multicastGroups) page of the AWS IoT console and choose the multicast group you created. In the multicast group details page, choose **Schedule downlink message** and then choose **Schedule downlink session**. 1. **Schedule downlink message window** You can set up a time window for a downlink message to be sent to the devices in your multicast group. The downlink message must be scheduled within 48 hours. To schedule your multicast session, specify the following parameters: + **Start date** and **Start time**: The start date and time must be at least 30 minutes after and 48 hours before the current time. **Note** The time that you specify is in UTC so consider checking the time difference with your time zone when scheduling the downlink window. + **Session timeout**: The time after which you want the multicast session to timeout if no downlink message has been received. The minimum timeout allowed is 60 seconds. The maximum timeout value is 2 days for class B multicast groups and 18 hours for class C multicast groups. **Note** We recommend that you provide a timeout value that is a power-of-two (such as 64, 128, 256). If a non-power-of-two value is provided, it will automatically be rounded up to the next supported power-of-two within the allowed range. 1. **Configure your downlink message** To configure your downlink message, specify the following parameters: + **Data rate**: Choose a data rate for your downlink message. The data rate depends on RFRegion and payload size. The default data rate is 8 for the US915 region and 0 for the EU868 region. + **Frequency**: Choose a frequency for sending your downlink message. To avoid messaging conflicts, choose an available frequency depending on the RFRegion. + **FPort**: Choose an available frequency port for sending the downlink message to your devices. + **Payload**: Specify the maximum size of your payload depending on the data rate. Using the default data rate, you can have a maximum payload size of 33 bytes in the US915 RfRegion and 51 bytes in the EU868 RfRegion. Using larger data rates, you can transfer up to a maximum payload size of 242 bytes. To schedule your downlink message, choose **Schedule**. ## Schedule a downlink message by using the API To schedule a downlink message by using the API, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartMulticastGroupSession.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartMulticastGroupSession.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-multicast-group-session](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-multicast-group-session) CLI command. You can use the following API operations or CLI commands to get information about a multicast group and to delete a multicast group. + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetMulticastGroupSession.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetMulticastGroupSession.html) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-multicast-group-session](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-multicast-group-session) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteMulticastGroupSession.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteMulticastGroupSession.html) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/delete-multicast-group-session](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/delete-multicast-group-session) To send data to a multicast group after the session has been started, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToMulticastGroup.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToMulticastGroup.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/send-data-to-multicast-group](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/send-data-to-multicast-group) CLI command. ## Next steps After you've configured a downlink message to be sent to the devices, the message is sent at the start of the session. The devices in a multicast group can't confirm whether the message has been received. ### Configure additional downlink messages You can also configure additional downlink messages to be sent to the devices in your multicast group: + To configure additional downlink messages from the console: 1. Go to the [Multicast groups](https://console.aws.amazon.com/iot/home#/wireless/multicastGroups) page of the AWS IoT console and choose the multicast group you created. 1. In the multicast group details page, choose **Schedule downlink message** and then choose **Configure additional downlink message**. 1. Specify the parameters **Data rate**, **Frequency**, **FPort**, and **Payload**, similar to how you configured these parameters for your first downlink message. + To configure additional downlink messages using the API or CLI, call the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToMulticastGroup.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToMulticastGroup.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/send-data-to-multicast-group](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/send-data-to-multicast-group) CLI command for each additional downlink message. ### Update session schedule You can also update the session schedule to use a new start date and time for your multicast session. The new session schedule will override the previously scheduled session. **Note** Update your multicast session only when required. These updates can cause a group of devices to wake up for a long duration and drain the battery. + To update the session schedule from the console: 1. Go to the [Multicast groups](https://console.aws.amazon.com/iot/home#/wireless/multicastGroups) page of the AWS IoT console and choose the multicast group you created. 1. In the multicast group details page, choose **Schedule downlink message** and then choose **Update session schedule**. 1. Specify the parameters **State date**, **Start time**, and **Session timeout**, similar to how you specified these parameters for your first downlink message. + To update the session schedule from the API or CLI, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartMulticastGroupSession.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartMulticastGroupSession.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-multicast-group-session](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-multicast-group-session) CLI command. # Firmware update over-the-air (FUOTA) for AWS IoT Core for LoRaWAN Use Firmware Updates Over-The-Air (FUOTA) to deploy firmware updates to AWS IoT Core for LoRaWAN devices. Using FUOTA, you can send firmware updates to individual devices or to a group of devices. You can also send firmware updates to multiple devices by creating a multicast group. First add your devices to the multicast group, and then send your firmware update image to all those devices. We recommend that you digitally sign the firmware images so that devices receiving the images can verify that they're coming from the right source. With AWS IoT Core for LoRaWAN's FUOTA, you can: + Deploy new firmware images or delta images to a single device or a group of devices. + Verify the authenticity and integrity of new firmware after it's deployed to devices. + Monitor the progress of a deployment and debug issues in case of a failed deployment. AWS IoT Core for LoRaWAN's support for FUOTA and multicast groups is based on the [LoRa Alliance's](https://lora-alliance.org/about-lorawan) following specifications: + LoRaWAN Remote Multicast Setup Specification, TS005-1.0.0 + LoRaWAN Fragmented Data Block Transportation Specification, TS004-1.0.0 + LoRaWAN Application Layer Clock Synchronization Specification, TS003-1.0.0 **Note** AWS IoT Core for LoRaWAN automatically performs the clock synchronization according to the LoRa Alliance specification. It uses the function `AppTimeReq` to reply the server-side time to the devices that request it using ClockSync signaling. The following video describes how AWS IoT Core for LoRaWAN FUOTA tasks can be created and walks you through the process of adding devices to the task and schedule a FUOTA task. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/0Yd6PFwL-IM/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/0Yd6PFwL-IM) **Topics** + [ # FUOTA process overview ](lorawan-fuota-mc-process.md) + [ # Create FUOTA task and provide firmware image ](lorawan-fuota-create-task.md) + [ # Add devices and multicast groups and schedule FUOTA session ](lorawan-fuota-add-devices.md) + [ # Monitor and troubleshoot your FUOTA task and devices ](lorawan-fuota-status.md) # FUOTA process overview The following diagram shows how AWS IoT Core for LoRaWAN performs the FUOTA process for your end devices. If you're adding individual devices to your FUOTA session, you can skip the steps for creating and configuring your multicast group. You can add your devices directly to a FUOTA session, and AWS IoT Core for LoRaWAN will then start the firmware update process. ![\[How AWS IoT Core for LoRaWAN performs FUOTA updates for your end devices.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-lorawan-fuota-flow.png) To perform FUOTA for your devices, first create your digitally signed firmware image and configure the devices and multicast groups that you want to add to your FUOTA task. After you start a FUOTA session, your end devices collect all fragments, reconstruct the image from the fragments, report the status to AWS IoT Core for LoRaWAN, and then apply the new firmware image. The following illustrates the different steps in the FUOTA process: 1. **Create a firmware image or delta image with a digital signature** For AWS IoT Core for LoRaWAN to perform FUOTA for your LoRaWAN devices, we recommend that you digitally sign the firmware image or the delta image when sending firmware updates over the air. The devices that receive the images can then verify that it's coming from the right source. Your firmware image must not be larger than 1 megabyte in size. The larger your firmware size, the longer it can take for your update process to complete. For faster data transfer or if your new image is larger than 1 Megabyte, use a delta image, which is the part of your new image that's the delta between your new firmware image and the previous image. **Note** AWS IoT Core for LoRaWAN doesn't provide the digital signature generation tool and the firmware version management system. You can use any third-party tool to generate the digital signature for your firmware image. We recommend that you use a digital signature tool such as the one embedded in the [ARM Mbed GitHub repository](https://github.com/armmbed/mbed-os-example-lorawan-fuota), which also includes tools for generating the delta image and for devices to use that image. 1. **Identify and configure the devices for FUOTA** After you identify the devices for FUOTA, send firmware updates to individual or multiple devices. + To send your firmware updates to multiple devices, create a multicast group, and configure the multicast group with end devices. For more information, see [Create multicast groups to send a downlink payload to multiple devices](lorawan-multicast-groups.md). + To send firmware updates to individual devices, add those devices to your FUOTA session and then perform the firmware update. 1. **Schedule a distribution window and set up fragmentation session** If you created a multicast group, you can specify the class B or class C distribution window to determine when the devices can receive the fragments from AWS IoT Core for LoRaWAN. Your devices might be operating in class A before they switch to class B or class C mode. You must also specify the start time of the session. Class B or class C devices wake up at the specified distribution window and start receiving the downlink packets. Devices operating in class C mode can consume more power than class B devices. For more information, see [Device classes](lorawan-manage-end-devices.md#lorawan-device-classes). 1. **End devices report status to AWS IoT Core for LoRaWAN and update firmware image** After you set up a fragmentation session, your end devices and AWS IoT Core for LoRaWAN perform the following steps to update the firmware of your devices. 1. Because LoRaWAN devices have a low data rate, to start the FUOTA process, AWS IoT Core for LoRaWAN sets up a fragmentation session to fragment the firmware image. Then it sends these fragments to the end devices. 1. After AWS IoT Core for LoRaWAN sends the image fragments, your LoRaWAN end devices perform the following tasks. 1. Collect the fragments and then reconstruct the binary image from these fragments. 1. Check the digital signature of the reconstructed image to authenticate the image and verify that it's coming from the right source. 1. Compare the firmware version from AWS IoT Core for LoRaWAN to the current version. 1. Report the status of the fragmented images that were transferred to AWS IoT Core for LoRaWAN, and then apply the new firmware image. **Note** In some cases, the end devices report the status of the fragmented images that were transferred to AWS IoT Core for LoRaWAN before checking the digital signature of the firmware image. Now that you've learned the FUOTA process, you can create your FUOTA task and add devices to the task for updating their firmware. For more information, see [Create FUOTA task and provide firmware image](lorawan-fuota-create-task.md). # Create FUOTA task and provide firmware image To update the firmware of your LoRaWAN devices, first create a FUOTA task and provide the digitally signed firmware image you want to use for the update. You can then add your devices and multicast groups to the task and schedule a FUOTA session. When the session starts, AWS IoT Core for LoRaWAN sets up a fragmentation session and your end devices collect the fragments, reconstruct the image, and apply the new firmware. For information about the FUOTA process, see [FUOTA process overview](lorawan-fuota-mc-process.md). The following shows how you can create a FUOTA task and upload the firmware image or delta image that you'll store in an S3 bucket. ## Prerequisites Before you can perform FUOTA, the firmware image must be digitally signed so that your end devices can verify the authenticity of the image when applying the image. You can use any third-party tool to generate the digital signature for your firmware image. We recommend that you use a digital signature tool such as the one embedded in the [ARM Mbed GitHub repository](https://github.com/armmbed/mbed-os-example-lorawan-fuota), which also includes tools for generating the delta image and for devices to use that image. ## Create FUOTA task and upload firmware image by using the console To create a FUOTA task and upload your firmware image by using the console, go to the [FUOTA tasks](https://console.aws.amazon.com/iot/home#/wireless/fuotaTasks) tab of the console and then choose **Create FUOTA task**. 1. **Create FUOTA task** To create your FUOTA task, specify the task properties and tags. 1. **Specify FUOTA task properties** To specify FUOTA task properties, enter the following information for your FUOTA task. + **Name**: Enter a unique name for your FUOTA task. The name must contain only letters, numbers, hyphens, and underscores. + **Description**: You can provide an optional description for your multicast group. The description field can be up to 2,048 characters. + **RFRegion**: Set the frequency band for your FUOTA task. The frequency band must match the one you used to provision your wireless devices or multicast groups. 1. **Tags for FUOTA task** You can optionally provide any key-value pairs as **Tags** for your FUOTA task. To continue creating your task, choose **Next**. 1. **Upload firmware image** Choose the firmware image file that you want to use to update the firmware of the devices you add to the FUOTA task. The firmware image file is stored in an S3 bucket. You can provide AWS IoT Core for LoRaWAN the permissions to access the firmware image on your behalf. We recommend that you digitally sign the firmware images so that its authenticity is verified when the firmware update is performed. 1. **Choose firmware image file** You can either upload a new firmware image file to an S3 bucket or choose an existing image that has already been uploaded to an S3 bucket. **Note** The firmware image file must not be larger than 1 megabyte in size. The larger your firmware size, the longer it can take for your update process to complete. + To use an existing image, choose **Select an existing firmware image**, choose **Browse S3**, and then choose the firmware image file you want to use. AWS IoT Core for LoRaWAN populates the S3 URL, which is the path to your firmware image file in the S3 bucket. The format of the path is `s3://bucket_name/file_name`. To view the file in the [Amazon Simple Storage Service](https://console.aws.amazon.com/s3/) console, choose **View**. + To upload a new firmware image. 1. Choose **Upload a new firmware image** and upload your firmware image. The image file must not be larger than 1 megabyte. 1. To create an S3 bucket and enter a **Bucket name** for storing your firmware image file, choose **Create S3 bucket**. 1. **Advanced transmission parameters - Optional** You can optionally specify advanced transmission parameters for your FUOTA transfer, which includes the following information. + **Fragment size (bytes)** The size of each fragment in bytes that is sent to the device, which also determines the number of fragments that will be sent. The data rate for the FUOTA transfer is determined based on the Fragment size by FUOTA. **Note** This parameter is only supported for multicast groups. + **Fragment interval (ms)** The time interval in milliseconds between each fragment that is sent from the cloud to your device, rounded to the nearest second. **Note** This interval only determines the timing for when the Cloud sends the fragments to yor device. There can be a delay for when your device will receive these fragments. This delay depends on the class of device that you use, and the communication delay with the cloud. If you are performing FUOTA for a multicast group and added participating gateways when creating the group, make sure that the fragment interval is less than or equal to the transmission interval for the gateways. + **Redundancy percent (ms)** The percentage of the added fragments that are redundant. For example, if the size of the firmware image file is 100 bytes and the fragment size is 10 bytes, with RedundancyPercent set to 50(%), the final number of encoded fragments is (100 / 10) \$1 (100 / 10 \$1 50%) = 15. + **Descriptor** The descriptor is the metadata about the file that is transferred to the device using FUOTA, such as the software version. It is a binary field encoded in base64. The descriptor is a freely-allocated four-byte field that takes a string input. It is sent to the device in FUOTA setup messages. For example, if the file transported is a firmware patch image, this field can be used to encode the version of the firmware being transported. This ensures compatibility verification when the firmware image is verified by the end device. If you specify a wrong descriptor field, it can result in the FUOTA session to fail. For information about this error, see [Status of devices in a FUOTA task](lorawan-fuota-status.md#lorawan-fuota-device-status). 1. **Permissions to access the bucket** You can either create a new service role or choose an existing role to allow AWS IoT Core for LoRaWAN to access the firmware image file in the S3 bucket on your behalf. Choose **Next**. To create a new role, you can enter a role name or leave it blank for a random name to be generated automatically. To view the policy permissions that grant access to the S3 bucket, choose **View policy permissions**. For more information about using an S3 bucket to store your image and granting AWS IoT Core for LoRaWAN permissions to access it, see [Upload the firmware file to an Amazon S3 bucket and add an IAM role](lorawan-upload-firmware-s3bucket.md). 1. **Review and create** To create your FUOTA task, review the FUOTA task and configuration details that you specified and the choose **Create task**. ## Create FUOTA task and upload firmware image by using the API To create a FUOTA task and specify your firmware image file by using the API, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateFuotaTask.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateFuotaTask.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-fuota-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-fuota-task.html) CLI command. You can provide an `input.json` file as input to the `create-fuota-task` command. When you use the API or CLI: + You must have already uploaded the firmware image file to an S3 bucket, which you'll then provide as input to the API. + You also specify the IAM role that gives AWS IoT Core for LoRaWAN access to the firmware image in the S3 bucket. + (Optional) You can also specify optional, advanced transmission parameters such as the fragment size in bytes, the interval between the fragments in milliseconds, the redundancy percentage, and the descriptor that can be used to provide metadata about the file that is being transferred. ``` aws iotwireless create-fuota-task \ --cli-input-json file://input.json ``` where: **Contents of input.json** ``` { "Description": "FUOTA task to update firmware of devices in multicast group.", "FirmwareUpdateImage": "S3:/firmware_bucket/firmware_image "FirmwareUpdateRole": "arn:aws:iam::123456789012:role/service-role/ACF1zBEI" "LoRaWAN": { "RfRegion": "US915" }, "Name": "FUOTA_Task_MC" } ``` After you create your FUOTA task, you can use the following API operations or CLI commands to update, delete, or get information about your FUOTA task. + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateFuotaTask](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateFuotaTask) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-fuota-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-fuota-task.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetFuotaTask](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetFuotaTask) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-fuota-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-fuota-task.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListFuotaTasks](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListFuotaTasks) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-fuota-tasks.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-fuota-tasks.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteFuotaTask](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteFuotaTask) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/delete-fuota-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/delete-fuota-task.html) ## Next steps Now that you've created a FUOTA task and provided the firmware image, you can add devices to the task for updating their firmware. You can either add individual devices or multicast groups to the task. For more information, see [Add devices and multicast groups and schedule FUOTA session](lorawan-fuota-add-devices.md). # Add devices and multicast groups and schedule FUOTA session After you've created a FUOTA task, you can add devices to your task for which you want to update the firmware. After your devices have been added successfully to the FUOTA task, you can schedule a FUOTA session to update the device firmware. + If you have only a small number of devices, you can add those devices directly to your FUOTA task. + If you have a large number of devices that you want to update firmware for, you can add these devices to your multicast groups, and then add the multicast groups to your FUOTA task. For information about creating and using multicast groups, see [Create multicast groups to send a downlink payload to multiple devices](lorawan-multicast-groups.md). **Note** You can add either individual devices or multicast groups to the FUOTA task. You can't add both devices and multicast groups to the task. After you've added your devices or multicast groups, you can start a firmware update session. AWS IoT Core for LoRaWAN collects the firmware image, fragments the images, and then stores the fragments in an encrypted format. Your end devices collect the fragments and apply the new firmware image. The time that it takes for the firmware update depends on the image size and how the images were fragmented. After the firmware update is complete, the encrypted fragments of the firmware image stored by AWS IoT Core for LoRaWAN is deleted. You can still find the firmware image in the S3 bucket. **Note** If you use the AWS CLI to start a FUOTA session, you can configure the downlink frequency and the `PingSlotPeriod` for Class B devices. First, you must run the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartMulticastGroupSession.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartMulticastGroupSession.html) API command with the desired values for these parameters. Then, when you run the `StartFuotaTask` API, it will use the appropriate values once the multicast session has started. For more information, see [(Optional) Configure downlink frequency of multicast group before starting FUOTA session](#lorawan-fuota-devices-api-downlinkfreq). ## Prerequisites Before you can add devices or multicast groups to your FUOTA task, do the following. + You must have already created the FUOTA task and provided your firmware image. For more information, see [Create FUOTA task and provide firmware image](lorawan-fuota-create-task.md). + Provision the wireless devices that you want to update the device firmware for. For more information about onboarding your device, see [Onboard your devices to AWS IoT Core for LoRaWAN](lorawan-onboard-end-devices.md). + To update the firmware of multiple devices, you can add them to a multicast group. For more information, see [Create multicast groups to send a downlink payload to multiple devices](lorawan-multicast-groups.md). + When you onboard the devices to AWS IoT Core for LoRaWAN, specify the FUOTA configuration parameter `FPorts`. If you're using a LoRaWAN v1.0.x device, you must also specify the `GenAppKey`. For more information about the FUOTA configuration parameters, see [Prepare devices for multicast and FUOTA configuration](lorawan-prepare-devices-multicast.md). ## Add devices to a FUOTA task and schedule a FUOTA session by using the console To add devices or multicast groups and schedule a FUOTA session by using the console, go to the [FUOTA tasks](https://console.aws.amazon.com/iot/home#/wireless/fuotaTasks) tab of the console. Then, choose the FUOTA task that you want to add devices to and perform the firmware update. **Add devices and multicast groups** 1. You can add either individual devices or multicast groups to your FUOTA task. However, you can't add both individual devices and multicast groups to the same FUOTA task. To add devices using the by console, do the following. 1. In the **FUOTA task details**, choose **Add device**. 1. Choose the frequency band or **RFRegion** for the devices you add to the task. This value must match the **RFRegion** that you chose for the FUOTA task. 1. Choose whether you want to add individual devices or multicast groups to the task. + To add individual devices, choose **Add individual devices** and enter the device ID of each device that you want to add to your FUOTA task. + To add multicast groups, choose **Add multicast groups** and add your multicast groups to the task. You can filter the multicast groups you want to add to the task by using the device profile or tags. When you filter by device profile, you can choose multicast groups that with devices that have a profile with **Supports Class B** or **Supports Class C** enabled. 1. **Schedule FUOTA session** After your devices or multicast groups have been added successfully, you can schedule a FUOTA session. To schedule a session, do the following. 1. Choose the FUOTA task for which you want to update the device firmware and then choose **Schedule FUOTA session**. 1. Specify a **Start date** and **Start time** for your FUOTA session. Make sure that the start time is 30 minutes or later from the current time. ## Add devices to a FUOTA task and schedule a FUOTA session by using the API You can use the AWS IoT Wireless API or the CLI to add your wireless devices or multicast groups to your FUOTA task. You can then schedule a FUOTA session. **Topics** + [ ### (Optional) Configure downlink frequency of multicast group before starting FUOTA session ](#lorawan-fuota-devices-api-downlinkfreq) + [ ### Add devices and multicast groups to FUOTA task ](#lorawan-fuota-devices-api-adddevices) + [ ### Schedule FUOTA session ](#lorawan-fuota-devices-api-schedule) ### (Optional) Configure downlink frequency of multicast group before starting FUOTA session By default, when you start a FUOTA session, it will automatically start a multicast session. If you haven't already started a multicast session, the FUOTA session will use the default values for the downlink frequency and the `PingSlotPeriod` parameter for class B devices. To configure the downlink frequency and `PingSlotPeriod` parameter, you can start a multicast session by specifying the values that you want to use for these parameters. To start a multicast session, you can use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartMulticastGroupSession.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartMulticastGroupSession.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-multicast-group-session.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-multicast-group-session.html) CLI command. For information about using this API, see [Schedule a downlink message by using the API](lorawan-multicast-schedule-downlink.md#lorawan-multicast-downlink-api). After you have started the multicast session, when you start a FUOTA task, the task will automatically derive the downlink frequency and the `PingSlotPeriod` parameter values that you specified when using the API. In addition: + The data rate for the FUOTA transfer is determined based on the fragment size by FUOTA. + The session timeout for the multicast group is calculated when starting the FUOTA task. If a multicast session has already started, then the session is restarted with a new timeout. The session timeout for the FUOTA task is calculated based on the data rate and the number of fragments to be sent. You can start the multicast group session with any session time out. If this timeout is used for the FUOTA task, the session timeout will be automatically updated. For information about starting a FUOTA task, see [Schedule FUOTA session](#lorawan-fuota-devices-api-schedule). ### Add devices and multicast groups to FUOTA task You can associate either wireless devices or multicast groups with your FUOTA task. + To associate individual devices to your FUOTA task, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_AssociateWirelessDeviceWithFuotaTask.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_AssociateWirelessDeviceWithFuotaTask.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/associate-wireless-device-with-fuota-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/associate-wireless-device-with-fuota-task.html) CLI command, and provide the `WirelessDeviceID` as input. ``` aws iotwireless associate-wireless-device-with-fuota-task \ --id "01a23cde-5678-4a5b-ab1d-33456808ecb2" --wireless-device-id "ab0c23d3-b001-45ef-6a01-2bc3de4f5333" ``` + To associate multicast groups to your FUOTA task, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_AssociateMulticastGroupWithFuotaTask.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_AssociateMulticastGroupWithFuotaTask.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/associate-multicast-group-with-fuota-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/associate-multicast-group-with-fuota-task.html) CLI command, and provide the `MulticastGroupID` as input. ``` aws iotwireless associate-multicast-group-with-FUOTA-task \ --id "01a23cde-5678-4a5b-ab1d-33456808ecb2" --multicast-group-id "ab0c23d3-b001-45ef-6a01-2bc3de4f5333" ``` After you've associated your wireless devices or multicast group to your FUOTA task, use the following API operations or CLI commands to list your devices or multicast groups or to disassociate them from your task. + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DisassociateWirelessDeviceFromFuotaTask.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DisassociateWirelessDeviceFromFuotaTask.html) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/disassociate-wireless-device-from-fuota-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/disassociate-wireless-device-from-fuota-task.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DisassociateMulticastGroupFromFuotaTask.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DisassociateMulticastGroupFromFuotaTask.html) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/disassociate-multicast-group-from-fuota-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/disassociate-multicast-group-from-fuota-task.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListWirelessDevices.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListWirelessDevices.html) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/delete-multicast-group.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/delete-multicast-group.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListMulticastGroups.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListMulticastGroups.html) or [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-multicast-groups.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-multicast-groups.html) **Note** The API: `ListWirelessDevices` can list wireless devices in general, and devices associated with a multicast group, when `MulticastGroupID` is used as the filter. The API lists wireless devices associated with a FUOTA task when `FuotaTaskID` is used as the filter. `ListMulticastGroups` can list multicast groups in general and multicast groups associated with a FUOTA task when `FuotaTaskID` is used as the filter. ### Schedule FUOTA session After your devices or multicast groups have been successfully added to the FUOTA task, you can start a FUOTA session to update the device firmware. The start time must be 30 minutes or later from the current time. To schedule a FUOTA session by using the API or CLI, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartFuotaTask.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartFuotaTask.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-fuota-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-fuota-task.html) CLI command. ``` aws iotwireless start-fuota-task --id "01a23cde-5678-4a5b-ab1d-33456808ecb2" ``` After you've started a FUOTA session, You can no longer add devices or multicast groups to the task. You can get information about the status of your FUOTA session by using the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GettFuotaTask.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GettFuotaTask.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-fuota-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-fuota-task.html) CLI command. # Monitor and troubleshoot your FUOTA task and devices After you have provisioned the wireless devices and created any multicast groups that you might want to use, you can start a FUOTA session by performing the following steps. ## FUOTA task status Your FUOTA task can have one of the following status messages displayed in the AWS Management Console. + **Pending** This status indicates that you've created a FUOTA task, but it doesn't yet have a firmware update session. You'll see this status message displayed when your task has been created. During this time, you can update your FUOTA task, and associate or disassociate devices or multicast groups with your task. After the status changes from **Pending**, additional devices can't be added to the task. + **FUOTA session waiting** After your devices have been added successfully to the FUOTA task, when your task has a scheduled firmware update session, you'll see this status message displayed. During this time, you can't update or add devices to your FUOTA session. If you cancel your FUOTA session, the group status changes to **Pending**. + **In FUOTA session** When your FUOTA session begins, you'll see this status message displayed. The fragmentation session starts and your end devices collect the fragments, reconstruct the firmware image, compare the new firmware version with the original version, and apply the new image. + **FUOTA done** After your end devices report to AWS IoT Core for LoRaWAN that the new firmware image has been applied, or when the session times out, the FUOTA session is marked as done, and you'll see this status displayed. You'll also see this status displayed in any of the following cases so be sure to check whether the firmware update was applied correctly to the devices. + When the FUOTA task status was **FUOTA session waiting**, and there's an S3 bucket error, such as the link to the image file in the S3 bucket is incorrect or AWS IoT Core for LoRaWAN doesn't have sufficient permissions to access the file in the bucket. + When the FUOTA task status was **FUOTA session waiting**, and there's a request to start a FUOTA session, but a response isn't received from the devices or multicast groups in your FUOTA task. + When the FUOTA task status was **In FUOTA session**, and the devices or multicast groups haven't sent any fragments for a certain time period, which results in the session to timeout. + **Delete waiting** If you delete your FUOTA task that's in any of the other states, you'll see this status displayed. A deletion action is permanent and can't be undone. This action can take time and the task status will be **Delete waiting** until the FUOTA task has been deleted. After your FUOTA task enters this state, it can't transition to one of the other states. ## Status of devices in a FUOTA task The devices in your FUOTA task can have one of the following status messages displayed in the AWS Management Console. You can hover over each status message to get more information about what it indicates. + **Initial** When it's the start time of your FUOTA session, AWS IoT Core for LoRaWAN checks whether your device has the supported package for the firmware update. If your device has the supported package, the FUOTA session for the device starts. The firmware image is fragmented and the fragments are sent to your device. When you see this status displayed, it indicates that the FUOTA session for the device hasn't started yet. + **Package unsupported** If the device doesn't have the supported FUOTA package, you'll see this status displayed. If the firmware update package isn't supported, the FUOTA session for your device can't start. To resolve this error, check whether your device's firmware can receive firmware updates using FUOTA. + **Fragmentation algorithm unsupported** At the start of your FUOTA session, AWS IoT Core for LoRaWAN sets up a fragmentation session for your device. If you see this status displayed, it means that the type of fragmentation algorithm used can't be applied for your device's firmware update. The error occurs because your device doesn't have the supported FUOTA package. To resolve this error, check whether your device's firmware can receive firmware updates using FUOTA. + **Not enough memory** After AWS IoT Core for LoRaWAN sends the image fragments, your end devices collect the image fragments and reconstruct the binary image from these fragments. This status is displayed when your device doesn't have enough memory to assemble the incoming fragments of the firmware image, which can result in your firmware update session ending prematurely. To resolve the error, check whether your device's hardware can receive this update. If your device can't receive this update, use a delta image to update the firmware. + **Fragmentation index unsupported** The fragmentation index identifies one of the four simultaneously possible fragmentation sessions. If your device doesn't support the indicated fragmentation index value, this status is displayed . To resolve this error, do one or more of the following. + Start a new FUOTA task for the device. + If the error persists, switch from unicast to multicast mode. + If the error still isn't resolved, check your device firmware. + **Memory error** This status indicates that your device has experienced a memory error when receiving the incoming fragments from AWS IoT Core for LoRaWAN. If this error occurs, your device might not be capable of receiving this update. To resolve the error, check whether your device's hardware can receive this update. If needed, use a delta image to update the device firmware. + **Wrong descriptor** Your device doesn't support the indicated descriptor. The descriptor is a field that describes the file that will be transported during the fragmentation session. If you see this error, contact [AWS Support Center](https://console.aws.amazon.com/support/home#/). + **Session count replay** This status indicates that your device has previously used this session count. To resolve the error, start a new FUOTA task for the device. + **Missing fragments** As your device collects the image fragments from AWS IoT Core for LoRaWAN, it reconstructs the new firmware image from the independent, coded fragments. If your device hasn't received all the fragments, the new image can't be reconstructed, and you'll see this status. To resolve the error, start a new FUOTA task for the device. + **MIC error** When your device reconstructs the new firmware image from the collected fragments, it performs a MIC (Message Integrity Check) to verify the authenticity of your image and whether it's coming from the right source. If your device detects a mismatch in the MIC after reassembling the fragments, this status is displayed. To resolve the error, start a new FUOTA task for the device. + **Device exists in conflict FUOTA task** If a device has already used in another conflict FUOTA task, then it will generate an error when retrying the new FUOTA task. For example, if a device is part of a multicast group, and it has already been used with another FUOTA task as part of a multicast group, the device will exist in this conflict status as it retries to run the new FUOTA task. + **Successful** The FUOTA session for your device was successful. **Note** While this status message indicates that the devices have reconstructed the image from the fragments and verified it, the device firmware might not have been updated when the device reports the status to AWS IoT Core for LoRaWAN. Check whether your device firmware has been updated. ## Next steps You've learned about the different statuses of the FUOTA task and its devices and how you can troubleshoot any issues. For more information about each of these statuses, see the [LoRaWAN Fragmented Data Block Transportation Specification, TS004-1.0.0](https://lora-alliance.org/wp-content/uploads/2020/11/fragmented_data_block_transport_v1.0.0.pdf). # Monitoring of LoRaWAN resources using network analyzer Network analyzer uses a default WebSocket connection to receive real-time trace message logs for your wireless connectivity resources. By using network analyzer, you can add the resources you want to monitor, activate a trace messaging session, and start receiving trace messages in real time. To monitor your resources, you can also use Amazon CloudWatch. To use CloudWatch, you set up an IAM role to configure logging and then wait for the log entries to be displayed in the console. Network analyzer significantly reduces the time that it takes to set up a connection and start receiving trace messages, providing you with just-in-time log information for your fleet of resources. For information about monitoring by using CloudWatch, see [Monitoring your AWS IoT Wireless resources using Amazon CloudWatch Logs](monitoring-cloudwatch.md). By reducing your setup time and using the information from the trace messages, you can monitor your resources more effectively, get meaningful insights, and troubleshoot errors. You can monitor both LoRaWAN devices and LoRaWAN gateways. For example, you can quickly identify a join error when onboarding one of your LoRaWAN devices. To debug the error, use the information in the provided trace message log. **How to use network analyzer** To monitor your resource fleet and start receiving trace messages, perform the following steps 1. **Create network analyzer configuration and add resources** Before you can activate trace messaging, create a network analyzer configuration and add resources to your configuration. First, specify the configuration settings, which include log levels and wireless device frame information. Then, add the wireless resources you want to monitor by using the wireless gateway and wireless device identifiers. 1. **Stream trace messages with WebSockets** You can generate a presigned request URL using the credentials for your IAM role to stream network analyzer trace messages by using the WebSocket protocol. 1. **Activate trace messaging session and monitor trace messages** To start receiving trace messages, activate your trace messaging session. To avoid incurring additional costs, you can either deactivate or close your network analyzer trace messaging session. The following video describes how AWS IoT Core for LoRaWAN network analyzer works and walks you through the process of adding resources and tracing join activities using network analyzer. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/Qk9pkhL8xjc/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/Qk9pkhL8xjc) The following topics show how to create your configuration, add resources, and activate your trace messaging session. **Topics** + [ # Add necessary IAM role for network analyzer ](network-analyzer-iam.md) + [ # Create network analyzer configuration and add resources ](network-analyzer-create-resources.md) + [ # Stream network analyzer trace messages with WebSockets ](network-analyzer-api.md) + [ # View and monitor trace message logs in real time ](network-analyzer-logs.md) + [ # Debug and troubleshoot your multicast groups and FUOTA tasks using network analyzer ](lorawan-network-analyzer-fuota.md) # Add necessary IAM role for network analyzer When you use network analyzer, you must grant a user permission to use the API operations [UpdateNetworkAnalyzerConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateNetworkAnalyzerConfiguration.html) and [GetNetworkAnalyzerConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetNetworkAnalyzerConfiguration.html) to access network analyzer resources. The following shows the IAM policies that you use to grant permissions. ## IAM policies for network analyzer Use either of the following: + **Full access wireless policy** Grant AWS IoT Core for LoRaWAN the full access policy by attaching the policy **AWSIoTWirelessFullAccess** to your role. For more information, see [`AWSIoTWirelessFullAccess` policy summary](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSIoTWirelessFullAccess$serviceLevelSummary). + **Scoped IAM policy for Get and Update API** Create the following IAM policy by going to the [Create policy](https://console.aws.amazon.com/iam/home#/policies$new?step=edit) page of the IAM console, and on the **Visual editor** tab: 1. Choose **IoTWireless** for **Service**. 1. Under **Access level**, expand **Read** and choose **GetNetworkAnalyzerConfiguration**, and then expand **Write** and choose **UpdateNetworkAnalyzerConfiguration**. 1. Choose **Next:Tags**, and enter a **Name** for the policy, such as **IoTWirelessNetworkAnalyzerPolicy**. Choose **Create policy**. The following shows the policy **IoTWirelessNetworkAnalyzerPolicy** that you created. For more information about creating a policy, see [Create IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create). **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "iotwireless:GetNetworkAnalyzerConfiguration", "iotwireless:UpdateNetworkAnalyzerConfiguration" ], "Resource": "*" } ] } ``` **Scoped policy to access specific resources** To configure more fine-grained access control, you must add the wireless gateways and devices to the **Resource** field. The following policy uses the wildcard ARN to grant access to all gateways and devices. You can control access to specific gateways and devices by using the `WirelessGatewayId` and `WirelessDeviceId`. **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "iotwireless:GetNetworkAnalyzerConfiguration", "iotwireless:UpdateNetworkAnalyzerConfiguration" ], "Resource": [ "arn:aws:iotwireless:*:111122223333:WirelessDevice/*", "arn:aws:iotwireless:*:111122223333:WirelessGateway/*", "arn:aws:iotwireless:*:111122223333:NetworkAnalyzerConfiguration/*" ] } ] } ``` To grant a user permission to use network analyzer but not to use any wireless gateways or devices, use the following policy. Unless specified, permissions to use the resources are implicitly denied. **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "iotwireless:GetNetworkAnalyzerConfiguration", "iotwireless:UpdateNetworkAnalyzerConfiguration" ], "Resource": [ "arn:aws:iotwireless:*:111122223333:NetworkAnalyzerConfiguration/*" ] } ] } ``` ## Next steps Now that you've created the policy, you can add resources to your network analyzer configuration and receive trace messaging information for those resources. For more information, see [Create network analyzer configuration and add resources](network-analyzer-create-resources.md). # Create network analyzer configuration and add resources Before you can stream trace messages, create a network analyzer configuration and add the resources you want to monitor to this configuration. A LoRaWAN network analyzer configuration is a set of settings and rules that define how network analyzer should capture and analyze traffic in a LoRaWAN network. It specifies the types of information and messages that should be included in the network trace, and any filtering or processing rules that should be applied. a LoRaWAN network analyzer configuration providesvisibility into the communication between LoRaWAN devices and the network server. This enables troubleshooting, performance monitoring, and security analysis of the LoRaWAN network. When you create a configuration, you can: + Specify a configuration name and optional description. + Customize the configuration settings such as frame info and level of detail for your log messages. + Add the resources that you want to monitor. The resources can be wireless devices or wireless gateways, or both. The configuration settings that you specify will determine the trace messaging information that you'll receive for resources you add to the configuration. You may also want to create multiple configurations depending on your monitoring use case. The following shows how to create a configuration and add resources. **Topics** + [ # Create a network analyzer configuration ](network-analyzer-create.md) + [ # Add resources and update the network analyzer configuration ](network-analyzer-resources.md) # Create a network analyzer configuration Before you can monitor your wireless gateways or wireless devices, you must create a network analyzer configuration. When creating the configuration, you only need to specify a configuration name. You can customize your configuration settings and add the resources that you want to monitor to your configuration even after it's created. The configuration settings determine the trace messaging information that you'll receive for those resources. Depending on the resources you want to monitor and the level of information you want to receive for them, you may want to create multiple configurations. For example, you can create a configuration that displays only error information for a set of gateways in your AWS account. You can also create a configuration that displays all information about a wireless device that you want to monitor. The following sections show the various configuration settings and how to create your configuration. ## Configuration settings When creating or updating your network analyzer configuration, you can also customize the following parameters to filter the log stream information. + **Frame info** This setting is the frame info for your wireless device resources for trace messages. The frame info can be used to debug the communication between your network server and the end devices. It is enabled by default. + **Log levels** You can view Info or Error logs, or you can turn off logging. + **Info** Logs with a log level of **Info** are more verbose and contain both error log streams and informational log streams. The informational logs can be used to view changes to the state of a device or gateway. **Note** Collecting more verbose log streams can incur additional costs. For more information about pricing, see [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/). + **Error** Logs with a log level of **Error** are less verbose and display only error information. You can use these logs when an application has an error, such as a device connection error. By using the information from the log stream, you can identify and troubleshoot errors for resources in your fleet. ## Create a configuration using the console You can create a network analyzer configuration and customize the optional parameters using the AWS IoT console or the AWS IoT Wireless API. You can also create multiple configurations and later delete any configurations that you're no longer using. **Create a network analyzer configuration** 1. Open the [Network Analyzer hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/wireless/networkAnalyzer) and choose **Create configuration**. 1. Specify the configuration settings. + **Name, description, and tags** Specify a unique **Configuration name** that only contains letters, numbers, hyphens, or underscores. Use the optional **Description** field to provide information about the configuration, and the **Tags** field to add key-value pairs of metadata about the configuration. For more information about naming and describing your resources, see [Describing your AWS IoT Wireless resources](getting-started.md#iotwireless-describe-resources). + **Configuration settings** Choose whether to disable frame info, and use **Select log levels** to choose the log levels that you want to use for your trace message logs. Choose **Next**. 1. Add resources to your configuration. You can either add your resources now or choose **Create** and then add your resources later. To add resources later, choose **Create**. In the **Network Analyzer hub page**, you'll see the configuration that you created along with its settings. To view the details of the new configuration, choose the configuration name. **Delete your network analyzer configuration** You can create multiple network analyzer configurations depending on the resources you want to monitor and the level of trace messaging information that you want to receive for them. **To remove configurations from the console** 1. Go to the [Network Analyzer hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/wireless/networkAnalyzer) and choose the configuration that you want to remove. 1. Choose **Actions**, and then choose **Delete**. ## Create a configuration using the API To create a network analyzer configuration using the API, use the [ CreateNetworkAnalyzerConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateNetworkAnalyzerConfiguration.html) API operation or the [ create-network-analyzer-configuration](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-network-analyzer-configuration.html) CLI command. When you create your configuration, you only need to specify a configuration name. You can also use this API operation to specify the configuration settings and add resources when creating the configuration. Alternatively, you can specify them later by using the [UpdateNetworkAnalyzerConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateNetworkAnalyzerConfiguration.html) API operation or the [update-network-analyzer-configuration](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-network-analyzer-configuration.html) CLI. + **Create a configuration** When you create your configuration, you must specify a name. For example, the following command creates a configuration by providing only a name and an optional description. By default, the configuration has frame info activated and uses a log level of `INFO`. ``` aws iotwireless create-network-analyzer-configuration \ --configuration-name My_Network_Analyzer_Config \ --description "My first network analyzer configuration" ``` Running this command displays the ARN and ID of your network analyzer configuration. ``` { "Arn": "arn:aws:iotwireless:us-east-1:123456789012:NetworkAnalyzerConfiguration/12345678-a1b2-3c45-67d8-e90fa1b2c34d", "Id": "12345678-a1b2-3c45-67d8-e90fa1b2c34d" } ``` + **Create configuration with resources** To customize the configuration settings, use the `trace-content` parameter. To add resources, use the `WirelessDevices` and `WirelessGateways` parameters to specify the gateways, devices, or both that you want to add to your configuration. For example, the following command customizes the configuration settings and adds to your configuration the wireless resources, specified by their `WirelessGatewayID` and `WirelessDeviceID`. ``` aws iotwireless create-network-analyzer-configuration \ --configuration-name My_NetworkAnalyzer_Config \ --trace-content WirelessDeviceFrameInfo=DISABLED,LogLevel="ERROR" \ --wireless-gateways "12345678-a1b2-3c45-67d8-e90fa1b2c34d" "90123456-de1f-2b3b-4c5c-bb1112223cd1" --wireless-devices "1ffd32c8-8130-4194-96df-622f072a315f" ``` The following example shows the output of running the command: ``` { "Arn": "arn:aws:iotwireless:us-east-1:123456789012:NetworkAnalyzerConfiguration/12345678-a1b2-3c45-67d8-e90fa1b2c34d", "Id": "12345678-a1b2-3c45-67d8-e90fa1b2c34d" } ``` **List network analyzer configurations** You can create multiple network analyzer configurations depending on the resources that you want to monitor and the level of detail of trace messaging information that you want to receive for the resources. After you create these configurations, you can use the [ListNetworkAnalyzerConfigurations](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListNetworkAnalyzerConfigurations.html) API operation or the [list-network-analyzer-configuration](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-network-analyzer-configuration.html) CLI command to get a list of these configurations. ``` aws iotwireless list-network-analyzer-configurations ``` Running this command displays all the network analyzer configurations in your AWS account. You can also use the `max-results` parameter to specify how many configurations you want to display. The following shows the output of running this command. ``` { "NetworkAnalyzerConfigurationList": [ { "Arn": "arn:aws:iotwireless:us-east-1:123456789012:NetworkAnalyzerConfiguration/12345678-a1b2-3c45-67d8-e90fa1b2c34d", "Name": "My_Network_Analyzer_Config1" }, { "Arn": "arn:aws:iotwireless:us-east-1:123456789012:NetworkAnalyzerConfiguration/90123456-a1a2-9a87-65b4-c12bf3c2d09a", "Name": "My_Network_Analyzer_Config2" } ] } ``` **Delete your network analyzer configuration** You can delete a configuration that you're no longer using with the [ DeleteNetworkAnalyzerConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteNetworkAnalyzerConfiguration.html) API operation or the [delete-network-analyzer-configuration](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/delete-network-analyzer-configuration.html) CLI command. ``` aws iotwireless delete-network-analyzer-configuration \ --configuration-name My_NetworkAnalyzer_Config ``` Running this command doesn't produce any output. To see the available configurations, you can use the `ListNetworkAnalyzerConfigurations` API operation. ## Next steps Now that you've created a network analyzer configuration, you can add resources to your configuration or update your configuration settings. For more information, see [Add resources and update the network analyzer configuration](network-analyzer-resources.md). # Add resources and update the network analyzer configuration Before you can activate trace messaging, you must add resources to your configuration. You can use only a single, default network analyzer configuration. AWS IoT Core for LoRaWAN assigns the name, **NetworkAnalyzerConfig\$1Default**, to this configuration, and this field can't be edited. This configuration is automatically added to your AWS account when you use network analyzer from the console. You can add the resources that you want to monitor to this default configuration. Resources can be either or both LoRaWAN devices and LoRaWAN gateways. To add each individual resource to the configuration, use the wireless gateway and wireless device identifiers. ## Configuration settings To configure settings, first add resources to your default configuration and activate trace messaging. After you've received the trace message logs, you can also customize the following parameters to update your default configuration and filter the log stream. + **Frame info** This setting is the frame info of your wireless device resources for trace messages. the frame info is enabled by default, and can be used to debug the communication between your network server and the end devices. + **Log levels** You can view Info or Error logs, or you can turn off logging. + **Info** Logs with a log level of **Info** are more verbose and contain log streams that are both informative and contain errors. The informative logs can be used to view changes to the state of a device or gateway. **Note** Collecting more verbose log streams can incur additional costs. For more information about pricing, see [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/). + **Error** Logs with a log level of **Error** are less verbose and display only error information. You can use these logs when an application has an error, such as a device connection error. By using the information from the log stream, you can identify and troubleshoot errors for resources in your fleet. ## Prerequisites Before you can add resources, you must have onboarded the gateways and devices that you want to monitor to AWS IoT Core for LoRaWAN. For more information, see [Connecting gateways and devices to AWS IoT Core for LoRaWAN](lorawan-getting-started.md). ## Add resources and update the network analyzer configuration by using the console You can add resources and customize the optional parameters by using the AWS IoT console or the AWS IoT Wireless API. In addition to resources, you can also edit your configuration settings and save the updated configuration. **To add resources to your configuration (console)** 1. Open the [Network Analyzer hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/wireless/networkAnalyzer) and choose the network analyzer configuration, **NetworkAnalyzerConfig\$1Default**. 1. Choose **Add resources**. 1. Add the resources you want to monitor by using the wireless gateway and wireless device identifiers. You can add up to 250 wireless gateways or wireless devices. To add your resource: 1. Use the **View gateways** or **View devices** tab to see the list of gateways and devices that you've added to your AWS account. 1. Copy the `WirelessDeviceID` or the `WirelessGatewayID` of the device or gateway that you want to monitor and enter the identifier value for the corresponding resource. 1. To continue adding resources, choose **Add gateway** or **Add device** and add your wireless gateway or device. If you added a resource that you no longer want to monitor, choose **Remove resource**. 1. After you've added all the resources, choose **Add**. You'll see the number of gateways and devices that you added in the **Network Analyzer hub page**. You can still continue adding gateways and devices until you activate the trace messaging session. After the session has been activated, to add resources, you'll have to deactivate the session. **To edit the network analyzer configuration (console)** You can also edit the network analyzer configuration and choose whether to disable frame info and the log level for your trace message logs. 1. Open the [Network Analyzer hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/wireless/networkAnalyzer) and choose the network analyzer configuration, **NetworkAnalyzerConfig\$1Default**. 1. Choose **Edit**. 1. Choose whether to disable frame info and use **Select log levels** to choose the log levels that you want to use for your trace message logs. Choose **Save**. You'll see the configuration settings that you specified in the details page of your network analyzer configuration. ## Add resources and update the network analyzer configuration by using the API You can use the [AWS IoT Wireless API operations](https://docs.aws.amazon.com/iot-wireless/latest/apireference/) or the [AWS IoT Wireless CLI commands](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/index.html) to add resources and update the configuration settings for your network analyzer configuration. + To add resources and update your network analyzer configuration, use the [UpdateNetworkAnalyzerConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateNetworkAnalyzerConfiguration.html) API or the [update-network-analyzer-configuration](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-network-analyzer-configuration.html) CLI. + **Add resources** For the wireless devices you want to add, use `WirelessDevicesToAdd` to enter the `WirelessDeviceID` for the devices as an array of strings. For the wireless gateways you want to add, use `WirelessGatewaysToAdd` to enter the `WirelessGatewayID` for the gateways as an array of strings. + **Edit configuration** To edit your network analyzer configuration, use the `TraceContent` parameter to specify whether `WirelessDeviceFrameInfo` should be `ENABLED` or `DISABLED`, and whether the `LogLevel` parameter should be `INFO`, `ERROR`, or `DISABLED`. ``` { "TraceContent": { "LogLevel": "string", "WirelessDeviceFrameInfo": "string" }, "WirelessDevicesToAdd": [ "string" ], "WirelessDevicesToRemove": [ "string" ], "WirelessGatewaysToAdd": [ "string" ], "WirelessGatewaysToRemove": [ "string" ] } ``` + To get information about the configuration and the resources that you've added, use the [GetNetworkAnalyzerConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateNetworkAnalyzerConfiguration.html) API operation or the [get-network-analyzer-configuration](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-network-analyzer-configuration.html) command. Provide the name of the network analyzer configuration, `NetworkAnalyzerConfig_Default`, as input. ## Next steps Now that you've added resources and specified any optional configuration settings for your configuration, you can use the WebSocket protocol to establish a connection with AWS IoT Core for LoRaWAN for using network analyzer. You can then activate trace messaging and start receiving trace messages for your resources. For more information, see [Stream network analyzer trace messages with WebSockets](network-analyzer-api.md). # Stream network analyzer trace messages with WebSockets Using the network analyzer API provided by AWS IoT Core for LoRaWAN, you can gain insights into the health and performance of your LoRaWAN network. This API provides visibility into various network metrics, including packet delivery rates, signal strengths, and device connectivity. Using the network analyzer API, you can identify and address potential issues in advance, which ensures reliable and efficient communication between your LoRaWAN devices and the cloud. Network analyzer trace messages capture detailed information about uplink and downlink transmissions, including packet metadata, signal strengths, and timing information. For example, you can use these trace messages to gain invaluable insights into the root cause of network performance issues or device connectivity problems. When you use the WebSocket protocol, you can stream network analyzer trace messages in real time. When you send a request, the service responds with a JSON structure. After you activate trace messaging, you can use the message logs to get information about your resources and troubleshoot errors. For more information, see [WebSocket protocol](https://tools.ietf.org/html/rfc6455). The following topics show how to stream network analyzer trace messages with WebSockets. **Topics** + [ # Generate a presigned request with the WebSocket library ](network-analyzer-generate-request.md) + [ # Sample Python code to generate presigned URL ](network-analyzer-request-sample.md) + [ # WebSocket messages and status codes ](network-analyzer-messages-status.md) # Generate a presigned request with the WebSocket library The following shows how you to generate a presigned request so that you can use the WebSocket library to send requests to the service,. ## Add a policy for WebSocket requests to your IAM role To use the WebSocket protocol to call network analyzer, attach the following policy to the AWS Identity and Access Management (IAM) role that makes this request. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iotwireless:StartNetworkAnalyzerStream", "Resource": "*" } ] } ``` ## Create a presigned URL Construct a URL for your WebSocket request that contains the information needed to set up communication between your application and the network analyzer. To verify the identity of the request, WebSocket streaming uses the Amazon Signature Version 4 process for signing requests. For more information about Signature Version 4, see [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) in the *AWS AWS Identity and Access Management User Guide*. To call network analyzer, use the `StartNetworkAnalyzerStream` request URL. The request will be signed using the credentials for the IAM role mentioned previously. The URL has the following format with line breaks added for readability. ``` GET wss://api.iotwireless..amazonaws.com/start-network-analyzer-stream?X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=Signature Version 4 credential scope &X-Amz-Date=date &X-Amz-Expires=time in seconds until expiration &X-Amz-Security-Token=security-token &X-Amz-Signature=Signature Version 4 signature &X-Amz-SignedHeaders=host ``` Use the following values for the Signature Version 4 parameters: + **X-Amz-Algorithm** – The algorithm you're using in the signing process. The only valid value is `AWS4-HMAC-SHA256`. + **X-Amz-Credential** – A string separated by slashes ("/") that is formed by concatenating your access-key ID and your credential scope components. Credential scope includes the date in YYYYMMDD format, the AWS Region, the service name, and a termination string (aws4\$1request). + **X-Amz-Date** – The date and time that the signature was created. Generate the date and time by following the instructions in [SigV4 request elements](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-signing-elements.html) in the *Amazon Web Services General Reference*. + **X-Amz-Expires** – The length of time in seconds until the credentials expire. The maximum value is 300 seconds (5 minutes). + **X-Amz-Security-Token** – (optional) A Signature Version 4 token for temporary credentials. If you specify this parameter, include it in the canonical request. For more information, see [Requesting Temporary Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html) in the *AWS Identity and Access Management User Guide*. + **X-Amz-Signature** – The Signature Version 4 signature that you generated for the request. + **X-Amz-SignedHeaders** – The headers that are signed when creating the signature for the request. The only valid value is `host`. ## Construct the request URL and create Signature Version 4 signature To construct the URL for the request and create the Signature Version 4 signature, use the following steps. **Note** The examples in this section are in pseudocode. For a sample Python code that shows how to create the signature, see [Sample Python code to generate presigned URL](network-analyzer-request-sample.md). ### Task 1: Create a canonical request Create a string that includes information from your request in a standardized format. This ensures that when AWS receives the request, it can calculate the same signature that you calculate in [Task 3: Calculate the signature](#calculate-signature). For more information, see [Create a Signed AWS API request](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html) in the *AWS AWS Identity and Access Management User Guide*. 1. Define variables for the request in your application. ``` # HTTP verb method = "GET" # Service name service = "iotwireless" # AWS Region region = "AWS Region" # Service streaming endpoint endpoint = "wss://api.iotwireless.region.amazonaws.com" # Host host = "api.iotwireless..amazonaws.com" # Date and time of request amz-date = YYYYMMDD'T'HHMMSS'Z' # Date without time for credential scope datestamp = YYYYMMDD ``` 1. Create a canonical URI (uniform resource identifier). The canonical URI is the part of the URI between the domain and the query string. ``` canonical_uri = "/start-network-analyzer-stream" ``` 1. Create the canonical headers and signed headers. Note the trailing `\n` in the canonical headers. + Append the lowercase header name followed by a colon. + Append a comma-separated list of values for that header. Don't sort the values in headers that have multiple values. + Append a new line (`\n`). ``` canonical_headers = "host:" + host + "\n" signed_headers = "host" ``` 1. Match the algorithm to the hashing algorithm. You must use SHA-256. ``` algorithm = "AWS4-HMAC-SHA256" ``` 1. Create the credential scope, which scopes the derived key to the date, Region, and service to which the request is made. ``` credential_scope = datestamp + "/" + region + "/" + service + "/" + "aws4_request" ``` 1. Create the canonical query string. Query string values must be URI-encoded and sorted by name. + Sort the parameter names by character code point in ascending order. Parameters with duplicate names should be sorted by value. For example, a parameter name that begins with the uppercase letter F precedes a parameter name that begins with a lowercase letter b. + Do not URI-encode any of the unreserved characters that [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) defines: A–Z, a–z, 0–9, hyphen ( - ), underscore ( \$1 ), period ( . ), and tilde ( \$1 ). + Percent-encode all other characters with %XY, where X and Y are hexadecimal characters (0-9 and uppercase A-F). For example, the space character must be encoded as %20 (not using '\$1', as some encoding schemes do) and extended UTF-8 characters must be in the form %XY%ZA%BC. + Double-encode any equals ( = ) characters in parameter values. ``` canonical_querystring = "X-Amz-Algorithm=" + algorithm canonical_querystring += "&X-Amz-Credential="+ URI-encode(access key + "/" + credential_scope) canonical_querystring += "&X-Amz-Date=" + amz_date canonical_querystring += "&X-Amz-Expires=300" canonical_querystring += "&X-Amz-Security-Token=" + token canonical_querystring += "&X-Amz-SignedHeaders=" + signed_headers canonical_querystring += "&language-code=en-US&media-encoding=pcm&sample-rate=16000" ``` 1. Create a hash of the payload. For a GET request, the payload is an empty string. ``` payload_hash = HashSHA256(("").Encode("utf-8")).HexDigest() ``` 1. Combine all of the elements to create the canonical request. ``` canonical_request = method + '\n' + canonical_uri + '\n' + canonical_querystring + '\n' + canonical_headers + '\n' + signed_headers + '\n' + payload_hash ``` ### Task 2: Create the string to sign The string to sign contains meta information about your request. You use the string to sign in the next step when you calculate the request signature. For more information, see [Create a Signed AWS API request](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html) in the *AWS AWS Identity and Access Management User Guide*. ``` string_to_sign=algorithm + "\n" + amz_date + "\n" + credential_scope + "\n" + HashSHA256(canonical_request.Encode("utf-8")).HexDigest() ``` ### Task 3: Calculate the signature You derive a signing key from your AWS secret access key. For a greater degree of protection, the derived key is specific to the date, service, and AWS Region. You use the derived key to sign the request. For more information, see [Create a Signed AWS API request](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html) in the *AWS AWS Identity and Access Management User Guide*. The code assumes that you have implemented the `GetSignatureKey` function to derive a signing key. For more information and example functions, see [Create a Signed AWS API request](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html) in the *AWS AWS Identity and Access Management User Guide*. The function `HMAC(key, data)` represents an HMAC-SHA256 function that returns the results in binary format. ``` #Create the signing key signing_key = GetSignatureKey(secret_key, datestamp, region, service) # Sign the string_to_sign using the signing key signature = HMAC.new(signing_key, (string_to_sign).Encode("utf-8"), Sha256()).HexDigest ``` ### Task 4: Add signing information to request and create request URL After you calculate the signature, add it to the query string. For more information, see [Create a Signed AWS API request](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html) in the *AWS AWS Identity and Access Management User Guide*. ``` #Add the authentication information to the query string canonical_querystring += "&X-Amz-Signature=" + signature # Sign the string_to_sign using the signing key request_url = endpoint + canonical_uri + "?" + canonical_querystring ``` ## Next steps You can now use the request URL with your WebSocket library to make the request to the service and observe the messages. For more information, see [WebSocket messages and status codes](network-analyzer-messages-status.md). For a sample Python code that shows how to generate a presigned request, see [Sample Python code to generate presigned URL](network-analyzer-request-sample.md). # Sample Python code to generate presigned URL The following code shows an example for generating the pre-signed URL using Python as the programming language. ## Pre-requisites To use the Python programming language to generate requests, you must have: + Python installed on your computer. You can either run the following command or download the [Python installer](https://www.python.org/downloads/) and then run it. ``` sudo apt install python3 ``` + The Python requests library. You can either run the following command or download the [Requests library](https://pypi.python.org/pypi/requests), which is used in the example script to make web requests. ``` pip install requests ``` + An access key that consists of the access key ID and secret access key in environment variables named `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. Alternatively, you can keep these values in a credentials file and read them from that file. **Note** As a best practice, we recommend that you do not embed credentials in code. For more information, see [Best Practices for AWS accounts](https://docs.aws.amazon.com/accounts/latest/reference/best-practices.html) in the AWS account Management Reference Guide. ``` $ export AWS_ACCESS_KEY_ID=My_Access_Key $ export AWS_SECRET_ACCESS_KEY=My_Secret_Key # Session token is required only if you use temporary access key starting with "ASIA" $ export AWS_SESSION_TOKEN=My_Session_token ``` ## Sample Python code This Python code generates the pre-signed URL that the WebSocket library can use to send requests to the service. The function creates a canonical request, then creates the string to sign which is used to calculate the signature, and then adds the signature to the HTTP request to create the pre-signed URL. You can then use the WebSocket library to request the pre-signed URL. To run the script, `generate_presigned_url.py`, run the following command if you're running it from the same path where the script is located. ``` python generate_presigned_url.py ``` The following shows the contents of the `generate_presigned_url.py` script. ``` # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 # Version 4 signing example """ Sample Python code to generate the pre-signed URL. You can change the parameters in this code to your own values, such as the variables that are required for the request URL, the network analyzer configuration name, and Region. """ # ------------------------------------------------------------------ # Step 1. Import the required libraries and define the functions # sign and getSignatureKey that will be used to derive a signing key. # ------------------------------------------------------------------ import sys, os, base64, datetime, hashlib, hmac, urllib.pars import requests # pip install requests def sign(key, msg): return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest() def getSignatureKey(key, dateStamp, regionName, serviceName): kDate = sign(("AWS4" + key).encode("utf-8"), dateStamp) kRegion = sign(kDate, regionName) kService = sign(kRegion, serviceName) kSigning = sign(kService, "aws4_request") return kSigning # ------------------------------------------------------------------ # Step 2. Define the variables required for the request URL. Replace # values for the variables, such as region, with your own values. # ------------------------------------------------------------------ method = "GET" service = "iotwireless" region = "us-east-1" # Host and endpoint information. host = "api.iotwireless." + region + ".amazonaws.com" endpoint = "wss://" + host # Create a date for headers and the credential string. t = datetime.datetime.utcnow() amz_date = t.strftime("%Y%m%dT%H%M%SZ") # For date stamp, the date without time is used in credential scope. datestamp = t.strftime("%Y%m%d") # ----------------------------------------------------------------------- # Step 3. Create the canonical URI and canonical headers for the request. # ----------------------------------------------------------------------- canonical_uri = "/start-network-analyzer-stream" configuration_name = "My_Network_Analyzer_Config" canonical_headers = "host:" + host + "\n" signed_headers = "host" algorithm = "AWS4-HMAC-SHA256" credential_scope = datestamp + "/" + region + "/" + service + "/" + "aws4_request" # ----------------------------------------------------------------------- # Step 4. Read the credentials that are required for the request # from environment variables or configuration file. # ----------------------------------------------------------------------- # IMPORTANT: Best practice is NOT to embed credentials in code. access_key = os.environ.get("AWS_ACCESS_KEY_ID") secret_key = os.environ.get("AWS_SECRET_ACCESS_KEY") token = os.environ.get("AWS_SESSION_TOKEN") if access_key is None or secret_key is None: print("No access key is available.") sys.exit() if access_key.startswith("ASIA") and token is None: print("Detected temporary credentials. You must specify a token.") sys.exit() # ---------------------------------------------------------------------- # Step 5. Create the canonical query string. Query string values must be # URI-encoded and sorted by name. Query headers must in alphabetical order. # ---------------------------------------------------------------------- canonical_querystring = "X-Amz-Algorithm=" + algorithm canonical_querystring += "&X-Amz-Credential=" + \ urllib.parse.quote(access_key + "/" + credential_scope, safe="-_.~") canonical_querystring += "&X-Amz-Date=" + amz_date canonical_querystring += "&X-Amz-Expires=300" if access_key.startswith("ASIA"): # percent encode the token and double encode "=" canonical_querystring += "&X-Amz-Security-Token=" + \ urllib.parse.quote(token, safe="-_.~").replace("=", "%253D") canonical_querystring += "&X-Amz-SignedHeaders=" + signed_headers canonical_querystring += "&configuration-name=" + configuration_name # ---------------------------------------------------------------------- # Step 6. Create a hash of the payload. # ---------------------------------------------------------------------- payload_hash = hashlib.sha256(("").encode("utf-8")).hexdigest() # ------------------------------------------------------------------ # Step 7. Combine the elements, which includes the query string, the # headers, and the payload hash, to form the canonical request. # ------------------------------------------------------------------ canonical_request = method + "\n" + canonical_uri + "\n" + canonical_querystring \ + "\n" + canonical_headers + "\n" + signed_headers + "\n" + payload_hash # ---------------------------------------------------------------------- # Step 8. Create the metadata string to store the information required to # calculate the signature in the following step. # ---------------------------------------------------------------------- string_to_sign = algorithm + "\n" + amz_date + "\n" + \ credential_scope + "\n" + hashlib.sha256(canonical_request.encode("utf-8")).hexdigest() # ---------------------------------------------------------------------- # Step 9. Calculate the signature by using a signing key that"s obtained # from your secret key. # ---------------------------------------------------------------------- # Create the signing key from your secret key. signing_key = getSignatureKey(secret_key, datestamp, region, service) # Sign the string_to_sign using the signing key. signature = hmac.new(signing_key, (string_to_sign).encode("utf-8"), hashlib.sha256).hexdigest() # ---------------------------------------------------------------------- # Step 10. Create the request URL using the calculated signature and by # combining it with the canonical URI and the query string. # ---------------------------------------------------------------------- canonical_querystring += "&X-Amz-Signature=" + signature request_url = endpoint + canonical_uri + "?" + canonical_querystring print("\n-----------PRESIGNED URL-----------") print(request_url) ``` ## Next steps You can now use the request URL with your WebSocket library to make the request to the service and observe the messages. To install a WebSocket library to use with Python, run the following command. For information about how you can use a WebSocket client with Python, see [WebSocket client for Python with low level API options](https://pypi.org/project/websocket-client/). ``` pip install websocket-client ``` After you install the client and make the request, you'll see messages and status codes that indicate the status of your request. For more information, see [WebSocket messages and status codes](network-analyzer-messages-status.md). # WebSocket messages and status codes After you've created a presigned request, you can use the request URL with your WebSocket library, , or a library that's suited to your programming language, to make requests to the service. For more information about how you can generate this presigned request, see [Generate a presigned request with the WebSocket library](network-analyzer-generate-request.md). ## WebSocket messages The WebSocket protocol can be used to establish a bi-directional connection. Messages can be transmitted from client to server and from server to client. However, network analyzer supports only messages that are sent from server to client. Any message received from the client is unexpected and the server will automatically close the WebSocket connection if a message is received from client. When the request is received and a trace messaging session has started, the server responds with a JSON structure, which is the payload. For more information about the payload and how you can activate trace messaging from the AWS Management Console, see [View and monitor trace message logs in real time](network-analyzer-logs.md). ## WebSocket status codes The following shows the WebSocket status codes for the communication from the server to client. The WebSocket status codes follow the [RFC Standard of Normal closure of connections](https://datatracker.ietf.org/doc/html/rfc6455#section-7.3). The following shows the supported status codes: + **1000** This status code indicates a normal closure, which means that the WebSocket connection has been established and the request has been fulfilled. This status can be observed when a session is idle, causing the connection to time out. + **1002** This status code indicates that the endpoint is terminating the connection because of a protocol error. + **1003** This status code indicates an error status where the endpoint terminated the connection because it received data in a format that it can't accept. The endpoint supports only text data and might display this status code if it receives a binary message or a message from the client that's using an unsupported format. + **1008** This status code indicates an error status where the endpoint terminated the connection because it received a message that violates its policy. This status is generic and is displayed when the other status codes, such as 1003 or 1009, aren't applicable. You'll also see this status displayed if there's a need to hide the policy, or when there's an authorization failure, such as an expired signature. + **1011** This status code indicates an error status where the server is terminating the connection because it encountered an unexpected condition or internal error that prevented it from fulfilling the request. ## Next steps Now that you've learned how to generate a presigned request and how you can observe messages from the server by using the WebSocket connection, you can activate trace messaging and start receiving message logs for your wireless gateway and wireless device resources. For more information, see [View and monitor trace message logs in real time](network-analyzer-logs.md). # View and monitor trace message logs in real time If you've added resources to your network analyzer configuration, you can activate trace messaging to start receiving trace messages for your resources. You can use either the AWS Management Console, the AWS IoT Wireless API, or the AWS CLI. ## Prerequisites Before you can activate trace messaging by using network analyzer, you must have: + Added the resources that you want to monitor to your default network analyzer configuration. For more information, see [Add resources and update the network analyzer configuration](network-analyzer-resources.md). + Generated a presigned request by using the `StartNetworkAnalyzerStream` request URL. The request will be signed using the credentials for the AWS Identity and Access Management role that makes this request. For more information, see [Create a presigned URL](network-analyzer-generate-request.md#network-analyzer-presigned-url). ## Activate trace messaging by using the console To activate trace messaging 1. Open the [Network Analyzer hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/wireless/networkAnalyzer) and choose your network analyzer configuration, **NetworkAnalyzerConfig\$1Default**. 1. In the details page of your network analyzer configuration, choose **Activate trace messaging** and then choose **Activate**. You'll start receiving trace messages where the newest trace message appears first in the console. **Note** After the messaging session starts, receiving trace messages can incur additional costs until you deactivate the session or leave the trace session. For more information about pricing, see [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/). ## View and monitor trace messages After you activate trace messaging, the WebSocket connection is established and trace messages start appearing in real time, newest first. You can customize the preferences to specify the number of trace messages to be displayed in each page and to display only the relevant fields for each message. For example, you can customize the trace message log to show only logs for wireless gateway resources that have **Log level** set to `ERROR`, so that you can quickly identify and debug errors with your gateways. The trace messages contain the following information. + **Message Number**: A unique number that shows the last message received first. + **Resource ID**: The wireless gateway or wireless device ID of the resource. + **Timestamp**: The time when the message was received. + **Message ID**: An identifier that AWS IoT Core for LoRaWAN assigns to each received message. + **FPort**: The frequency port for communicating with the device by using the WebSocket connection. + **DevEui**: The extended unique identifier (EUI) for your wireless device. + **Resource**: Whether the monitored resource is a wireless device or a wireless gateway. + **Event**: The event for a log message for a wireless device, which can be **Join**, **Rejoin**, **Uplink\$1Data**, **Downlink\$1Data**, or **Registration**. + **Log level**:Information about `INFO` or `ERROR` log streams for your device. ## Network analyzer JSON log message You can also choose one trace message at a time to view the JSON payload for that message. Depending on the message that you select in the trace message logs, you'll see information in the JSON payload that indicates contains 2 parts: **CustomerLog** and **LoRaFrame**. **CustomerLog** The **CustomerLog** part of the JSON displays the type and identifier of the resource that received the message, the log level, and the message content. The following example shows a **CustomerLog** log message. You can use the `message` field in the JSON to get more information about the error and how it can be resolved. **LoRaFrame** The **LoRaFrame** part of the JSON has a **Message ID** and contains information about the physical payload for the device and the wireless metadata. The wireless metadata also contains information about the gateway metadata, and whether the trave message was received from the public network or from a private LoRaWAN gateway. The following shows examples of the trace message. ### Trace message log for private gateways The following example shows a sample trace message received using network analyzer if your devices connect to AWS IoT Core for LoRaWAN using your own private LoRaWAN gateways. The metadata consists of the ID of the gateway and it's EUI, and the SNR and RSSI values. These values can help you determine the strength of your gateway channel and whether to switch to a stronger channel. For more information about the public network, see [Managing LoRaWAN traffic from public networks (Everynet)](iot-lorawan-roaming.md). ``` { "resource_id": "d05bef08-cab2-41bf-b69e-ce306b9a5f81", "frame_type": "LoRa", "timestamp": "2024-02-15T16:49:35.966023978Z", "lora_frame": { "dev_eui": "4d767373e0ec05c4", "message_id": "8e6dcc61-80b6-45c1-89d3-c712cf5603fb", "phy_payload": "XXX", "wireless_metadata": { "dev_eui": "4d767373e0ec05c4", "m_type": "CONFIRMED_DATA_UP", "f_port": 22, "data_rate": 3, "frequency": 904300000, "timestamp": "2024-02-15T16:49:35.966023978Z", "lorawan_gateways": { "wireless_gateway_id": "d0bfb1d8-b0b6-48f8-b9bb-d0aadf1ab2cf", "gateway_eui": "4b634d3cc5879def", "snr": 5.099999904632568, "rssi": -35 } }, "dev_addr": "012c58d1" } } ``` ### Trace message log for public network The following example shows a sample trace message received using network analyzer if your devices use the public network to connect to AWS IoT Core for LoRaWAN. The public network is provided and operated as a service directly by Everynet. The following example shows the public LoRaWAN network metadata in the uplink 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. These values can help you determine the strength of your public network. For more information about the public network, see [Managing LoRaWAN traffic from public networks (Everynet)](iot-lorawan-roaming.md). **Note** The uplink message will mention `public_lorawan_gateways` to indicate that it's received from the public network and not a private LoRaWAN gateway. ``` { "resource_id": "d05bef08-cab2-41bf-b69e-ce306b9a5f81", "frame_type": "LoRa", "timestamp": "2024-02-15T16:49:35.966023978Z", "lora_frame": { "dev_eui": "4d767373e0ec05c4", "message_id": "8e6dcc61-80b6-45c1-89d3-c712cf5603fb", "phy_payload": "XXX", "wireless_metadata": { "dev_eui": "4d767373e0ec05c4", "m_type": "CONFIRMED_DATA_UP", "f_port": 22, "data_rate": 3, "frequency": 904300000, "timestamp": "2024-02-15T16:49:35.966023978Z", "public_lorawan_gateways": { "provider_net_id: "0x0000b", "id": "3abe094", "snr": 5.099999904632568, "rssi": -35, "rfregion": US915, "dl_allowed": true } }, "dev_addr": "012c58d1" } } ``` ### Trace message log without gateway metadata If you want to exclude the gateway metadata information from your trace message, 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). The following example shows a trace message with the `lora_frame` and `customer_log` information and doesn't contain any gateway information. ``` { "resource_id": "d05bef08-cab2-41bf-b69e-ce306b9a5f81", "frame_type": "LoRa", "timestamp": "2024-02-15T16:49:35.966023978Z", "lora_frame": { "dev_eui": "4d767373e0ec05c4", "message_id": "8e6dcc61-80b6-45c1-89d3-c712cf5603fb", "phy_payload": "XXX", "wireless_metadata": { "dev_eui": "4d767373e0ec05c4", "m_type": "CONFIRMED_DATA_UP", "f_port": 22, "data_rate": 3, "frequency": 904300000, "timestamp": "2024-02-15T16:49:35.966023978Z" }, "dev_addr": "012c58d1" }, "customer_log" { "resource": "WirelessDevice", "wireless_device_id":8 "ab0c23d3-b001-45ef-6a01-2bc3de4f5333", "wireless_device_type": "LoRaWAN", "log_level": "INFO", "event": "Uplink_Data", "message": "Uplink message received", "messageId": "59e7d840-d756-4978-8c64-7f60cfd3fd3b" } } ``` ## Review and next steps In this section, you've viewed trace messages and learned how you can use the information to debug errors. After you've viewed all messages, you can: + **Deactivate trace messaging** To avoid incurring any additional costs, you can deactivate the trace messaging session. Deactivating the session disconnects your WebSocket connection so you won't receive any additional trace messages. You can still continue viewing the existing messages in the console. + **Edit frame info for your configuration** You can edit the network analyzer configuration and choose whether to deactivate frame info and choose the log levels for your messages. Before you update your configuration, consider deactivating your trace messaging session. To make these edits, open the [Network Analyzer details page in the AWS IoT console](https://console.aws.amazon.com/iot/home#/wireless/networkAnalyzer/details/NetworkAnalyzerConfig_Default) and choose **Edit**. You can then update your configuration with the new configuration settings and activate trace messaging to see the updated messages. + **Add resources to your configuration** You can also add more resources to your network analyzer configuration and monitor them in real time. You can add up to a combined total of 250 wireless gateway and wireless device resources. To add resources, on the [Network Analyzer details page of the AWS IoT console](https://console.aws.amazon.com/iot/home#/wireless/networkAnalyzer/details/NetworkAnalyzerConfig_Default), choose the **Resources** tab and choose **Add resources**. You can then update your configuration with the new resources and activate trace messaging to see the updated messages for the additional resources. For more information about updating your network analyzer configuration by editing the configuration settings and adding resources, see [Add resources and update the network analyzer configuration](network-analyzer-resources.md). # Debug and troubleshoot your multicast groups and FUOTA tasks using network analyzer The wireless resources that you can monitor include LoRaWAN devices, LoRaWAN gateways, and multicast groups. You can also use network analyzer to debug and troubleshoot any issues with your FUOTA task. You can also monitor and track messages related to setup, data transmission, and status query when the FUOTA task is in progress. To monitor your FUOTA task, if the task contains multicast groups, you must add both the multicast group and the devices in the group to your network analyzer configuration. You must also activate frame info and multicast frame info to track the unicast and multicast uplink and downlink messages that are exchanged with the multicast group and the devices while the FUOTA task is in progress. To monitor multicast groups, you can add them to your network analyzer configuration and use multicast frame info to troubleshoot multicast downlink messages that are sent to these groups. For troubleshooting devices that are attempting to join a group, where unicast communication is used, you must also include these devices in the network analyzer configuration. To monitor only the unicast communication with the devices in the group, activate the frame info for your wireless devices. This approach ensures comprehensive monitoring and diagnostics for both multicast groups and devices that are joining the group. The following sections describe how to debug and troubleshoot your multicast groups and FUOTA tasks using network analyzer. **Topics** + [ ## Debug FUOTA tasks that only contains devices ](#lorawan-network-analyzer-fuota-devices) + [ ## Debug FUOTA tasks with multicast groups ](#lorawan-network-analyzer-fuota-multicast) + [ ## Debug devices that are attempting to join a multicast group ](#lorawan-network-analyzer-fuota-multicast) + [ ## Debug a multicast group session ](#lorawan-network-analyzer-fuota-multicastsession) ## Debug FUOTA tasks that only contains devices You can use network analyzer to debug a FUOTA task that only has LoRaWAN devices added to the task. For information about adding devices to a FUOTA task, see [Add devices and multicast groups and schedule FUOTA session](lorawan-fuota-add-devices.md). To debug the FUOTA task, perform the following steps: 1. Create a network analyzer configuration by activating frame info for the wireless devices so that you can monitor the FUOTA uplink and downlink messages that are exchanged with the devices while the task is in progress. 1. Add the devices in your FUOTA task to the network analyzer configuration by using their wireless device identifiers. 1. Activate trace messaging to start receiving trace messages for the devices in your network analyzer configuration. In the `applicationCommandType` column of the trace message information, you'll start receiving unicast downlink messages related to data transmission and fragmentation setup. **Note** If you don't see the `applicationCommandType` column in the trace message table, you can adjust the settings to show this column in the table. You can also see the `applicationCommandType` and other detailed messages in the JSON log message under **WirelessMetadata > ApplicationInfo**. ## Debug FUOTA tasks with multicast groups You can use network analyzer to debug a FUOTA task that has multicast groups and LoRaWAN devices added to the group. For information about adding devices to a FUOTA task, see [Add devices and multicast groups and schedule FUOTA session](lorawan-fuota-add-devices.md). To debug the FUOTA task, perform the following steps: 1. Create a network analyzer configuration by activating the frame info and multicast frame info settings for the wireless devices and multicast groups. 1. Add the multicast group in your FUOTA task to the network analyzer configuration by using their multicast group identifier. By enabling multicast frame info, you can debug the firmware data message and FUOTA status query messages that are sent to the group while the FUOTA task is in progress. 1. Add the devices in your multicast group to the network analyzer configuration by using their wireless device identifiers. By activating frame info, you can monitor uplink and downlink messages that are exchanged directly with the devices while the FUOTA task is in progress. 1. Activate trace messaging to start receiving trace messages for the devices and multicast groups in your network analyzer configuration. You can then view the trace messages and debug them using the `applicationCommandType` column of the trace message table and using the details in the JSON log message as described in [Debug FUOTA tasks that only contains devices](#lorawan-network-analyzer-fuota-devices). ## Debug devices that are attempting to join a multicast group You can use network analyzer to debug devices that are attempting to join a multicast group. For information about adding devices to a multicast group, see [Create multicast groups and add devices to the group](lorawan-create-multicast-groups.md). To debug the multicast group, perform the following steps: 1. Create a network analyzer configuration by activating frame info for the wireless devices. 1. Add the devices you want to monitor to the network analyzer configuration by using their wireless device identifiers. 1. Activate trace messaging to start receiving trace messages for the devices in your network analyzer configuration. 1. Start associating the devices to the multicast group after trace messaging has been activated for the devices in the group. ## Debug a multicast group session You can use network analyzer to debug a multicast group session. For more information, see [Schedule a downlink message for your multicast group](lorawan-multicast-schedule-downlink.md). To debug a multicast group session, perform the following steps: 1. Create a network analyzer configuration by activating multicast frame info for the multicast group. 1. Add the multicast group that you want to monitor to the network analyzer configuration by using their multicast group identifier. 1. Before the multicast session starts, activate trace messaging to start receiving trace messages for the multicast group session. 1. Start the multicast group session and monitor the status by viewing the messages that are displayed in the trace message table and the JSON log message. In the trace message table, the `MulticastAddr` will be displayed in the `DevAddr` column. In the JSON log message, you can view detailed information such as the `MulticastGroupId` under **WirelessMetadata > ApplicationInfo**. # Use AWS IoT Core for LoRaWAN metrics Use AWS IoT Core for LoRaWAN metrics to monitor the health of your LoRaWAN resources in a dashboard view. It provides information about the connectivity of your devices with the cloud, how they are functioning, and whether they are operating within specifications. These metrics can be aggregated to provide historical and up-to-the-minute view of data and trends for your resources. ## What metrics can I view? When you activate summary metrics, you can view the following information for all resources, or for your individual devices and gateways. If you see that no data is available for one or more widgets, check whether you have completed the activation steps for viewing summary metrics. You can use the **Activation steps** widget in the dashboard to check whether you have correctly configured your LoRaWAN devices, gateways, and destinations, and activated summary metrics. For information about onboarding your LoRaWAN resources, see [Connecting gateways and devices to AWS IoT Core for LoRaWAN](lorawan-getting-started.md). **List of summary metrics** | Metric name | AWS account | Individual devices | Individual gateways | | --- | --- | --- | --- | | Active devices/gateways | Yes | – | – | | Uplink message count | Yes | Yes | Yes | | Downlink message count | Yes | Yes | Yes | | Join metrics | Yes | Yes | Yes | | Message lost rate | Yes | Yes | Yes | | Signal to noise ratio (SNR) average | – | Yes | Yes | | Received signal strength indicator (RSSI) average | – | Yes | Yes | | Gateway availability | – | – | Yes | ## How to view summary metrics? To view the metrics for your LoRaWAN resources, you can activate the summary metrics dashboard either from the console or using the AWS IoT Wireless API operations. You activate summary metrics for all LoRaWAN resources in your AWS account, which includes all LoRaWAN devices and gateways. The data can be aggregated to provide you with hourly, daily, or weekly information for your resources. The LoRaWAN metrics dashboard uses the compute API to display information for your LoRaWAN resources. When you activate summary metrics, charges might be incurred for using the LoRaWAN dashboard. To avoid incurring additional charges, you can deactivate summary metrics. For information about pricing, see [https://aws.amazon.com//iot-core/pricing](https://aws.amazon.com//iot-core/pricing) AWS IoT Core pricing. **Note** The summary metrics have an expiration time. Hourly metrics expire after six months, and daily and weekly metrics expire after 12 months. **Topics** + [ ### Activate summary metrics (console) ](#iot-lorawan-metrics-how-console) + [ ### Activate summary metrics (CLI) ](#iot-lorawan-metrics-how-cli) ### Activate summary metrics (console) 1. Go to the [https://console.aws.amazon.com/iot/home#/dashboard](https://console.aws.amazon.com/iot/home#/dashboard) dashboard of the AWS IoT console and choose **LoRaWAN metrics**. 1. Choose **Activate summary metrics** and specify the period that you want to use for data to be aggregated, which can be **Daily**,**Hourly**, or **Weekly**. You'll see data flowing through the dashboard and displayed for your resources in the **LoRaWAN overview** widget and in the widget corresponding to each metric. If you don't see any data displayed, check whether you have correctly configured your LoRaWAN resources and performed the join procedure for your LoRaWAN devices so that they can start sending uplink data. ### Activate summary metrics (CLI) To activate summary metrics and see data flowing through the dashboard, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateMetricConfiguration.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateMetricConfiguration.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-metric-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-metric-configuration.html) CLI command. The following code shows a sample request body. ``` { "SummaryMetricQueries": [ { "AggregationPeriod": "OneWeek", "Dimensions": [ { "name": "DeviceId", "value": "30758fe6-56f1-4f32-8c4c-f17f000e01d3" } ], "EndTimestamp": 1699574400, "MetricName": "DeviceUplinkLostRate", "QueryId": "DeviceUplinkLostRate", "StartTimestamp": 1698969600 } ] } ``` After you've activated summary metrics, you can use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetMetrics.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetMetrics.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-metrics.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-metrics.html) CLI command. ``` { "SummaryMetric": { "Status": Disabled } } ``` You can then use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetMetricConfiguration.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetMetricConfiguration.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-metric-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-metric-configuration.html) CLI command to view the metric configuration status. The following shows a sample response. ``` { "SummaryMetric": { "Status": Disabled } } ``` ## LoRaWAN metrics After you activate summary metrics, you can view metrics pertaining to historical data for all LoRaWAN devices and gateways in your AWS account. You can also find metrics for each of your LoRaWAN devices and gateways. The following sections describe the overall metrics for all your resources in general, and for each resource in your AWS account. If you don't see any data in the widgets for the metrics, make sure that you have performed the activation steps correctly for viewing the metrics. You can also configure logging and use the network analyzer to debug any issues. **Note** In the console, you can drag the widgets for the metrics to different locations on the dashboard. Relocating the widgets might temporarily change the layout of the dashboard. The following shows the metrics that you can see in the dashboard and in the details pages of your gateways and devices on the console. ### LoRaWAN summary metrics To view the summary metrics for all resources, go to the [https://console.aws.amazon.com/iot/home#/dashboard](https://console.aws.amazon.com/iot/home#/dashboard) dashboard of the AWS IoT console and then choose the **LoRaWAN metrics** tab. + An overview of key LoRaWAN summary metrics. + The activation steps and their progress. + The number of active devices and gateways. + The count of uplink and downlink messages. + The message loss rate, which shows the ratio of the total number of packets that are lost. + The join metrics, which shows the number of join requests and join accepts. ### LoRaWAN device metrics You can view metrics showing historical data for each LoRaWAN device that you onboarded to AWS IoT Core for LoRaWAN. You'll find similar metrics as in the **Monitor** dashboard with some additional metrics such as the average received signal strength indicator (RSSI) and signal to noise ratio (SNR). You can also find a summary of the metrics for all your LoRaWAN devices in the [https://console.aws.amazon.com/iot/home#/wireless/devices/](https://console.aws.amazon.com/iot/home#/wireless/devices/) hub of the AWS IoT console. This includes: + The number of active devices within the specified time duration, which can be the last hour, day, or week + The total number of devices that have been provisioned up to the specified timestamp range, which can be the last hour, day, or week. + The uplink packet loss rate, which corresponds to the ratio of total number of uplink packets that are lost during transmission. + The individual device metrics, go to the [https://console.aws.amazon.com/iot/home#/wireless/devices/](https://console.aws.amazon.com/iot/home#/wireless/devices/) hub of the AWS IoT console and then choose the device for which you want to see the metrics. For information about activating these metrics, see [How to view summary metrics?](#iot-lorawan-metrics-how). You can view the following metrics for each LoRaWAN device. **Note** If you don't see any data in the widgets for the metrics, make sure that you have onboarded your device correctly for viewing the metrics. You can also configure logging and use the network analyzer to debug any issues. + A summary of key LoRaWAN device metrics + The count of uplink and downlink messages + The uplink packet loss rate, which shows the ratio of the total number of packets that are lost. + The join metrics, which shows the number of join requests and join accepts. + The average received signal strength indicator (RSSI) and signal to noise ratio (SNR). ### LoRaWAN gateways metrics You can view metrics showing historical data for each LoRaWAN gateway that you onboarded to AWS IoT Core for LoRaWAN. You'll find similar metrics as in the **Monitor** dashboard with some additional metrics such as the average received signal strength indicator (RSSI), signal to noise ratio (SNR), and gateway availability. You can also find a summary of the metrics for all your LoRaWAN gateways in the **Gateways** hub of the AWS IoT console. You can also find a summary of the metrics for all your LoRaWAN gateways in the [https://console.aws.amazon.com/iot/home#/wireless/gateways/](https://console.aws.amazon.com/iot/home#/wireless/gateways/) hub of the AWS IoT console. This includes: + The number of uplink and downlink messages that were exchanged between the devices and the cloud using the gateways within the specified time duration, which can be the last hour, day, or week. + The total number of gateways that have been provisioned up to the specified timestamp range, which can be the last hour, day, or week. You can view the following metrics for each LoRaWAN gateway. **Note** If you don't see any data in the widgets for the metrics, make sure that you have onboarded your gateway correctly for viewing the metrics. You can also configure logging and use the network analyzer to debug any issues. + A summary of key LoRaWAN gateway metrics + The count of uplink and downlink messages + The uplink packet loss rate, which shows the ratio of the total number of packets that are lost. + The join metrics, which shows the number of join requests and join accepts. + The gateway availability information. + The average received signal strength indicator (RSSI) and signal to noise ratio (SNR). ### Active devices and gateways After you've onboarded your gateways and devices to AWS IoT Core for LoRaWAN, your devices will start exchanging messages with the cloud. This metric displays the number of active LoRaWAN devices and gateways within a specified time duration in your AWS account. Active devices and gateways are those devices that have transmitted or received any uplink or downlink data, or gateways that facilitate such data transmission. In the Monitor dashboard, you can use the LoRaWAN overview section to see the total number of gateways and devices that have been provisioned, and the number of gateways and devices that are active. Using this information, you can identify what percentage of devices and gateways that have been provisioned are active. ### Uplink message count This metric displays the number of uplink messages that are sent within a specified time duration for all active gateways and devices in your AWS account. Uplink messages are messages that are sent from your device to AWS IoT Core for LoRaWAN. The count of uplink messages includes the total number of uplink messages and the number of uplink messages that are sent from your device to AWS IoT Core for LoRaWAN using a public network. You can use this information to identify the volume of uplink messages and the quantity of uplink messages that are arriving at the cloud over the public network during that period. ### Downlink message count This metric displays the number of downlink messages that are sent within a specified time duration for all active gateways and devices in your AWS account. Downlink messages are messages that are sent from AWS IoT Core for LoRaWAN to your devices. The count of downlink messages includes the total number of downlink messages and the number of downlink messages that are sent from AWS IoT Core for LoRaWAN to your devices using a public network. You can use this information to identify the volume of downlink messages and the quantity of downlink messages that are arriving at your devices over the public network during that period. ### Message loss rate After you've added your device and connected to AWS IoT Core for LoRaWAN, your device can initiate an uplink message to start exchanging messages with the cloud. You can use this metric to then track the rate of uplink messages that are lost. Uplink messages are lost due to the loss of signal during radio transmission from the device to gateway. The rate of uplink message loss is indicated by non-sequential frame counters (FCnt) over the specified time duration. This information can be used to assess the stability of the connection. An increase in the message loss rate can indicate that the connection is unstable. To improve the stability of the connection, you can use adaptive data rate (ADR) by setting the ADR bit in the frame header of your devices. If the connection still doesn't improve, you can move the device closer to the gateway or add more gateways around your devices. ### Join metrics After you've added your device and gateway, you perform a join procedure so that your device can send uplink data and communicate with AWS IoT Core for LoRaWAN. You can use this metric to obtain information about join metrics for all active devices in your AWS account. This metric displays the rate of total number of device join requests and join accepts under a gateway within a certain time duration. This information can be used to determine the total number of join requests and the proportion of requests that have been approved. If all join requests haven't been accepted, you can use network analyzer or configure CloudWatch Logs to check whether AWS IoT Core for LoRaWAN receives the join requests and if the requests get accepted. If your LoRaWAN devices are setup correctly, the number of join requests and join accepts must be equal. If all requests are not accepted, check whether you specified the correct DevEUI and root key or session keys when provisioning the device. ### Average received signal strength indicator (RSSI) You can use this metric to monitor the average RSSI (Received signal strength indicator) within the specified time duration. This metric can be used with the average SNR (signal to noise ratio) to measure signal strength and provide information about connectivity status. RSSI is a measurement that indicates if the signal is strong enough for a good wireless connection. The RSSI average is an average of all RSSI values for the device over a specified time duration, which can help provide information about the device's connection for that duration. The RSSI value is negative and must be closer to zero for a strong wireless connection. If the signal is weak, you can use adaptive data rate (ADR) by setting the ADR bit in the frame header of your devices to make it stronger. If the connection still doesn't improve, you can move the device closer to the gateway or add more gateways around your device. ### Average signal to noise ratio (SNR) You can use this metric to monitor the average SNR (Signal to noise ratio) within the specified time duration. This metric can be used with RSSI to measure signal strength and provide information about connectivity status. SNR is a measurement that indicates if the received signal is strong enough compared to the noise level for a good wireless connection. The SNR average is an average of all SNR values for the device over a specified time duration, which can help provide information about the device's connection for that duration. The SNR value is positive and must be greater than zero to indicate that the signal power is stronger than the noise power. If the signal is weak, you can use adaptive data rate (ADR) by setting the ADR bit in the frame header of your devices to make it stronger. If the connection still doesn't improve, you can move the device closer to the gateway or add more gateways around your device. ### Gateway availability You can use this metric to obtain information about the availability of this gateway within a specified time duration. This metric displays the websocket connection time of this gateway for a specified time duration. This connection time includes the gateway up time and the gateway down time. You can use this information to identify when a gateway was available. It can also be used with the message loss rate to identify when a packet got lost in transmission. # AWS IoT Core for LoRaWAN and interface VPC endpoints (AWS PrivateLink) You can connect directly to AWS IoT Core for LoRaWAN through [ Interface VPC endpoints (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/privatelink/vpce-interface.html) in your Virtual Private Cloud (VPC) instead of connecting over the public internet. When you use a VPC interface endpoint, communication between your VPC and AWS IoT Core for LoRaWAN is conducted entirely and securely within the AWS network. AWS IoT Core for LoRaWAN supports Amazon Virtual Private Cloud interface endpoints that are powered by AWS PrivateLink. Each VPC endpoint is represented by one or more [Elastic Network Interfaces](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) with private IP addresses in your VPC subnets. For more information, see [Interface VPC endpoints (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html) in the *Amazon VPC User Guide*. **Note** AWS IoT Core for LoRaWAN support both IPv6 and IPv4 address formats when communicating with the interface VPC endpoints using AWS PrivateLink. See [AWS services that support IPv6](https://docs.aws.amazon.com/general/latest/gr/aws-ipv6-support.html#ipv6-service-support). For more information about VPC and endpoints, see [What is Amazon VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html#what-is-privatelink). For more information about AWS PrivateLink, see [AWS PrivateLink and VPC endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/endpoint-services-overview.html). ## Considerations for AWS IoT Wireless VPC endpoints Before you set up an interface VPC endpoint for AWS IoT Wireless, ensure that you review [Interface endpoint properties and limitations](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#vpce-interface-limitations) in the *Amazon VPC User Guide*. AWS IoT Wireless supports making calls to all of its API actions from your VPC. VPC endpoint policies are not supported for AWS IoT Wireless. By default, full access to AWS IoT Wireless is allowed through the endpoint. For more information, see [Controlling access to services with VPC endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-access.html) in the *Amazon VPC User Guide*. ## AWS IoT Core for LoRaWAN privatelink architecture The following diagram shows the privatelink architecture of AWS IoT Core for LoRaWAN. The architecture uses a Transit Gateway and Route 53 Resolver to share the AWS PrivateLink interface endpoints between your VPC, the AWS IoT Core for LoRaWAN VPC, and an on-premises environment. You'll find a more detailed architecture diagram when setting up the connection to the VPC interface endpoints. ![\[Image showing how you can use AWS PrivateLink to connect to AWS IoT Core for LoRaWAN endpoints.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-lorawan-privatelink-architecture.png) ## AWS IoT Core for LoRaWAN endpoints AWS IoT Core for LoRaWAN has three public endpoints. Each public endpoint has a corresponding VPC interface endpoint. The public endpoints can be classified into control plane and data plane endpoints. For information about these endpoints, see [AWS IoT Core for LoRaWAN API endpoints](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#iot-wireless_region). + **Control plane API endpoints** You can use control plane API endpoints to interact with the AWS IoT Wireless APIs. These endpoints can be accessed from a client that is hosted in your Amazon VPC by using AWS PrivateLink. + **Data plane API endpoints** Data plane API endpoints are LoRaWAN Network Server (LNS) and Configuration and Update Server (CUPS) endpoints that you can use to interact with the AWS IoT Core for LoRaWAN LNS and CUPS endpoints. These endpoints can be accessed from your LoRa gateways on premises by using Site-to-Site VPN or AWS Direct Connect. You get these endpoints when onboarding your gateway to AWS IoT Core for LoRaWAN. For more information, see [Add a gateway to AWS IoT Core for LoRaWAN](lorawan-onboard-gateway-add.md). **Topics** + [ ## Considerations for AWS IoT Wireless VPC endpoints ](#vpc-endpoint-considerations) + [ ## AWS IoT Core for LoRaWAN privatelink architecture ](#vpc-endpoint-architecture) + [ ## AWS IoT Core for LoRaWAN endpoints ](#vpc-lorawan-endpoints) + [ # Onboard AWS IoT Core for LoRaWAN control plane API endpoint ](lorawan-onboard-control-endpoint.md) + [ # Onboard AWS IoT Core for LoRaWAN data plane API endpoints ](onboard-lns-cups-endpoints.md) # Onboard AWS IoT Core for LoRaWAN control plane API endpoint You can use AWS IoT Core for LoRaWAN control plane API endpoints to interact with the AWS IoT Wireless APIs. For example, you can use this endpoint to run the [SendDataToWirelessDevice](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToWirelessDevice.html) API to send data from AWS IoT to your LoRaWAN device. For more information, see [AWS IoT Core for LoRaWAN Control Plane API Endpoints](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#iot-core.html#iot-wireless-control-plane-endpoints). You can use the client hosted in your Amazon VPC to access the control plane endpoints that are powered by AWS PrivateLink. You use these endpoints to connect to the AWS IoT Wireless API through an interface endpoint in your Virtual Private Cloud (VPC) instead of connecting over the public internet. **Topics** + [ ## Create your Amazon VPC and subnet ](#create-vpc) + [ ## Launch an Amazon EC2 instance in your subnet ](#launch-ec2-instance) + [ ## Create Amazon VPC interface endpoint ](#create-vpc-endpoint) + [ ## Test your connection to the interface endpoint ](#connect-vpc-endpoint) ## Create your Amazon VPC and subnet Before you can connect to the interface endpoint, you must create a VPC and subnet. You'll then launch an EC2 instance in your subnet, which you can use to connect to the interface endpoint. To create your VPC: 1. Navigate to the [VPCs](https://console.aws.amazon.com/vpc/home#/vpcs) page of the Amazon VPC console and choose **Create VPC**. 1. On the **Create VPC** page: + Enter a name for **VPC Name tag - optional** (for example, **VPC-A**). + Enter an IPv4 address range for your VPC in the **IPv4 CIDR** (for example, **10.100.0.0/16**). + If you want to create dualstack VPC endpoints in your VPC, choose **Amazon-provided IPv6 CIDR block** for **IPv6 CIDR block**. 1. Keep the default values for other fields and choose **Create VPC**. To create your subnet: 1. Navigate to the [Subnets](https://console.aws.amazon.com/vpc/home#/subnets) page of the Amazon VPC console and choose **Create subnet**. 1. On the **Create subnet** page: + For **VPC ID**, choose the VPC that you created earlier (for example, `VPC-A`). + Enter a name for **Subnet name** (for example, **Private subnet**). + Choose the **Availability Zone** for your subnet. + Enter your subnet's IP address block in the **IPv4 subnet CIDR block** in CIDR format (for example, **10.100.0.0/24**). + If you want to create dualstack endpoints, choose the **IPv6 VPC CIDR block** for your VPC. Optionally, you can customize the **IPv6 subnet CIDR block**. 1. To create your subnet and add it to your VPC, choose **Create subnet**. For more information, see [Work with VPCs and subnets](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html). ## Launch an Amazon EC2 instance in your subnet To launch your EC2 instance: 1. Navigate to the [Amazon EC2](https://console.aws.amazon.com/ec2/home#/) console and choose **Launch Instance**. 1. For AMI, choose **Amazon Linux 2 AMI (HVM), SSD Volume Type** and then choose the **t2 micro** instance type. To configure the instance details, choose **Next**. 1. In the **Configure Instance Details** page: + For **Network**, choose the VPC that you created earlier (for example, `VPC-A`). + For **Subnet**, choose the subnet that you created earlier (for example, **Private subnet**). **Note** If you provided an IPv6 CIDR block for your VPC and subnet, you can optionally choose to auto-assign an IPv6 IP address for your EC2 instance. + For **IAM role**, choose the role **AWSIoTWirelessFullAccess** to grant AWS IoT Core for LoRaWAN full access policy. For more information, see [`AWSIoTWirelessFullAccess` policy summary](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSIoTWirelessFullAccess$serviceLevelSummary). + For **Assume Private IP**, use an IP address, for example, **10.100.0.42**. 1. Choose **Next: Add Storage** and then choose **Next: Add Tags**. You can optionally add any tags to associate with your EC2 instance. Choose **Next: Configure Security Group**. 1. In the **Configure Security Group** page, configure the security group to allow: + Open **All TCP** for Source as `10.200.0.0/16`. + Open **All ICMP - IPV4** for Source as `10.200.0.0/16`. 1. To review the instance details and launch your EC2 instance, choose **Review and Launch**. For more information, see [Get started with Amazon EC2 Linux instances](https://docs.aws.amazon.com/AWSEC2/latest/userguide/EC2_GetStarted.html). ## Create Amazon VPC interface endpoint You can create a VPC endpoint for your VPC, which can then be accessed by the EC2 API. To create the endpoint: 1. Navigate to the [VPC](https://console.aws.amazon.com/vpc/home#/endpoints) **Endpoints** console and choose **Create Endpoint**. 1. In the **Create Endpoint** page, specify the following information. + Choose **AWS services** for **Service category**. + For **Service Name**, search by entering the keyword **iotwireless**. In the list of `iotwireless` services displayed, choose the control plane API endpoint for your Region. The endpoint will be in the format `com.amazonaws.region.iotwireless.api`. + For **VPC** and **Subnets**, choose the VPC where you want to create the endpoint, and the Availability Zones (AZs) in which you want to create the endpoint network. **Note** The `iotwireless` service might not support all Availability Zones. + For **Enable DNS name**, choose **Enable for this endpoint**. Choosing this option will automatically resolve the DNS and create a route in Amazon Route 53 Public Data Plane so that the APIs you use later to test the connection will go through the privatelink endpoints. + For **Security group**, choose the security groups you want to associate with the endpoint network interfaces. + Optionally, you can add or remove tags. Tags are name-value pairs that you use to associate with your endpoint. 1. To create your VPC endpoint, choose **Create endpoint**. ## Test your connection to the interface endpoint You can use an SSH to access your Amazon EC2 instance and then use the AWS CLI to connect to the privatelink interface endpoints. Before you connect to the interface endpoint, download the most recent AWS CLI version by following the instructions described in [Installing, updating, and uninstalling AWS CLI version 2 on Linux](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-linux.html). The following examples show how you can test your connection to the interface endpoint using the CLI. ``` aws iotwireless create-service-profile \ --endpoint-url https://api.iotwireless.region.amazonaws.com \ --name='test-privatelink' ``` The following shows a sample response of running the command. ``` { "Arn": "arn:aws:iotwireless:region:acct_number:ServiceProfile/1a2345ba-4c5d-67b0-ab67-e0c8342f2857", "Id": "1a2345ba-4c5d-67b0-ab67-e0c8342f2857" } ``` Similarly, you can run the following commands to get the service profile information or list all service profiles. ``` aws iotwireless get-service-profile \ --endpoint-url https://api.iotwireless.region.amazonaws.com --id="1a2345ba-4c5d-67b0-ab67-e0c8342f2857" ``` The following shows an example for the list-device-profiles command. ``` aws iotwireless list-device-profiles \ --endpoint-url https://api.iotwireless.region.amazonaws.com ``` # Onboard AWS IoT Core for LoRaWAN data plane API endpoints AWS IoT Core for LoRaWAN data plane endpoints consist of the following endpoints. You get these endpoints when adding your gateway to AWS IoT Core for LoRaWAN. For more information, see [Add a gateway to AWS IoT Core for LoRaWAN](lorawan-onboard-gateway-add.md). + **LoRaWAN Network Server (LNS) endpoints** The LNS endpoints are of the format `account-specific-prefix.lns.lorawan.region.amazonaws.com`. You can use this endpoint to establish a connection for exchanging LoRa uplink and downlink messages. + **Configuration and Update Server (CUPS) endpoints** The CUPS endpoints are of the format `account-specific-prefix.cups.lorawan.region.amazonaws.com`. You can use this endpoint for credentials management, remote configuration, and firmware update of gateways. For more information, see [Using CUPS and LNS protocols](lorawan-manage-gateways.md#lorawan-cups-lns-protocols). To find the Data Plane API endpoints for your AWS account and Region, use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iotwireless/get-service-endpoint.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iotwireless/get-service-endpoint.html) CLI command shown here, or the [https://docs.aws.amazon.com//iotwireless/latest/apireference/API_GetServiceEndpoint.html](https://docs.aws.amazon.com//iotwireless/latest/apireference/API_GetServiceEndpoint.html) REST API. For more information, see [AWS IoT Core for LoRaWAN Data Plane API Endpoints](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#iot-core.html#iot-wireless-data-plane-endpoints). You can connect your LoRaWAN gateway on premises to communicate with AWS IoT Core for LoRaWAN endpoints. To establish this connection, first connect your on premises gateway to your AWS account in your VPC by using a VPN connection. You can then communicate with the data plane interface endpoints in the AWS IoT Core for LoRaWAN VPC that are powered by privatelink. **Topics** + [ # Create VPC interface endpoint and private hosted zone ](create-vpc-lns-cups.md) + [ # Use VPN to connect LoRa gateways to your AWS account ](lorawan-vpc-vpn-connection.md) # Create VPC interface endpoint and private hosted zone AWS IoT Core for LoRaWAN has two data plane endpoints, Configuration and Update Server (CUPS) endpoint and LoRaWAN Network Server (LNS) endpoint. The setup process to establish a privatelink connection to both endpoints is the same, so we can use the LNS endpoint for illustration purposes. For your data plane endpoints, the LoRa gateways first connect to your AWS account in your Amazon VPC, which then connects to the VPC endpoint in the AWS IoT Core for LoRaWAN VPC. When connecting to the endpoints, the DNS names can be resolved within one VPC but can't be resolved across multiple VPCs. To disable private DNS when creating the endpoint, disable the **Enable DNS name** setting. You can use private hosted zone to provide information about how you want Route 53 to respond to DNS queries for your VPCs. To share your VPC with an on-premises environment, you can use a Route 53 Resolver to facilitate hybrid DNS. **Topics** + [ ## Create an Amazon VPC and subnet ](#lns-create-vpc) + [ ## Create an Amazon VPC interface endpoint ](#lns-create-vpc-endpoint) + [ ## Configure private hosted zone ](#create-phz-lns) + [ ## Configure Route 53 inbound resolver ](#configure-route53-resolver) + [ ## Next steps ](#lns-cups-next-steps) ## Create an Amazon VPC and subnet You can reuse your Amazon VPC and subnet that you created when onboarding your control plane endpoint. For information, see [Create your Amazon VPC and subnet](lorawan-onboard-control-endpoint.md#create-vpc). ## Create an Amazon VPC interface endpoint You can create a VPC endpoint for your VPC, which is similar to how you would create one for your control plane endpoint. 1. Navigate to the [VPC](https://console.aws.amazon.com/vpc/home#/endpoints) **Endpoints** console and choose **Create Endpoint**. 1. In the **Create Endpoint** page, specify the following information. + Choose **AWS services** for **Service category**. + For **Service Name**, search by entering the keyword **lns**. In the list of `lns` services displayed, choose the LNS data plane API endpoint for your Region. The endpoint will be of the format `com.amazonaws.region.lorawan.lns`. **Note** If you're following this procedure for your CUPS endpoint, search for `cups`. The endpoint will be of the format `com.amazonaws.region.lorawan.cups`. + For **VPC** and **Subnets**, choose the VPC where you want to create the endpoint, and the Availability Zones (AZs) in which you want to create the endpoint network. **Note** The `iotwireless` service might not support all Availability Zones. + For **Enable DNS name**, make sure that **Enable for this endpoint** is not selected. By not selecting this option, you can disable private DNS for the VPC endpoint and use private hosted zone instead. + For **Security group**, choose the security groups you want to associate with the endpoint network interfaces. + Optionally, you can add or remove tags. Tags are name-value pairs that you use to associate with your endpoint. 1. To create your VPC endpoint, choose **Create endpoint**. ## Configure private hosted zone After you create the privatelink endpoint, in the **Details** tab of your endpoint, you'll see a list of DNS names. You can use one of these DNS names to configure your private hosted zone. The DNS name will be of the format `vpce-xxxx.lns.lorawan.region.vpce.amazonaws.com`. **Topics** + [ ### Create the private hosted zone ](#create-phz-how) + [ ### Create a record ](#create-phz-record) ### Create the private hosted zone To create the private hosted zone: 1. Navigate to the [Route 53](https://console.aws.amazon.com/route53/v2/hostedzones#/) **Hosted zones** console and choose **Create hosted zone**. 1. In the **Create hosted zone** page, specify the following information. + For **Domain name**, enter the full service name for your LNS endpoint, **lns.lorawan.region.amazonaws.com**. **Note** If you're following this procedure for your CUPS endpoint, enter **cups.lorawan.region.amazonaws.com**. + For **Type**, choose **Private hosted zone**. + Optionally, you can add or remove tags to associate with your hosted zone. 1. To create your private hosted zone, choose **Create hosted zone**. For more information, see [Creating a private hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zone-private-creating.html). After you have created a private hosted zone, you can create a record that tells the DNS how you want traffic to be routed to that domain. ### Create a record After you have created a private hosted zone, you can create a record that tells the DNS how you want traffic to be routed to that domain. How you create the record depends on whether you want to route the traffic to an IPv4 or an IPv6 address. When routing traffic to an IPv4 address, choose the record type A. When routing traffic to an IPv6 address, choose the record type AAAA. The following steps show how you how to create a record for both A and AAAA record types. **Topics** + [ #### Create record of type A (for IPv4 traffic) ](#create-phz-record-typeA) + [ #### Create record of type AAAA (for IPv6 traffic) ](#create-phz-record-typeAAAA) #### Create record of type A (for IPv4 traffic) To create a record of type A, perform the following steps. 1. In the list of hosted zones displayed, choose the private hosted zone that you created earlier and choose **Create record**. 1. Use the wizard method to create the record. If the console presents you the **Quick create** method, choose **Switch to wizard**. 1. Choose **Simple Routing** for **Routing policy** and then choose **Next**. 1. In the **Configure records** page, choose **Define simple record**. 1. In the **Define simple record** page: + For **Record name**, enter the alias of your AWS account number. You get this value when onboarding your gateway or by using the [https://docs.aws.amazon.com//iotwireless/latest/apireference/API_GetServiceEndpoint.html](https://docs.aws.amazon.com//iotwireless/latest/apireference/API_GetServiceEndpoint.html) REST API. + For **Record type**, keep the value as `A - Routes traffic to an IPv4 address and some AWS resources`. + For **Value/Route traffic to**, choose **Alias to VPC endpoint**. Then choose your **Region** and then choose the endpoint that you created previously, as described in [Create an Amazon VPC interface endpoint](#lns-create-vpc-endpoint) from the list of endpoints displayed. 1. Choose **Define simple record** to create your record. #### Create record of type AAAA (for IPv6 traffic) When you use the record type AAAA, you'll not be able to use the **Alias to VPC endpoint** option for the **Value/Route traffic to** field. Instead, you can perform the following steps when creating a record of type AAAA. 1. Create an EC2 instance in a subnet that has access to the VPC endpoint. **Note** You must make sure that the VPC and subnet that you created supports routing of IPv6 traffic. For information about the steps to be performed, see [Create your Amazon VPC and subnet](lorawan-onboard-control-endpoint.md#create-vpc). 1. Create an EC2 instance in a subnet that has access to the VPC endpoint. For information about the steps to be performed, see [Launch an Amazon EC2 instance in your subnet](lorawan-onboard-control-endpoint.md#launch-ec2-instance). 1. Create an Amazon VPC interface endpoint for the VPC that you created. For information about the steps to be performed, see [Create Amazon VPC interface endpoint](lorawan-onboard-control-endpoint.md#create-vpc-endpoint). 1. SSH into the EC2 instance and run the following command. In this command, replace ** with the domain name for your VPC interface endpoint. You can obtain this information from the **DNS names** section in the details page of the endpoint that you created. ``` nslookup ``` Running this command will generate information about the domain, such as the IP address, DNS record, and nameservers. 1. In the response obtained from the `nslookup` command, copy the IP address returned from the **Non-authoritative answer** section. Store this information securely as you'll need to use it when creating the record. 1. Go to the [Route 53](https://console.aws.amazon.com/route53/v2/hostedzones#/)**Hosted zones** console, and in the list of hosted zones displayed, choose the private hosted zone that you created earlier and choose **Create record**. 1. Use the wizard method to create the record. If the console presents you the **Quick create** method, choose **Switch to wizard**. 1. Choose **Simple Routing** for **Routing policy** and then choose **Next**. 1. In the **Configure records** page, choose **Define simple record**. 1. In the **Define simple record** page: + For **Record name**, enter the alias of your AWS account number. You get this value when onboarding your gateway or by using the [https://docs.aws.amazon.com//iotwireless/latest/apireference/API_GetServiceEndpoint.html](https://docs.aws.amazon.com//iotwireless/latest/apireference/API_GetServiceEndpoint.html) REST API. + For **Record type**, keep the value as `AAAA - Routes traffic to an IPv6 address and some AWS resources`. + For **Value/Route traffic to**, choose **IP address or another value, depending on the record type** and then enter the IP address that you obtained using the `nslookup` command. 1. Choose **Define simple record** to create your record. ## Configure Route 53 inbound resolver To share a VPC endpoint to an on-premises environment, a Route 53 Resolver can be used to facilitate hybrid DNS. The inbound resolver will enable you to route traffic from the on-premises network to the data plane endpoints without going over the public internet. To return the private IP address values for your service, create the Route 53 Resolver in the same VPC as the VPC endpoint. When you create the inbound resolver, you only have to specify your VPC and the subnets that you created previously in your Availability Zones (AZs). The Route 53 Resolver uses this information to automatically assigns an IP address to route traffic to each of the subnets. To create the inbound resolver: 1. Navigate to the [Route 53](https://console.aws.amazon.com/route53/v2/inbound-endpoints#/) **Inbound endpoints** console and choose **Create inbound endpoint**. **Note** Make sure that you're using the same AWS Region that you used when creating the endpoint and private hosted zone. 1. In the **Create inbound endpoint** page, specify the following information. + Enter a name for **Endpoint name** (for example, **VPC\$1A\$1Test**). + For **VPC in the region**, choose the same VPC that you used when creating the VPC endpoint. + Configure the **Security group for this endpoint** to allow incoming traffic from the on premises network. + For IP address, choose **Use an IP address that is selected automatically.** 1. Choose **Submit** to create your inbound resolver. For this eample, let's assume that the IP addresses `10.100.0.145` and `10.100.192.10` were assigned for the inbound Route 53 Resolver for routing traffic. ## Next steps You've created the private hosted zone and an inbound resolver to route traffic for your DNS entries. You can now use either a Site-to-Site VPN or a Client VPN endpoint. For more information, see [Use VPN to connect LoRa gateways to your AWS account](lorawan-vpc-vpn-connection.md). # Use VPN to connect LoRa gateways to your AWS account To connect your gateways on premises to your AWS account, you can use either a Site-to-Site VPN connection or a Client VPN endpoint. Before you can connect your on premises gateways, you must have created the VPC endpoint, and configured a private hosted zone and inbound resolver so that traffic from the gateways don't go over the public internet. For more information, see [Create VPC interface endpoint and private hosted zone](create-vpc-lns-cups.md). ## Site-to-Site VPN endpoint If you don't have the gateway hardware or want to test the VPN connection using a different AWS account, you can use a Site-to-Site VPN connection. You can use Site-to-Site VPN to connect to the VPC endpoints from the same AWS account or another AWS account that you might be using in a different AWS Region. **Note** If you've the gateway hardware with you and want to set up a VPN connection, we recommend that you use Client VPN instead. For instructions, see [Client VPN endpoint](#vpc-client-vpn). To set up a Site-to-Site VPN: 1. Create another VPC in the site from which you want to set up the connection. For `VPC-A`, you can reuse the VPC that you created previously. To create another VPC (for example, `VPC-B`), use a CIDR block that doesn't overlap with the CIDR block of the VPC you created previously. For information about setting up the VPCs, follow the instructions described in [AWS setup Site-to-Site VPN connection](samples/Setup_Site_to_Site_VPN.zip). **Note** The Site-to-Site VPN VPN method described in the document uses OpenSWAN for the VPN connection, which supports only one VPN tunnel. If you use a different commercial software for the VPN, you might be able to set up two tunnels bettween the sites. 1. After you set up the VPN connection, update the `/etc/resolv.conf` file by adding the inbound resolver's IP address from your AWS account. You use this IP address for the nameserver. For information about how to obtain this IP address, see [Configure Route 53 inbound resolver](create-vpc-lns-cups.md#configure-route53-resolver). For this example, we can use the IP address `10.100.0.145` that was assigned when you created the Route 53 Resolver. ``` options timeout:2 attempts:5 ; generated by /usr/sbin/dhclient-script search region.compute.internal nameserver 10.100.0.145 ``` 1. We can now test whether the VPN connection uses the AWS PrivateLink endpoint instead of going over the public internet by using an `nslookup` command. The following shows an example of running the command. ``` nslookup account-specific-prefix.lns.lorawan.region.amazonaws.com ``` The following shows an example output of running the command, which shows a private IP address indicating that the connection has been established to the AWS PrivateLink LNS endpoint. ``` Server: 10.100.0.145 Address: 10.100.0.145 Non-authoritative answer: Name: https://xxxxx.lns.lorawan.region.amazonaws.com Address: 10.100.0.204 ``` For information about using a Site-to-Site VPN connection, see [How Site-to-Site VPN works](https://docs.aws.amazon.com/vpn/latest/s2svpn/how_it_works.html). ## Client VPN endpoint AWS Client VPN is a managed client-based VPN service that enables you to securely access AWS resources and resources in your on-premises network. The following shows the architecture for the client VPN service. ![\[Image showing how you can use AWS Client VPN to connect your LoRa gateway on premises.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/lorawan-privatelink-client-vpn.png) To establish a VPN connection to a Client VPN endpoint: 1. Create a Client VPN endpoint by following the instructions described in [ Getting started with AWS Client VPN](https://docs.aws.amazon.com/vpn/latest/clientvpn-admin/cvpn-getting-started.html). 1. Log in to your on-premises network (for example, a Wi-Fi router) by using the access URL for that router (for example, `192.168.1.1`), and find the root name and password. 1. Set up your LoRaWAN gateway by following the instructions in the gateway's documentation and then add your gateway to AWS IoT Core for LoRaWAN. For information about how to add your gateway, see [Onboard your gateways to AWS IoT Core for LoRaWAN](lorawan-onboard-gateways.md). 1. Check whether your gateway's firmware is up to date. If the firmware is out of date, you can follow the instructions provided in the on-premises network to update your gateway's firmware. For more information, see [Update gateway firmware using CUPS service with AWS IoT Core for LoRaWAN](lorawan-update-firmware.md). 1. Check whether OpenVPN has been enabled. If it has been enabled, skip to the next step to configure the OpenVPN client inside the on-premises network. If it hasn't been enabled, follow the instructions in [Guide to install OpenVPN for OpenWrt](https://www.ovpn.com/en/guides/openwrt). **Note** For this example, we use OpenVPN. You can use other VPN clients such as Site-to-Site VPN or AWS Direct Connect to set up your Client VPN connection. 1. Configure the OpenVPN client based on information from the client configuration and how you can use [OpenVPN client using LuCi](https://openwrt.org/docs/guide-user/services/vpn/openvpn/client-luci). 1. SSH to your on-premises network and update the `/etc/resolv.conf` file by adding the IP address of the inbound resolver in your AWS account (`10.100.0.145`). 1. For the gateway traffic to use AWS PrivateLink to connect to the endpoint, replace the first DNS entry for your gateway to the inbound resolver's IP address. For information about using a Site-to-Site VPN connection, see [Getting started with Client VPN](https://docs.aws.amazon.com/vpn/latest/clientvpn-user/user-getting-started.html). ## Connect to LNS and CUPS VPC endpoints The following shows how you can test your connection to the LNS and CUPS VPC endpoints. **Test CUPS endpoint** To test your AWS PrivateLink connection to the CUPS endpoint from your LoRa gateway, run the following command: ``` curl -k -v -X POST https://xxxx.cups.region.iotwireless.iot:443/update-info --cacert cups.trust --cert cups.crt --key cups.key --header "Content-Type: application/json" --data '{ "router": "xxxxxxxxxxxxx", "cupsUri": "https://xxxx.cups.lorawan.region.amazonaws.com:443", "cupsCredCrc":1234, "tcCredCrc":552384314 }' —output cups.out ``` **Test LNS endpoint** To test your LNS endpoint, first provision a LoRaWAN device that will work with your wireless gateway. You can then add your device and perform the *join* procedure after which you can start sending uplink messages.