├── .main-meta
└── main.json
├── README.md
├── a-more-thorough-look-into-the-provisioning-process
├── README.md
├── figures
│ ├── aws-iot-connections.svg
│ ├── find-rules.jpg
│ ├── forward-rule.jpg
│ ├── jitr-aws-diagram.svg
│ ├── jitr-flow.svg
│ └── next_primary.svg
├── jitr_lambda.py
└── policy_example.json
├── access-the-sandbox
├── README.md
└── figures
│ ├── next_primary.svg
│ └── sandbox.gif
├── an-introduction-to-device-shadows-and-aws-lambda
├── README.md
├── figures
│ ├── IAM_Add_role.gif
│ ├── add_trigger_to_route_data.gif
│ ├── application_example_aws_flowchart.svg
│ ├── creating_empty_lambda_function.gif
│ ├── next.svg
│ ├── show_shadow_update_messages.gif
│ └── working_application_example.gif
└── lambda_function.py
├── connect-the-board-to-your-aws-account
├── MCHPProvToolAccess.json
├── README.md
└── figures
│ ├── beginner.svg
│ ├── iam-1.png
│ ├── iam-2.jpg
│ ├── iam-policy.png
│ ├── iot-test-1.jpg
│ ├── next_primary.svg
│ ├── next_secondary.svg
│ └── screenshot-tool.png
├── crash-course-in-cryptography-and-x509
├── README.md
└── figures
│ ├── crypto-signing.svg
│ ├── next_primary.svg
│ ├── next_secondary.svg
│ ├── public-key.svg
│ └── x509-1.svg
├── device-monitoring-in-amazon-cloudWatch
├── README.md
└── figures
│ ├── application_example_aws_flowchart.svg
│ ├── changing_graph_settings_in_cloudwatch.gif
│ ├── demonstration_of_graphed_metrics.gif
│ ├── how_to_create_an_IoT_Core_rule.gif
│ ├── how_to_create_lambda_function.gif
│ ├── how_to_create_lambda_test_event.gif
│ ├── lambda_function_execution_failed.png
│ ├── lambda_function_execution_succeeded.png
│ └── next.svg
├── figures
├── action-button.svg
├── feedback_button.svg
├── flowchart_path_legend.svg
├── header_safari.jpg
└── header_safari.png
├── visualizing-sensor-data-in-jupyter-notebooks
├── README.md
└── figures
│ ├── Configure_IAM_Notebook.gif
│ ├── IoTAnalyticsDataSetSuccess.JPG
│ ├── IoT_Analytics_step1_create_rule.gif
│ ├── JuPy_Coding1.gif
│ ├── JuPy_Coding2.gif
│ ├── JuPy_IoTAnalytics_NB.gif
│ ├── SageMaker_Create_NotebookInstance.gif
│ ├── Step_0_mqtt.gif
│ ├── next_primary.svg
│ ├── output_6_1.png
│ └── system_overview_flowchart.png
└── your-first-application-sending-and-receiving-data
├── README.md
└── figures
├── Subscribe_to_buttonPresses_in_IoT_Core.gif
├── embedded_and_cloud_connectivity_flowchart.svg
├── make_and_program_device.png
├── next_primary.svg
├── next_secondary.svg
└── show_working_IoT_board_example.gif
/.main-meta/main.json:
--------------------------------------------------------------------------------
1 | {
2 | "metaDataVersion": "1.0.0",
3 | "category": "com.microchip.ide.project",
4 | "content": {
5 | "metaDataVersion": "1.1.0",
6 | "name": "com.microchip.mcu8.mplabx.project.microchip-iot-developer-guides-for-aws",
7 | "version": "1.0.0",
8 | "displayName": "Microchip IoT Developer Guides for AWS",
9 | "projectName": "AWSDeveloperGuides",
10 | "shortDescription": "Microchip IoT Developer Guides for AWS (Amazon Web Services) is a set of tutorials tailored to get started with your IoT Design, from embedded to cloud.",
11 | "ide": {
12 | "name": "MPLABX",
13 | "semverRange": ">=5.30.0"
14 | },
15 | "compiler": [
16 | {"name": "xc8", "semverRange": "^2.10.0"},
17 | {"name": "gcc", "semverRange": "^3.6.1"}
18 | ],
19 | "dfp": {
20 | "name": "Atmega_DFP",
21 | "semverRange": "^2.0.12"
22 | },
23 | "configurator": {
24 | "name": "MCC",
25 | "semverRange": ">=3.9.50"
26 | },
27 | "device": {
28 | "metaDataVersion": "1.0.0",
29 | "category": "com.microchip.portal.contentRef",
30 | "content": {
31 | "metaDataVersion": "1.0.0",
32 | "category": "com.microchip.device",
33 | "name": "ATMEGA4808",
34 | "versionRange": "*"
35 | }
36 | },
37 | "author": "MCU8 Library Development Team",
38 | "subcategories": [
39 | "IoT","AWS",
40 | [
41 | "Perpherals", "SPI"
42 | ],
43 | [
44 | "Perpherals", "I2C"
45 | ],
46 | [
47 | "Perpherals", "TIMER"
48 | ],
49 | [
50 | "Perpherals", "UART"
51 | ]
52 | ],
53 | "peripherals": [
54 | "Interrupt","PWM","CCP","TIMER"
55 | ],
56 | "keywords": [
57 | "IoT",
58 | "CloudWatch",
59 | "AWS services",
60 | "AWS Lambda",
61 | "Lambda function",
62 | "serverless computing",
63 | "IoT Core",
64 | "certificate",
65 | "private key",
66 | "sensor",
67 | "Jupyter Notebook",
68 | "cloud analytics",
69 | "SageMaker",
70 | "temperature",
71 | "device shadow",
72 | "JITR",
73 | "IoT Provisioning Tool",
74 | "X.509",
75 | "public-key cryptography",
76 | "public key infrastructure",
77 | "pki",
78 | "public key",
79 | "encryption",
80 | "AVR-IoT",
81 | "PIC-IoT",
82 | "light",
83 | "weather",
84 | "ECC608",
85 | "WINC1510",
86 | "Wireless",
87 | "MQTT",
88 | "Internet of things",
89 | "Security",
90 | "Crypto Authentication Library",
91 | "Cloud",
92 | "AWS",
93 | "Amazon web Services",
94 | "amazon",
95 | "sensors"
96 | ],
97 | "additionalData": {
98 | "longDescription": {
99 | "metaDataVersion": "1.0.0",
100 | "category": "com.microchip.portal.fileRef",
101 | "content": {
102 | "metaDataVersion": "1.0.0",
103 | "fileName": "./README.md",
104 | "mimeType": "text/markdown"
105 | }
106 | }
107 | }
108 | }
109 | }
110 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Microchip IoT Developer Guides for AWS
2 |
3 | 
4 |
5 | ## The Survival Guide for Your Embedded to Cloud Journey
6 |
7 | Connecting an embedded design to the cloud can bring a wealth of benefits, such as advanced data insights and remote monitoring. But all too often, embedded designers who start off on their journey to the cloud don't make it. They fall into time sinks, succumb to skirmishes with pythons, or worst of all, *they forget about security*.
8 |
9 | Your embedded to cloud journey shouldn’t be stressful. It should be *an adventure* – you should enjoy it, learn a lot, end up in the right place, and you should be done before lunch.
10 |
11 | In the **Microchip IoT Developer Guides for AWS**, we have mapped out an ideal embedded to cloud journey so that you can quickly learn the basics and start designing your own deployable cloud-connected IoT application.
12 |
13 | Let the adventure begin.
14 |
15 | ## Technical Journey
16 |
17 | ### Overview
18 |
19 | Microchip IoT Developer Guides for AWS is a set of hands-on tutorials and technical articles curated to help you get started with integrated IoT design. You will start at the [sandbox](./access-the-sandbox), where you can explore sending and receiving data to the cloud with almost no setup. When you are ready, you will securely [connect the node to your own AWS account](./connect-the-board-to-your-aws-account) and build an [example application](./your-first-application-sending-and-receiving-data). All of the tutorials, as well as the recommended reading path, can be seen in the [Map of Resources](#map-of-resources). A short description of each tutorial can also be found in the [List of Tutorials](#list-of-tutorials) section.
20 |
21 | ### Hardware Requirements
22 |
23 | These tutorials use the [AVR-IoT WA](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-intro) and [PIC-IoT WA](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-intro) Boards, although the discussed concepts are applicable to most IoT Designs.
24 |
25 | *Pro Tip*: if you have an [AVR-IoT WG](https://www.microchip.com/DevelopmentTools/ProductDetails/ac164160?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-intro) or [PIC-IoT WG](https://www.microchip.com/DevelopmentTools/ProductDetails/ac164164?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-intro) board, you can convert it to the AWS variant (WA) by following the instructions in [this video](https://www.youtube.com/watch?v=nwP8obSRaaE).
26 |
27 | ### Software Requirements
28 |
29 | Embedded projects use [MPLAB® X IDE](https://www.microchip.com/mplab/mplab-x-ide?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-intro) and the [XC8](https://www.microchip.com/mplab/compilers?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-intro) (AVR-IoT) or [XC16](https://www.microchip.com/mplab/compilers?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-intro) (PIC-IoT) compiler.
30 |
31 | _Note that newer versions of the XC8 compiler might lead to the program not being able to fit within the program memory due to changes in the standard library. Please use version 2.32 of the XC8 compiler if this problem occurs._
32 |
33 | The AWS Command Line Interface is required for the [Connect the Board to your AWS Account](./connect-the-board-to-your-aws-account) tutorial.
34 |
35 | ## Map of Resources
36 |
37 | [](https://microchip-pic-avr-solutions.github.io/microchip-iot-developer-guides-for-aws-interactive-flowchart/)
38 |
39 | ## List of Tutorials
40 |
41 | ### [Access the Sandbox](./access-the-sandbox)
42 |
43 | An introductory tutorial that demonstrates how to connect the IoT boards to the internet in 30 seconds flat, provides real-time plotting of the board's sensor data and guides you through your first encounter with the board's firmware.
44 |
45 | ### [Connect the Board to your AWS Account](./connect-the-board-to-your-aws-account)
46 |
47 | An introductory tutorial explaining how to securely connect either an [AVR-IoT WA](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-tutorial-list) or [PIC-IoT WA](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-tutorial-list) to Amazon Web Services® (AWS) through the AWS IoT Core Module. Introduces the [*IoT Provisioning Tool*](http://www.microchip.com/mymicrochip/filehandler.aspx?ddocname=en1001525), a tool to *provision* the board without the need to know complex cryptography.
48 |
49 | ### [Your First Application - Sending and Receiving Data](./your-first-application-sending-and-receiving-data)
50 |
51 | A tutorial teaching you how to create a *cloud*-based application for the [PIC-IoT](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-tutorial-list) and [AVR-IoT](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-tutorial-list) Development Boards using [Amazon Web Services®](https://aws.amazon.com/what-is-aws/) and the *MQTT* messaging protocol. You will learn how to communicate with [AWS IoT Core](https://aws.amazon.com/iot-core/) by publishing and subscribing to custom MQTT *topics*, and the tutorial will also cover the embedded side of the application development.
52 |
53 | ### [Crash Course in Cryptography and X.509](./crash-course-in-cryptography-and-x509)
54 |
55 | A crash course in basic public-key cryptography, and their use in the X.509 standard. Discusses the concepts of key-pairs, encryption, signing, certificates, and how to achieve [*confidentiality* and *authenticity*](https://en.wikipedia.org/wiki/Information_security). Recommended for readers who desire a deeper understanding of device provisioning.
56 |
57 | ### [A More Thorough Look into the Provisioning Process](./a-more-thorough-look-into-the-provisioning-process)
58 |
59 | Explores what happens when a board is provisioned through *MAR* (Multi-Account Registration) and *JITR* (Just In Time Registration) using the [*IoT Provisioning Tool*](http://www.microchip.com/mymicrochip/filehandler.aspx?ddocname=en1001525). The JITR method uses an AWS Lambda function to register devices and certificates in the cloud during the first connection, while the MAR method is based around pre-registered devices and certificates. Recommended for readers who desire to understand the details of how devices are authenticated.
60 |
61 | ### [An Introduction to Device Shadows and AWS Lambda](./an-introduction-to-device-shadows-and-aws-lambda)
62 |
63 | A tutorial demonstrating how [Amazon Web Services®](https://aws.amazon.com/what-is-aws/) can be used with the [PIC-IoT](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-tutorial-list) and [AVR-IoT](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-tutorial-list) Development Boards to perform *serverless cloud computing* and to keep track of *local* state variables using [AWS Lambda](https://aws.amazon.com/lambda/) and the [Device Shadow service](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html) in [AWS IoT Core](https://aws.amazon.com/iot-core/). The tutorial covers important aspects of both embedded and cloud development.
64 |
65 | ### [Visualizing Sensor Data in Jupyter Notebooks](./visualizing-sensor-data-in-jupyter-notebooks)
66 |
67 | A tutorial where sensor data from the [PIC-IoT](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-tutorial-list) and [AVR-IoT](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-tutorial-list) Development boards are used to construct *data sets* that can be visualized using the *Jupyter Notebook* environment in [Amazon Web Services®](https://aws.amazon.com/what-is-aws/). The tutorial covers configuration of a wide range of services, such as [AWS IoT Core](https://aws.amazon.com/iot-core/), [AWS Lambda](https://aws.amazon.com/lambda/), [AWS IoT Analytics](https://aws.amazon.com/iot-analytics/) and [Amazon Sagemaker](https://aws.amazon.com/sagemaker/) - providing a flexible platform for data exploration.
68 |
69 | ### [Device Monitoring in Amazon CloudWatch](./device-monitoring-in-amazon-cloudWatch)
70 |
71 | A tutorial showcasing how sensor data from the [PIC-IoT](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-tutorial-list) and [AVR-IoT](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-main-tutorial-list) Development Boards can be visualized in near *real-time* with [Amazon Web Services®](https://aws.amazon.com/what-is-aws/). [AWS IoT Core](https://aws.amazon.com/iot-core/) and [AWS Lambda](https://aws.amazon.com/lambda/) are used to route the sensor data to [Amazon CloudWatch](https://aws.amazon.com/cloudwatch/), where it is used to generate a continuously updating plot of the temperature and light level measured by the device.
72 |
73 | ## Feedback and questions
74 |
75 |
76 |
--------------------------------------------------------------------------------
/a-more-thorough-look-into-the-provisioning-process/README.md:
--------------------------------------------------------------------------------
1 | # A More Thorough Look into the Provisioning Process
2 |
3 | *Author: Johan Lofstad, Microchip Technology Inc.*
4 |
5 |
6 |
7 |
8 |
9 | This document is a follow-up of the [Connect the Board to your AWS Account](../connect-the-board-to-your-aws-account) introductory guide, going into more detail of how the provisioning works. This document is intended for readers who desire to understand how devices are authenticated when using the [IoT Provisioning Tool](https://www.microchip.com/mymicrochip/filehandler.aspx?ddocname=en1001525).
10 |
11 | *It is highly recommended to read the [Crash Course in Cryptography and X.509](../crash-course-in-cryptography-and-x509) if unfamiliar with X.509 and basic cryptography.*
12 |
13 | This document involves the following topics:
14 |
15 | - Generating Certificates with the Provisioning Tool
16 | - Multi-Account Registration (MAR)
17 | - Just-In-Time Registration (JITR)
18 | - AWS IoT Policies
19 | - Using AWS Lambda and AWS IoT Core to implement JITR
20 |
21 | ## Table of Contents
22 |
23 | - [A More Thorough Look into the Provisioning Process](#a-more-thorough-look-into-the-provisioning-process)
24 | - [Table of Contents](#table-of-contents)
25 | - [IoT Provisioning Tool](#iot-provisioning-tool)
26 | - [Just-in-time Registration](#just-in-time-registration)
27 | - [Setting up JITR in AWS](#setting-up-jitr-in-aws)
28 | - [Multi-account Registration](#multi-account-registration)
29 | - [Device Permissions in AWS](#device-permissions-in-aws)
30 | - [Policy Example](#policy-example)
31 | - [Finding the AWS Resources](#finding-the-aws-resources)
32 | - [Next Steps](#next-steps)
33 | - [Resources](#resources)
34 |
35 | ## IoT Provisioning Tool
36 |
37 | The [IoT Provisioning Tool](http://www.microchip.com/mymicrochip/filehandler.aspx?ddocname=en1001525) is a tool offered by Microchip to easily provision the AWS variant of the PIC & AVR IoT Boards. It handles all the cryptography and interactions with all Microchip PIC & AVR IoT Boards.
38 |
39 | The IoT Provisioning Tool is a command-line utility and must be run from a terminal (e.g. cmd.exe for Windows®, Terminal for MacOS® & Linux®). The following list contains some typical use cases for the tool:
40 |
41 | - Provision a board with your own AWS Project:
42 | - `./iotprovision-bin -c aws -m jitr` (using JITR)
43 | - `./iotprovision-bin -c aws -m mar` (using MAR)
44 | - Provision a board with the AWS Sandbox:
45 | - `./iotprovision-bin -c aws -m sandbox`
46 | - Provision a board with a specifiec firmware:
47 | - `./iotprovision-bin -c aws -m jitr -app myfirm.hex` (using JITR)
48 | - `./iotprovision-bin -c aws -m mar -app myfirm.hex` (using MAR)
49 | - Set Wi-Fi credentials:
50 | - `./iotprovision-bin -auth wpa-psk -ssid mywifi -psk password`
51 |
52 | > Note: Using the tool is not the only way to install Wi-Fi® credentials and custom firmware. See [AVR-IoT WA Quick Start Guide](http://microchip.com/DS30010218).
53 |
54 | For a complete description of what the tool can do, run `./iotprovision-bin --help`. The following is a printout of that command:
55 |
56 | ```console
57 | PS C:\Users\Username\ProvToolFolder> .\iotprovision-bin.exe --help
58 | usage: iotprovision-bin.exe [-h] [-c {google,aws,azure}] [-A ARCHIVE]
59 | [-m {sandbox,custom,jitr,mar}] [-a AWS_PROFILE]
60 | [-P PORT] [-p PROVISION_FIRMWARE] [-f]
61 | [-app APPLICATION_FIRMWARE] [-ssid WIFI_SSID]
62 | [-psk WIFI_PSK]
63 | [-auth {open,wpa-psk,wep,ieee802.1x}] [-w]
64 | [-s SERIAL_NUMBER] [--verify]
65 | [-l {fatal,error,warning,info,debug}] [-V]
66 | [{all,dbgupgrade,certs,provision,links,application,none} [{all,dbgupgrade,certs,provision,links,application,none} ...]]
67 |
68 | Provision MCU8 IoT kits for cloud provider
69 |
70 | positional arguments:
71 | {all,dbgupgrade,certs,provision,links,application,none}
72 | action(s) to perform (default: all)
73 |
74 | optional arguments:
75 | -h, --help show this help message and exit
76 | -c {google,aws,azure}, --cloud-provider {google,aws,azure}
77 | Cloud provider to provision for (default: aws)
78 | -A ARCHIVE, --archive ARCHIVE
79 | On-board debugger firmware archive, use bundled file
80 | if none specified (default: None)
81 | -m {sandbox,custom,jitr,mar}, --provision-method {sandbox,custom,jitr,mar}
82 | Provisioning method: Microchip sandbox or custom
83 | account. Custom acount can be setup with just in time
84 | registration(JITR,default) or Multi account
85 | registration(MAR) (default: sandbox)
86 | -a AWS_PROFILE, --aws-profile AWS_PROFILE
87 | AWS profile name (default: default)
88 | -P PORT, --port PORT Kit virtual serial port for provisioning, will try to
89 | determine automatically if none specified (default:
90 | None)
91 | -p PROVISION_FIRMWARE, --provision-firmware PROVISION_FIRMWARE
92 | Provisioning firmware hex file, use bundled file if
93 | none specified (default: None)
94 | -f, --force Force provisioning even if already done (default:
95 | False)
96 | -app APPLICATION_FIRMWARE, --application-firmware APPLICATION_FIRMWARE
97 | Application/demo firmware hex file, use bundled file
98 | if none specified (default: None)
99 | -ssid WIFI_SSID, --wifi-ssid WIFI_SSID
100 | SSID for wifi connection (default: None)
101 | -psk WIFI_PSK, --wifi-psk WIFI_PSK
102 | PSK (password) for wifi connection (default: )
103 | -auth {open,wpa-psk,wep,ieee802.1x}, --wifi-auth {open,wpa-psk,wep,ieee802.1x}
104 | wifi authentication mechanism (default: wpa-psk)
105 | -w, --wincupgrade upgrade WINC module firmware to latest bundled
106 | firmware (default: False)
107 | -s SERIAL_NUMBER, --serial-number SERIAL_NUMBER
108 | USB serial number of the unit to provision (default:
109 | None)
110 | --verify verify after write from file (default: False)
111 | -l {fatal,error,warning,info,debug}, --logging {fatal,error,warning,info,debug}
112 | Logging severity level (default: warning)
113 | -V, --version Print iotprovision version number and exit (default:
114 | False)
115 | ```
116 |
117 | The `-m mar` and `-m jitr` options of the provisioning tool are used to authenticate a board with a non-sandbox AWS project. When running the provisioning tool for the first time using either of these options, the provisioning tool connects to AWS via the command line interface (AWS CLI) and sets up the cloud for successful device authentication. The details of the process differ somewhat for MAR and JITR, and we will therefore cover each method separately.
118 |
119 | ## Just-in-time Registration
120 |
121 | *Just-in-time registration* is a provisioning method where device certificates are validated the first time they connect to the cloud. Upon connecting, a certificate authority (CA) in AWS checks the validity of the device certificate. If it is found to be valid, both the device's name and its certificate are stored in AWS IoT Core and is used to authenticate device-to-cloud and cloud-to-device communication.
122 |
123 | When the `./iotprovision-bin -c aws -m jitr` provisioning command is run for the first time, the following happens:
124 |
125 | 1. A *self-signed* **Certificate Authority** (root-ca.crt) is generated. This is the Root CA.
126 | 2. A **Signer CA** (signer-ca.crt) is generated and signed by the Root-CA.
127 | 3. A **Device Certificate** (device.crt) is generated and signed by the signer certificate.
128 | 4. The **Device Certificate** and **Thing Name** is stored in the IoT Board.
129 | 5. The **Signer Certificate** is uploaded to AWS IoT as a CA.
130 |
131 | Step 3 and 4 are a bit simplified, as in reality, a [*Certificate Signing Request*](https://en.wikipedia.org/wiki/Certificate_signing_request) is performed. All of these certificates and their private keys (except the device certificates) can be found in the folder `.microchip-iot` under the users home directory. See the flowchart below for an illustration of the generation process.
132 |
133 | | OS | Path |
134 | | ------------- | ----------------------------- |
135 | | Windows | %userprofile%\\.microchip-iot |
136 | | Mac and Linux | ~/.microchip-iot |
137 |
138 | 
139 |
140 | The next time the tool runs, it checks for existing certificates in the `.microchip-iot` folder. If nothing is found, it runs through the process described above. If all certificates exist, it does nothing. If a Root CA and Signer CA exist, but the device is unknown, it signs the connected devices certificate with the Signer CA.
141 |
142 | After the initial setup, the device's certificate has been signed by the certificate authority that has been uploaded to AWS. When the device is connected to AWS for the first time, the certificate can, therefore, be verified and registered automatically. The *thing*'s name is then also registered and a predefined policy is assigned to the certificate. The authentication of the device for subsequent connections is described in the flowchart below.
143 |
144 | 
145 |
146 | ### Setting up JITR in AWS
147 |
148 | In AWS, JITR functionality can be obtained using an [*AWS Lambda Function*](https://aws.amazon.com/lambda/). A Lambda Function is a code snippet that runs without having dedicated resources. Whenever a call to the function is made, AWS allocates resources for the duration of the function call. From the AWS Documentation:
149 |
150 | > AWS Lambda is a compute service that lets you run code without provisioning or managing servers. AWS Lambda executes your code only when needed and scales automatically, from a few requests per day to thousands per second.
151 | >
152 | > \- [AWS Documentation - What is AWS Lambda?](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)
153 |
154 | A lambda function is precisely what is needed to implement the loop in the flowchart above. When an unknown device tries to connect using a CA-signed certificate, an MQTT message with the topic `$aws/events/certificates/registered/#` is published. Using an IoT Action (also called a *rule*), these messages are picked up and forwarded to a Lambda Function executing the code found in [jitr_lambda.py](jitr_lambda.py).
155 |
156 | > A device is *unknown* if it does not exist in the AWS IoT Thing Registry.
157 |
158 | The Lambda Function checks if a policy named `zt_policy` already exists, creating it if not. The device's certificate is linked to the policy and registered in AWS IoT Core. When the devices try to reconnect, it is authenticated. The figure below describes this process.
159 |
160 | 
161 |
162 | A screenshot of the "Forward Signed but Unknown Devices" rule is shown below.
163 |
164 | 
165 |
166 | ## Multi-account Registration
167 |
168 | *Multi-account registration* is a provisioning method where device names and certificates have to be uploaded and registered in AWS before device-to-cloud connectivitiy can be authorized and established. There is not need for an AWS Lambda function using this method, since everything is registered before connecting.
169 |
170 | When the `./iotprovision-bin -c aws -m mar` provisioning command is run for the first time, the following happens:
171 |
172 | 1. A *self-signed* **Certificate Authority** (root-ca.crt) is generated. This is the Root CA.
173 | 2. A **Signer CA** (signer-ca.crt) is generated and signed by the Root-CA.
174 | 3. A **Device Certificate** (device.crt) is generated and signed by the signer certificate.
175 | 4. The **Device Certificate** and **Thing Name** is stored in the IoT Board.
176 | 5. The **Device Certificate** and **Thing Name** is uploaded and registered with AWS
177 |
178 | The first four steps are similar to the JITR procedures above, and step 3 and 4 are simplified here as well. In reality, a [*Certificate Signing Request*](https://en.wikipedia.org/wiki/Certificate_signing_request) is performed. All of these certificates and their private keys (except the device certificates) can be found in the folder `.microchip-iot` under the users home directory.
179 |
180 | | OS | Path |
181 | | ------------- | ----------------------------- |
182 | | Windows | %userprofile%\\.microchip-iot |
183 | | Mac and Linux | ~/.microchip-iot |
184 |
185 | When the above process is complete, the device is authorized to communicate with AWS and there is no need for further registrations upon the first connection.
186 |
187 | ## Device Permissions in AWS
188 |
189 | All devices that interact with an AWS account are registered in the IoT Core Module and are called *things*. A thing has a *certificate* attached to it, which again is connected to a *policy*, which defines the certificates permissions and thus also the things permissions. When a device connects, it provides a certificate and a *thing name*. If the thing with the specified name exists and the certificate is valid, the device is allowed to connect and perform the actions specified in the certificates policy.
190 |
191 | **Summarized**: Permissions in AWS, such as connect and send data, are defined by a *policy*. Policies are attached to *certificates*, which are used to authenticate *things* (devices).
192 |
193 | ### Policy Example
194 |
195 | Policies are defined as JSON documents, with one or more *statements*. From the AWS Documentation:
196 |
197 | > An AWS IoT Core policy is a JSON document that contains one or more policy statements. Each statement contains:
198 | >
199 | > - Effect, which specifies whether the action is allowed or denied
200 | >
201 | > - Action, which specifies the action the policy is allowing or denying
202 | >
203 | > - Resource, which specifies the resource or resources on which the action is allowed or denied
204 | >
205 | > \- [AWS Documentation - AWS IoT Core Policies](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html)
206 |
207 | When using the IoT Provisioning Tool, a policy is generated and added based on the project's properties. An example of this policy can be seen in [policy_example.json](policy_example.json).
208 |
209 | ## Finding the AWS Resources
210 |
211 | The IoT Provisioning Tool sets up the process described above on initial execution, and the resources it sets up can be found in the AWS Console. The resources can be found in the following locations:
212 |
213 | - **Certificate**: IoT Core -> Security -> Certificates
214 | - **Certificate Authority**: IoT Core -> Security -> CAs
215 | - **Policies**: IoT Core -> Security -> Policies
216 | - **Things** (Devices): IoT Core -> Manage -> Things
217 | - **JITR Lambda Function**: Lambda -> JITR
218 |
219 | ## Next Steps
220 |
221 | [](../your-first-application-sending-and-receiving-data)
222 |
223 | ## Resources
224 |
225 | - [PIC-IoT WA Development Board Product Page](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-the-provisioning-process)
226 | - [AVR-IoT WA Development Board Product Page](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-the-provisioning-process)
227 | - [IoT Provisioning Tool](https://www.microchip.com/mymicrochip/filehandler.aspx?ddocname=en1001525)
228 | - [AWS Blog on JITR](https://aws.amazon.com/blogs/iot/just-in-time-registration-of-device-certificates-on-aws-iot/)
229 | - [AWS IoT Core Multi-Account Registration Developer documentation](https://docs.aws.amazon.com/iot/latest/developerguide/x509-client-certs.html)
230 | - [AWS Lambda Function](https://aws.amazon.com/lambda/)
231 |
--------------------------------------------------------------------------------
/a-more-thorough-look-into-the-provisioning-process/figures/find-rules.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/a-more-thorough-look-into-the-provisioning-process/figures/find-rules.jpg
--------------------------------------------------------------------------------
/a-more-thorough-look-into-the-provisioning-process/figures/forward-rule.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/a-more-thorough-look-into-the-provisioning-process/figures/forward-rule.jpg
--------------------------------------------------------------------------------
/a-more-thorough-look-into-the-provisioning-process/figures/jitr-aws-diagram.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/a-more-thorough-look-into-the-provisioning-process/figures/jitr-flow.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/a-more-thorough-look-into-the-provisioning-process/jitr_lambda.py:
--------------------------------------------------------------------------------
1 | import os
2 | import boto3
3 | import botocore
4 | import json
5 | from cryptography import x509
6 | from cryptography.hazmat.backends import default_backend
7 | import binascii
8 | from string import Template
9 |
10 | iot = boto3.client('iot')
11 | ZT_THING_TYPE_NAME = 'microchip-zero-touch-kit'
12 | ZT_POLICY_NAME = "zt_policy"
13 | ZT_POLICY_TEMPLATE = {
14 | "Version": "2012-10-17",
15 | "Statement": [
16 | {
17 | "Effect": "Allow",
18 | "Action": [
19 | "iot:Connect"
20 | ],
21 | "Resource": [
22 | "arn:aws:iot:${region}:${account_id}:client/${iot:Connection.Thing.ThingName}"
23 | ]
24 | },
25 | {
26 | "Effect": "Allow",
27 | "Action": [
28 | "iot:Publish",
29 | "iot:Receive"
30 | ],
31 | "Resource": [
32 | "arn:aws:iot:${region}:${account_id}:topic/${iot:Connection.Thing.ThingName}/*",
33 | "arn:aws:iot:${region}:${account_id}:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*"
34 | ]
35 | },
36 | {
37 | "Effect": "Allow",
38 | "Action": [
39 | "iot:Subscribe"
40 | ],
41 | "Resource": [
42 | "arn:aws:iot:${region}:${account_id}:topicfilter/${iot:Connection.Thing.ThingName}/#",
43 | "arn:aws:iot:${region}:${account_id}:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*"
44 | ]
45 | },
46 | {
47 | "Effect": "Allow",
48 | "Action": [
49 | "iot:UpdateThingShadow",
50 | "iot:GetThingShadow"
51 | ],
52 | "Resource": [
53 | "arn:aws:iot:${region}:${account_id}:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*"
54 | ]
55 | }
56 | ]
57 | }
58 |
59 |
60 | def cert_get_skid(certificate_pem):
61 |
62 | cert = x509.load_pem_x509_certificate(data=bytearray(
63 | certificate_pem, "utf-8"), backend=default_backend())
64 | """
65 | The generated digest is the SHA1 hash of the subjectPublicKey ASN.1 bit string.
66 | This is the first recommendation in RFC 5280 section 4.2.1.2
67 | """
68 | ski = x509.SubjectKeyIdentifier.from_public_key(cert.public_key())
69 |
70 | return binascii.b2a_hex(ski.digest).decode('ascii')
71 |
72 |
73 | def create_policy(account_id, region):
74 | """
75 | Creates the policy if it does not exist.
76 | """
77 | try:
78 | iot.get_policy(policyName=ZT_POLICY_NAME)
79 | except botocore.exceptions.ClientError as e:
80 | if e.response["Error"]["Code"] == "ResourceNotFoundException":
81 | policy_template = Template(
82 | json.dumps(ZT_POLICY_TEMPLATE, indent=4))
83 | policy_document = policy_template.safe_substitute(
84 | account_id=account_id, region=region)
85 | iot.create_policy(policyName=ZT_POLICY_NAME,
86 | policyDocument=policy_document)
87 | else:
88 | raise e
89 |
90 | def lambda_handler(event, context):
91 | region = os.environ['AWS_DEFAULT_REGION']
92 | account_id = event['awsAccountId']
93 | certificate_id = event['certificateId']
94 |
95 | response = iot.describe_certificate(certificateId=certificate_id)
96 | certificate_arn = response['certificateDescription']['certificateArn']
97 |
98 | subj_key_id = cert_get_skid(
99 | response['certificateDescription']['certificatePem'])
100 |
101 | print('Certificate Subject Key ID: {}'.format(subj_key_id))
102 | thing_name = subj_key_id
103 |
104 | response = iot.create_thing_type(thingTypeName=ZT_THING_TYPE_NAME)
105 | response = iot.create_thing(
106 | thingName=thing_name, thingTypeName=ZT_THING_TYPE_NAME)
107 |
108 | create_policy(account_id, region)
109 |
110 | iot.attach_principal_policy(
111 | policyName=ZT_POLICY_NAME,
112 | principal=certificate_arn)
113 |
114 | iot.attach_thing_principal(
115 | thingName=thing_name,
116 | principal=certificate_arn)
117 |
118 | response = iot.update_certificate(
119 | certificateId=certificate_id,
120 | newStatus='ACTIVE')
121 |
--------------------------------------------------------------------------------
/a-more-thorough-look-into-the-provisioning-process/policy_example.json:
--------------------------------------------------------------------------------
1 | {
2 | "Version": "2012-10-17",
3 | "Statement": [
4 | {
5 | "Effect": "Allow",
6 | "Action": [
7 | "iot:Connect"
8 | ],
9 | "Resource": [
10 | "arn:aws:iot:us-east-2:420230807713:client/${iot:Connection.Thing.ThingName}"
11 | ]
12 | },
13 | {
14 | "Effect": "Allow",
15 | "Action": [
16 | "iot:Publish",
17 | "iot:Receive"
18 | ],
19 | "Resource": [
20 | "arn:aws:iot:us-east-2:420230807713:topic/${iot:Connection.Thing.ThingName}/*",
21 | "arn:aws:iot:us-east-2:420230807713:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*"
22 | ]
23 | },
24 | {
25 | "Effect": "Allow",
26 | "Action": [
27 | "iot:Subscribe"
28 | ],
29 | "Resource": [
30 | "arn:aws:iot:us-east-2:420230807713:topicfilter/${iot:Connection.Thing.ThingName}/#",
31 | "arn:aws:iot:us-east-2:420230807713:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*"
32 | ]
33 | },
34 | {
35 | "Effect": "Allow",
36 | "Action": [
37 | "iot:UpdateThingShadow",
38 | "iot:GetThingShadow"
39 | ],
40 | "Resource": [
41 | "arn:aws:iot:us-east-2:420230807713:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*"
42 | ]
43 | }
44 | ]
45 | }
--------------------------------------------------------------------------------
/access-the-sandbox/README.md:
--------------------------------------------------------------------------------
1 | # Access the Sandbox
2 |
3 | *Author: Johan Lofstad, Microchip Technology Inc.*
4 |
5 |
6 |
7 |
8 |
9 | The IoT Boards comes bundled with a pre-provisioned demo with a couple of tutorials. To access the demo:
10 |
11 | 1. Connect a [AVR-IoT WA](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-access-the-sandbox), [AVR-IoT WG](https://www.microchip.com/DevelopmentTools/ProductDetails/ac164160?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-access-the-sandbox), [PIC-IoT WA](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-access-the-sandbox), or [PIC-IoT WG](https://www.microchip.com/DevelopmentTools/ProductDetails/ac164164?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-access-the-sandbox) through USB
12 |
13 | - If you have a [AVR-IoT WG](https://www.microchip.com/DevelopmentTools/ProductDetails/ac164160?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-access-the-sandbox) or [PIC-IoT WG](https://www.microchip.com/DevelopmentTools/ProductDetails/ac164164?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-access-the-sandbox) board, convert it to the AWS variant (WA) by following [this video](https://www.youtube.com/watch?v=nwP8obSRaaE).
14 | 2. Download the newest firmware and follow the instructions to install
15 | - [AVR-IoT WA](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-access-the-sandbox): https://github.com/microchip-pic-avr-solutions/avr-iot-aws-sensor-node-mplab/releases
16 | - [PIC-IoT WA](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-access-the-sandbox): https://github.com/microchip-pic-avr-solutions/pic-iot-aws-sensor-node/releases
17 | 3. Open the `CURIOSITY` drive
18 | 4. Open `CLICK-ME.htm`
19 | 5. Enter your Wi-Fi Credentials and download a `WIFI.CFG` file
20 | 6. Drag & Drop the `WIFI.CFG` File to the `CURIOSITY` Drive
21 | 7. Wait for the board to connect. A blinking yellow light indicates that the board has connected successfully.
22 |
23 | 
24 |
25 | ## Next Steps
26 |
27 | [](../connect-the-board-to-your-aws-account)
28 |
--------------------------------------------------------------------------------
/access-the-sandbox/figures/sandbox.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/access-the-sandbox/figures/sandbox.gif
--------------------------------------------------------------------------------
/an-introduction-to-device-shadows-and-aws-lambda/figures/IAM_Add_role.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/an-introduction-to-device-shadows-and-aws-lambda/figures/IAM_Add_role.gif
--------------------------------------------------------------------------------
/an-introduction-to-device-shadows-and-aws-lambda/figures/add_trigger_to_route_data.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/an-introduction-to-device-shadows-and-aws-lambda/figures/add_trigger_to_route_data.gif
--------------------------------------------------------------------------------
/an-introduction-to-device-shadows-and-aws-lambda/figures/creating_empty_lambda_function.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/an-introduction-to-device-shadows-and-aws-lambda/figures/creating_empty_lambda_function.gif
--------------------------------------------------------------------------------
/an-introduction-to-device-shadows-and-aws-lambda/figures/show_shadow_update_messages.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/an-introduction-to-device-shadows-and-aws-lambda/figures/show_shadow_update_messages.gif
--------------------------------------------------------------------------------
/an-introduction-to-device-shadows-and-aws-lambda/figures/working_application_example.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/an-introduction-to-device-shadows-and-aws-lambda/figures/working_application_example.gif
--------------------------------------------------------------------------------
/an-introduction-to-device-shadows-and-aws-lambda/lambda_function.py:
--------------------------------------------------------------------------------
1 | import boto3 # AWS SDK for python
2 | import json # JSON encoder and decoder
3 |
4 | # Name of the AWS IoT Core thing that should be notified about process anomalies
5 | notificationThing = 'notificationThingName'
6 |
7 | lightLevelThreshold = 200 # Light threshold for process anomaly notification
8 |
9 | # Main function
10 | def lambda_handler(event, context):
11 | # Initialize dictionary for state variables
12 | dict = {}
13 |
14 | if event['Light'] > lightLevelThreshold:
15 | dict['anomaly'] = 1
16 | else:
17 | dict['anomaly'] = 0
18 |
19 | update_shadow(dict, notificationThing)
20 |
21 | # Updates the device shadow of the specified thing_name
22 | def update_shadow(state_dict, thing_name):
23 |
24 | # Construct payload and convert it to JSON format
25 | payload = {
26 | "state": {
27 | "desired": state_dict
28 | }
29 | }
30 | JSON_payload = json.dumps(payload)
31 |
32 | # Initialize AWS IoT Core SDK communicaiton client
33 | IoT_client = boto3.client('iot-data', 'us-east-2')
34 |
35 | # Send shadow update request
36 | response = IoT_client.update_thing_shadow(thingName=thing_name,payload=JSON_payload)
--------------------------------------------------------------------------------
/connect-the-board-to-your-aws-account/MCHPProvToolAccess.json:
--------------------------------------------------------------------------------
1 | {
2 | "Version": "2012-10-17",
3 | "Statement": [
4 | {
5 | "Sid": "VisualEditor0",
6 | "Effect": "Allow",
7 | "Action": [
8 | "lambda:CreateFunction",
9 | "iot:*",
10 | "iam:CreateRole",
11 | "lambda:GetFunctionConfiguration",
12 | "iam:AttachRolePolicy",
13 | "iam:PutRolePolicy",
14 | "iam:PassRole",
15 | "iam:DetachRolePolicy",
16 | "iam:DeleteRolePolicy",
17 | "lambda:DeleteFunction",
18 | "iam:GetRole",
19 | "lambda:ListFunctions",
20 | "lambda:GetFunction",
21 | "iam:DeleteRole",
22 | "cloudformation:DescribeStacks",
23 | "cloudformation:ListStacks",
24 | "lambda:UpdateFunctionCode",
25 | "lambda:AddPermission",
26 | "cloudformation:CreateStack",
27 | "cloudformation:DeleteStack",
28 | "lambda:RemovePermission",
29 | "iam:GetRolePolicy"
30 | ],
31 | "Resource": "*"
32 | }
33 | ]
34 | }
--------------------------------------------------------------------------------
/connect-the-board-to-your-aws-account/README.md:
--------------------------------------------------------------------------------
1 | # Connect the Board to your AWS Account
2 |
3 | *Author: Johan Lofstad, Microchip Technology Inc.*
4 |
5 |
6 |
7 |
8 |
9 | ## Introduction
10 |
11 | This introductory guide explains how to securely connect an embedded design to [Amazon Web Services® (AWS)](https://aws.amazon.com/) through the [AWS IoT Core](https://aws.amazon.com/iot-core/) module. When connected, the AWS API can be used to send and receive data between the cloud and the board.
12 |
13 | ### Recommended Hardware
14 |
15 | This document is primarily written for the [AVR-IoT WA](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-connect-board-to-aws), [AVR-IoT WG](https://www.microchip.com/DevelopmentTools/ProductDetails/ac164160?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-connect-board-to-aws), [PIC-IoT WA](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-connect-board-to-aws), and [PIC-IoT WG](https://www.microchip.com/DevelopmentTools/ProductDetails/ac164164?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-connect-board-to-aws) development boards. Users with these boards can follow the guide on a step-by-step basis. Users of AVR-IoT and PIC-IoT are recommended to run the quick start first to connect the board to the internet and explore the cloud sandbox before continuing. Instructions can be found at the ["See it in Action"](../access-the-sandbox) page.
16 |
17 | ### Required Software
18 |
19 | The [*IoT Provisioning Tool*](http://www.microchip.com/mymicrochip/filehandler.aspx?ddocname=en1001525) is used to generate and upload the required certificates to AWS and the IoT Board using either *Multi-Account Registration (MAR)* or *Just In Time Registration (JITR)*. For a deeper understanding of the provisioning process, see [Crash Course in Cryptography and X.509](../crash-course-in-cryptography-and-x509) and [A More Thorough Look into the Provisioning Process](../a-more-thorough-look-into-the-provisioning-process) after reading this document.
20 |
21 | **This guide explores the following topics:**
22 |
23 | - Configure AWS IAM with appropriate permissions
24 |
25 | - Use the IoT Provisioning Tool to authenticate the board with AWS IoT Core
26 |
27 | - Configure AWS IoT Core to communicate with the board through MQTT
28 |
29 | An AWS account is required for this guide. You can obtain one at [aws.amazon.com](https://aws.amazon.com/).
30 |
31 | ## Table of Contents
32 |
33 | - [Connect the Board to your AWS Account](#connect-the-board-to-your-aws-account)
34 | - [Introduction](#introduction)
35 | - [Recommended Hardware](#recommended-hardware)
36 | - [Required Software](#required-software)
37 | - [Table of Contents](#table-of-contents)
38 | - [Step 1: Configuring AWS Identity and Access Management (IAM)](#step-1-configuring-aws-identity-and-access-management-iam)
39 | - [Create a Policy](#create-a-policy)
40 | - [Creating a New IAM User](#creating-a-new-iam-user)
41 | - [Step 2: Provisioning of the IoT Board](#step-2-provisioning-of-the-iot-board)
42 | - [Step 2.1 Install the Provisioning Tool and its Dependencies](#step-21-install-the-provisioning-tool-and-its-dependencies)
43 | - [Step 2.2 Generate the Certificates](#step-22-generate-the-certificates)
44 | - [Registering the AWS Credentials](#registering-the-aws-credentials)
45 | - [Running the IoT Provisioning Tool](#running-the-iot-provisioning-tool)
46 | - [Step 3: Testing and Receiving the Messages](#step-3-testing-and-receiving-the-messages)
47 | - [Step 4: Adding Multiple Devices](#step-4-adding-multiple-devices)
48 | - [Next Steps](#next-steps)
49 | - [Resources](#resources)
50 |
51 | ## Step 1: Configuring AWS Identity and Access Management (IAM)
52 |
53 | IAM is an AWS service managing who and what has access to different *resources*. A resource is something "existing" in AWS. This could, for instance, be a registered IoT device, a cloud module such as the IoT Core, or a cryptographic certificate. The security philosophy is, *you only have access to a resource if you **need** that resource*.
54 |
55 | > *AWS Identity and Access Management (IAM) is a web service that helps you securely control access to AWS resources. You use IAM to control who is authenticated (signed in) and authorized (has permissions) to use resources.*
56 | >
57 | > \- [*AWS IAM Documentation*](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html)
58 |
59 | To connect the board to an AWS account, it must be *provisioned* using the [*IoT Provisioning Tool*](http://www.microchip.com/mymicrochip/filehandler.aspx?ddocname=en1001525), which requires specific AWS access to configure the required modules.
60 |
61 | ### Create a Policy
62 |
63 | Permission for these specific resources is given to the tool through a *policy*. From the AWS Documentation:
64 |
65 | > *You manage access in AWS by creating policies and attaching them to IAM identities (users, groups of users, or roles) or AWS resources. A policy is an object in AWS that, when associated with an identity or resource, defines their permissions.*
66 | >
67 | > \- [AWS Documentation - Policies and Permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html)
68 |
69 | Open the [IAM module](https://console.aws.amazon.com/iam/home#/home) in AWS and select **Policies** in the menu on the left-hand side. Click **Create policy** and select the **JSON** tab. Copy and paste the contents of [MCHPProvToolAccess.json](./MCHPProvToolAccess.json) into the editor and click **Review Policy**. Name it `MCHPProvToolAccess` before clicking **Create policy**.
70 |
71 | > **Note**: The MCHPProvToolAccess.json file has been updated in newer revisions of this guide to reflect changes in the IoT Provisioning Tool. If you have already added the permissions at an earlier point, it is recommended to re-add them.
72 |
73 | 
74 |
75 | ### Creating a New IAM User
76 |
77 | With the policy created, it must be attached to a *user*. Navigate to the [IAM module](https://console.aws.amazon.com/iam/home#/home) and click **Users** followed by **Add user**. Give it a suitable name such as `provtooluser`. Check **Programmatic access** as the **Access type**. Click on **Next: Permissions**.
78 |
79 | 
80 |
81 | When presented with the **Add user** screen:
82 |
83 | 1. Click **Create group** and name it `provtoolgroup`.
84 | 2. Check the **MCHPProvToolAccess** policy.
85 | 3. Click **Create group** in the bottom right corner.
86 |
87 | Proceed to click **Next** until the review screen. Review the details and click **Create User**. A set of user credentials is generated. Make note of the **Access key ID** and **Secret access key** (click **Show** to reveal the secret access key).
88 |
89 | 
90 |
91 | ## Step 2: Provisioning of the IoT Board
92 |
93 | > *Provisioning* a device is the process of authenticating it with the cloud.
94 |
95 | There are several methods to provision the board with AWS, and the method is dependent on the application. In this guide the *Multi-Account Registration* (MAR) approach is used, where the IoT Provisioning tool takes care of the cryptography. This is a good choice to get started with a small number of boards (for example when buying with Microchip's [Trust&GO Platform](https://www.microchip.com/design-centers/security-ics/trust-platform/trust-go?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-connect-board-to-aws)).
96 |
97 | ### Step 2.1 Install the Provisioning Tool and its Dependencies
98 |
99 | - Install the [AWS Command Line Interface](https://aws.amazon.com/cli/)
100 | - Download the [IoT Provisioning Tool](http://www.microchip.com/mymicrochip/filehandler.aspx?ddocname=en1001525). Extract the zip folder to a known location.
101 |
102 | ### Step 2.2 Generate the Certificates
103 |
104 | Open a command line (the [Command Prompt](https://en.wikipedia.org/wiki/Cmd.exe) for Windows® and the terminal for Mac® and Linux®) and navigate to the extracted IoT Provisioning Tool folder. Run `aws configure` and enter the fields being asked for. The access credentials are the ones from [the IAM section](#creating-a-new-iam-user). See the screenshot below.
105 |
106 | *Note that the console syntax below might be different for your system.*
107 |
108 | *Note also that not all AWS regions are supported by the IoT boards. See the table below for a complete list of supported regions:*
109 |
110 | | Region name | Region |
111 | | ------------------------ | -------------- |
112 | | US East (Ohio) | us-east-2 |
113 | | US East (N. Virginia) | us-east-1 |
114 | | US West (Oregon) | us-west-2 |
115 | | Asia Pacific (Singapore) | ap-southeast-1 |
116 | | Asia Pacific (Sydney) | ap-southeast-2 |
117 | | Asia Pacific (Tokyo) | ap-northeast-1 |
118 | | Asia Pacific (Seoul) | ap-northeast-2 |
119 | | EU (Frankfurt) | eu-central-1 |
120 | | EU (Ireland) | eu-west-1 |
121 | | EU (London) | eu-west-2 |
122 | | China (Beijing) | cn-north-1 |
123 |
124 | #### Registering the AWS Credentials
125 |
126 | ```console
127 | user@sys:/provtool$ aws configure
128 | AWS Access Key ID [None]: AKIAWDV5V***********
129 | AWS Secret Access Key [None]: *********************
130 | Default region name [None]: us-east-2
131 | Default output format [None]:
132 | ```
133 |
134 | #### Running the IoT Provisioning Tool
135 |
136 | Connect the board through USB to the computer. With the board connected and the AWS credentials set, the provisioning tool can create and upload the certificates.
137 |
138 | ```console
139 | user@sys:/provtool$ ./iotprovision-bin -c aws -m mar --force
140 | ......
141 | ......
142 | ......
143 | Rebooting debugger
144 | Done.
145 | ```
146 |
147 | 
148 |
149 | The tool connects to AWS in the region specified in the [Registering the AWS Credentials](#registering-the-aws-credentials) section. A self-signed certificate is generated by the board and is uploaded to AWS by the provisioning tool. The board itself is registered as a *thing* in AWS IoT Core, and is then linked to the uploaded certificate - ensuring that device-to-cloud communicaton is authorized.
150 |
151 | The details of this process is part of the [X.509](https://en.wikipedia.org/wiki/X.509) cryptography standard and is not required reading for this introductory guide. For now, understand that the uploaded certificate causes AWS to trust the board. For reference, all the certificates and their private keys can be found in the `.microchip-iot` folder in the user home directory.
152 |
153 | | OS | Path |
154 | | ------------- | ----------------------------- |
155 | | Windows | %userprofile%\\.microchip-iot |
156 | | Mac and Linux | ~/.microchip-iot |
157 |
158 | > *In cryptography, a certificate authority or certification authority (CA) is an entity that issues digital certificates. A digital certificate certifies the ownership of a public key by the named subject of the certificate. This allows others (relying parties) to rely upon signatures or on assertions made about the private key that corresponds to the certified public key.*
159 | >
160 | > \- [Wikipedia.org - Certificate Authority](https://en.wikipedia.org/wiki/Certificate_authority)
161 |
162 | Make sure the device is connected to the internet, indicated by a solid blue light on the board. See the ["See it in Action"](../access-the-sandbox) page for instructions on connecting to the internet.
163 |
164 | If the device blinks a yellow LED, the board is provisioned, and data flows from the board to AWS. The provisioning tool created and uploaded the following items:
165 |
166 | - The board's certificate under **Secure -> Certificates**
167 |
168 | - The device (thing) under **Manage -> Things**
169 |
170 | > In AWS, a device is called a *thing*, as in Internet of *Things*.
171 |
172 | ## Step 3: Testing and Receiving the Messages
173 |
174 | The board is now provisioned, and data is sent from the board to AWS. This data can be viewed by going to **Test** in [AWS IoT Core](https://aws.amazon.com/iot-core/). Under **Subscription topic**, enter `thingName/sensors`. The `thingName` is a unique identifier for the device. The name is found under **Manage -> Things**. Click **Subscribe to topic**. The data now streams out to the console, as seen in the figure below.
175 |
176 | *Potential Pitfall: The thing name must be **lowercase** when subscribing to its sensor topic.*
177 |
178 | > The protocol used to send and receive data is [*MQTT*](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html). It is recommended to become familiar with MQTT when working with these kinds of IoT devices. By default, the IoT board sends data on the `sensors` topic.
179 |
180 | 
181 |
182 | ## Step 4: Adding Multiple Devices
183 |
184 | Fore every new device added to AWS IoT, a corresponding self-signed certificate must be extracted from the device and uploaded in a similar manner to that described in [Step 2.2 Generate the certificates](#step-22-generate-the-certificates). Connect the new board through USB, and run the provisioning tool in the same manner:
185 |
186 | ```console
187 | user@sys:/provtool$ ./iotprovision-bin -c aws -m mar
188 | ......
189 | ......
190 | ......
191 | Rebooting debugger
192 | Done.
193 | ```
194 |
195 | The tool creates a new certificate and uploads it to AWS IoT, ensuring a trust relationship between the device and AWS. The device's data can be access in the same manner as the first one, on the `thingName/sensors` MQTT topic.
196 |
197 | ## Next Steps
198 |
199 |
8 |
9 | The [AVR-IoT WA](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-crash-course-crypto-x509) and [PIC-IoT WA](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-crash-course-crypto-x509) use the X.509 cryptographic standard to authenticate devices and transfer data securely. This is the same standard most of the web relies on. This document provides a crash course in X.509, explaining the basic concepts required to understand the provisioning process between the IoT Board and AWS. It is recommended to read the [A More Thorough Look into the Provisioning Process](../a-more-thorough-look-into-the-provisioning-process) document after this one.
10 |
11 | It uses *Public-Key Cryptography* to provide [confidentiality and authenticity](https://en.wikipedia.org/wiki/Information_security).
12 |
13 | > In cryptography, X.509 is a standard defining the format of public-key certificates. X.509 certificates are used in many Internet protocols, including TLS/SSL, which is the basis for HTTPS[2], the secure protocol for browsing the web.
14 | >
15 | > \- [Wikipedia.org - X.509](https://en.wikipedia.org/wiki/X.509)
16 |
17 | > *Confidentiality* is the principle that only entities that are authorized to access the data can access the data.
18 | > *Authenticity* is the principle that an entity that is communicated is what it claims to be.
19 |
20 | ## Table of Contents
21 |
22 | - [Crash Course in Cryptography and X.509](#crash-course-in-cryptography-and-x509)
23 | - [Table of Contents](#table-of-contents)
24 | - [Public Key Cryptography](#public-key-cryptography)
25 | - [Signing a Document](#signing-a-document)
26 | - [The Concept of *Certificates* and X.509](#the-concept-of-certificates-and-x509)
27 | - [Chain of Trust](#chain-of-trust)
28 | - [Cryptography in Embedded Solutions](#cryptography-in-embedded-solutions)
29 | - [Next Steps](#next-steps)
30 | - [Resources](#resources)
31 |
32 | ## Public Key Cryptography
33 |
34 | In *Public Key Cryptography*, entities have a *key pair*, a non-secret **public key** that can encrypt messages and a secret **private key** that can decrypt messages. As the names suggest, the public key can be shared without any consequence, while the private key is never to be shared.
35 |
36 | A private key can, however, only decrypt messages encrypted with its corresponding public key. In other words:
37 |
38 | - A Public Key can **encrypt** but not decrypt a message, converting the text into *ciphertext*
39 | - A Private Key can **decrypt** a ciphertext generated by its corresponding public key
40 |
41 | > When a message is encrypted, its content is called *ciphertext*
42 |
43 | For instance, Bob wants to send Alice a secret message over an insecure medium, *the internet*. As the message is secret, it is important that no one eavesdrops and reads its contents. Alice gives Bob her public key, which Bob uses to encrypt his message into ciphertext. He sends the message to Alice, which uses her private key to decrypt the ciphertext into the message. See the figure below for an illustration.
44 |
45 | 
46 |
47 | ## Signing a Document
48 |
49 | By using a public key pair, *confidentiality* is ensured. Only the intended recipient can read the message. However, *authenticity* has still not been addressed. For instance, in the above example, Alice has no way of knowing that the message indeed came from Bob.
50 |
51 | A message can be *signed* with a private key and verified with a public key. In this example, Bob could use his private key to *sign* the message before sending it. Alice uses Bob's public key to verify that the message indeed came from Bob. The figure below illustrates this example, where Bob sends an encrypted and signed message to Alice.
52 |
53 | 
54 |
55 | ## The Concept of *Certificates* and X.509
56 |
57 | A *Certificate* is a document that proves ownership of a public key. The X.509 standard is nothing more than a standard on these certificates. An entity *owns* a public key if it knows the corresponding private key. Some of the contents of a certificate are:
58 |
59 | - The public key in question
60 | - Information about the owner
61 | - A signature from an entity that has verified the contents of the certificate
62 |
63 | The signature is a digital signature, signed with a private key. It proves that a private key has verified the message (in this case, a certificate). A certificate can be signed by the corresponding private key, making it a *self-signed* certificate. This proves that the sender of the certificate knows the certificates private key.
64 |
65 | Conversely, it can be signed by another private key, a *certificate authority (CA)*. The basic idea is as follows: If the CA is trusted, and it again *trusts* the certificate by signing it, the signed certificate is also trusted. This is called the *chain of trust* and is an important concept in X.509.
66 |
67 | *If confused, think of certificates as proof that a device indeed is the device it claims to be.*
68 |
69 | ## Chain of Trust
70 |
71 | A *chain of trust* is used to authenticate components (in this case, devices). At the start of the chain, one certificate is trusted fully, a *root certificate*. The issuer/owner of this root certificate is called the *Certificate Authority (CA)*. Every device that is authenticated to an AWS IoT Project must be trusted somewhere in the chain.
72 |
73 | The CA *trusts* some other certificate, for instance, a *Certificate Signer*. This certificate signer again trusts several devices. As trust can be traced up the chain to the CA from a device. The device itself is trusted and authenticated.
74 |
75 | A common line of questioning is, "Why do we have a certificate signer? Why not sign the devices directly?". A certificate that signs devices directly is more exposed. More systems need to know about it, so it must be deployed more widely. This increases the chances of the private key being getting compromised. If that happens, the CA must be revoked, destroying the entire chain of trust. If, however, a certificate signer is compromised, only that certificate must be revoked, destroying a smaller part of the tree.
76 |
77 | > *In computer security, a chain of trust is established by validating each component of hardware and software from the end entity up to the root certificate.*
78 | >
79 | > \- [*Wikipedia.org - Chain of Trust*](https://en.wikipedia.org/wiki/Chain_of_trust)
80 |
81 | > The provisioning tool uses the term *signer certificate authority*, which serves as the *intermediate certificate authority*.
82 |
83 | 
84 |
85 | ## Cryptography in Embedded Solutions
86 |
87 | Any embedded solution which communicates with the internet *securely* requires some kind of *secret* to do so. The secret when using X.509 is the private key. This secret must be stored on the embedded device in a manner where it is not possible to read the secret, and at the same time, be able to decrypt incoming messages to the device. Generally, storing such secrets in any general-purpose memory (such as *flash*) is bad practice.
88 |
89 | A higher level of security is achieved by using a *secure element*. The PIC- & AVR-IoT boards use the [**ATECC608A**](https://www.microchip.com/wwwproducts/en/ATECC608A?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-crash-course-crypto-x509), a cryptographic chip that stores the key securely, providing (but not limited to) signing and decrypting capabilities. The MCU never touches the secret and it is never stored in the MCU's memory. The ATECC608A can generate a new key-pair when requested, and through a [*Certificate Signing Request* (CSR)](https://en.wikipedia.org/wiki/Certificate_signing_request) the key can be signed by a CA.
90 |
91 | In most IoT solutions with a secure element, every device must be signed by a CA, or the device's secret must be authenticated in some manner. This can introduce a significant cost during manufacturing, as every device has to go through a CSR. Said cost can be mitigated through the [Microchip Trust Platform](https://www.microchip.com/design-centers/security-ics/trust-platform?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-crash-course-crypto-x509), which secure elements that have already been signed. The trust platform comes in three flavors: [Trust&Go](https://www.microchip.com/design-centers/security-ics/trust-platform/trust-go?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-crash-course-crypto-x509), [TrustFlex](https://www.microchip.com/design-centers/security-ics/trust-platform/trustflex?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-crash-course-crypto-x509) and [TrustCUSTOM](https://www.microchip.com/design-centers/security-ics/trust-platform/trustcustom?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-crash-course-crypto-x509), with minimum ordering quantities of 10, 2000 and 4000 devices, respectively.
92 |
93 | ## Next Steps
94 |
95 |
8 |
9 | ## Introduction
10 |
11 | In this tutorial, we will showcase how Amazon CloudWatch can be used to monitor sensor data from PIC-IoT and AVR-IoT development boards.
12 |
13 | The tutorial assumes that you have a device that is already connected to your AWS account, and that is sending sensor data with the pre-loaded firmware on the [PIC-IoT](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-device-monitor-cloudwatch-intro) or [AVR-IoT](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-device-monitor-cloudwatch-intro) board, as outlined [here](../connect-the-board-to-your-aws-account).
14 |
15 | The pre-loaded firmware configures the IoT boards to send temperature and light sensor data to AWS every second. In this tutorial, we will forward those messages to Amazon CloudWatch to monitor the state of the device in near real-time (from 10 seconds to 15 minutes latency).
16 |
17 | To do so, we will create an [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) function that:
18 |
19 | 1. Processes the event.
20 | 2. Extracts the sensor data from the payload.
21 | 3. Pushes it to a CloudWatch metric namespace for near real-time data visualization.
22 |
23 | Check out the real-time visualization in the time-lapse animation below:
24 |
25 | 
26 |
27 | > Amazon CloudWatch monitors your Amazon Web Services (AWS) resources and the applications you run on AWS in real-time. You can use CloudWatch to collect and track metrics, which are variables you can measure for your resources and applications.
28 | >
29 | > [AWS Documentation: Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)
30 |
31 | Note that the closest to "real-time" we can get - such as in the [sandbox](../access-the-sandbox) - requires a more entailed approach that involves storing the data in a real-time processing database such as [Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html).
32 |
33 | ## Table of Contents
34 |
35 | - [Device Monitoring in Amazon CloudWatch](#device-monitoring-in-amazon-cloudwatch)
36 | - [Introduction](#introduction)
37 | - [Table of Contents](#table-of-contents)
38 | - [System Overview](#system-overview)
39 | - [Step-by-Step Instructions](#step-by-step-instructions)
40 | - [Step 1: Set up the Lambda Function](#step-1-set-up-the-lambda-function)
41 | - [Step 2: Configure IoT Core Rule](#step-2-configure-iot-core-rule)
42 | - [Step 3 See Results in CloudWatch Metrics](#step-3-see-results-in-cloudwatch-metrics)
43 | - [Next Steps](#next-steps)
44 | - [Resources](#resources)
45 |
46 | ### System Overview
47 |
48 | Below is a diagram of the system architecture for reference.
49 |
50 | 
51 |
52 | ## Step-by-Step Instructions
53 |
54 | ### Step 1: Set up the Lambda Function
55 |
56 | First, we will create the [AWS Lambda](https://aws.amazon.com/lambda/) function that will process and push MQTT messages from AWS IoT Core to Amazon CloudWatch. Lambda functions follow the broader paradigm of [serverless computing](https://en.wikipedia.org/wiki/Serverless_computing), where simple functions can be written in code without the need for configuring and managing servers and other hardware.
57 |
58 | This provides consistent performance, and continuous scaling as an IoT system grows in size. Cloud providers manage the allocation of resources, and users are billed primarily based on the number of resources consumed by their application.
59 |
60 | 1. Navigate to the AWS Lambda service console and create a new Lambda function with the name `iot_Core_to_CwMetrics`. Use **Python 3.8** as the runtime, and select **Create a new role with basic Lambda permissions** under **Execution role**.
61 | 
62 | 2. Scroll down to the **Function Code** section, and copy the code below into the code editor. Remember to click the **Save** button afterward.
63 |
64 | ```python
65 | import json # Python library for dealing with JSON objects
66 | import boto3 # boto3 is the AWS SDK for Python
67 |
68 | cloudwatch = boto3.client('cloudwatch')
69 |
70 | # Define payload attributes that may be changed based on device message schema
71 | ATTRIBUTES = ['Light','Temp']
72 |
73 | # Define CloudWatch namespace
74 | CLOUDWATCH_NAMESPACE = "thing2/MonitorMetrics"
75 |
76 | # Define function to publish the metric data to CloudWatch
77 | def cw(topic, metricValue, metricName):
78 | metric_data = {
79 | 'MetricName': metricName,
80 | 'Dimensions': [{'Name': 'topic', 'Value': topic}],
81 | 'Unit': 'None',
82 | 'Value': metricValue,
83 | 'StorageResolution': 1
84 | }
85 |
86 | cloudwatch.put_metric_data(MetricData=[metric_data],Namespace=CLOUDWATCH_NAMESPACE)
87 | return
88 |
89 | # Define the handler to loop through all the messages and looks to see if the message attributes
90 | # include light or temp and calls the cw() function if so to publish the custom metrics to Amazon CloudWatch
91 | def lambda_handler(event, context):
92 | # TODO implement
93 | for e in event:
94 | print("Received a message: {}".format(str(e)))
95 | # print(e) # Potential test point
96 |
97 | # Iterate through each attribute we'd like to publish
98 | for attribute in ATTRIBUTES:
99 | # Validate the event payload contains the desired attribute
100 | if attribute in e:
101 | print("publishing {} to CloudWatch".format(attribute))
102 | cw("AVR-IoT", event[attribute], attribute)
103 | return event
104 | ```
105 |
106 | - The key function here is the `lambda_handler` function, which will be invoked every time the Lambda function is triggered. The code above simply loops through the event data (e.g., the JSON payload from AWS IoT Core) for the defined `ATTRIBUTES`, and subsequently pushes those `ATTRIBUTES` to a user-defined `CLOUDWATCH_NAMESPACE` where the device data can be found later on.
107 | 3. To facilitate testing of our Lambda function, let us create a *test event* with some example data:
108 | 1. On the configuration page for the `iot_Core_to_Cw_Metrics` Lambda function, select **Configure test events** in the dropdown menu next to the **Test** button.
109 | 2. Select **Create new test event** and make sure `hello-world` is selected as the **Event template**.
110 | 3. Enter `TempAndLightLevelTest` as the **Event name**.
111 | 4. Replace the default code snippet with the code below:
112 |
113 | ```json
114 | {
115 | "Light": 32,
116 | "Temp": 32.06
117 | }
118 | ```
119 |
120 | 5. Click **Create**.
121 | 4. Click the **Test** button in the top right corner to test the newly created Lambda function. Now, inspecting the **Execution results** log below the code editor, we notice that the Lambda function has not been executed successfully.  The reason for this is that the Lambda function has not yet been given permissions to access the Amazon CloudWatch resource. Let us fix that:
122 | 1. Navigate to the [IAM console](https://console.aws.amazon.com/iam/home) and select **Roles** in the menu on the left-hand side.
123 | 2. Select the role that was created in step 1 previously. It will be named `iot_Core_to_CwMetrics-role-********` where the asterisks will be a randomly generated sequence of characters.
124 | 3. Click **Attach policies**.
125 | 4. Use the search bar to find the `CloudWatchFullAccess` and `AWSIoTFullAccess` policies and tick the boxes to select them.
126 | 5. Click **Attach policy**.
127 | 5. Return to the Lambda function that was created previously and try to run the test event one more time. This time it should succeed. 
128 |
129 | ### Step 2: Configure IoT Core Rule
130 |
131 | In the previous step, we configured an AWS Lambda function to process sensor data and send it to Amazon CloudWatch. In this step, we will create an AWS IoT *Rule* that registers sensor data received in the AWS IoT Core module and relays it to AWS Lambda for processing. The IoT Rule can be created both from AWS IoT Core directly and from the configuration interface for the Lambda function directly.
132 |
133 | 1. In the **Designer** panel, click on **Add trigger**.
134 | 2. Select `AWS IoT` as the trigger from the dropdown menu.
135 | 3. Select **Custom IoT rule**.
136 | 4. In the **Rule** dropdown menu, select `Create a new rule`.
137 | 5. Enter `IoTCore_to_Cw_Rule` as the **Rule name**.
138 | 6. Enter the following query as the **Rule query statement**.
139 |
140 | ```sql
141 | SELECT * FROM 'thingName/sensors'
142 | ```
143 |
144 | - Remember to replace `thingName` in the query with your device's thing name. The thing name can be found in AWS IoT Core under **Manage -> Things** in the menu on the left-hand side. Note also that the thing name should be lowercase for the IoT boards.
145 | 7. Ensure that the **Enable trigger** checkbox is checked.
146 | 8. Click **Add**.
147 |
148 | 
149 |
150 | Note that the IoT Core Rule can be created in AWS IoT Core as well, but it will not automatically be assigned to the Lambda function as a trigger. If the rule is created in AWS IoT Core directly, it is, therefore, necessary to manually add the trigger to the Lambda function. To do that, follow the steps above, but select the existing rule instead of `Create a new rule` in the dropdown menu in step 4 above.
151 |
152 | ### Step 3 See Results in CloudWatch Metrics
153 |
154 | 1. Navigate to Amazon CloudWatch and click on **Metrics** in the menu on the left-hand side.
155 | 2. In the **Custom Namespaces** section, click on the `thing2/MonitorMetrics` metric (we defined the name of this namespace in the Lambda function earlier).
156 | 3. Select the `topic` metric.
157 | 4. Tick the boxes next to both the `Temp` and `Light` metrics.
158 | 5. The data should now be plotted, and you can play around with the settings for the graphed metrics (period, auto-refresh, line, or stacked) to get the visualization you desire.
159 |
160 | 
161 |
162 | ## Next Steps
163 |
164 | 
165 |
166 | ## Resources
167 |
168 | - [PIC-IoT WA Development Board Product Page](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-device-monitor-cloudwatch-resources)
169 | - [AVR-IoT WA Development Board Product Page](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-device-monitor-cloudwatch-resources)
170 | - [Amazon CloudWatch Documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)
171 | - [AWS Lambda Documentation](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)
172 | - [AWS IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html)
173 |
--------------------------------------------------------------------------------
/device-monitoring-in-amazon-cloudWatch/figures/changing_graph_settings_in_cloudwatch.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/device-monitoring-in-amazon-cloudWatch/figures/changing_graph_settings_in_cloudwatch.gif
--------------------------------------------------------------------------------
/device-monitoring-in-amazon-cloudWatch/figures/demonstration_of_graphed_metrics.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/device-monitoring-in-amazon-cloudWatch/figures/demonstration_of_graphed_metrics.gif
--------------------------------------------------------------------------------
/device-monitoring-in-amazon-cloudWatch/figures/how_to_create_an_IoT_Core_rule.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/device-monitoring-in-amazon-cloudWatch/figures/how_to_create_an_IoT_Core_rule.gif
--------------------------------------------------------------------------------
/device-monitoring-in-amazon-cloudWatch/figures/how_to_create_lambda_function.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/device-monitoring-in-amazon-cloudWatch/figures/how_to_create_lambda_function.gif
--------------------------------------------------------------------------------
/device-monitoring-in-amazon-cloudWatch/figures/how_to_create_lambda_test_event.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/device-monitoring-in-amazon-cloudWatch/figures/how_to_create_lambda_test_event.gif
--------------------------------------------------------------------------------
/device-monitoring-in-amazon-cloudWatch/figures/lambda_function_execution_failed.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/device-monitoring-in-amazon-cloudWatch/figures/lambda_function_execution_failed.png
--------------------------------------------------------------------------------
/device-monitoring-in-amazon-cloudWatch/figures/lambda_function_execution_succeeded.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/device-monitoring-in-amazon-cloudWatch/figures/lambda_function_execution_succeeded.png
--------------------------------------------------------------------------------
/figures/action-button.svg:
--------------------------------------------------------------------------------
1 |
2 |
84 |
--------------------------------------------------------------------------------
/figures/feedback_button.svg:
--------------------------------------------------------------------------------
1 |
2 |
118 |
--------------------------------------------------------------------------------
/figures/header_safari.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/figures/header_safari.jpg
--------------------------------------------------------------------------------
/figures/header_safari.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/figures/header_safari.png
--------------------------------------------------------------------------------
/visualizing-sensor-data-in-jupyter-notebooks/README.md:
--------------------------------------------------------------------------------
1 | # Visualizing Sensor Data With Jupyter Notebooks
2 |
3 | *Author: Patrick Kennedy, Microchip Technology Inc.*
4 |
5 |
6 |
7 |
8 |
9 | ## Introduction
10 |
11 | This tutorial will show you how to get data from [AWS IoT Core](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) to the ubiquitous [Jupyter Notebook](https://jupyter.org/) environment commonly used for data exploration, analytics, modeling, and visualization.
12 |
13 | Note this tutorial assumes you have a [PIC-IoT](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-sensor-viz-jupy-nb-intro) or [AVR-IoT](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-sensor-viz-jupy-nb-intro) Development Board, and that this board is successfully sending sensor data to AWS IoT Core. A tutorial on how to set up the IoT boards is available [here](../connect-the-board-to-your-aws-account).
14 |
15 | > AWS IoT Analytics automates the steps required to analyze data from IoT devices. AWS IoT Analytics
16 | filters, transforms, and enriches IoT data before storing it in a time-series data store for analysis.
17 | >
18 | > \- [AWS IoT Analytics Documentation](https://docs.aws.amazon.com/iotanalytics/latest/userguide/welcome.html)
19 |
20 | As noted above, AWS IoT Analytics automates the steps required to build a scalable system that ingests, processes, and analyzes IoT data. The nature of IoT systems requires an architecture that offers long-term storage, asynchronous event management, real-time processing, and analysis tools. Similar systems can be built from scratch using other AWS services, but IoT Analytics provides a quick and easy method of correctly setting up the cloud architecture in the correct manner as recommended by the AWS team. The service is far easier to use and can be further extended to other AWS services via the channel and pipeline activities described below.
21 |
22 | Jupyter Notebook is a web-based interactive environment praised for inline documentation and a staple in data science. Jupyter Notebooks are a great way to explore newly created data sets and are further useful in terms of portability and containerization for deployment.
23 |
24 | Furthermore, the Jupyter Notebook environment created here is hosted directly on AWS, giving easy access to Amazon SageMaker services that provides the ability to seamlessly build, train, and deploy machine learning models for a variety of applications such as anomaly detection and predictive maintenance.
25 |
26 | ## Table of contents
27 |
28 | - [Visualizing Sensor Data With Jupyter Notebooks](#visualizing-sensor-data-with-jupyter-notebooks)
29 | - [Introduction](#introduction)
30 | - [Table of contents](#table-of-contents)
31 | - [System Overview](#system-overview)
32 | - [Associated Costs (Billing)](#associated-costs-billing)
33 | - [Walk-Through](#walk-through)
34 | - [Step 0: Prerequisites](#step-0-prerequisites)
35 | - [Step 1: Configure IoT Analytics](#step-1-configure-iot-analytics)
36 | - [Step 2: Create and Configure a SageMaker Notebook Instance](#step-2-create-and-configure-a-sagemaker-notebook-instance)
37 | - [Reference Jupyter Code](#reference-jupyter-code)
38 | - [Conclusion](#conclusion)
39 | - [Next Steps](#next-steps)
40 | - [Resources](#resources)
41 |
42 | ## System Overview
43 |
44 | 
45 | Above is an outline showing the system created when following the tutorial below. For more details on what each of the components above (e.g., channel, pipeline, etc.) provides, see the mini user guides provided by AWS. A brief description of each is included below for reference.
46 |
47 | [**Channels**](https://d1.awsstatic.com/IoT/User%20Guide%20PDFs/01_AWS_Mini-User_Guide_Channels_August2018.pdf) - A Channel ingests data and feeds it to a Pipeline(s) while keeping a copy of the raw MQTT messages for a certain time. This can be likened to a real-time database where data is continuously received and handled.
48 |
49 | [**Pipelines**](https://d1.awsstatic.com/IoT/User%20Guide%20PDFs/02_AWS_Mini-User_Guide_Pipelines_August2018.pdf) - A Pipeline provides mechanisms for enriching, cleaning, and transforming IoT messages of various structures. An example of this might be enriching data with weather information from the national weather service.
50 |
51 | [**Data Stores and Data Sets**](https://d1.awsstatic.com/IoT/User%20Guide%20PDFs/03_AWS_Mini-User_Guide_Datastores-and-Datasets_August2018.pdf) - Data stores are time-partitioned SQL database tables for useful long-term storage of IoT data. Data sets are typically created from Data stores by running SQL queries that effectively extract, transform, and load (ETL) that can be run on an ad-hoc basis or scheduled periodically. The Jupyter notebook becomes useful here as it can perform all the analysis needed by loading the data set into the notebook and running the code. Furthermore, the Jupyter Notebook can be deployed as a Docker container.
52 |
53 | A [Docker container](https://aws.amazon.com/docker/) is essentially an application that includes a manifest outlining the dependencies and configurations needed to run the application. Similar to how a virtual machine allows an Operating System to run on any piece of hardware, a Docker container allows an application to run on any Operating System. This becomes useful in scaling and portability as it means our analyses can be cloned and run on a variety of platforms.
54 |
55 | ## Associated Costs (Billing)
56 |
57 | You may incur charges from this tutorial. Before you start, please familiarize yourself with [Amazon SageMaker Pricing](https://aws.amazon.com/sagemaker/pricing/).
58 |
59 | If this is your first time using Amazon Sagemaker you will likely have access to [AWS Free Tier](https://aws.amazon.com/free) pricing. As part of this tier you get a certain amount of hours free for each notebook type. It is easy to exceed the free tier time limit and incur charges if you do not 'stop' the notebook after you are done.
60 |
61 | You will also be charged for storage space but this is typically less than $1.
62 |
63 | **To keep your charges under the cost of a candy bar you should 'stop' the notebook after you are done with the tutorial.**
64 |
65 | ## Walk-Through
66 |
67 | ### Step 0: Prerequisites
68 |
69 | Before starting, you should have a secure connection setup between your device and IoT Core, which you can verify by viewing incoming messages to the MQTT Client within the IoT Core console, as shown below.
70 |
71 | If unsure how to do this, see [Connect the Board to your AWS Account](../connect-the-board-to-your-aws-account).
72 |
73 | 
74 |
75 | ### Step 1: Configure IoT Analytics
76 |
77 | First, we need to configure an IoT Core rule to send a message to IoT Analytics. In the process of creating the rule, we will use the quick create function that will automatically create all the resources needed from IoT Analytics (e.g., channel, pipeline, data store, data set, etc.).
78 |
79 | > AWS IoT Analytics automates the steps required to analyze data from IoT devices. AWS IoT Analytics
80 | filters, transforms, and enriches IoT data before storing it in a time-series data store for analysis.
81 | >
82 | > \- [AWS IoT Analytics Documentation](https://docs.aws.amazon.com/iotanalytics/latest/userguide/welcome.html)
83 |
84 | 
85 |
86 | 1. Copy the subscription topic: `thingName/sensors`, where `thingName` is the unique name for your device.
87 | - (e.g. `4609efe9cf000c5e518ac0e8bf949ff8ae56df10/sensors`)
88 | 2. Create a new rule in IoT Core.
89 | - In the left-hand pane, navigate to **Act -> Rules** and click the blue **"Create"** button on the right-hand side to create a new rule. This will open the create rule GUI.
90 | 3. Let's start first with the action by scrolling down to the **"Set one or more actions"** section just below the code editor. Click **"Add action"**.
91 | 4. Select **"Send a message to IoT Analytics"** and click the **"Configure action"** button.
92 | 5. We are prompted to manually select an IoT Analytics channel and role OR just quickly create one.
93 | 1. Select **"Quick create IoT Analytics resources"** and enter `JupyterTutorial` as the **Resource prefix**. You will notice that this automatically generates and configures a generic channel, data store, pipeline, data set, and role necessary for basic operation.
94 | 2. Click the **"Add Action"** button on the bottom of screen.
95 | 6. Proceed by naming your rule and giving it a brief description.
96 | 7. Under **Rule query statement**, enter the code below. Remember to replace `thingName` with your device's thing name. Note that this is a SQL statement for which you can find further documentation [here](https://docs.aws.amazon.com/iot/latest/developerguide/iot-sql-reference.html).
97 |
98 | ```sql
99 | SELECT * FROM 'thingName/sensor'
100 | ```
101 |
102 | 8. Click **"Create rule"**.
103 | 9. Enable the rule by clicking on the three dots next to the rule and selecting **"Enable Rule"**. (**Hint:** If it is not showing up, try switching to the list view.)
104 | 10. Navigate to your data set: **IoT Analytics Console -> Data Set**. You can find the IoT Analytics console by using the AWS Services search feature on the toolbar at the top of the page. Click on the three-dot menu next to your data set and select **Run now**. This will run the SQL query you wrote in step 7.
105 | 11. **SUCCESS** - check out the IoT Analytics data set you just created! You can do this by opening the data set and seeing the result preview. It includes data recently published from the MQTT messages.
106 |
107 | 
108 |
109 | ### Step 2: Create and Configure a SageMaker Notebook Instance
110 |
111 | 
112 |
113 | 1. Create the Notebook Instance:
114 | 1. Navigate to Amazon Sagemaker and select **Notebook instances** in the menu on the left-hand side.
115 | 2. Click **Create notebook instance**. (Orange button on the top right-hand side.)
116 | 3. Leave settings as default, which should include a medium-sized instance and elastic inference disabled.
117 | > The **instance size** is how much cloud space you are afforded, so more data/computation might require more space. Additionally, elastic inference GPU acceleration for instances that can take advantage of parallel workflows to speed up the inference rate for a deployed model. The inference rate of model is similar to the interrupt latency of an embedded system, in that it is measured by how quickly a response can be "inferred" (e.g., classification) for a given input.
118 | 4. Create an IAM role for the notebook under **Permissions and encryption** -> **IAM Role** (drop-down menu) -> Select **"Create role"** to create a role with the default settings.
119 | 5. Click **Create notebook instance**. (Orange button on the bottom right-hand corner.)
120 | 6. Continue only when the notebook instance is **"InService"**. This may take a couple of minutes, and you might need to refresh for it to notify you.
121 |
122 | 
123 |
124 | 2. Modify the SageMaker NoteBook instance role:
125 | 1. Navigate back to **IoT Analytics Console -> Data sets**.
126 | 2. Click on the data set that you created and copy the data set *ARN*. We need to add this to the SageMaker role permissions within the IAM console.
127 | > Amazon Resource Names (ARNs) uniquely identify AWS resources.
128 | >
129 | > \- AWS General Reference Guide: [Amazon Resource Names (ARNs)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)
130 | 3. Navigate to **IAM console -> Roles** (Left-hand pane under Access Management). Then click on the SageMaker role.
131 | 4. Create and add a `GetDatasetContent` policy to the SageMaker role:
132 | 1. Select **"Add Inline Policy"**.
133 | 2. For **Service**, select **"IoT Analytics"**.
134 | 3. For **Actions**, type **"GetDatasetContent"**.
135 | 4. Add the Data Set ARN you copied previously from IoT Analytics.
136 | 5. Click **"Review Policy"**.
137 | 6. Give it a name and create the policy.
138 | 5. Ensure that the policy is added to the SageMaker role before continuing.
139 | 3. Create a new Notebook:
140 | 1. Navigate back to **IoT Analytics Console -> Notebooks**.
141 | 2. Click the blue **"Create"** button on the right-hand side to create a new notebook.
142 | 3. Select **"Blank Notebook"** and give the notebook a name.
143 | 4. Select the data set and notebook instance you just created and click **"Create Notebook"**.
144 | 
145 | 4. Configure the Notebook environment:
146 | 1. Within the Notebooks section of the IoT Analytics Console, find and open the notebook you just created (`.ipynb` extension).
147 | 2. Select the `conda_python3` kernel:
148 | - In the toolbar, select: **"Kernel" -> "Change Kernel" -> "conda_python3"**.
149 | 5. Write Python code to output and plot the sensor data. The required code, as well as an example output, is provided in the [Reference Jupyter Code](#reference-jupyter-code) section below.
150 | 1. First, we will need to import the `pandas` library that will allow us to read the CSV-formatted data set and store it in a *DataFrame*.
151 | > A DataFrame is a pandas object similar to an array that is commonly used in conjunction with machine learning and AI frameworks such as Tensorflow, Keras, and PyTorch.
152 | 
153 | 1. Second, we will need to import the `pyplot` function from the `matplotlib` library, which will allow us to easily plot the DataFrame we just stored. 
154 |
155 | ## Reference Jupyter Code
156 |
157 | ```python
158 | dataset = "iotanalyticstestproject_dataset"
159 | dataset_url = client.get_dataset_content(datasetName = dataset)['entries'][0]['dataURI']
160 |
161 | # start working with the data
162 | ```
163 |
164 | ```python
165 | import pandas as pd
166 | #load the dataset
167 |
168 |
169 | df=pd.read_csv(dataset_url)
170 | df
171 | ```
172 |
173 | | | light | temp | __dt |
174 | | --- | ----- | ----- | ----------------------- |
175 | | 0 | 23 | 32.93 | 2020-05-05 00:00:00.000 |
176 | | 1 | 24 | 32.87 | 2020-05-05 00:00:00.000 |
177 | | 2 | 22 | 32.87 | 2020-05-05 00:00:00.000 |
178 | | 3 | 20 | 32.93 | 2020-05-05 00:00:00.000 |
179 | | 4 | 19 | 32.87 | 2020-05-05 00:00:00.000 |
180 | | 5 | 20 | 32.87 | 2020-05-05 00:00:00.000 |
181 | | 6 | 22 | 32.87 | 2020-05-05 00:00:00.000 |
182 |
183 | ```python
184 | import matplotlib.pyplot as plt
185 | plt.plot(df['light'])
186 | plt.plot(df['temp'])
187 |
188 | ```
189 |
190 | 
191 |
192 | ## Conclusion
193 |
194 | This tutorial showed how to get data from AWS IoT Core to a Jupyter Notebook environment. Now that your environment is set up, try applying SageMaker models or other Python libraries to your data.
195 |
196 | Alternatively, you can [automate your workflow](https://docs.aws.amazon.com/iotanalytics/latest/userguide/automate.html) by deploying your notebook as a container so that it runs locally or remotely, and may further update periodically via an IoT Analytics data set update.
197 |
198 | ## Next Steps
199 |
200 | **To prevent incurring excess charges, we recommend that you stop the notebook instance after you're done exploring.** To stop the notebook: find your notebook instance (**IoT Analytics > Notebooks**), click on the **three dots** and select **Stop Instance**.
201 |
202 | [](../device-monitoring-in-amazon-cloudWatch)
203 |
204 | ## Resources
205 |
206 | - [PIC-IoT WA Development Board Product Page](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-sensor-viz-jupy-nb-resources)
207 | - [AVR-IoT WA Development Board Product Page](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-sensor-viz-jupy-nb-resources)
208 | - [AWS IoT Analytics User Guide](https://docs.aws.amazon.com/iotanalytics/latest/userguide/welcome.html)
209 | - [AWS IoT Developer Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html)
210 | - [Channels Mini Guide](https://d1.awsstatic.com/IoT/User%20Guide%20PDFs/01_AWS_Mini-User_Guide_Channels_August2018.pdf)
211 | - [Pipelines Mini Guide](https://d1.awsstatic.com/IoT/User%20Guide%20PDFs/02_AWS_Mini-User_Guide_Pipelines_August2018.pdf)
212 | - [Data Stores and Data Sets Mini Guide](https://d1.awsstatic.com/IoT/User%20Guide%20PDFs/03_AWS_Mini-User_Guide_Datastores-and-Datasets_August2018.pdf)
213 |
--------------------------------------------------------------------------------
/visualizing-sensor-data-in-jupyter-notebooks/figures/Configure_IAM_Notebook.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/visualizing-sensor-data-in-jupyter-notebooks/figures/Configure_IAM_Notebook.gif
--------------------------------------------------------------------------------
/visualizing-sensor-data-in-jupyter-notebooks/figures/IoTAnalyticsDataSetSuccess.JPG:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/visualizing-sensor-data-in-jupyter-notebooks/figures/IoTAnalyticsDataSetSuccess.JPG
--------------------------------------------------------------------------------
/visualizing-sensor-data-in-jupyter-notebooks/figures/IoT_Analytics_step1_create_rule.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/visualizing-sensor-data-in-jupyter-notebooks/figures/IoT_Analytics_step1_create_rule.gif
--------------------------------------------------------------------------------
/visualizing-sensor-data-in-jupyter-notebooks/figures/JuPy_Coding1.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/visualizing-sensor-data-in-jupyter-notebooks/figures/JuPy_Coding1.gif
--------------------------------------------------------------------------------
/visualizing-sensor-data-in-jupyter-notebooks/figures/JuPy_Coding2.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/visualizing-sensor-data-in-jupyter-notebooks/figures/JuPy_Coding2.gif
--------------------------------------------------------------------------------
/visualizing-sensor-data-in-jupyter-notebooks/figures/JuPy_IoTAnalytics_NB.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/visualizing-sensor-data-in-jupyter-notebooks/figures/JuPy_IoTAnalytics_NB.gif
--------------------------------------------------------------------------------
/visualizing-sensor-data-in-jupyter-notebooks/figures/SageMaker_Create_NotebookInstance.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/visualizing-sensor-data-in-jupyter-notebooks/figures/SageMaker_Create_NotebookInstance.gif
--------------------------------------------------------------------------------
/visualizing-sensor-data-in-jupyter-notebooks/figures/Step_0_mqtt.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/visualizing-sensor-data-in-jupyter-notebooks/figures/Step_0_mqtt.gif
--------------------------------------------------------------------------------
/visualizing-sensor-data-in-jupyter-notebooks/figures/output_6_1.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/visualizing-sensor-data-in-jupyter-notebooks/figures/output_6_1.png
--------------------------------------------------------------------------------
/visualizing-sensor-data-in-jupyter-notebooks/figures/system_overview_flowchart.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/visualizing-sensor-data-in-jupyter-notebooks/figures/system_overview_flowchart.png
--------------------------------------------------------------------------------
/your-first-application-sending-and-receiving-data/README.md:
--------------------------------------------------------------------------------
1 | # Your First Application – Sending and Receiving Data
2 |
3 | *Author: Lars Olav Skrebergene, Microchip Technology Inc.*
4 |
5 |
6 |
7 |
8 |
9 | ## Introduction
10 |
11 | In this tutorial, we will showcase how the AVR-IoT and PIC-IoT Development Boards can be configured to communicate with the cloud using Amazon Web Services® (AWS) and the MQTT messaging protocol.
12 |
13 | We will walk you through how to develop an example application where a network of IoT devices are configured to blink their LEDs whenever a button is pressed on any of them. Detailed step-by-step instructions will be provided and relevant concepts will also be covered as we go.
14 |
15 | The primary goal of this tutorial is for the reader to experience how to develop their own applications with the AVR-IoT and PIC-IoT Development Boards.
16 |
17 | ### Prerequisites
18 |
19 | It is assumed that the reader has already provisioned their PIC-IoT and/or AVR-IoT Development Board(s) to communicate with their own AWS account, as described in the previous tutorial: [Connecting to AWS with the IoT Provisioning Tool](../connect-the-board-to-your-aws-account).
20 |
21 | Before starting this tutorial, make sure that your IoT device(s) are successfully sending sensor data to AWS IoT Core. It is also assumed that the reader has installed the [MPLAB® X IDE](https://www.microchip.com/mplab/mplab-x-ide?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-first-app-send-receive-data-prequisites) and the [XC8](https://www.microchip.com/mplab/compilers?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-first-app-send-receive-data-prequisites) (AVR-IoT) or [XC16](https://www.microchip.com/mplab/compilers?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-first-app-send-receive-data-prequisites) (PIC-IoT) compiler. Note, for the AVR-IoT Cellular Mini board, the Arduino IDE must be used. More information [here](https://iot.microchip.com/docs/arduino/introduction/devenv).
22 |
23 | Links to software and other useful tools and guides are provided in the [Resources](#resources) section at the end of this tutorial.
24 |
25 | ## Table of Contents
26 |
27 | - [Your First Application – Sending and Receiving Data](#your-first-application--sending-and-receiving-data)
28 | - [Introduction](#introduction)
29 | - [Prerequisites](#prerequisites)
30 | - [Table of Contents](#table-of-contents)
31 | - [A Brief Introduction to the Firmware of the IoT Boards](#a-brief-introduction-to-the-firmware-of-the-iot-boards)
32 | - [Implementing the Example Application](#implementing-the-example-application)
33 | - [Step 0: Update the AWS IoT Core Policy](#step-0-update-the-aws-iot-core-policy)
34 | - [Step 1: Start With an Unmodified Version of the Github Project](#step-1-start-with-an-unmodified-version-of-the-github-project)
35 | - [Step 2: Sending MQTT Messages to the Cloud](#step-2-sending-mqtt-messages-to-the-cloud)
36 | - [Procedures for AVR-IoT Boards](#procedures-for-avr-iot-boards)
37 | - [Procedures for PIC-IoT Boards](#procedures-for-pic-iot-boards)
38 | - [Procedures for Both AVR-IoT and PIC-IoT Boards](#procedures-for-both-avr-iot-and-pic-iot-boards)
39 | - [Verify That Messages Are Successfully Being Sent to AWS](#verify-that-messages-are-successfully-being-sent-to-aws)
40 | - [Step 3: Receiving MQTT Messages From the Cloud](#step-3-receiving-mqtt-messages-from-the-cloud)
41 | - [Next Steps](#next-steps)
42 | - [Resources](#resources)
43 |
44 | ## A Brief Introduction to the Firmware of the IoT Boards
45 |
46 | The firmware that is pre-loaded onto the PIC-IoT and AVR-IoT Development Boards is available on GitHub and will form the starting point for the example application we will design in this tutorial. The MPLAB X projects for the different microcontroller families can be found here:
47 |
48 | - [GitHub repository for the **PIC**-IoT Development Boards](https://github.com/microchip-pic-avr-solutions/pic-iot-aws-sensor-node)
49 | - [GitHub repository for the **AVR**-IoT Development Boards](https://github.com/microchip-pic-avr-solutions/avr-iot-aws-sensor-node-mplab)
50 |
51 | _If you are using the AVR-IoT Cellular Mini, step 0 in this guide is relevant for setting up the topics in AWS, but a more comprehensive guide on using MQTT can be found [here](https://iot.microchip.com/docs/arduino/userguide/mqtt)_
52 |
53 | The `PICIoT.X` and `AVRIoT.X` projects contain many different files that handle cryptography, Wi-Fi connectivity, MQTT communication, and so on. In this tutorial, we will primarily work with `application_manager.c`, which is located under `Source Files -> MCC Generated Files` in MPLAB X. This file contains a lot of useful high-level functions that make it easy to develop an AWS application.
54 |
55 | Here is a summary of some important functions in `application_manager.c` that is relevant for this tutorial:
56 |
57 | - `subscribeToCloud`
58 | - Defines which MQTT topics the IoT board should be subscribed to and which functions should be run when messages are received to these topics. In the unmodified `PICIoT.X` and `AVRIoT.X` projects, the board is only subscribed to its device shadow update MQTT topic, and `receivedFromCloud` is the function specified to handle these updates.
59 | - `receivedFromCloud`
60 | - Runs when an MQTT shadow update message is received in the unmodified `PICIoT.X` or `AVRIoT.X` projects. This function analyzes the message and performs some action based on its contents. It then calls the `updateDeviceShadow` function to acknowledge that the shadow update has been received.
61 | - `sendToCloud`
62 | - Called every second to send sensor data to the cloud as MQTT messages. This function is a good template to learn how to send custom MQTT messages to custom MQTT topics using the IoT boards.
63 |
64 | We recommend the reader to take a quick look at `application_manager.c`, and, in particular, these functions, to get an overview of the existing functionality.
65 |
66 | ## Implementing the Example Application
67 |
68 | In this example, we will demonstrate how devices can be configured to send and receive messages over custom MQTT topics. An example application will be implemented where button presses on any of the configured devices will cause all devices to flash their LEDs. All communication will be sent between the IoT Boards and AWS IoT Core, as illustrated in the schematic below. No direct device-to-device communication will be used.
69 |
70 | 
71 |
72 | ### Step 0: Update the AWS IoT Core Policy
73 | In the [previous tutorial](../connect-the-board-to-your-aws-account), we provisioned the IoT boards using the [IoT Provisioning Tool](http://www.microchip.com/mymicrochip/filehandler.aspx?ddocname=en1001525). This generated an AWS IoT Core Policy that determines which permissions the boards have when they interact with AWS resources. By default, this policy is configured to only grant an IoT board the right to publish and subscribe to MQTT topics containing the board's thing name.
74 |
75 | In this tutorial, we will send and receive MQTT messages over the `buttonPresses` topic. We must, therefore, expand the permissions to also include this topic:
76 |
77 | 1. Open the [IoT Core](https://us-east-2.console.aws.amazon.com/iot/home) module in AWS and select **Secure -> Policies** in the menu on the left-hand side.
78 | 2. Open **zt_policy** and scroll down to the **Policy document** section.
79 | 3. Click **Edit policy document** and perform the changes described below.
80 | 1. Update the `iot:Publish` and `iot:Receive` permissions to include the `buttonPresses` topic, as shown below. Note that `############` in the code below is a placeholder for your unique AWS resource identifier. Remember to replace this with the identifier found in your original policy document.
81 |
82 | ```json
83 | {
84 | "Effect": "Allow",
85 | "Action": [
86 | "iot:Publish",
87 | "iot:Receive"
88 | ],
89 | "Resource": [
90 | "arn:aws:iot:us-east-2:############:topic/${iot:Connection.Thing.ThingName}/*",
91 | "arn:aws:iot:us-east-2:############:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*",
92 | "arn:aws:iot:us-east-2:############:topic/buttonPresses"
93 | ]
94 | },
95 | ```
96 |
97 | 2. Update the `iot:Subscribe` permissions to include the `buttonPresses` topic, as shown below. Replace `############` with the identifier found in your original policy document.
98 |
99 | ```json
100 | {
101 | "Effect": "Allow",
102 | "Action": [
103 | "iot:Subscribe"
104 | ],
105 | "Resource": [
106 | "arn:aws:iot:us-east-2:############:topicfilter/${iot:Connection.Thing.ThingName}/*",
107 | "arn:aws:iot:us-east-2:############:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*",
108 | "arn:aws:iot:us-east-2:############:topicfilter/buttonPresses"
109 | ]
110 | },
111 | ```
112 | 4. Click **Save as new version**.
113 |
114 | The permissions have now been updated, and the board should be able to send and receive data over the `buttonPresses` MQTT topic.
115 |
116 | ### Step 1: Start With an Unmodified Version of the Github Project
117 |
118 | The starting point for this example is an unmodified copy of the GitHub project compatible with your device's microcontroller family:
119 |
120 | - [GitHub repository for the **PIC**-IOT Development Boards](https://github.com/microchip-pic-avr-solutions/pic-iot-aws-sensor-node)
121 | - [GitHub repository for the **AVR**-IOT Development Boards](https://github.com/microchip-pic-avr-solutions/avr-iot-aws-sensor-node-mplab)
122 |
123 | Download the correct repository and open the `PICIoT.X` and/or `AVRIoT.X` project in MPLAB X.
124 |
125 | ### Step 2: Sending MQTT Messages to the Cloud
126 |
127 | The first thing we need to do is to detect when a button is pressed, which we will do using interrupts. The procedures for this differ somewhat for the AVR-IoT and PIC-IoT boards. Follow [Procedures for AVR-IoT boards](#procedures-for-avr-iot-boards) or [Procedures for PIC-IoT boards](#procedures-for-pic-iot-boards), depending on which board you are using, and then continue with [Procedures for both AVR-IoT and PIC-IoT boards](#procedures-for-both-avr-iot-and-pic-iot-boards).
128 |
129 | #### Procedures for AVR-IoT Boards
130 |
131 | In `application_manager.c`, add the following code just after the `SYSTEM_Initialize()` call in the `application_init` function:
132 |
133 | ```c
134 | SW0_EnableInterruptForFallingEdge();
135 | PORTF_SW0_SetInterruptHandler(sendButtonPressToCloud);
136 | ```
137 |
138 | The first line enables falling edge interrupt detection for the `SW0` button on the AVR-IoT boards, and a function handler for this interrupt is then assigned on the second line. The interested reader is encouraged to take a look at the `pin_manager.c` file to see how these functions are implemented.
139 |
140 | Skip ahead to [Procedures for both AVR-IoT and PIC-IoT boards](#procedures-for-both-avr-iot-and-pic-iot-boards) to complete this step.
141 |
142 | #### Procedures for PIC-IoT Boards
143 |
144 | In `pin_manager.c`, perform the following edits:
145 |
146 | 1. In the `PIN_MANAGER_initialize` function, enable interrupts for the `SW0` button (which is connected to RA7) and clear its interrupt flag by including these two lines:
147 |
148 | ```c
149 | IOCNAbits.IOCNA7 = 1; //Pin : RA7
150 | IOCFAbits.IOCFA7 = 0; //Pin : RA7
151 | ```
152 |
153 | 2. Add another variable below the `INT_InterruptHandler` variable to store the interrupt handler for the `SW0` hardware button:
154 |
155 | ```c
156 | void (*SW0_InterruptHandler)(void) = NULL;
157 | ```
158 |
159 | 3. Add a function that sets the variable we just created (place it just after the `INT_SetInterruptHandler` function):
160 |
161 | ```c
162 | void SW0_SetInterruptHandler(void (* InterruptHandler)(void))
163 | {
164 | IEC1bits.IOCIE = 0; //Disable IOCI interrupt
165 | SW0_InterruptHandler = InterruptHandler;
166 | IEC1bits.IOCIE = 1; //Enable IOCI interrupt
167 | }
168 | ```
169 |
170 | 4. Modify the `_IOCInterrupt` interrupt service routine to also handle the `SW0` button presses (the interrupt service routine is located near line 155 in `pin_manager.c`). The `SW0` button is connected to the `RA7` pin. The fully modified interrupt service routine is provided below. Either copy and replace `_IOCInterrupt` in its entirety or add the second nested `if` statement to your project.
171 |
172 | ```c
173 | void __attribute__ (( interrupt, no_auto_psv )) _IOCInterrupt ( void )
174 | {
175 | if(IFS1bits.IOCIF == 1)
176 | {
177 | // Clear the flag
178 | IFS1bits.IOCIF = 0;
179 | if(IOCFAbits.IOCFA12 == 1)
180 | {
181 | IOCFAbits.IOCFA12 = 0; //Clear flag for Pin - RA12
182 | if(INT_InterruptHandler)
183 | {
184 | INT_InterruptHandler();
185 | }
186 | }
187 |
188 | // Handle SW0 button presses
189 | if(IOCFAbits.IOCFA7 == 1)
190 | {
191 | IOCFAbits.IOCFA7 = 0; //Clear flag for Pin - RA7
192 | if(SW0_InterruptHandler)
193 | {
194 | SW0_InterruptHandler();
195 | }
196 | }
197 | }
198 | }
199 | ```
200 |
201 | In `pin_manager.h`, add a declaration of the `SW0_SetInterruptHandler` function we just added to make it available in other files, for example after the declaration of the `INT_SetInterruptHandler` function:
202 |
203 | ```c
204 | void SW0_SetInterruptHandler(void (* InterruptHandler)(void));
205 | ```
206 |
207 | In `application_manager.c`, set the `SW0` interrupt handler just after the call to the `SYSTEM_Initialize()` in the `application_init` function:
208 |
209 | ```c
210 | // Set interrupt handler for button presses
211 | SW0_SetInterruptHandler(sendButtonPressToCloud);
212 | ```
213 |
214 | #### Procedures for Both AVR-IoT and PIC-IoT Boards
215 |
216 | Now, any time the `SW0` button is pressed, the `sendButtonPressToCloud` function will be called. Before we implement this function, let us declare a variable for the MQTT topic that we will use. Add the following declaration to `application_manager.c` (e.g., below the declaration of the `mqttSubscribeTopic` variable):
217 |
218 | ```c
219 | char tutorialMqttTopic[SUBSCRIBE_TOPIC_SIZE];
220 | ```
221 |
222 | Implement the aforementioned function handler by adding the following code to `application_manager.c`:
223 |
224 | ```c
225 | static void sendButtonPressToCloud(){
226 | // Ensure that we have a valid cloud connection
227 | if (shared_networking_params.haveAPConnection)
228 | {
229 | static char tutorialPayload[PAYLOAD_SIZE];
230 | int tutorialLen = 0;
231 |
232 | // Set MQTT topic
233 | memset((void*)tutorialMqttTopic, 0, sizeof(tutorialMqttTopic));
234 | sprintf(tutorialMqttTopic, "buttonPresses");
235 |
236 | // Construct payload
237 | tutorialLen = sprintf(tutorialPayload,"{\"thing_name\":\"%s\"}", cid);
238 |
239 | // Publish data to cloud
240 | CLOUD_publishData((uint8_t*)tutorialMqttTopic ,(uint8_t*)tutorialPayload, tutorialLen);
241 | }
242 | }
243 | ```
244 |
245 | This function closely resembles the `sendToCloud` function that we mentioned earlier and will publish an MQTT message to the `buttonPresses` topic. The content of the message will be a JSON object that contains the name of the thing/device that sent the message.
246 |
247 | Build the modified project and program it onto the device using MPLAB X. This is done by clicking on the **Make and Program Device Main Project** button on the MPLAB X toolbar (see the image below).
248 |
249 | 
250 |
251 | > If you are unfamiliar with the MPLAB X integrated developer environment (IDE), check out the following guide:
252 | >
253 | > [Get Started with MPLAB® X IDE and Microchip Tools](https://microchipdeveloper.com/tls0101:start)
254 |
255 | #### Verify That Messages Are Successfully Being Sent to AWS
256 |
257 | When the device has been successfully programmed, let us make sure that we are receiving the messages in AWS:
258 |
259 | 1. Sign in to the AWS Management Console and select the IoT Core service.
260 | 2. Select **Test** in the menu on the left-hand side
261 | 3. In the **Subscription topic** field, enter `buttonPresses`.
262 | 4. Click the **Subscribe to topic** button.
263 | 5. Press the `SW0` button on the board and observe that the button press is successfully registered in the cloud.
264 |
265 | 
266 |
267 | ### Step 3: Receiving MQTT Messages From the Cloud
268 |
269 | Now that we have successfully modified our project to send messages to a custom topic, we must also find a way to subscribe to this topic:
270 |
271 | 1. Change the definition of `NUM_TOPICS_SUBSCRIBE` in `mqtt_config.h` (Header Files -> MCC Generated Files -> config) to allow up to two simultaneous MQTT topic subscriptions:
272 |
273 | ```c
274 | #define NUM_TOPICS_SUBSCRIBE 2
275 | ```
276 |
277 | 2. Edit the `subscribeToCloud` function in `application_manager.c` to include a subscription to the `buttonPresses` topic. The fully modified function is provided below. Either copy and replace the `subscribeToCloud` function in its entirety or add the last two lines of the code below in your MPLAB X project.
278 |
279 | ```c
280 | static void subscribeToCloud(void)
281 | {
282 | sprintf(mqttSubscribeTopic, "$aws/things/%s/shadow/update/delta", cid);
283 | CLOUD_registerSubscription((uint8_t*)mqttSubscribeTopic,receivedFromCloud);
284 | sprintf(tutorialMqttTopic, "buttonPresses");
285 | CLOUD_registerSubscription((uint8_t*)tutorialMqttTopic,receiveButtonPressFromCloud);
286 | }
287 | ```
288 |
289 | - The second parameter of the `CLOUD_registerSubscription` function is a handler that dictates which function will be run when a message is received to the specified topic. We, therefore, need to implement the `receiveButtonPressFromCloud` function to handle any received messages.
290 | 3. Add the following function definition to `application_manager.c` (somewhere above the `subscribeToCloud` function) to make the device's LEDs blink twice when a message is received:
291 |
292 | ```c
293 | static void receiveButtonPressFromCloud(uint8_t *topic, uint8_t *payload){
294 | LED_test();
295 | LED_test();
296 | }
297 | ```
298 |
299 | 4. Build the project and program the device in MPLAB X. If you have multiple AVR-IoT or PIC-IoT devices available, you can try to program all of them using the same project.
300 |
301 | > Remember that all of the devices first will have to be provisioned for use with your AWS account. Note also that even though AVR-IoT and PIC-IoT devices can be connected to AWS simultaneously and communicate with each other over MQTT, the GitHub project we have been working with in this tutorial is only compatible with either AVR-IoT devices or PIC-IoT devices. To use devices from two different device families together, it is necessary to complete this tutorial individually for the AVR-IoT and PIC-IoT repositories on GitHub and program the devices with the compatible firmware.
302 |
303 | Your device(s) should now be configured correctly. If the `SW0` button is pressed on any of the configured IoT kits, the LEDs on all configured IoT kits should blink twice. If this is not the case, make sure that the tutorial has been followed correctly and that the devices are properly conditioned.
304 |
305 | 
306 |
307 | ## Next Steps
308 |
309 |
310 |
311 |
312 |
313 |
314 | ## Resources
315 |
316 | - [PIC-IoT WA Development Board Product Page](https://www.microchip.com/DevelopmentTools/ProductDetails/ev54y39a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-first-app-send-receive-data-prequisites)
317 | - [AVR-IoT WA Development Board Product Page](https://www.microchip.com/DevelopmentTools/ProductDetails/ev15r70a?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-first-app-send-receive-data-prequisites)
318 | - [Get Started with MPLAB® X IDE and Microchip Tools](https://microchipdeveloper.com/tls0101:start?utm_campaign=IoT-WA-DevBoards&utm_source=GitHub&utm_medium=hyperlink&utm_term=&utm_content=microchip-iot-developer-guide-for-aws-first-app-send-receive-data-resources)
319 | - [AWS IoT Developer Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html)
320 | - [IoT Provisioning Tool](http://www.microchip.com/mymicrochip/filehandler.aspx?ddocname=en1001525)
321 | - GitHub repositories with the IoT Boards' pre-loaded firmware:
322 | - [For the PIC-IoT Development Boards](https://github.com/microchip-pic-avr-solutions/pic-iot-aws-sensor-node)
323 | - [For the AVR-IoT Development Boards](https://github.com/microchip-pic-avr-solutions/avr-iot-aws-sensor-node-mplab)
--------------------------------------------------------------------------------
/your-first-application-sending-and-receiving-data/figures/Subscribe_to_buttonPresses_in_IoT_Core.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/your-first-application-sending-and-receiving-data/figures/Subscribe_to_buttonPresses_in_IoT_Core.gif
--------------------------------------------------------------------------------
/your-first-application-sending-and-receiving-data/figures/make_and_program_device.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/your-first-application-sending-and-receiving-data/figures/make_and_program_device.png
--------------------------------------------------------------------------------
/your-first-application-sending-and-receiving-data/figures/show_working_IoT_board_example.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microchip-pic-avr-solutions/microchip-iot-developer-guides-for-aws/007a8e5553a7b94a97b5c3ade8ed2c8578da6b93/your-first-application-sending-and-receiving-data/figures/show_working_IoT_board_example.gif
--------------------------------------------------------------------------------
76 | 
7 | 
201 | 
202 |