IoT Data

Introduction

IoT Data provides secure, bi-directional communication between Internet-connected things, such as sensors, actuators, embedded devices, or smart appliances, and the AWS Cloud. It allows you to connect your devices to the cloud and interact with them using the AWS Management Console, AWS CLI, or AWS SDKs.

LocalStack allows you to use the IoT Data APIs to update, get, and delete the shadow of a thing in your local environment. The supported APIs are available on our API Coverage Page, which provides information on the extent of IoT Data integration with LocalStack.

Getting started

This guide is designed for users new to IoT Data and assumes basic knowledge of the AWS CLI and our awslocal wrapper script.

Start your LocalStack container using your preferred method. We will demonstrate how to create a thing, update its shadow, get its shadow, and delete its shadow using IoT Data.

Update the shadow

You can update the shadow of a thing using the UpdateThingShadow API. Run the following command to update the shadow of a thing named MyRPi:

$ awslocal iot-data update-thing-shadow \
    --thing-name "MyRPi" \
    --payload "{\"state\":{\"reported\":{\"moisture\":\"okay\"}}}" \
    output.txt --cli-binary-format raw-in-base64-out

The output.txt file contains the following output:

{
    "state": {
        "reported": {
            "moisture": "okay"
        }
    },
    "metadata": {
        "reported": {
            "moisture": {
                "timestamp": 1724226109
            }
        }
    },
    "version": 1,
    "timestamp": 1724226109
}

Get the shadow

You can get the shadow of a thing using the GetThingShadow API. Run the following command to get the shadow:

$ awslocal iot-data get-thing-shadow \
    --thing-name "MyRPi" \
    output.txt

The output.txt will contain the same output as the previous command.

Delete the shadow

You can delete the shadow of a thing using the DeleteThingShadow API. Run the following command to delete the shadow:

$ awslocal iot-data delete-thing-shadow \
    --thing-name "MyRPi" \
    output.txt

The output.txt will contain the following output:

{
    "version": 1,
    "timestamp": 1724226371
}

Device Shadows

LocalStack supports both unnamed (classic) and named device shadows.

You can use AWS CLI and MQTT topics to get, update or delete device shadow state information.

The endpoint as returned by DescribeEndpoint currently does not support the device shadow REST API