Event notifications for Amazon IoT Wireless - Amazon IoT Core
How your resources can be notified of eventsPricing for wireless events
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Event notifications for Amazon IoT Wireless

Amazon IoT Wireless can publish messages to notify you of events for LoRaWAN and Sidewalk devices that you onboard to Amazon IoT Core. For example, you can be notified of events such as when the Sidewalk devices in your account have been provisioned or registered.

How your resources can be notified of events

Event notifications are published when certain events occur. For example, events are generated when your Sidewalk device is provisioned. 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, which applies to all resources of a particular type, or for select resources, as described in the following section. For more information about the different event types, see Event notifications for LoRaWAN resources and Event notifications for Sidewalk resources.

Event types based on resources
Resource Resource type Event type
Wireless device LoRaWAN Join
Sidewalk

  • Device registration state

  • Proximity

  • Message delivery status
Wireless gateway LoRaWAN Connection status
Sidewalk account Sidewalk

  • Device registration state

  • Proximity

  • Message delivery status

Policy for receiving wireless event notifications

To receive event notifications, your IAM role or user must use an appropriate policy that allows it to connect to the Amazon IoT device gateway and subscribe to MQTT event topics. You must also subscribe to the appropriate topic filters.

The following is an example of the policy required for receiving notifications for the various wireless events.

{
    "Version":"2012-10-17",
    "Statement":[{
        "Effect":"Allow",
        "Action":"iot:Subscribe",
        "Resource":[
            "arn:aws:iot:region:account:topicfilter/$aws/iotwireless/events/join/*",
            "arn:aws:iot:region:account:topicfilter/$aws/iotwireless/events/connection_status/*",
            "arn:aws:iot:region:account:topicfilter/$aws/iotwireless/events/device_registration_state/*", 
            "arn:aws:iot:region:account:topicfilter/$aws/iotwireless/events/proximity/*",
            "arn:aws:iot:region:account:topicfilter/$aws/iotwireless/events/message_delivery_status/*"
        ]
    },
    {
        "Effect":"Allow",
        "Action":"iot:Receive",        
        "Resource":[
            "arn:aws:iot:region:account:topic/$aws/iotwireless/events/join/*",
            "arn:aws:iot:region:account:topic/$aws/iotwireless/events/connection_status/*",
            "arn:aws:iot:region:account:topic/$aws/iotwireless/events/device_registration_state/*", 
            "arn:aws:iot:region:account:topic/$aws/iotwireless/events/proximity/*",
            "arn:aws:iot:region:account:topic/$aws/iotwireless/events/message_delivery_status/*"
        ]
    }]
}

Format of MQTT topics for wireless events

To send you notifications of events for your wireless resources, Amazon IoT uses MQTT reserved topics that begin with a dollar sign ($). 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 Amazon Web Services account and use the format arn:aws:iotwireless:aws-region:Amazon-account-ID:topic/Topic. For more information, see MQTT topics.

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 Amazon Web Services account that you've onboarded to Amazon IoT Wireless.

    $aws/iotwireless/events/{eventName}/{eventType}/{resourceType}/resources

  • Identifier-level topics

    These topics apply to select resources of a particular type in your Amazon Web Services account that you've onboarded to Amazon IoT Wireless, 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.

The following table shows examples of MQTT topics for the various events:

Events and MQTT topics
Event MQTT topic Notes
Sidewalk device registration state
  • Resource-level topic

    $aws/iotwireless/events/device_registration_state/{eventType}/sidewalk/wireless_devices

  • Identifier-level topic

    $aws/iotwireless/events/device_registration_state/{eventType}/sidewalk/{resourceType}/{resourceID}/{id}

  • {eventType} can be registered or provisioned

  • {resourceType} can be sidewalk_accounts or wireless_devices

  • {resourceID} is the amazon_id for sidewalk_accounts and wireless_device_id for wireless_devices
Sidewalk proximity
  • Resource-level topic

    $aws/iotwireless/events/proximity/{eventType}/sidewalk/wireless_devices

  • Identifier-level topic

    $aws/iotwireless/events/proximity/{eventType}/sidewalk/{resourceType}/{resourceID}/{id}

  • {eventType} can be beacon_discovered or beacon_lost

  • {resourceType} can be sidewalk_accounts or wireless_devices

  • {resourceID} is the amazon_id for sidewalk_accounts and wireless_device_id for wireless_devices
Sidewalk message delivery status
  • Resource-level topic

    $aws/iotwireless/events/message_delivery_status/{eventType}/sidewalk/wireless_devices

  • Identifier-level topic

    $aws/iotwireless/events/message_delivery_status/{eventType}/sidewalk/{resourceType}/{resourceID}/{id}

  • {eventType} can be success or error

  • {resourceType} can be sidewalk_accounts or wireless_devices

  • {resourceID} is the amazon_id for sidewalk_accounts and wireless_device_id for wireless_devices
LoRaWAN join
  • Resource-level topic

    $aws/iotwireless/events/join/{eventType}/lorawan/wireless_devices

  • Identifier-level topic

    $aws/iotwireless/events/join/{eventType}/lorawan/wireless_devices/{resourceID}/{id}

  • {eventType} can be join_req_0_received or join_req_2_received or join_accepted

  • {resourceID} can be wireless_device_id or dev_eui
LoRaWAN gateway connection status
  • Resource-level topic

    $aws/iotwireless/events/join/{eventType}/lorawan/wireless_gateways

  • Identifier-level topic

    $aws/iotwireless/events/join/{eventType}/lorawan/wireless_gateways/{resourceID}/{id}

  • {eventType} can be connected or disconnected

  • {resourceID} can be wireless_gateway_id or gateway_eui

For more information about the different events, see Event notifications for LoRaWAN resources and Event notifications for Sidewalk resources.

If you've subscribed to these topics, you'll be notified when a message is published to one of the event notification topics. For more information, see Reserved topics.

Pricing for wireless events

For information about pricing for subscribing to events and for receiving notifications, see Amazon IoT Core pricing.