Skip to content

Commit 919451b

Browse files
author
David
authored
Merge pull request #10 from MicrochipTech/v2.0.0-dev
Releasing v2.0.0
2 parents 90496bc + fa0f823 commit 919451b

File tree

79 files changed

+13751
-5385
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

79 files changed

+13751
-5385
lines changed

‎documents/images/configurationSelect.png

19.2 KB
Loading

‎documents/iot-ethernet-firmware-compile-and-program.md

+6-4
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,10 @@ This document will show you where to find the latest _released_ version of the f
1313
You will need the following Microchip development tools to program and develop with the Microchip IoT Ethernet.
1414

1515
- Download the latest project for IoT Ethernet from here: [IoT Ethernet Project](https://github.com/MicrochipTech/aws-iot-firmware-pic32mz/releases/latest)
16-
- Download and install Microchip MPLAB<sup>&reg;</sup> Harmony Integrated Software Framework v1.08.01 for your OS from here: [Harmony](http://www.microchip.com/mplab/mplab-harmony)
16+
- Download and install Microchip MPLAB<sup>&reg;</sup> Harmony Integrated Software Framework v1.09 for your OS from here: [Harmony](http://www.microchip.com/mplab/mplab-harmony)
1717
- Download and install Microchip MPLAB<sup>&reg;</sup> X IDE for your OS from here:
18-
[Microchip MPLAB<sup>&reg;</sup> X IDE](http://www.microchip.com/mplabx) (3.35 tested)
19-
- Download and install the v1.42 XC32 compiler for your OS from here: [Microchip MPLAB<sup>&reg;</sup> XC32 Compiler](http://www.microchip.com/xc32)
18+
[Microchip MPLAB<sup>&reg;</sup> X IDE](http://www.microchip.com/mplabx) (3.40 Required)
19+
- Download and install the v1.42 XC32 compiler for your OS from here: [Microchip MPLAB<sup>&reg;</sup> XC32 Compiler](http://www.microchip.com/xc32)
2020

2121
More information about Microchip tools can be found on [Microchip's developer help site](http://microchip.wikidot.com/swtools:start)
2222

@@ -32,8 +32,10 @@ Example below is shown on MAC OS X, these instructions may vary slightly on diff
3232
- Navigate to: ` <path-to-your-project>/aws-iot-firmware-pic32mz/software/aws-iot-ethernet/firmware`
3333
- Select the project __aws-iot-ethernet.X__
3434
- With your project opened, right click on the project __aws-iot-ethernet__ in the Projects tab and select __Set as Main Project__
35+
- Select the configuration for the board you wish to program from the dropdown box at the top.
36+
![](images/configurationSelect.png)
3537
- Follow these directions to install the Microchip Harmony Configurator (MHC): [Steps to Install MHC](http://ww1.microchip.com/downloads/en/DeviceDoc/MPLAB%20Harmony%20Configurator%20(MHC)%20and%20MPLAB%20Harmony%20Graphics%20Composer.pdf)
36-
- Open the MHC by clicking __Tools -> Embedded -> MPLAB Harmony Configurator__
38+
- Open the MHC by clicking __Tools -> Embedded -> MPLAB Harmony Configurator__
3739
- The MHC will prompt asking to choose a Harmony framework to use, select "Yes" and select the location of your Harmony install and click "OK"
3840
- The MHC will then ask if you want to open the configuration file __IoT-Ethernet.mhc__ for the __aws-iot-ethernet__ project, select "Open" to proceed.
3941
- With the new Harmony framework selected for your project, you will need to regenerate code by clicking the generate code button. ![](images/generateCode.png)

‎documents/iot-ethernet-mplab-ipe.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ You will need the following Microchip development tools to program the Microchip
1515

1616
- Download the latest HEX file for IoT Ethernet from here: [IoT Ethernet Project](https://github.com/MicrochipTech/aws-iot-firmware-pic32mz/releases/latest)
1717
- Download and install Microchip MPLAB<sup>&reg;</sup> X IDE for your OS from here:
18-
[Microchip MPLAB<sup>&reg;</sup> X IDE](http://www.microchip.com/mplabx) (3.35 tested)
18+
[Microchip MPLAB<sup>&reg;</sup> X IDE](http://www.microchip.com/mplabx)
1919
- PICKit<sup>&trade;</sup> 3 In-Circuit Debugger/Programmer (or other programmer)
2020

2121
---

‎documents/iot-ethernet-out-of-box-guide.md

+8-140
Original file line numberDiff line numberDiff line change
@@ -16,157 +16,25 @@ You will need the following Microchip development tools to run out of box demo
1616
- Download and install [Insight on Things](https://github.com/MicrochipTech/aws-iot-insight-on-things-desktop-app) desktop application; [Download latest version](https://github.com/MicrochipTech/aws-iot-insight-on-things-desktop-app/releases/latest)
1717
- To learn more about building the project from source or just upgrading the firmware, read [IoT Ethernet Firmware Compiling and Programing](iot-ethernet-firmware-compile-and-program.md) in our documents folder
1818

19-
#### AWS Tools and Applications
20-
- You will need an AWS account to use AWS IoT.
21-
- For more information how to setup an AWS Account please go to [AWS](http://aws.amazon.com) main page
22-
- Please check with your IT or IS department on your company's policies on using cloud computing, or to see if you have a corporate AWS account that should be used.
23-
24-
- To use the AWS IoT services you will need to make use of _AWS Command Line Interface_ (awscli) tool. For more information on how to install, configure, and use the awscli tool please go to [AWS Command Line Interface User Guide](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html).
25-
26-
> NOTE: If you are a **Microchip Employee** we have a corporate AWS account that must be used. To setup your AWS IoT device please go to https://setup.iot.microchip.com for more information
27-
2819
---
29-
### Setting Up the AWS IoT Service
30-
31-
To setup your AWS IoT service to work with the _IoT Ethernet Kit_ you will need to work with the awscli that you installed in the previous section.
32-
33-
1. Using the awscli you will need to find the endpoint that will be used for your AWS IoT account. To do this run the following command in your terminal/command window.
34-
35-
```
36-
aws iot describe-endpoint
37-
```
38-
You will receive the following back that you will need to add to the firmware in the next section. The output will look like: `<random-string>.iot.us-east-1.amazonaws.com`
39-
- Create certificates that will be used in the application firmware by running the following command in your terminal/command prompt window:
40-
41-
```
42-
aws iot create-keys-and-certificate --set-as-active --output text
43-
```
44-
> You will need to copy the output on the terminal/command window to text files for the certs and private key. Please also note the _certificate arn_ value that will be used later in this section; it is the first long string of text that you will seen on the screen.
45-
>
46-
> NOTE: this is the only time that you will be able to see this information and make sure there is no text or spaces at the beginning of each of the files you create. For example in the output below you will need to remove the `KEYPAIR` text and spaces so that the first line of the private key starts with the dashes:
47-
>
48-
>```
49-
>...
50-
>Gmh/2ib2NsA8Tf+8drTQXf3gQ4oemdOfnA4IlXiFGA9QAP9i/krzYvaVAlSogLWh
51-
>wRHaP1hzPuS9+0UjZkS1Uzyfqmd+vR4Om8S+t2VmEwYMJMG3mUaFXdhBhMDJ
52-
>-----END CERTIFICATE-----
53-
>
54-
>KEYPAIR -----BEGIN RSA PRIVATE KEY-----
55-
>MIIEpAIBAAKCAQEAynvp1r7jl9HzbAVCgVWzYmKu4O6nNM4wBZQ1YjHpSOL1+joF
56-
>KKcXM8eS8jmUbHRJ84JeDrr9A50ok1cyUCDBPkf6c7VO4xWGzXruR3WoVjRYq3vc
57-
>...
58-
>```
59-
- Create and attach the following policy that will allow your thing to publish and subscribe to the AWS IoT service
60-
- First create a file that will have the policy information in it and save it to you computer:
61-
> NOTE: Make sure you replace `<AWS-IoT Region>` and `<AWS Account Number>` with the AWS-IoT region and your AWS account number
62-
63-
```
64-
{
65-
"Version": "2012-10-17",
66-
"Statement": [{
67-
"Effect": "Allow",
68-
"Action": [
69-
"iot:Connect"
70-
],
71-
"Resource": [
72-
"arn:aws:iot:<AWS-IoT Region>:<AWS Account Number>:client/${iot:ClientId}"
73-
]
74-
},
75-
{
76-
"Effect": "Allow",
77-
"Action": [
78-
"iot:Publish"
79-
],
80-
"Resource": [
81-
"arn:aws:iot:<AWS-IoT Region>:<AWS Account Number>:topic/$aws/things/${iot:ClientId}/shadow/update",
82-
"arn:aws:iot:<AWS-IoT Region>:<AWS Account Number>:topic/$aws/things/${iot:ClientId}/shadow/get"
83-
]
84-
},
85-
{
86-
"Effect": "Allow",
87-
"Action": [
88-
"iot:Subscribe"
89-
],
90-
"Resource": [
91-
"arn:aws:iot:<AWS-IoT Region>:<AWS Account Number>:topicfilter/$aws/things/${iot:ClientId}/shadow/update/delta",
92-
"arn:aws:iot:<AWS-IoT Region>:<AWS Account Number>:topicfilter/$aws/things/${iot:ClientId}/shadow/update/accepted",
93-
"arn:aws:iot:<AWS-IoT Region>:<AWS Account Number>:topicfilter/$aws/things/${iot:ClientId}/shadow/update/rejected",
94-
"arn:aws:iot:<AWS-IoT Region>:<AWS Account Number>:topicfilter/$aws/things/${iot:ClientId}/shadow/get/accepted",
95-
"arn:aws:iot:<AWS-IoT Region>:<AWS Account Number>:topicfilter/$aws/things/${iot:ClientId}/shadow/get/rejected"
96-
]
97-
},
98-
{
99-
"Effect": "Allow",
100-
"Action": [
101-
"iot:Receive"
102-
],
103-
"Resource": [
104-
"arn:aws:iot:<AWS-IoT Region>:<AWS Account Number>:topic/$aws/things/${iot:ClientId}/shadow/update/delta",
105-
"arn:aws:iot:<AWS-IoT Region>:<AWS Account Number>:topic/$aws/things/${iot:ClientId}/shadow/update/accepted",
106-
"arn:aws:iot:<AWS-IoT Region>:<AWS Account Number>:topic/$aws/things/${iot:ClientId}/shadow/update/rejected",
107-
"arn:aws:iot:<AWS-IoT Region>:<AWS Account Number>:topic/$aws/things/${iot:ClientId}/shadow/get/accepted",
108-
"arn:aws:iot:<AWS-IoT Region>:<AWS Account Number>:topic/$aws/things/${iot:ClientId}/shadow/get/rejected"
109-
]
110-
}]
111-
}
112-
```
113-
- Load the policy to the AWS IoT services with the following command:
114-
115-
```
116-
aws iot create-policy --policy-name 'MQTTandShadowPolicy' --policy-document file://<path-to-your-policy-document>
117-
```
118-
- You will need to attached this policy to a principal to allow the cert the rights to publish and subscribe to topics:
119-
120-
```
121-
aws iot attach-principal-policy --principal '<certificate-arn>' --policy-name 'MQTTandShadowPolicy'
122-
```
123-
- Create a thing shadow based on the MAC address of the board:
124-
125-
```
126-
aws iot create-thing --thing-name '<MAC Address of the board>'
127-
```
12820

129-
---
13021
### Running the Demo
131-
There are two parts to running the demo. First you have to commission the demo so it knows how to talk to your AWS Account that you setup in the [Setting Up the AWS IoT Service](Setting Up the AWS IoT Service) section of this out of box guide. Second is sending and receiving data from AWS IoT.
22+
There are two parts to running the demo. First you have to commission the demo so it knows how to talk to your AWS Account. Second is sending and receiving data from AWS IoT.
13223

13324
#### Commissioning
13425
To setup and run the demo follow these instructions:
13526

136-
1. Plug the IoT Ethernet Kit into a router or switch using an ethernet cable
137-
- Power the IoT Ethernet Kit by connecting the supplied Micro-USB cable to a power source and setting the power switch on the board to USB
138-
- Connect your computer to the same network that the IoT Ethernet Kit is connected
139-
- Your board will register a Multicast DNS (mDNS) name with the local network that will allow you to access a configuration webpage.
140-
- Use a bonjour or multicast DNS service to find your board's IP address and enter the IP address into a web browser. The kit will have a service name such as `xxxxxx_IoT-E` where `xxxxxx` is the last six characters of the kit's MAC address.
141-
- Alternatively you can try entering `xxxxxx_iot-e.local` into a web browser to navigate to the webpage where `xxxxxx` is the last six characters of the MAC address on the board
142-
- Once the web browser finds and displays the IoT Ethernet Kit configuration webpage
143-
- Enter your AWS IoT Endpoint Address that you received from the previous AWS IoT Service Setup section. The endpoint will have the form `<random-string>.iot.us-east-1.amazonaws.com`
144-
- Copy and paste your AWS Certificate into the box labeled AWS Certificate.
145-
- The cert should look like
146-
147-
```
148-
-----BEGIN CERTIFICATE-----
149-
<cert data>
150-
-----END CERTIFICATE-----
151-
```
152-
- Copy and paste your AWS Certificate Private Key into the box labeled AWS Certificate Private Key.
153-
- The key should look like
154-
155-
```
156-
-----BEGIN RSA PRIVATE KEY----
157-
<key data>
158-
-----END RSA PRIVATE KEY-----
159-
```
160-
- Click the __Join__ button and a _Connecting to server_ page will appear showing the endpoint that the IoT Ethernet board will connect to along with the AWS Thing Name (MAC Address).
161-
> NOTE: The information you enter above will be sent in the clear and is not secured as if you where using https; this is an option that you can add to your code later
27+
1. Power the IoT Ethernet Kit by connecting the supplied Micro-USB cable to a computer that will be running the Insight on Things application in the next step and set the power switch on the board to USB.
28+
- Download and install the [Insight on Things](https://github.com/MicrochipTech/aws-iot-insight-on-things-desktop-app) application v2.0.0 or greater.
29+
- Follow the instructions for running the Insight on Things application.
16230
- You will see a LEDs D1-D6 light up while the board gets initial data from the server.
163-
- If not, please see the [Status and Error Code Table](Status and Error Code Table) table below for more information
31+
- If not, please see the [Status and Error Code Table](Status and Error Code Table) table below for more information.
16432
- The board is now connect and running; there are two blue LED status indicator on the board.
165-
- LED D6 will flash briefly when transmitting data
166-
- LED D5 will flash briefly when receiving data
33+
- LED D6 will flash briefly when transmitting data.
34+
- LED D5 will flash briefly when receiving data.
16735

16836
#### Sending and Receiving Data with AWS IoT
169-
This demo is controlled though the AWS IoT shadow registors by the [Insight on Things](https://github.com/MicrochipTech/aws-iot-insight-on-things-desktop-app) desktop application that we provide you. [Click here download the latest version](https://github.com/MicrochipTech/aws-iot-insight-on-things-desktop-app/releases/latest). You will need to follow the README.md guide on the github page to setup this application.
37+
This demo is controlled though the AWS IoT shadow registers by the [Insight on Things](https://github.com/MicrochipTech/aws-iot-insight-on-things-desktop-app) desktop application that we provide you. [Click here download the latest version](https://github.com/MicrochipTech/aws-iot-insight-on-things-desktop-app/releases/latest). You will need to follow the README.md guide on the github page to setup this application.
17038

17139
---
17240

0 commit comments

Comments
 (0)