AWS IoT Core - Amazon Timestream
PrerequisitesUsing the consoleUsing the CLISample applicationVideo tutorial

AWS IoT Core

You can collect data from IoT devices using AWS IoT Core and route the data to Amazon Timestream through IoT Core rule actions. AWS IoT rule actions specify what to do when a rule is triggered. You can define actions to send data to an Amazon Timestream table, an Amazon DynamoDB database, and invoke an AWS Lambda function.

The Timestream action in IoT Rules is used to insert data from incoming messages directly into Timestream. The action parses the results of the IoT Core SQL statement and stores data in Timestream. The names of the fields from returned SQL result set are used as the measure::name and the value of the field is the measure::value.

For example, consider the SQL statement and the sample message payload: 

SELECT temperature, humidity from 'iot/topic'
{
  "dataFormat": 5, 
  "rssi": -88,
  "temperature": 24.04,    
  "humidity": 43.605,    
  "pressure": 101082,    
  "accelerationX": 40,    
  "accelerationY": -20,    
  "accelerationZ": 1016,    
  "battery": 3007,    
  "txPower": 4,    
  "movementCounter": 219,    
  "device_id": 46216,
  "device_firmware_sku": 46216   
}

If an IoT Core rule action for Timestream is created with the SQL statement above, two records will be added to Timestream with measure names temperature and humidity and measure values of 24.04 and 43.605, respectively.

You can modify the measure name of a record being added to Timestream by using the AS operator in the SELECT statement. The SQL statement below will create a record with the message name temp instead of temperature.

The data type of the measure are inferred from the data type of the value of the message payload. JSON data types such as integer, double, boolean, and string are mapped to Timestream data types of BIGINT, DOUBLE, BOOLEAN, and VARCHAR respectively. Data can also be forced to specific data types using the cast() function. You can specify the timestamp of the measure. If the timestamp is left blank, the time that the entry was processed is used.

You can refer to the Timestream rules action documentation for additional details

To create an IoT Core rule action to store data in Timestream, follow the steps below:

Prerequisites

  1. Create a database in Amazon Timestream using the instructions described in Create a database.

  2. Create a table in Amazon Timestream using the instructions described in Create a table.

Using the console

  1. Use the AWS Management Console for AWS IoT Core to create a rule by clicking on Manage > Messsage routing > Rules followed by Create rule.

  2. Set the rule name to a name of your choice and the SQL to the text shown below

    SELECT temperature as temp, humidity from 'iot/topic'

  3. Select Timestream from the Action list

  4. Specify the Timestream database, table, and dimension names along with the role to write data into Timestream. If the role does not exist, you can create one by clicking on Create Roles

  5. To test the rule, follow the instructions shown here.

Using the CLI

If you haven't installed the AWS Command Line Interface (AWS CLI), do so from here.

  1. Save the following rule payload in a JSON file called timestream_rule.json. Replace arn:aws:iam::123456789012:role/TimestreamRole with your role arn which grants AWS IoT access to store data in Amazon Timestream

    { 
    "actions": [ 
            { 
                "timestream": { 
                    "roleArn": "arn:aws:iam::123456789012:role/TimestreamRole", 
                    "tableName": "devices_metrics", 
                    "dimensions": [ 
                        { 
                            "name": "device_id", 
                            "value": "${clientId()}" 
                        }, 
                        { 
                            "name": "device_firmware_sku", 
                            "value": "My Static Metadata" 
                        } 
                    ], 
                    "databaseName": "record_devices" 
                } 
            } 
    ], 
    "sql": "select * from 'iot/topic'", 
    "awsIotSqlVersion": "2016-03-23", 
    "ruleDisabled": false 
}

  2. Create a topic rule using the following command

    aws iot create-topic-rule --rule-name timestream_test --topic-rule-payload file://<path/to/timestream_rule.json> --region us-east-1

  3. Retrieve details of topic rule using the following command

    aws iot get-topic-rule --rule-name timestream_test

  4. Save the following message payload in a file called timestream_msg.json

    {
  "dataFormat": 5, 
  "rssi": -88,
  "temperature": 24.04,    
  "humidity": 43.605,    
  "pressure": 101082,    
  "accelerationX": 40,    
  "accelerationY": -20,    
  "accelerationZ": 1016,    
  "battery": 3007,    
  "txPower": 4,    
  "movementCounter": 219,    
  "device_id": 46216,
  "device_firmware_sku": 46216   
}

  5. Test the rule using the following command

    aws iot-data publish --topic 'iot/topic' --payload file://<path/to/timestream_msg.json>

Sample application

To help you get started with using Timestream with AWS IoT Core, we've created a fully functional sample application that creates the necessary artifacts in AWS IoT Core and Timestream for creating a topic rule and a sample application for publishing a data to the topic.

  1. Clone the GitHub repository for the sample application for AWS IoT Core integration following the instructions from GitHub

  2. Follow the instructions in the README to use an AWS CloudFormation template to create the necessary artifacts in Amazon Timestream and AWS IoT Core and to publish sample messages to the topic.

Video tutorial

This video explains how IoT Core works with Timestream.