Get started using AWS IoT Core for Amazon Sidewalk

Create IAM role

Create an IAM role that grants AWS IoT Core for Amazon Sidewalk permission to send data to the AWS IoT rule. To create the role, use the CreateRole API operation or create-role CLI command. You can name the role as SidewalkRole.

aws iam create-role --role-name lambda-ex \ 
    --assume-role-policy-document file://lambda-trust-policy.json

Create an AWS IoT rule for the destination

Create an AWS IoT rule that will process the device's data and specify the topic to which messages are published. You'll observe messages on this topic after connecting to the hardware platform. Use the AWS IoT Core API operation, CreateTopicRule, or the AWS CLI command, create-topic-rule, to create a rule for the destination.

aws iot create-topic-rule --rule-name Sidewalkrule \ 
    --topic-rule-payload file://myrule.json

Create a destination

Create a destination that associates your Sidewalk device with the IoT rule (or MQTT topic) that processes it for use with other AWS services. You can add a destination using the Destinations hub of the AWS IoT console, or the CreateDestination API operation or the create-destination CLI command. You'll send your Sidewalk end device's uplink data and location data to these destinations.

aws iotwireless create-destination --name SidewalkDestination \
    --expression-type RuleName --expression SidewalkRule \
    --role-arn arn:aws:iam::123456789012:role/SidewalkRole

Alternatively, if you want to provide an MQTT topic as the destination, replace the expression-type option with MqttTopic instead of RuleName. Replace SidewalkRule with the topic name.

Create a device profile

Create a device profile that contains the shared configurations for your Sidewalk devices. When creating the profile, specify a name for the profile as an alphanumeric string. To create a profile, either go to the Sidewalk tab of the Profiles hub in the AWS IoT console and choose Create profile, or use the CreateDeviceProfile API operation or the create-device-profile CLI command as shown in this example.

// Add your device profile using a name and the sidewalk object.
aws iotwireless create-device-profile --name sidewalk_profile --sidewalk {}

Create your Sidewalk end device and optionally get the device location

1. Create your Sidewalk end device

   Create your Sidewalk end device with AWS IoT Core for Amazon Sidewalk. Specify a destination name and the ID of the device profile obtained from the previous step. To add a device, either go to the Sidewalk tab of the Devices hub in the AWS IoT console and choose Provision device, or use the CreateWirelessDevice API operation or the create-wireless-device CLI command as shown in this example.

   Note

   Specify a name for your destination that's unique to your AWS account and AWS Region. You'll use the same destination name when you add your destination to AWS IoT Core for Amazon Sidewalk.

   // Add your Sidewalk device by using the device profile ID.
   aws iotwireless create-wireless-device
       --type "Sidewalk"
       --name "sidewalk_device" \
       --destination-name "SidewalkDestination" \
       --sidewalk DeviceProfileId="12345678-234a-45bc-67de-e8901234f0a1"

2. (Optional) Create your Sidewalk end device and get the Sidewalk device location

   If you want to enable location data when you create your Sidewalk end device with AWS IoT Core for Amazon Sidewalk, enable positioning. Replace LocationDestination with the destination to which you want to send the device location data to. The destination can either be an AWS AWS IoT rule or an MQTT topic. You can use the destination you created in Step 1 above as your UplinkDestination. Alternatively, you can specify a different destination as LocationDestination.

   AWS IoT Core for Amazon Sidewalk resolves the location of your Sidewalk end device using Bluetooth Low Energy (BLE), Wi-Fi, or GNSS uplink messages published by your Sidewalk end device. For more information on AWS IoT's location resolution capabilities, see AWS IoT Core Device Location.

   Note

   You must enable positioning to use the device location feature.

   If you enable device location for the Sidewalk-enabled device, your raw uplink payload won't be propagated to the destination.

   // Add your Sidewalk device by using the device profile ID.
   aws iotwireless create-wireless-device  --type "Sidewalk" --name ""sidewalk_device" \
     --description "My Sidewalk Device Description" \
     --positioning "Enabled" \
     --destination-name "UplinkDestination" \
     --sidewalk DeviceProfileId="12345678-234a-45bc-67de-e8901234f0a1",Positioning={DestinationName="LocationDestination"}

   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.

(Optional) Update your existing Sidewalk end device and get the device's location data

If you've already provisioned a Sidewalk end device in AWS IoT Wireless, you can update the device to get the device location data.

Replace LocationDestination with the destination name from the destination to which you want to send the device location data to.

aws iotwireless update-wireless-device  --id wireless-device-id \
  --positioning "Enabled" \
  --sidewalk Positioning={DestinationName="LocationDestination"}

Get device profile and wireless device information

Get the device profile and wireless device information as a JSON. The JSON will contain information about the device details, device certificates, private keys, DeviceTypeId, and the Sidewalk manufacturing serial number (SMSN).

Connect your Sidewalk end device

Connect the HDK to your computer and follow the instructions provided by the vendor documentation to connect to your HDK. For more information, see Provisioning and registering your end device in the Amazon Sidewalk documentation.

View and exchange messages

Use the MQTT client to subscribe to the topic specified in the rule and view the message received. You can also use the SendDataToWirelessDevice API operation or the send-data-to-wireless-device CLI command to send a downlink message to your device and verify the connectivity status.

(Optional) You can enable the message delivery status event to check whether the downlink message was successfully received.

aws iotwireless send-data-to-wireless-device \
    --id "<Wireless_Device_ID>" \
    --payload-data "SGVsbG8gVG8gRGV2c2lt" \
    --wireless-metadata Sidewalk={Seq=1,AckModeRetryDurationSecs=10}