Build a connected maraca with AWS and Intel Edison

Introduction

Today, we will build a simple connected device that will act like a Maraca. When you shake the device, it will start streaming data to AWS. You will then be able to see that data real-time on a dashboard hosted in your AWS account.

Maracas, sometimes called rumba shakers and various other names, are percussion musical instruments—rattles—that originated in Latin America. They are classified as idiophones. Players hold them by their handles, usually in pairs, and shake them.

Once you connect the core to your Edison and your AWS environment, the final Connected Maraca system will look like this:

Part 1: Setup your Intel Edison

After you open the box, Intel Edison with Arduino Expansion Board, follow these one-time steps to setup, connect and flash the latest image.

Step 1: Assemble your Intel Edison board

To setup your edison, snap in your Edison to the breakout board. Next, move the J9 jumper to the "top" position. Finally, connect your Edison to your computer using both of the micro-USB cables provided.

Click here for further instructions on how to assemble the board.

Step 2: Flash your Edison.

Next, you need to flash your Edison board. First, download the latest Yocto image and the Flash Tool Lite from Intel's downloads page:

• Intel IoT Downloads

Note: When you install and open the Flash Tool Lite, it may be named "Phone" Flash Tool Lite. That is normal!

Ensure that your Intel Edison is connected to your computer with both micro USB cables. Open Flash Tool Lite and you should see your board listed in the application. Follow these steps:

1. Browse and select the Yocto image that you downloaded above.

2. Click "Start to Flash". At this point, it may ask you to disconnect and reconnect your Edison. If so, unplug the USB cables and plug them back in.

3. Wait until the board has completed flashing. This will require a reboot of the board.

   
   

Congratulations! You have successfully flashed your edison.

Step 3: Connect to your Intel Edison.

In order to connect to the device, you will need to make a serial connection. On Mac or Linux operating systems, you can do this with the screen utility. On a Windows machine, you can do this using PuTTy.

Note: Once you have made the serial connection, if you are seeing a blank screen - press enter twice.

On a Mac:

• Open a new Terminal window and type screen /dev/tty.usbs . Press "tab" to auto-complete the line. Finally, add 115200 -L at the end of the line and press enter twice.

On a PC:

• Once you have downloaded PuTTy, select "serial" and set the baud rate to 115200. In Device Manager, you can find the COM port that your Edison is using. Connect, and when you see a blank window press enter twice.

On Linux:

• Before you can connect to your Edison using the screen command, you need to install screen. Type these commands followed by pressing enter twice.:

  $ sudo apt-get install screen
  $ sudo screen /dev/ttyUSB0 115200
  

  
  

Step 4: Setup and configure your Intel Edison.

Once you have connected to your device, configure the Edison by typing configure_edison --setup .

Step 5: Setup Arduino IDE and upload a basic sketch to test your system out.

If you do not have the Arduino IDE installed, follow the steps here to install it.

To test that everything is setup correctly, try uploading and running the "Blink an LED" sketch using the Arduino IDE.

1. Open File > Examples > Basics > Blink
2. Under Tools > Board, ensure that you have selected "Intel Edison". If it does not appear, follow the steps here.
3. Under Tools > Port, select dev/cu.usbmodem...
4. Click Verify and then later when it compiles, hit upload
5. See if the on-board LED on the Edison is blinking!

Part 2: Create Your AWS Environment

Your AWS environment consists of a number of different AWS services providing security, transport, and storage of the sendor data producted by your Connected Maraca. Your AWS environment will include resources provisioned using the following services:

Lambda + Kinesis + DynamoDB + Cognito + S3 + SNS + IAM + CloudFormation

Here is how the system will work:

All services in AWS are delivered via a rich set of REST APIs. You can use a service programmatically through the APIs by leveraging one of the many SDKs. Alternatively, you can invoke services through the web-based AWS Management Console. To build our AWS environment, we will invoke serveral services manually through the console. But keep in mind that every step we perform today can be done completely programmatically, which is one of the many reasons why the AWS cloud is so powerful.

To create your AWS environment, we will use a CloudFormation template. CloudFormation templates use JSON formatted documents to quickly and reliably provision AWS resources, referred to as a "stack".

Step 1: Create a CloudFormation Stack.

Note: In this tutorial, we will be setting up resources in the AWS Oregon region (us-west-2). Before continuing, ensure that the region dropdown in the top right of your screen says Oregon.

1. Open the CloudFormation console page by clicking Services > CloudFormation

2. Press the blue Create Stack button.

3. Name your stack. Next, copy and paste the following URL into the S3 template URL field:

   https://s3-us-west-2.amazonaws.com/iot-hackseries/_static/hack-series-backend-lambda.json
   

4. Create and enter a new Device ID that will be used to identify your device in your connected applications. You can put anything into this field, but it must be between 5 and 10 characters, and contain no spaces or special characters.

   
   

5. Select "Edison" as the DeviceType.

6. Press Next. Add any tags that will help you identify this stack in the future.

7. Press Next. This screen will give you an overview of your stack. Note: Here you can get an estimate for how much this environment will cost on a monthly basis.

8. Press Create. Your stack will now be launched.

Step 2: Note the Outputs that were created.

Once your CloudFormation stack has been successfully launched, you will be able to see the Outputs that it created. These are the values you will use when configuring your Connected Maraca and the website visualization tool. To see the outputs, click on the Outputs tab. It will look like this:

Part 3: Create the Lambda Function

To process data from the device, we will use a Kinesis stream and a Lambda function.

This is the Lambda function that will be used to process the data being written to the Kinesis stream. You will cut and paste the source code in this function into the Lambda console.

Note: In this tutorial, we will be setting up resources in the AWS Oregon region (us-west-2). Before continuing, ensure that the region dropdown in the top right of your screen says Oregon.

1. Open the Lambda console page by clicking Services > Lambda

2. Press the blue Get Started Now button.

3. Enter the name of the fuction and an optional description.

4. Cut and paste the source code from the Javascript file at the URL listed above. Substitute the string "[TABLE_NAME]" with the name of the device table that was created in the CloudFormation stack.

5. Select the role that was created from the CloudFormation stack in the previous step. It should have a name like [StackName]-DeviceExecutionRole-XXXXX

6. Press Create. The function has now been created.

7. Add an event source to the function by selecting "Actions->Add Event Source"

8. Choose the Kinesis stream created by the CloudFormation stack as the event source.

9. Press Submit. You should now see the Kinesis stream show up in the "Event Source" list beneath the function.

Congratulations!! You have now successfully set up your AWS backend infrastructure.

Part 4: Assemble the Connected Maraca

Connected Maraca Introduction: What will it do?

The Connected Maraca will run in one of three modes:

1. DynamoDB mode: it will post items to a DynamoDB table with columns as <device_id>, <time>.
2. Kinesis mode: it will send a JSON record with device_id, timestamp, and sensor data to a Kinesis Stream.
3. SNS mode: it will post a timestamp to an SNS topic.

Some notes about the application:

• The application uses DynamoDB mode by default.
• The button at socket D7 (the "mode" button) changes (cycles through) the currently supported service
• RGB led indicates the current mode (blue: dynamo, orange: kinesis, purple: sns)
• The Buzzer beeps when mode is changed & serial console output verifies the new mode
• Shaking the maraca triggers posting a record to current mode AWS service
• Serial console output displays message sending and response information
• RBG mode led dims between when the message sent and AWS target service response is received

Step 1: Ensure you have all of the right components

Now let's assemble the connected maraca. You will need following parts:

Note: For more detailed descriptions of all of the components in the Grove Kit, check out the Grove Wiki.

Step 2: Connect all of the components

Once you have all of the components, attach the Grove base shield to the Edison Arduino board. You will be connecting the various Grove Kit components to the base shield. When that is complete, follow these steps:

1. Set the 3.3-to-5V switch on the Shield to 3.3V
2. Grove Button connected to base shield socket D7
3. Grove buzzer connected to base shield socket D6
4. Grove LED connected to base shield socket D3
5. Grove 3-Axis Accelerometer to any bottom I2C port

Part 5: Build and run your Connected Maraca

In this section, we will build the connected maraca using the Arduino IDE.

First, you will need to download the AWS/Edison Connected Maraca Sample Code:

AWS_Edison_Maraca_Sample.zip

Step 1: Open the Connected Maraca sketch and upload it to your Edison.

Follow these steps:

1. Unzip the Maraca Sample file above.

2. Open Arduino IDE.

3. There are three folders (libraries) in the unzipped folder to import into the Arduino IDE: HardwareLibrary, AWSEdisonLibrary, and AWSArduinoLibrary. To import them, click Sketch > Import Library > Add Library.

   1 / 2

4. Open the folder Edison_Maraca and double click the Edison_Maraca.ino file

5. Modify the keys.cpp and add the information provided to you in the CloudFormation outputs. To get here, click on the AWS service CloudFormation and under your successfully deployed stack, click the tab "Outputs".

6. Press Verify, and then Upload. They are icons in the top left corner of the IDE window.

   1 / 2

7. This will upload and start the application on your Edison.

Here is a video that guides you through the process:

Note: This video demonstrates the key steps required to get your Connected Maraca project setup in the Arduino IDE. Keep in mind, you will also need to add the remainder of the constants in your keys.cpp file. As described above, you can find these (Kinesis stream name, DynamoDB table name etc.) by clicking on the Outputs tab in CloudFormation.

Step 2: View the output on the Serial Monitor

You can monitor the output in real-time by clicking Tools > Serial Monitor. It should display something like the following:

Note: When you press and hold the button connected to your Edison, it will change the mode of delivery to AWS. The three options are DynamoDB, Kinesis and SNS.

Attempting to connect to SSID: condensate
Connected to wifi
SSID: condensate
IP Address:  10. 36.  0. 22
signal strength (RSSI):-60 dBm
Setup complete! Looping main program
Initial mode: Kinesis
Posting to Kinesis
{"device_id":"Team7","time":20000101000103,"device":"edison","sensors":[{"Piezo":"true"}]}
Kinesis record posted to Stream
Button pressed - changing mode. New mode: DynamoDB
Posting to DynamoDB
DynamoDB PutItem succeeded!
Button pressed - changing mode. New mode: SNS
Posting to SNS
Sent message ID: a500139f-5c1c-5010-8126-5f44c782b2d9
Button pressed - changing mode. New mode: Kinesis
Posting to Kinesis
{"device_id":"Team7","time":20141111050645,"device":"edison","sensors":[{"Piezo":"true"}]}
Kinesis record posted to Stream
Button pressed - changing mode. New mode: DynamoDB
Button pressed - changing mode. New mode: SNS
Button pressed - changing mode. New mode: Kinesis
Posting to Kinesis
{"device_id":"Team7","time":20141111050720,"device":"edison","sensors":[{"Piezo":"true"}]}
Kinesis record posted to Stream
Button pressed - changing mode. New mode: DynamoDB
Posting to DynamoDB
DynamoDB PutItem succeeded!
Button pressed - changing mode. New mode: SNS
Posting to SNS
Sent message ID: 10afc97f-7a1f-5911-bbfe-85a4e1cce71e

You are now successfully sending data to the cloud from Intel Edison using Arduino.

Congratulations! You have successfully built out the Connected Maraca! As you shake your Maraca, your data will be displayed on the leaderboard at the front of the room.

(Optional) Part 6: Visualize your data

The visualization application is a static Angular.JS website that is delivered through S3. Since this site consists entirely of HTML, CSS, and Javascript, it is important to secure the credentials used by the Javascript code that makes calls to AWS services.

To provide secure access to the resources created in your environment, we will use the Cognito service. Cognito integrates with the IAM service, allowing you to create policies that define how resources in your environment can be accessed. For example, you probably don't want the entire world to be able to read and write data to your tables in DynamoDB. But you may want to allow some users or applications access to the tables. Using Cognito and IAM, you can restrict access to your DynamoDB tables to only those users or applications that you trust, while shutting out access to everything else.

Step 1: Create a Cognito Identity Pool.

Note: In this tutorial, we will be using the Cognito service, which is only available in the AWS N. Virginia region (us-east-1). Before continuing, ensure that the region dropdown in the top right of your screen says N. Virginia.

1. Open the Cognito console page by clicking Services > Cognito

2. Press the blue Get Started button.

3. Name your Cognito Identity Pool. You can use any name that you want.

4. Under the Unauthenticated Identities section, check the box to enable access to unauthenticated identities.

5. Click the Create Pool button. You will now see the following screen:

6. Click on View Details and note the name of the unauthenticated IAM Role that is created during this process. Press Allow.

Congratulations! You have set up your Cognito Identity Pool.

Now that the Cognito identity pool has been created, we can link it to an IAM role that defines the permissions required by the visualization application. This role essentially allows for read-only access to the data in the DynamoDB table.

Step 2: Attach the Visualization Policy in IAM

1. Open the IAM console page by clicking Services > IAM

2. On the left hand menu, click Roles.

3. Find the unauthenticated role that was created when you setup your Cognito identity pool. Click on the name of the role to edit the role.

4. Under Managed Policies, click Attach Policy.

5. AWS has many ready-to-go managed policies that can be used to define access permissions to your IAM Users, Groups and Roles. When you launched your CloudFormation stack, a managed policy was created for visualization. Search "visualization" and the managed policy should show up.

6. Click on the check box and press Attach Policy.

Congratulations! You have successfully attached your visualization policy to your Cognito unauthenticated IAM role! Now, you are all ready to configure and upload the web application.

Step 3: Upload and configure your S3 visualization website.

To configure and install the visualization website, first download the application and follow these steps:

visualization.tar.gz

1. Unpack the tarball into a local directory on your laptop.

2. Open the file visualization/scripts/config.js in a text editor.

3. Replace all the config values that have the form "[TOKEN]" with the required values. The values that you will use are all outputs from your CloudFormation stack you created in Part 2.

4. Save the changes to the file.

5. Open the S3 console page by clicking Services > S3

6. Find the Visualization bucket that was created when you launched your CloudFormation Stack. Click on the bucket name to open the bucket.

7. On the top left, click Upload.

8. In some browsers, you can simply drag and drop the files into the box specified on the page. In others, you can use the Enhanced Uploader to copy over all of the files in the folder.

Alternatively, if you have the AWS CLI tools setup, you could upload the visualization files to your S3 bucket from the command line. Below is the command to use to copy the files, where [YOUR S3 VISUALIZATION BUCKET] is the value of the output parameter called "VisualizationBucketName" from your CloudFormation stack.:

aws s3 cp --recusive visualization s3://[YOUR S3 VISUALIZATION BUCKET] --acl public-read

Now if you click on the link provided in your CloudFormation outputs, you will see the visualization website with your streaming device data.

Congratulations!! You have completed the Connected Maraca!