Skip to Main Content

Setting up AWS IoT with LightBlue® Cloud Connect

    • LightBlue® Explorer has the ability to send data received from your BLE devices via indication or notification to AWS’s Internet of Things (IoT) platform.
    • You’ll be prompted to provide some information for your AWS IoT set up from within LightBlue® Explorer when you opt to send data to AWS IoT.
    • There are many ways to set up your AWS IoT instance, and this guide is just one of them. This guide aims to help you set up your AWS IoT instance and related services in the simplest way possible so that you can provide the information required for LightBlue® Explorer to send data to your AWS IoT instance. If you’re an advanced user, feel free to skip or customize any step listed here to your preference.
    • By following this guide you understand that you’re responsible for any and all charges incurred on your AWS IoT account. Punch Through is not responsible for any usage charges incurred as a direct or indirect result of following this guide or using the LightBlue® Cloud Connect feature in general.

Before we begin

  • Prerequisites
    • A BLE device/peripheral that supports sending notification or indication
    • An Amazon AWS account. Note that a Free Tier account will work just fine, though you will need to at least associate your account with a payment method.
    • Decide on a MQTT topic name (e.g. “lightblue_indications”, the guide will assume this is the desired topic name in the following sections) that’ll be used by LightBlue® Explorer to send BLE indication data to AWS
  • Services used:
    • AWS Internet of Things (IoT): IoT platform with support for MQTT topics. This is the first point of entry in the cloud.
    • AWS Cognito: AWS’s identity authentication service. LightBlue® Explorer prompts for your Cognito credential ID to authenticate the connection to AWS services. This basically ensures that we’re using your AWS instances instead of someone else’s.
    • (Optional) AWS DynamoDB: a database service that supports table management. If you choose to set up DynamoDB, all the data received via BLE indication or notification can be stored in a table and can be visualized as a function of time using other third-party tools or database extraction/visualization software.

Step 1: Setting up AWS Cognito

  • Head to the AWS Cognito console and make sure you’re logged in to the right AWS account, then visit this link to create an identity pool that’ll be used by LightBlue® Explorer.

3.png

 

  • Choose a descriptive name for the identity pool and make sure to check “Enable access to unauthenticated identities” since we are not authenticating with an identity provider and instead only require an ad-hoc connection to your AWS service instances.
  • Select “Create pool”.
  • You’ll be directed to a page to set up Identity and Access Management (IAM) roles. You should see two sections, the top one corresponds to authenticated identities while the bottom one corresponds to unauthenticated identities. As mentioned before, we’re only interested in setting up the unauthenticated identity. The following step is only specific to the “unauthenticated” or bottom section.
  • Make sure that the IAM role picker has “Create a new IAM Role” selected. The role name should already be pre-populated for you and should say something like “Cognito_LightBlueExplorerUnauth_Role”. Expand the “View Policy Document” section and tap on the Edit button to the right. Select “OK” on the dialog that pops up, and we now have access to modify the policy document directly. Copy and paste the following snippet, replacing the entire content of the text box with it. If you’re an advanced user, feel free to tweak this snippet to more finely control the permissions you grant to the IAM role.
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "mobileanalytics:PutEvents",
                "cognito-sync:*",
                "iot:*"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}
  • The fields should look similar to the screenshot below:

4.png

  • Click on the “Allow” button on the bottom right of the page to finalize the creation of the identity pool and the assignment of roles. You’ll now see the “Getting started with Amazon Cognito” page with your identity pool ID highlighted in red (redacted and shown as a red block in the example screenshot below). ACTION ITEM
    : Copy this string of text and save it somewhere convenient—we’ll need this to authenticate your connection to AWS. Also remember to take note of the region as shown in the sample code snippet as you’ll be prompted for this information as well in LightBlue® Explorer.

5.png


Step 2: Setting up AWS IoT

  • Head to the AWS IoT console and tap on “Get Started”.
  • On the left sidebar, click on “Security” and then “Policies”. Select “Create a policy”.

1.png

 

  • Name the policy lightblue_awsiot_policy, and click on the “Advanced mode”.
  • Cmd+A or Ctrl+A to select all the content into the in-browser editor and replace them with the following:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:*",
      "Resource": "*"
    }
  ]
}
  • Tap on “Create” to finalize the creation of the policy.

2.png

 

  • On the left sidebar, click on “Settings”. ACTION ITEM
    : note down the custom endpoint of your AWS IoT instance, you’ll need to input this into LightBlue® Explorer when prompted. See the following screenshot for what you should be looking for.

6.png

 

  • Right now you should have everything you need to start sending data received from your BLE device via indication/notification to the AWS IoT platform. While this may be sufficient for some people, be sure to read the “Setting up rules for AWS IoT” section to learn how to set up an AWS IoT rule that’ll forward that data to AWS’s DynamoDB—a database service—and store it in a table. This is helpful if you want to take your testing to another level and visualize the data changes as a function of time.

Step 3: Sending BLE indications data to AWS IoT via LightBlue® Explorer

  • Armed with a fully set up AWS IoT instance and AWS Cognito for un-authenticated users (i.e. the LightBlue® Explorer app), you should be sure to have the following information handy (replace us-east-1 with your region, of course):
    • Your AWS Cognito identity pool ID (in the form of us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
    • Your AWS IoT endpoint URL (e.g. https://xxxxxxxxxx.iot.us-east-1.amazonaws.com)
    • Your decided-upon MQTT topic name (e.g. lightblue_indications)
  • In LightBlue® Explorer, connect to your BLE device with at least one characteristic that supports notification or indication, and tap on that characteristic after the initial connection.

7.png

 

  • You’ll see a toggle for the Cloud Connect feature, flip that switch to enable the feature and select “Amazon Web Services (AWS)”

8.png

 

  • Populate the text fields in the alert dialog that appears with your AWS IoT endpoint (starting with “https://…”), your chosen MQTT topic name and your AWS Cognito identity pool ID, and tap OK.
  • Select your AWS region from the action sheet that appears afterwards. A loading spinner should appear and will disappear briefly after a MQTT session is successfully established between LightBlue® Explorer and your AWS IoT instance.
  • IMPORTANT
    : If you’ve previously left the app to copy the credentials from Safari or another iOS web browser, or if you keep getting connection failures to AWS IoT, you may have to navigate back to the main BLE scanning screen of the app and reconnect to your device for Cloud Connect to work correctly.
  • You’re now ready to start sending BLE indications data to your AWS IoT instance! Tap on “Listen for notifications” above the cloud feature toggle, and the data that appears in the “read/notified values” section should get sent to AWS IoT. Hint: you can use the “Test” feature on the AWS IoT console to verify that the information did end up on your AWS IoT instance—simply subscribe to the same topic that you specified under your chosen MQTT topic name!

9.png


OPTIONAL: Routing data from AWS IoT to AWS DynamoDB

This section is entirely optional and illustrates the steps to route all the data coming into AWS IoT (from your BLE device’s indications/notifications) to AWS DynamoDB. We’re assuming your AWS IoT instance has been set up as described in the previous sections.


Step 1: Setting up AWS DynamoDB

  • Before we can add a rule to route the data from AWS IoT, we first need a DynamoDB table to store those data.
  • Head to the AWS DynamoDB console and tap on “Create table”.
  • Name the table “lightblue_ble_indication_data” or some other descriptive name, and specify the primary key as “ble_device_name” of type String and add a sort key of “timestamp” of type Number.

13.png

 

  • Create the table. It can take up to a few minutes after initial setup before the table is usable.

Step 2: Setting up rules for AWS IoT

  • Once the DynamoDB table is ready, head to your AWS IoT console. On the left sidebar, click on “Rules” and then “Create a rule” when the page finishes loading.

10.png

 

  • Fill in the “Name” and “Description” fields with something descriptive, e.g. “Routes data from MQTT topic lightblue_indications to a table on DynamoDB”
  • Under the “Message Source” section, make sure “2016-03-23” is selected for the SQL version, and populate the Attribute and Topic Filter fields with “*” and your MQTT topic name respectively. The resulting rule query statement should be something like SELECT * from 'your_mqtt_topic_name'. Optionally you can also add a conditional check to filter out undesired data—we’ll leave this as an exercise for our savvy users!

11.png

 

  • Click on the “Add action” button below the fields and select “Insert a message into a DynamoDB table”, and confirm this selection by clicking on the button on the bottom right corner, “Configure action”.

12.png

 

  • Select the DynamoDB table that was created under the “Table name” dropdown picker, and populate the hash key value with ${ble_device_name} and the range key value with ${timestamp()}. Populate the final field with payload.

14.png

 

  • Select “Create a new role” from the bottom section and give it a descriptive name like “LightBlue-IoT-DynamoDB” and create it.

15.png

 

  • Select the newly created role from the dropdown and finalize the action by selecting “Add action” on the bottom right of the page.
  • Finally, select “Create rule” on the bottom right of the rule creation page. Verify that the new rule is now shown on the Rules page on your AWS IoT console.

Step 3: Looking at data coming into DynamoDB

  • Use LightBlue® Explorer to listen to a characteristic notification or indication with the Cloud Connect toggle turned on as detailed in the “Sending BLE indications data to AWS IoT via LightBlue® Explorer” section above. Make sure that the MQTT topic name you specify in the alert dialog matches the topic name you specified when setting up the AWS IoT rule.
  • Listen for notifications as usual, and the data should now be sent to AWS IoT and DynamoDB. To see this, head to your DynamoDB table page and click on the “Items” tab.

16.png

 

  • Et voilà!
  • Side note: AWS currently does not support visualizing DynamoDB data out of the box without additional setup. There are other third-party scripts that would allow you to access the DynamoDB table, pull all the values and visualize it as a graph plot over time, but that is out of the scope of this tutorial. We hope this guide was helpful in getting you started with Cloud Connect, happy hacking!