# Event notifications for AWS IoT Wireless AWS IoT Wireless can publish messages to notify you of events for your LoRaWAN and Sidewalk devices. For example, the device registration event notifies you when the Sidewalk devices in your account have been registered. ## How your resources can be notified of events When certain events occur, AWS IoT Wireless publishes event notifications. For example, when you've provisioned your Sidewalk device, it generates an event. Each event causes a single event notification to be sent. Event notifications are published over MQTT with a JSON payload. The content of the payload depends on the type of event. **Note** Event notifications are published at least once. It's possible for them to be published more than once. The ordering of event notifications is not guaranteed. ### Events and resource types The following table shows the different types of events for which you'll receive notifications. The event types depend on whether the resource type is a wireless device, a wireless gateway, or a Sidewalk account. You can also enable events for your resources at the resource level. This applies to all resources of a particular type, or for select resources, as described in the following section. For more information, see [Event notifications for LoRaWAN resources](iot-wireless-events-notifications.md#iot-lorawan-events) and [Event notifications for Sidewalk resources](iot-wireless-events-notifications.md#iot-sidewalk-events). **Event types based on resources** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-wireless-events.html) ### Policy for receiving wireless event notifications To receive event notifications, your device must use an appropriate policy. The policy allows it to connect to the AWS IoT device gateway and subscribe to MQTT event topics. You must also subscribe to the appropriate topic filters. The following is an example policy. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": [ "arn:aws:iotwireless:us-east-1:111122223333:/$aws/iotwireless/events/join/*", "arn:aws:iotwireless:us-east-1:111122223333:/$aws/iotwireless/events/connection_status/*", "arn:aws:iotwireless:us-east-1:111122223333:/$aws/iotwireless/events/device_registration_state/*", "arn:aws:iotwireless:us-east-1:111122223333:/$aws/iotwireless/events/proximity/*" ] } ] } ``` ### Format of MQTT topics for wireless events To send you event notifications, AWS IoT uses MQTT reserved topics that begin with a dollar sign (\$1). You can publish and subscribe to these reserved topics. However, you can't create new topics that begin with a dollar sign. **Note** MQTT topics are specific to your AWS account and use the format `arn:aws:iotwireless:aws-region:AWS-account-ID:topic/Topic`. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT developer guide*. Reserved MQTT topics for wireless devices use the following format: + **Resource-level topics** These topics apply to all resources of a particular type in your AWS account. `$aws/iotwireless/events/{eventName}/{eventType}/{resourceType}/resources` + **Identifier-level topics** These topics apply to select resources of a particular type, specified by the resource identifier. `$aws/iotwireless/events/{eventName}/{eventType}/{resourceType}/{resourceIdentifierType}/{resourceID}/{id}` For more information about topics at resource and identifier levels, see [Event configurations](iot-wireless-control-events.md#iot-wireless-control-events-config). The following table shows examples of MQTT topics for the various events: **Events and MQTT topics** | Event | MQTT topic | Notes | | --- | --- | --- | | Sidewalk device registration state | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-wireless-events.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-wireless-events.html) | | Sidewalk proximity | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-wireless-events.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-wireless-events.html) | | LoRaWAN join | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-wireless-events.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-wireless-events.html) | | LoRaWAN gateway connection status | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-wireless-events.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-wireless-events.html) | For more information about the different events, see [Event notifications for LoRaWAN resources](iot-wireless-events-notifications.md#iot-lorawan-events) and [Event notifications for Sidewalk resources](iot-wireless-events-notifications.md#iot-sidewalk-events). If you've subscribed to these topics, you'll be notified when a message is published to one of the topics. For more information, see [MQTT reserved topics](https://docs.aws.amazon.com/iot/latest/developerguide/reserved-topics.html) in the *AWS IoT developer guide*. ## Pricing for wireless events For information about pricing for subscribing to events and for receiving notifications, see [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/). # Enable events for wireless resources Before subscribers to the reserved topics can receive messages, you must enable event notifications. To do this, you can use the AWS Management Console, or the AWS IoT Wireless API or AWS CLI. ## Event configurations You can configure events to send notifications to either all resources that belong to a particular type, or for individual wireless resources. The resource type can be a wireless gateway, Sidewalk partner account, or a wireless device, which can be a LoRaWAN or Sidewalk device. For information about the type of events that you can enable for your wireless devices, see [Event notifications for LoRaWAN resources](iot-wireless-events-notifications.md#iot-lorawan-events) and [Event notifications for Sidewalk resources](iot-wireless-events-notifications.md#iot-sidewalk-events). **All resources** You can enable events such that all resources in your AWS account that belong to a particular resource type receives notifications. For example, you can enable an event that notifies you of changes to connection status for all LoRaWAN gateways that you've onboarded with AWS IoT Core for LoRaWAN. Monitoring these events will help you get notified in cases such as when certain LoRaWAN gateways in your resource fleet get disconnected or if a beacon is lost for a number of Sidewalk devices in your AWS account. **Individual resources** You can also add individual LoRaWAN and Sidewalk resources to your event configuration and enable notifications for them. This will help you monitor individual resources of a particular type. For example, you can add select LoRaWAN and Sidewalk devices to your configuration and receive notifications for join or device registration state events for these resources. ## Prerequisites Your LoRaWAN or Sidewalk resource must have an appropriate policy that allows it to receive event notifications. For more information, see [Policy for receiving wireless event notifications](iot-wireless-events.md#iot-wireless-events-policy). ## Enable notifications using the AWS Management Console To enable event messages from the console, go to the [Settings](https://console.aws.amazon.com/iot/home#/settings/) tab of the AWS IoT console, and then go to the **LoRaWAN and Sidewalk event notification** section. You can enable notifications for all resources in your AWS account that belong to a particular resource type and monitor them. **To enable notifications for all resources** 1. In the **LoRaWAN and Sidewalk event notification** section, go to the **All resources** tab, choose **Action**, and then choose **Manage events**. 1. Enable the events that you want to monitor, and then choose **Update events**. If you no longer want to monitor certain events, choose **Action** and choose **Manage events**, and then disable those events. You can also enable notifications for individual resources in your AWS account that belong to a particular resource type and monitor them. **To enable notifications for individual resources** 1. In the **LoRaWAN and Sidewalk event notification** section, choose **Action**, and then choose **Add resources**. 1. Select the resources and events for which you want to receive notifications: 1. Choose whether you want to monitor events for your **LoRaWAN resources** or **Sidewalk resources**. 1. Depending on the resource type, you can choose the events you want to enable for the resources. You can then subscribe to these events and receive notifications. If you choose: + **LoRaWAN resources**: You can enable **join** events for your LoRaWAN devices or **connection status** events for your LoRaWAN gateways. + Sidewalk resources: You can enable **device registration state** or **proximity** events or both for your Sidewalk partner accounts and Sidewalk devices. 1. Depending on the resource type and events that you chose, select the wireless devices or gateways that you want to monitor. You can select up to 250 resources for all resources combined. 1. Choose **Submit** to add your resources. The resources that you add will appear with their MQTT topics in the tab for your resource type in the **LoRaWAN and Sidewalk event notification** section of the console. + **LoRaWAN join** events and events for your Sidewalk devices will appear in the **Wireless devices** section of the console. + **Connection status** events for your LoRaWAN gateways will appear in the **Wireless gateways** section. + **Device registration state** and **proximity** events for your Sidewalk accounts will appear in the **Sidewalk accounts** tab. **Subscribe to topics using MQTT client** Depending on whether you enabled events for all resources or for individual resource types, the events that you enabled will appear in the console with their MQTT topics on the **All resources** tab or the tab for the specified resource type. + If you choose one of the MQTT topics, you can go to the MQTT client to subscribe to these topics and receive messages. + If you've added multiple events, you can subscribe to multiple event topics and receive notifications for them. To subscribe to multiple topics, choose your topics, and choose **Action** and then choose **Subscribe**. ## Enable notifications using the AWS CLI You can configure events and add resources to your configuration by using the AWS IoT Wireless API or the AWS CLI. **Enable notifications for all resources** You can enable notifications for all resources in your AWS account that belong to a particular resource type and monitor them by using the [UpdateEventConfigurationByResourceTypes](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateResourceEventConfiguration.html) API or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-event-configuration-by-resource-types.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-event-configuration-by-resource-types.html) CLI command. For example: ``` aws iotwireless update-event-configuration-by-resource-types \ --cli-input-json input.json ``` **Contents of input.json** ``` { "DeviceRegistrationState": { "Sidewalk": { "AmazonIdEventTopic": "Enabled" } }, "ConnectionStatus": { "LoRaWAN": { "WirelessGatewayEventTopic": "Enabled" } } } ``` **Note** All quotation marks (") are escaped with a backslash (\$1). You can get the current event configuration by calling the [GetEventConfigurationByResourceTypes](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetResourceEventConfiguration.html) API or by using the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-event-configuration-by-resource-types.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-event-configuration-by-resource-types.html) CLI command. For example: ``` aws iotwireless get-event-configuration-by-resource-types ``` **Enable notifications for individual resources** To add individual resources to your event configuration and control which events are published by using the API or CLI, call the [UpdateResourceEventConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateResourceEventConfiguration.html) API or use the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-resource-event-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-resource-event-configuration.html) CLI command. For example: ``` aws iotwireless update-resource-event-configuration \ --identifer 1ffd32c8-8130-4194-96df-622f072a315f \ --identifier-type WirelessDeviceId \ --cli-input-json input.json ``` **Contents of input.json** ``` { "Join": { "LoRaWAN": { "DevEuiEventTopic": "Disabled" }, "WirelessDeviceIdEventTopic": "Enabled" } } ``` **Note** All quotation marks (") are escaped with a backslash (\$1). You can get the current event configuration by calling the [GetResourceEventConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetResourceEventConfiguration.html) API or by using the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-resource-event-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-resource-event-configuration.html) CLI command. For example: ``` aws iotwireless get-resource-event-configuration \ --identifier-type WirelessDeviceId \ --identifier 1ffd32c8-8130-4194-96df-622f072a315f ``` **List event configurations** You can also use the AWS IoT Wireless API or the AWS CLI to list event configurations where at least one event topic has been enabled. To list configurations, use the [ListEventConfigurations](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListEventConfigurations.html) API operation or by using the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-event-configurations.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/list-event-configurations.html) CLI command. For example: ``` aws iotwireless list-event-configurations --resource-type WirelessDevice ``` # Event notifications for wireless resources You can use the AWS Management Console or AWS IoT Wireless API operations to notify you of events for your Sidewalk devices, and your LoRaWAN devices and gateways. For information about event notifications and how to enable them, see [Event notifications for AWS IoT Wireless](iot-wireless-events.md) and [Enable events for wireless resources](iot-wireless-control-events.md). ## Event notifications for LoRaWAN resources Events that you can enable for your LoRaWAN resources include: + Join events that notify you of join events for your LoRaWAN device. You'll receive notifications when a device joins with AWS IoT Core for LoRaWAN, or when a rejoin request of type 0 or type 2 is received. + Connection status events that notify you when the connection status of your LoRaWAN gateway changes to connected or disconnected. ## Event notifications for Sidewalk resources Events that you can enable for your Sidewalk resources include: + Device events that notify you of changes to the state of your Sidewalk device, such as when the device has been registered and is ready to use. + Proximity events that notify you when AWS IoT Wireless receives a notification from Amazon Sidewalk that a beacon has been discovered or lost. + Message delivery status events that notify you about the status of messages that are exchanged between your Sidewalk devices and AWS IoT Wireless. The following sections contain more information about the events for your LoRaWAN and Sidewalk resources. **Topics** + [Event notifications for LoRaWAN resources](#iot-lorawan-events) + [Event notifications for Sidewalk resources](#iot-sidewalk-events) + [Enable notifications for LoRaWAN join events](iot-lorawan-join-events.md) + [Enable notifications for LoRaWAN gateway connection status events](iot-lorawan-gateway-events.md) + [Enable notifications for Sidewalk device registration state events](iot-sidewalk-device-events.md) + [Enable notifications for Sidewalk proximity events](iot-sidewalk-proximity-events.md) + [Enable notifications for message delivery status events](iot-sidewalk-message-delivery-events.md) # Enable notifications for LoRaWAN join events AWS IoT Core for LoRaWAN can publish messages to notify you of join events for LoRaWAN devices that you onboard to AWS IoT. Join events notify you when a join or rejoin request of type 0 or type 2 is received, and the device has joined with AWS IoT Core for LoRaWAN. ## How join events work When you onboard your LoRaWAN devices with AWS IoT Core for LoRaWAN, AWS IoT Core for LoRaWAN performs a *join* procedure for your device with AWS IoT Core for LoRaWAN. Your device then becomes activated for use and can send an uplink message to indicate that it's available. After the device has joined, uplink and downlink messages can be exchanged between your device and AWS IoT Core for LoRaWAN. For more information about onboarding your device, see [Onboard your devices to AWS IoT Core for LoRaWAN](lorawan-onboard-end-devices.md). You can enable events to notify you when your device has joined with AWS IoT Core for LoRaWAN. You'll also be notified if the join event fails and when a rejoin request of type 0 or type 2 is received, and when it's accepted. ## Enable LoRaWAN join events Before subscribers to the LoRaWAN join reserved topics can receive messages, you must enable event notifications for them from the AWS Management Console, or by using the API or CLI. You can enable these events for all LoRaWAN resources in your AWS account or for select resources. For information about how to enable these events, see [Enable events for wireless resources](iot-wireless-control-events.md). ## Format of MQTT topics for LoRaWAN events Reserved MQTT topics for LoRaWAN devices use the following format. If you've subscribed to these topics, then all LoRaWAN devices that are registered to your AWS account can receive the notification: + **Resource-level topics** `$aws/iotwireless/events/{eventName}/{eventType}/lorawan/wireless_devices` + **Identifier topics** `$aws/iotwireless/events/{eventName}/{eventType}/lorawan/wireless_devices/{resourceID}/{id}` Where: **\$1eventName\$1** \$1eventName\$1 must be `join`. **\$1eventType\$1** \$1eventType\$1 can be: + `join_req_received` + `rejoin_req_0_received` + `rejoin_req_2_received` + `join_accepted` **\$1resourceID\$1** \$1resourceID\$1 can be `dev_eui` or `wireless_device_id`. For example, you can subscribe to the following topics to receive an event notification when AWS IoT Core for LoRaWAN has accepted a join request from your devices. `$aws/iotwireless/events/join/join_accepted/lorawan/wireless_devices/wireless_device_id/{id}` You can also use the `+` wildcard character to subscribe to multiple topics at the same time. The `+` wildcard character matches any string in the level that contains the character, such as the following topic: `$aws/iotwireless/events/join/join_req_received/lorawan/wireless_devices/wireless_device_id/+` **Note** You can't use the wildcard character `#` to subscribe to the reserved topics. For more information about using the `+` wildcard when subscribing to topics, see [MQTT topic filters](https://docs.aws.amazon.com/iot/latest/developerguide/topicfilters.html) in the *AWS IoT developer guide*. ## Message payload for LoRaWAN join event The following shows the message payload for the LoRaWAN join event. ``` { // General fields "eventId": "string", "eventType": "join_req_received|rejoin_req_0_received|rejoin_req_2_received|join_accepted", "WirelessDeviceId": "string", "timestamp": "timestamp", // Event-specific fields "LoRaWAN": { "DevEui": "string", // The fields below are optional indicating that it can be a null value. "DevAddr": "string", "JoinEui": "string", "AppEui": "string", } } ``` The payload contains the following attributes: **eventId** A unique event ID that's generated by AWS IoT Core for LoRaWAN (string). **eventType** The type of event that occurred. Can be one of the following values: + `join_req_received`: This field will show the EUI parameters `JoinEui` or `AppEui` + `rejoin_req_0_received` + `rejoin_req_2_received` + `join_accepted`: This field will show the `NetId` and `DevAddr`. **wirelessDeviceId** The ID of the LoRaWAN device. **timestamp** The Unix timestamp of when the event occurred. **DevEui** The unique identifier of the device found on the device label or device documentation. **DevAddr and EUIs (optional)** These fields are the optional device address and the EUI parameters `JoinEUI` or `AppEUI`. # Enable notifications for LoRaWAN gateway connection status events AWS IoT Core for LoRaWAN can publish messages to notify you of connection status events for LoRaWAN gateways that you onboard to AWS IoT. Connection status events notify you when the connection status of a LoRaWAN gateway changes to connected or disconnected. ## How connection status events work After you've onboarded your gateway to AWS IoT Core for LoRaWAN, you can connect your gateway to AWS IoT Core for LoRaWAN and verify its connection status. This event notifies you when your gateway connection status changes to connected or disconnected. For more information about onboarding and connecting your gateway to AWS IoT Core for LoRaWAN, see [Onboard your gateways to AWS IoT Core for LoRaWAN](lorawan-onboard-gateways.md) and [Connect your LoRaWAN gateway and verify its connection status](lorawan-gateway-connection-status.md). ## Format of MQTT topics for LoRaWAN gateways Reserved MQTT topics for LoRaWAN gateways use the following format. If you've subscribed to these topics, then all LoRaWAN gateways that are registered to your AWS account can receive the notification: + For resource-level topics: `$aws/iotwireless/events/{eventName}/{eventType}/lorawan/wireless_gateways` + For identifier topics: `$aws/iotwireless/events/{eventName}/{eventType}/lorawan/wireless_gateways/{resourceID}/{id}` Where: **\$1eventName\$1** \$1eventName\$1 must be `connection_status`. **\$1eventType\$1** \$1eventType\$1 can be `connected` or `disconnected`. **\$1resourceID\$1** \$1resourceID\$1 can be `gateway_eui` or `wireless_gateway_id`. For example, you can subscribe to the following topics to receive an event notification when all your gateways have connected to AWS IoT Core for LoRaWAN: `$aws/iotwireless/events/connection_status/connected/lorawan/wireless_gateways/wireless_gateway_id/{id}` You can also use the `+` wildcard character to subscribe to multiple topics at the same time. The `+` wildcard character matches any string in the level that contains the character, such as the following topic: `$aws/iotwireless/events/connection_status/connected/lorawan/wireless_gateways/wireless_gateway_id/+` **Note** You can't use the wildcard character `#` to subscribe to the reserved topics. For more information about using the `+` wildcard when subscribing to topics, see [MQTT topic filters](https://docs.aws.amazon.com/iot/latest/developerguide/topicfilters.html) in the *AWS IoT developer guide*. ## Message payload for connection status events The following shows the message payload for the connection status event. ``` { // General fields "eventId": "string", "eventType": "connected|disconnected", "WirelessGatewayId": "string", "timestamp": "timestamp", // Event-specific fields "LoRaWAN": { "GatewayEui": "string" } } ``` The payload contains the following attributes: **eventId** A unique event ID that's generated by AWS IoT Core for LoRaWAN (string). **eventType** The type of event that occurred. Can be `connected` or `disconnected`. **wirelessGatewayId** The ID of the LoRaWAN gateway. **timestamp** The ISO timestamp of when the event occurred. **GatewayEui** The unique identifier of the gateway found on the gateway label or gateway documentation. # Enable notifications for Sidewalk device registration state events Device registration state events publish event notifications when there is a change in the device registration state, such as when a Sidewalk device has been provisioned or registered. The events provide you information about the different states that the device goes through from when it's provisioned to when it has been registered. ## How device registration state events work When you onboard your Sidewalk device with Amazon Sidewalk and AWS IoT Wireless, AWS IoT Wireless performs a `create` operation and adds your Sidewalk device to your AWS account. Your device then enters the provisioned state and the `eventType` becomes `provisioned`. For more information about onboarding your device, see [Get started using AWS IoT Core for Amazon Sidewalk](sidewalk-getting-started.md). After the device has been `provisioned`, Amazon Sidewalk performs a `register` operation to register your Sidewalk device with AWS IoT Wireless. The registration process starts, where the encryption and session keys are set up with AWS IoT. When the device is registered, the `eventType` becomes `registered`, and your device is ready to use. After the device has been `registered`, Sidewalk can send a request to `deregister` your device. AWS IoT Wireless then fulfills the request and changes the device state back to `provisioned`. For more information about the device states, see [DeviceState](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SidewalkDeviceMetadata.html#iotwireless-Type-SidewalkDeviceMetadata-DeviceState). ## Enable notifications for device registration state events Before subscribers to the device registration state reserved topics can receive messages, you must enable event notifications for them from the AWS Management Console, or by using the API or CLI. You can enable these events for all Sidewalk resources in your AWS account or for select resources. For information about how to enable these events, see [Enable events for wireless resources](iot-wireless-control-events.md). ## Format of MQTT topics for device registration state events To notify you of device registration state events, you can subscribe to MQTT reserved topics that begin with a dollar (\$1) sign. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT developer guide*. Reserved MQTT topics for Sidewalk device registration state events use the following format: + For resource-level topics: `$aws/iotwireless/events/{eventName}/{eventType}/sidewalk/wireless_devices` + For identifier topics: `$aws/iotwireless/events/{eventName}/{eventType}/sidewalk/{resourceType}/{resourceID}/{id}` Where: **\$1eventName\$1** \$1eventName\$1 must be `device_registation_state`. **\$1eventType\$1** \$1eventType\$1 can be `provisioned` or `registered`. **\$1resourceType\$1** \$1resourceType\$1 can be `sidewalk_accounts` or `wireless_devices`. **\$1resourceID\$1** \$1resourceID\$1 is `amazon_id` for \$1resourceType\$1 of `sidewalk_accounts` and `wireless_device_id` for \$1resourceType\$1 of `wireless_devices`. You can also use the `+` wildcard character to subscribe to multiple topics at the same time. The `+` wildcard character matches any string in the level that contains the character. For example, if you want to be notified of all possible event types (`provisioned` and `registered`) and for all devices registered to a particular Amazon ID, you can use the following topic filter: `$aws/iotwireless/events/device_registration_state/+/sidewalk/sidewalk_accounts/amazon_id/+` **Note** You can't use the wildcard character `#` to subscribe to the reserved topics. For more information about topic filters, see [MQTT topic filters](https://docs.aws.amazon.com/iot/latest/developerguide/topicfilters.html) in the *AWS IoT developer guide*. ## Message payload for device registration state events After you enable notifications for device registration state events, event notifications are published over MQTT with a JSON payload. These events contain the following example payload: ``` { "eventId": "string", "eventType": "provisioned|registered", "WirelessDeviceId": "string", "timestamp": "timestamp", // Event-specific fields "operation": "create|deregister|register", "Sidewalk": { "AmazonId": "string", "SidewalkManufacturingSn": "string" } } ``` The payload contains the following attributes: **eventId** A unique event ID (string). **eventType** The type of event that occurred. Can be `provisioned` or `registered`. **wirelessDeviceId** The identifier of the wireless device. **timestamp** The Unix timestamp of when the event occurred. **operation** The operation that triggered the event. Valid values are `create`, `register`, and `deregister`. **sidewalk** The Sidewalk Amazon ID or `SidewalkManufacturingSn` for which you want to receive event notifications. # Enable notifications for Sidewalk proximity events Proximity events publish event notifications when AWS IoT receives a beacon from the Sidewalk device. When your Sidewalk device approaches Amazon Sidewalk, beacons that are sent from your device are filtered by Amazon Sidewalk at regular intervals and received by AWS IoT Wireless. AWS IoT Wireless then notifies you of these events when a beacon is received. ## How proximity events work Proximity events notify you when AWS IoT receives a beacon, Your Sidewalk devices can emit beacons any time. When your device is near Amazon Sidewalk, Sidewalk receives the beacons and forwards them to AWS IoT Wireless at regular time intervals. Amazon Sidewalk has configured this time interval as 10 minutes. When AWS IoT Wireless receives the beacon from Sidewalk, you'll be notified of the event. Proximity events will notify you when a beacon is discovered or when a beacon is lost. You can configure the intervals at which you're notified of the proximity event. ## Enable notifications for proximity events Before subscribers to the Sidewalk proximity reserved topics can receive messages, you must enable event notifications for them from the AWS Management Console, or by using the API or CLI. You can enable these events for all Sidewalk resources in your AWS account or for select resources. For information about how to enable these events, see [Enable events for wireless resources](iot-wireless-control-events.md). ## Format of MQTT topics for proximity events To notify you of proximity events, you can subscribe to MQTT reserved topics that begin with a dollar (\$1) sign. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT developer guide*. Reserved MQTT topics for Sidewalk proximity events use the format: + For resource-level topics: `$aws/iotwireless/events/{eventName}/{eventType}/sidewalk/wireless_devices` + For identifier topics: `$aws/iotwireless/events/{eventName}/{eventType}/sidewalk/{resourceType}/{resourceID}/{id}` Where: **\$1eventName\$1** \$1eventName\$1 must be `proximity`. **\$1eventType\$1** \$1eventType\$1 can be `beacon_discovered` or `beacon_lost`. **\$1resourceType\$1** \$1resourceType\$1 can be `sidewalk_accounts` or `wireless_devices`. **\$1resourceID\$1** \$1resourceID\$1 is `amazon_id` for \$1resourceType\$1 of `sidewalk_accounts` and `wireless_device_id` for \$1resourceType\$1 of `wireless_devices`. You can also use the `+` wildcard character to subscribe to multiple topics at the same time. The `+` wildcard character matches any string in the level that contains the character. For example, if you want to be notified of all possible event types (`beacon_discovered` and `beacon_lost`) and for all devices registered to a particular Amazon ID, you can use the following topic filter: `$aws/iotwireless/events/proximity/+/sidewalk/sidewalk_accounts/amazon_id/+` **Note** You can't use the wildcard character `#` to subscribe to the reserved topics. For more information about topic filters, see [MQTT topic filters](https://docs.aws.amazon.com/iot/latest/developerguide/topicfilters.html) in the *AWS IoT developer guide*. ## Message payload for proximity events After you enable notifications for proximity events, event messages are published over MQTT with a JSON payload. These events contain the following example payload: ``` { "eventId": "string", "eventType": "beacon_discovered|beacon_lost", "WirelessDeviceId": "string", "timestamp": "1234567890123", // Event-specific fields "Sidewalk": { "AmazonId": "string", "SidewalkManufacturingSn": "string" } } ``` The payload contains the following attributes: **eventId** A unique event ID, which is a string. **eventType** The type of event that occurred. Can be `beacon_discovered` or `beacon_lost`. **WirelessDeviceId** The identifier of the wireless device. **timestamp** The Unix timestamp of when the event occurred. **sidewalk** The Sidewalk Amazon ID or `SidewalkManufacturingSn` for which you want to receive event notifications. # Enable notifications for message delivery status events Message delivery status events publish event notifications about the status of messages that are exchanged between your Sidewalk devices and AWS IoT Wireless. Event notifications are published for both downlink messages that are sent from AWS IoT Wireless to the Sidewalk device, and uplink messages that are sent from your device to AWS IoT Wireless. ## How message delivery status events work After you've onboarded your Sidewalk device to AWS IoT Wireless and connected your device, messages can be exchanged between your device and AWS IoT Wireless. The events publish notifications about the message delivery status that indicate whether these messages were successfully delivered to your device or to AWS IoT Wireless. For example, if an uplink message is received from the device with an acknowledge (ACK) flag, a notification is published indicating that the message was delivered successfully. When you send downlink messages from AWS IoT Wireless to the Sidewalk device, the `SendDataToWirelessDevice` API returns a `MessageId` for the downlink message even if packets have dropped or the message wasn't delivered. In this case, the message delivery status events return an error indicating that the message failed to deliver to the device. ## Enable notifications for message delivery status events Before subscribers to the Sidewalk message delivery status reserved topics can receive messages, you must enable event notifications for them using the AWS IoT Wireless API or the AWS CLI. You can enable these events for all Sidewalk resources in your AWS account or for select resources. **Note** The Sidewalk message delivery status event configuration isn't available in the console. For information about how to enable these events, see [Enable notifications using the AWS CLI](iot-wireless-control-events.md#iot-wireless-control-events-cli). ## Format of MQTT topics for message delivery status events To receive notifications about message delivery status events, you can subscribe to MQTT reserved topics that begin with a dollar (\$1) sign. For more information, see [topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html). Reserved MQTT topics for Sidewalk proximity events use the format: + For resource-level topics: `$aws/iotwireless/events/{eventName}/{eventType}/sidewalk/wireless_devices` + For identifier topics: `$aws/iotwireless/events/{eventName}/{eventType}/sidewalk/{resourceType}/{resourceID}/{id}` Where: **\$1eventName\$1** \$1eventName\$1 must be `message_delivery_status`. **\$1eventType\$1** \$1eventType\$1 can be `success` or `error`. **\$1resourceType\$1** \$1resourceType\$1 can be `sidewalk_accounts` or `wireless_devices`. **\$1resourceID\$1** \$1resourceID\$1 is `amazon_id` for \$1resourceType\$1 of `sidewalk_accounts` and `wireless_device_id` for \$1resourceType\$1 of `wireless_devices`. You can also use the `+` wildcard character to subscribe to multiple topics at the same time. The `+` wildcard character matches any string in the level that contains the character. For example, if you want to be notified of all possible event types (`success` and `error`) and for all devices registered to a particular Amazon ID, you can use the following topic filter: `$aws/iotwireless/events/message_delivery_status/+/sidewalk/sidewalk_accounts/amazon_id/+` **Note** You can't use the wildcard character `#` to subscribe to the reserved topics. For more information about topic filters, see [topicfilters](https://docs.aws.amazon.com/iot/latest/developerguide/topicfilters.html). ## Message payload for message delivery status events After you enable notifications for message delivery status events, event messages are published over MQTT with a JSON payload. These events contain the following example payload depending on whether the event is a success, indicating that the device successfully received the message, or an error. **Success events** The following shows the payload format when the event is a success. ``` { "eventId": "string", "eventType": "success", "WirelessDeviceId": "string", "timestamp": "timestamp", "Sidewalk": { "Seq": "Integer", "MsgType": "CUSTOM_COMMAND_ID_RESP", "CmdExStatus": "COMMAND_EXEC_STATUS_SUCCESS", "Rssi": "Integer", "LinkType": "LoRa" | "BLE" | "FSK" } } ``` The payload contains the following attributes: **eventId** A unique event ID, which is a string. **eventType** The type of event that occurred. Can be `success` or `error`. In this case, the `eventType` is `error`. **WirelessDeviceId** The identifier of the wireless device. **timestamp** The Unix timestamp of when the event occurred. **sidewalk** The Sidewalk wrapper that contains the status code for success messages, sequence number of message, message type, received signal strength indicator, and the type of link used for the event. **Error events** The following shows the payload format when the event indicates that an error occurred. ``` { "eventId": "string", "eventType": "error" , "WirelessDeviceId": "string", "timestamp": "timestamp", "Sidewalk": { "Seq": "Integer", "Status": "DeviceNotReachable" | "RADIO_TX_ERROR" | "MEMORY_ERROR" } } ``` The payload contains similar attributes as when the `eventType` is a `success`. Following are some differences or additional attributes: **eventType** The type of event that occurred. In this case, the `eventType` is an `error`. **sidewalk** The Sidewalk wrapper that contains the sequence number and the status code that indicates why the downlink message wasn't sent successfully.