Connect your Sidewalk device and view uplink metadata format - Amazon IoT Core
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).

Connect your Sidewalk device and view uplink metadata format

In this tutorial, you'll use the MQTT test client to test the connectivity and see messages exhanged between your end device and the Amazon Web Services Cloud. To receive messages, in the MQTT test client, subscribe to the topic specified when creating the IoT rule for your destination. You can also send a downlink message from Amazon IoT Core for Amazon Sidewalk to your device using the SendDataToWirelessDevice API operation. You can verify that the message was delivered by enabling the message delivery status event notification.


For information about connecting your hardware platform and setting it up, see Provisioning and registering your end device and Setting up the hardware development kit (HDK) in the Amazon Sidewalk documentation..

Use the SendDataToWirelessDevice API operation or the send-data-to-wireless-device CLI command to send downlink messages from Amazon IoT Core for Amazon Sidewalk to your Sidewalk end device. Following shows an example of how to run this command. The payload data is the binary to be sent, encoded in base64.

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

Following shows a sample output of running this command, which is an ID of the downlink message sent to the device.

{ MessageId: "6011dd36-0043d6eb-0072-0008" }

The SendDataToWirelessDevice API can return a message ID but the message might not be successfully delivered. To check the status of the message that was sent to the device, you can enable message delivery status events for your Sidewalk accounts and devices. For information about how to enable this event, see Enable events for Sidewalk devices. For more information about this event type, see Message delivery events.

After you've connected your device, you can subscribe to the topic (for example, project/sensor/observed) that you specified when creating the destination rule, and observe uplink messages from the device.

If you specified a topic name when creating your destination, you can subscribe to the topic to monitor uplink messages from your end device. Go to the MQTT test client on the Test page of the Amazon IoT console, enter the topic name (for example, project/sensor/observed), and then choose Subscribe.

The following example shows the format of the uplink messages that are sent from Sidewalk devices to Amazon IoT. The WirelessMetadata contains metadata about the message request.

{ "MessageId": "6011dd36-0043d6eb-0072-0008", "PayloadData": "ZjRlNjY1ZWNlNw==", "WirelessDeviceId": "wireless_device_id", "WirelessMetadata": { "Sidewalk": { "CmdExStatus": "Cmd", "SidewalkId": "device_id", "Seq": 0, "MessageType": "messageType" } } }

The following table shows a definition of the different parameters in the uplink metadata. The device-id is the ID of the wireless device, such as ABCDEF1234 and the messageType is the type of uplink message that's received from the device.

Sidewalk uplink metadata parameters
Parameter Description Type Required

The message payload that is sent from the wireless device.

String Yes
WirelessDeviceID The identifier of the wireless device that's sending the data String Yes

Command runtime status. Response-type messages shall include the status code, COMMAND_EXEC_STATUS_SUCCESS. However, notifications might not include the status code.

Enumeration No

Response nack status, which can be RADIO_TX_ERROR or MEMORY_ERROR.

Array of strings No