GS2K Application Development Kit (ADK) for AWS IoT User Guide · 2018-02-02 · GS2K Application...

GS2K Application Development Kit (ADK) for AWS IoT

User Guide 1VV0301461 Rev. 1.1 – 2017-09-15

GS2K Application Development Kit (ADK) for AWS IoT User Guide

1VV0301461 Rev. 1.1 of 36 2017-09-15

NOTICE

COPYRIGHTS

COMPUTER SOFTWARE COPYRIGHTS

SPECIFICATIONS ARE SUBJECT TO CHANGE WITHOUT NOTICE

While reasonable efforts have been made to assure the accuracy of this document, Telit assumes no liability resulting from any inaccuracies or omissions in this document, or from use of the information obtained herein. The information in this document has been carefully checked and is believed to be reliable. However, no responsibility is assumed for inaccuracies or omissions. Telit reserves the right to make changes to any products described herein and reserves the right to revise this document and to make changes from time to time in content hereof with no obligation to notify any person of revisions or changes. Telit does not assume any liability arising out of the application or use of any product, software, or circuit described herein; neither does it convey license under its patent rights or the rights of others.

It is possible that this publication may contain references to, or information about Telit products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that Telit intends to announce such Telit products, programming, or services in your country.

This instruction manual and the Telit products described in this instruction manual may be, include or describe copyrighted Telit material, such as computer programs stored in semiconductor memories or other media. Laws in the Italy and other countries preserve for Telit and its licensors certain exclusive rights for copyrighted material, including the exclusive right to copy, reproduce in any form, distribute and make derivative works of the copyrighted material. Accordingly, any copyrighted material of Telit and its licensors contained herein or in the Telit products described in this instruction manual may not be copied, reproduced, distributed, merged or modified in any manner without the express written permission of Telit. Furthermore, the purchase of Telit products shall not be deemed to grant either directly or by implication, estoppel, or otherwise, any license under the copyrights, patents or patent applications of Telit, as arises by operation of law in the sale of a product.

The Telit and 3rd Party supplied Software (SW) products described in this instruction manual may include copyrighted Telit and other 3rd Party supplied computer programs stored in semiconductor memories or other media. Laws in the Italy and other countries preserve for Telit and other 3rd Party supplied SW certain exclusive rights for copyrighted computer programs, including the exclusive right to copy or reproduce in any form the copyrighted computer program. Accordingly, any copyrighted Telit or other 3rd Party supplied SW computer programs contained in the Telit products described in this instruction manual may not be copied (reverse engineered) or reproduced in any manner without the express written permission of Telit or the 3rd Party SW supplier. Furthermore, the purchase of Telit products shall not be deemed to grant either directly or by implication, estoppel, or otherwise, any license under the copyrights, patents or patent applications of Telit or other 3rd Party supplied SW, except for the normal non-exclusive, royalty free license to use that arises by operation of law in the sale of a product.


1VV0301461 Rev. 1.1 of 36 2017-09-15

USAGE AND DISCLOSURE RESTRICTIONS

I. License Agreements

II. Copyrighted Materials

III. High Risk Materials

IV. Trademarks

V. Third Party Rights

The software described in this document is the property of Telit and its licensors. It is furnished by express license agreement only and may be used only in accordance with the terms of such an agreement.

Software and documentation are copyrighted materials. Making unauthorized copies is prohibited by law. No part of the software or documentation may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, without prior written permission of Telit

Components, units, or third-party products used in the product described herein are NOT fault-tolerant and are NOT designed, manufactured, or intended for use as on-line control equipment in the following hazardous environments requiring fail-safe controls: the operation of Nuclear Facilities, Aircraft Navigation or Aircraft Communication Systems, Air Traffic Control, Life Support, or Weapons Systems (High Risk Activities"). Telit and its supplier(s) specifically disclaim any expressed or implied warranty of fitness for such High Risk Activities.

TELIT and the Stylized T Logo are registered in Trademark Office. All other product or service names are the property of their respective owners.

The software may include Third Party Right software. In this case, you agree to comply with all terms and conditions imposed on you in respect of such separate software. In addition to Third Party Terms, the disclaimer of warranty and limitation of liability provisions in this License shall apply to the Third Party Right software.

TELIT HEREBY DISCLAIMS ANY AND ALL WARRANTIES EXPRESS OR IMPLIED FROM ANY THIRD PARTIES REGARDING ANY SEPARATE FILES, ANY THIRD PARTY MATERIALS INCLUDED IN THE SOFTWARE, ANY THIRD PARTY MATERIALS FROM WHICH THE SOFTWARE IS DERIVED (COLLECTIVELY “OTHER CODE”), AND THE USE OF ANY OR ALL THE OTHER CODE IN CONNECTION WITH THE SOFTWARE, INCLUDING (WITHOUT LIMITATION) ANY WARRANTIES OF SATISFACTORY QUALITY OR FITNESS FOR A PARTICULAR PURPOSE.

NO THIRD PARTY LICENSORS OF OTHER CODE SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND WHETHER MADE UNDER CONTRACT, TORT OR OTHER LEGAL THEORY, ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE OTHER CODE OR THE EXERCISE OF ANY RIGHTS GRANTED UNDER EITHER OR BOTH THIS LICENSE AND THE LEGAL TERMS APPLICABLE TO ANY SEPARATE FILES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.


1VV0301461 Rev. 1.1 of 36 2017-09-15

APPLICABILITY TABLE

Note: The features described in the present document are provided by the products equipped with the software versions equal or higher than the versions shown in the table. See also the Revision History chapter.

PRODUCT

GS2K based Modules

SW Version

5.3 x onwards


1VV0301461 Rev. 1.1 of 36 2017-09-15

Revision History

Version Date Remarks

1.0 Dec 2016 Initial release

1.1 July 2017 Added Shadow support

Updated for GS2101M EVB and GS2200M EVB


1VV0301461 Rev. 1.1 of 36 2017-09-15

Table of Contents

NOTICE……… .......................................................................................................................... 2

COPYRIGHTS. .......................................................................................................................... 2

COMPUTER SOFTWARE COPYRIGHTS ................................................................................ 2

USAGE AND DISCLOSURE RESTRICTIONS ......................................................................... 3

APPLICABILITY TABLE .......................................................................................................... 4

OVERVIEW ....................................................................................................... 9

1.1 INTRODUCTION .............................................................................................................. 9 1.2 DEVICE SHADOWS FOR AWS IOT ................................................................................... 9

GETTING STARTED ....................................................................................... 10

2.1 GS2200M STARTER KIT BOARD (SKB) ........................................................................ 10 2.1.1 GS2200M SKB Jumper and Switch Settings ................................................... 10

2.2 GS2101M EVALUATION BOARD (EVB) ......................................................................... 12 2.2.1 GS2101M EVB Jumper and Switch Settings ................................................... 12

2.3 GS2200M EVALUATION BOARD (EVB) ......................................................................... 12 2.3.1 GS2200M EVB Jumper and Switch Settings ................................................... 13

2.4 CONNECTING SKB/EVB TO THE PC ............................................................................. 14 2.4.1 For SKB ........................................................................................................... 14 2.4.2 For EVB ........................................................................................................... 14

2.5 FIRMWARE PACKAGE CREATION ................................................................................... 15 2.6 PROGRAMMING SKB/EVB WITH APPLICATION FIRMWARE FOR AWS IOT ........................ 16

2.6.1 Programming SKB ........................................................................................... 16 2.6.2 Programming EVB ........................................................................................... 19

2.7 CONFIGURING AWS IOT .............................................................................................. 21 2.7.1 Creating an AWS IoT Account ......................................................................... 21 2.7.2 Creating Thing Resources in AWS IoT ............................................................ 21 2.7.3 Creating a Policy Resource ............................................................................. 21 2.7.4 Creating a Thing and its Security Certificate .................................................... 22 2.7.5 Obtaining the Host Name for Your AWS IoT Server ........................................ 23

2.8 PREPARING CREDENTIAL FILES FOR INSTALLATION ON THE SKB/EVB ............................ 24 2.9 CONFIGURING THE SKB/EVB TO CONNECT TO AWS IOT .............................................. 25

2.9.1 For SKB ........................................................................................................... 25 2.9.2 For EVB ........................................................................................................... 27

2.10 MONITORING THE SKB/EVB FROM AWS IOT CONSOLE ................................................. 29 2.10.1 Monitoring Status Messages ........................................................................... 29

2.11 CONTROLLING THE SKB/EVB FROM AWS IOT DEVICE SHADOW .................................... 31 2.11.1 Controlling an LED on the SKB/EVB Device ................................................... 31 2.11.2 Controlling an LED on the SKB through Button Press ..................................... 33

2.12 REVERTING THE SKB/EVB CONFIGURATION TO FACTORY DEFAULT CONFIGURATION ..... 35 2.12.1 For SKB: .......................................................................................................... 35 2.12.2 For EVB: .......................................................................................................... 35


1VV0301461 Rev. 1.1 of 36 2017-09-15

List of Figures Figure 1: GS2200M Starter Kit board ...................................................................................... 10

Figure 2: GS2101M Evaluation Board ..................................................................................... 12

Figure 3: GS2200M Evaluation Board ..................................................................................... 13

Figure 4: Custom AEK package creation for GS2200M EVB/SKB .......................................... 15

Figure 5: Custom AEK package creation for GS2101M EVB .................................................. 16

Figure 6: Checking Serial Flash Programmer Connection....................................................... 17

Figure 7: Programming Firmware ............................................................................................ 18

Figure 8: Checking Serial Flash Programmer Connection....................................................... 19

Figure 9: Programming Firmware ............................................................................................ 20

Figure 10: Create Certificate ................................................................................................... 23

Figure 11: Download link of Root CA for AWS IoT .................................................................. 23

Figure 12: Post Device Update Using AWS Console .............................................................. 32

Figure 13: Shadow Response from Publish to topic ................................................................ 32

Figure 14: Topic Response from Publish to topic .................................................................... 33

Figure 15: Controllable LED in GS2200MIZ SKB module ....................................................... 33

Figure 16: Controllable LED in GS2101MIP EVB module ....................................................... 34

Figure 17: Controllable LED in GS2200MIZ EVB module ....................................................... 34


1VV0301461 Rev. 1.1 of 36 2017-09-15

List of Tables Table 1: GS2200 SKB Jumper and Switch Settings ................................................................ 11

Table 2: GS2101M EVB Jumper and Switch Settings ............................................................. 12

Table 3: GS2200M EVB Jumper and Switch Settings ............................................................. 13


1VV0301461 Rev. 1.1 of 36 2017-09-15

Overview

1.1 INTRODUCTION

GS2K Application Development Kit (ADK) for AWS IoT embedded application provides an example of interfacing GainSpan’s GS2000 802.11b/g/n modules to AWS IoT services. Firmware executing on the GS2000 module uses the MQTT protocol to report sensor readings to an AWS IoT server. The firmware also supports receiving MQTT-based control messages from AWS IoT to control the state of an LED on the SKB board. The reference application firmware incorporates the AWS IoT SDK to provide MQTT protocol support.

The reference application executes on GainSpan’s GS2200M Starter Kit Board (SKB), GS2200 EVB and 2101M Evaluation Board (EVB). The SKB/EVB includes built-in temperature and light sensors and includes a battery gauge. The SKB also measures receive signal strength (RSSI) for the access point to which it is associated. The application periodically records measurements using these features. By default, the sensors are sampled and every 5 seconds the application reports the last two sets of sensor samples to AWS IoT. It does this by publishing a status message to an MQTT topic named “device/<deviceIdentifier>/status”,

where the <deviceIdentifier> is the MAC address printed on the GS2200M/GS2101M/GS2200M module label.

The reference application subscribes to receive messages from AWS IoT via an MQTT topic named “device/<deviceIdentifier>/message”. Switch the state a software-controlled LED on your SKB by transmitting a properly formatted message from AWS IoT to your SKB.

1.2 DEVICE SHADOWS FOR AWS IOT

The device shadow is the AWS IoT service that is used to store and retrieve current state information in JSON format for a device. The Device Shadows service maintains a thing shadow for each thing in AWS IoT and it is used to get and set the state of a thing over MQTT, regardless of whether the thing is connected to the Internet. Each thing shadow is uniquely identified by its name.

The SKB/EVB does this by publishing a status message to an MQTT topic named

“$aws/things/thingName/shadow/update”,

Where, the <thingName> is the MAC address printed on the GS2200M/GS2101M/GS2200M module label.


1VV0301461 Rev. 1.1 of 36 2017-09-15

Getting Started

2.1 GS2200M STARTER KIT BOARD (SKB)

The ADK for AWS IoT is based on GainSpan GS2200M Starter Kit Board (SKB) as shown in the following figure. The callouts identify the features that are most relevant to the reference application described here.

Figure 1: GS2200M Starter Kit board

For additional documentation and information about the GS2200M Starter Kit Board, please visit the product page on GainSpan’s website:

http://www.gainspan.com/products/gs2200m_skb

2.1.1 GS2200M SKB Jumper and Switch Settings The jumpers and switches on your SKB must be set correctly for the reference application to operate properly. The required settings are listed in the below Table. The jumper headers, numbers that are not listed do not affect the operation of the application.

See the SKB Hardware User Guide and Schematic for more information.


1VV0301461 Rev. 1.1 of 36 2017-09-15

Table 1: GS2200 SKB Jumper and Switch Settings

Designator Setting Description

SW6 Active Power Measurement Range Selection Switch – Set for active mode operation

J18 1-2

7-8

9-10

15-16

UART Configuration Jumpers – Set to connect UART0 to USB port

J19 1-2 USB/+5V Power Source Selection Jumper – Set to select USB power source

J12 1-2 J19/Battery Power Source Selection Jumper – Set to select J19 power source

J13 2-3 J12/Bench Power Source Selection Jumper – Set to select J12 power source

J14 2-3 3.3V/1.8V VREG Source Selection Jumper – Set to select 1.8V source

J15 1-2 Sensor, Power (VSN) Selection Jumper – Power sensors regardless of GS2200M state. (Note: Position 2-3 is also acceptable – switch sensor powers off when GS2200M is in standby or hibernate mode.)

J11 1-2 Battery Gauge Enable Jumper – Enable battery gauge

J16 1-2 Power LED Enable Jumper – Enable power LED

Note: The black triangle next to it each header designates pin 1 on that header.


1VV0301461 Rev. 1.1 of 36 2017-09-15

2.2 GS2101M EVALUATION BOARD (EVB)

The ADK for AWS IoT is based on GainSpan GS2101M Evaluation Board (EVB) as shown in the following figure. The callouts identify the features that are most relevant to the reference application described here.

Figure 2: GS2101M Evaluation Board

2.2.1 GS2101M EVB Jumper and Switch Settings

Table 2: GS2101M EVB Jumper and Switch Settings


SW7 Program Programmer/RUN Switch.

J2

1-2 USB0 Power Source

2-3 External Power Source

J13 1-2 Programming - 921K Baud Rate

J4, J10, J11, J12 and J23

Ensure all are shorted

2.3 GS2200M EVALUATION BOARD (EVB)

The ADK for AWS IoT is based on GainSpan GS2200M Evaluation Board (EVB) as shown in the following figure. The callouts identify the features that are most relevant to the reference application described here.


1VV0301461 Rev. 1.1 of 36 2017-09-15

Figure 3: GS2200M Evaluation Board

2.3.1 GS2200M EVB Jumper and Switch Settings

Table 3: GS2200M EVB Jumper and Switch Settings


SW8 Program Programmer/RUN Switch.

J31

1-2 USB0 Power Source

2-3 External Power Source

J13 1-2 Programming - 921K Baud Rate

J4, J14, J15 and J23 Ensure all are shorted

J30 1-2 Ensure its shorted for 3.3V regulator

J32 1-2 Ensure shorted-always on Mode


1VV0301461 Rev. 1.1 of 36 2017-09-15

2.4 CONNECTING SKB/EVB TO THE PC

2.4.1 For SKB The USB0 port on the SKB provides power to the board and provides a serial connection to a personal computer for debugging and flash programming. The flash programming tool is designed for Microsoft Windows. This guide assumes that Windows-based PC is being used.

The SKB includes an on-board USB to serial converter. When plugged into the personal computer for the first time, the PC will automatically discover it and allocate a new “COMx” port.

The debug display output from the embedded application using a terminal emulator program, such as Tera Term (Tera Term is available free on the Internet).

Following are the steps for SKB connection:

1. Verify “SW6” on the SKB is in the “ACTIVE” position and the power switch (SW5) is in the “OFF” position.

2. Connect the USB port of SKB to the PC. 3. Wait for Windows to install the driver for the USB Serial port.

Note: - The name Windows allocates to the port. For example, “COM2”.

4. Start the Tera Term program and set the serial port settings to COM port name allocated to your SKB. Configure the other settings to 115200 baud, 8 data bits, 1 stop bit, no parity and no flow control.

5. Switch the SKB’s power switch (SW5) to “ON”. 6. Observe the debug output displayed in the terminal window.

If the serial port settings are correct and there is no output displayed check the following:

• SW6 is in the ACTIVE position

• Terminal emulator serial port settings are correct

If there is still no output, the SKB may not be running the reference firmware. In order to install the latest firmware, refer section 2.6 Programming SKB/EVB with Application Firmware for AWS IoT.

2.4.2 For EVB The USB0 port on the EVB provides power to the board and provides a serial connection to a personal computer for debugging and flash programming. The flash programming tool is designed for Microsoft Windows. This guide assumes that Windows-based PC is being used.

The EVB includes an on-board USB to serial converter. When plugged into the personal computer for the first time, the PC will automatically discover it and allocate a new “COMx” port.

The debug display output from the embedded application using a terminal emulator program, such as Tera Term (Tera Term is available free on the Internet).

Following are the steps for EVB connection:

1. Verify “SW7” on the EVB is in the “RUN” position and the power switch (SW1) is in the “OFF” position.

2. Connect the USB port of EVB to the PC. 3. Wait for Windows to install the driver for the USB Serial port.


1VV0301461 Rev. 1.1 of 36 2017-09-15

NOTE: The name Windows allocates to the port. For example, “COM2”.

4. Start the Tera Term program and set the serial port settings to COM port name allocated to your SKB. Configure the other settings to 115200 baud, 8 data bits, 1 stop bit, no parity and no flow control.

5. Switch the EVB power switch (SW1) to “ON”. 6. Observe the debug output displayed in the terminal window. 7. If the serial port settings are correct and there is no output displayed check the following:

• SW7 is in the RUN position

• Terminal emulator serial port settings are correct.

If there is still no output, the EVB may not be running the reference firmware. In order to install the latest firmware, refer section 2.6 Programming SKB/EVB with Application Firmware for AWS IoT.

2.5 FIRMWARE PACKAGE CREATION

AWS IoT Firmware is supported in following EVB's and SKB.

• GS2200M EVB

• GS2200M SKB

• GS2101M EVB

The above-mentioned firmware’s can be built with the help of Gain Span SDK builder which can be downloaded from the Gain Span website:

https://www.gainspan.com/secure/getting_started

The following figure displays the custom AEK package creation for GS2200M EVB/SKB and GS2101M EVB.

Figure 4: Custom AEK package creation for GS2200M EVB/SKB

https://www.gainspan.com/secure/getting_started


1VV0301461 Rev. 1.1 of 36 2017-09-15

Figure 5: Custom AEK package creation for GS2101M EVB

NOTE:

By default, ADK and ADK including SDK packages of “AWS-IoT Cloud” Project, support GS2200 SKB.

For supporting GS2101 EVB and GS2200 EVB, refer to the “Build Options” Section in “README.txt” file located “\SDK\Embedded\adk\ aws_iot.

2.6 PROGRAMMING SKB/EVB WITH APPLICATION FIRMWARE FOR

AWS IOT

2.6.1 Programming SKB Steps to program the firmware are as follows:

1. Extract the files from Package created as explained in the above section 2.5 Firmware Package creation.


3. Open the GainSpan Serial Falsh Programmer GUI application file:

Tools\GS_programming_tool\gs2k_flashprogrm.exe


1VV0301461 Rev. 1.1 of 36 2017-09-15

In the Serial Flash Programmer, select “UART”, the SKB’s COM port and 921600 baud, as shown in the following figure:

Figure 6: Checking Serial Flash Programmer Connection

1. Press and hold both the “PROGRAM” and “RESTORE” push buttons on the SKB. 2. Push the power switch to the “ON” position. 3. Release the buttons. 4. If either “LED1” or “LED2” is ON or blinking, repeat the previous three steps until both

LEDs remain OFF. (Note: Please press and hold PROGRAM and RESTORE buttons while switching the POWER to ON).

5. Click Check Connection in the GUI. 6. Verify Connection OK! is displayed. 7. Click the browse button to the right of the Super Block field. 8. Browse to the “QuickStart” folder and select the file with the name that starts with

“superblock. Refer to Figure 7. 9. Click the browse button to the right of the Current FW Version field. 10. Browse to the “QuickStart” folder and select the file with the name that starts with

“singleImage”. 11. Click Erase and Program. 12. Wait for the Serial Flash Programmer to indicate programming is finished, as shown in

the below figure. 13. Close the Serial Flash Programmer window.


1VV0301461 Rev. 1.1 of 36 2017-09-15

Figure 7: Programming Firmware

14. Switch the SKB’s power switch to the “OFF” position. 15. Start the terminal emulator and set the serial port settings to the SKB’s COM port,

115200 baud, 8 data bits, 1 stop bit, no parity and no flow control. 16. Switch SKB’s power switch (SW5) to “ON”.

17. Verify the display output in the terminal window:

**********

APP NCM started in USER-AP mode

**********

[TLS]SSID = GS_PROV_TLS-95e2f3. Channel

= 1 [TLS]IP Address - 192.168.240.1


1VV0301461 Rev. 1.1 of 36 2017-09-15

2.6.2 Programming EVB EVB is shipped from the factory with reference firmware pre-installed. However, to be certain that the EVB is running with the latest version of the reference firmware, reprogram the firmware.

Programming the firmware is as follows:

1. If zipped file package is already not provided, then it is required to be download from GainSpan’s web site:

https://www.gainspan.com/sdk2k/sdk_builder

2. Extract the files from the zip file package containing reference application. 3. Verify “SW7” on EVB is in the “PROGRAM” position and the power switch (SW1) is in

the “OFF” position with jumper “J13” is shorted. 4. Open the GainSpan Serial Flash Programmer GUI application file:

Tools\GS_programming_tool\gs2k_flashprogrm.exe

In the Serial Flash Programmer, select “UART”, the EVB COM port and 921600 baud, as shown in the figure below:

Figure 8: Checking Serial Flash Programmer Connection

5. Push the power switch to the “ON” position. 6. Ensure that the “D6” RED LED next to SW7 is glowing. 7. Click Check Connection in the GUI. 8. Verify Connection OK! is displayed. 9. Click the browse button to the right of the Super Block field. 10. Browse to the “QuickStart” folder and select the file with the name that starts with

“superblock. Refer to Error! Reference source not found.. 11. Click the browse button to the right of the Current FW Version field. 12. Browse to the “QuickStart” folder and select the file with the name that starts with

“singleImage”. 13. Click Erase and Program.

https://www.gainspan.com/sdk2k/sdk_builder


1VV0301461 Rev. 1.1 of 36 2017-09-15

14. Wait for the Serial Flash Programmer to indicate programming is finished, as shown in the below figure.

15. Close the Serial Flash Programmer window.

Figure 9: Programming Firmware

1. Switch the EVB’s power switch to the “OFF” position. 2. Start the terminal emulator and set the serial port settings to the EVB’s COM port,

115200 baud, 8 data bits, 1 stop bit, no parity and no flow control. 3. Switch EVB’s power switch (SW5) to “ON”.


1VV0301461 Rev. 1.1 of 36 2017-09-15

4. Verify the display output in the terminal window:

**********


**********

[TLS]SSID = GS_PROV_TLS-95e2f3. Channel =

1 [TLS]IP Address - 192.168.240.1

2.7 CONFIGURING AWS IOT

Before connecting the device to AWS IoT, it is required to have an Amazon Web Service account. Also, configure the resources so that AWS IoT recognizes the SKB and allows it to connect.

2.7.1 Creating an AWS IoT Account If AWS account with AWS IoT enabled is not present, visit https://aws.amazon.com/ to create your own AWS IoT account.

Note: As of late 2016 AWS IoT provided two console interfaces, an “old console” interface and a “new console” interface. The procedures in this document is based on the “new console” interface.

2.7.2 Creating Thing Resources in AWS IoT In order for the SKB/EVB to connect to AWS IoT, first configure AWS IoT to know its identity and what access policies to apply to it.

AWS IoT uses three resources to manage devices. Each device is registered as a “Thing” in the AWS IoT Registry. Each Thing has an associated security certificate and each security certificate has at least one associated access policy. Before the SKB/EVB connection creates these resources and associations. The following hierarchy of resources is created to enable the SKB/EVB to connect:

Thing

Certificate

Policy

After registering the device, a things shadow gets created automatically. A thing shadow is sometimes referred to as a device shadow. The thing shadow is a JSON document that is used to store and retrieve current state information for a thing (device, app, and so on).

The following are the sections to create the resources.

2.7.3 Creating a Policy Resource Policy resources is first created. A policy controls access to the devices that are associated with the policy. A single policy may be used to control/access for many different devices.

https://aws.amazon.com/


1VV0301461 Rev. 1.1 of 36 2017-09-15

NOTE: Please refer the below URL to configure the appropriate AWS IoT policy for your device

URL:http://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html

To create a policy that allows unrestricted access to AWS IoT:

1. Sign in to the AWS console. 2. Select AWS IoT from the Services menu. 3. Click the Security item in the AWS IoT navigation panel. 4. Click the Policies item under Security. 5. Click the Create a policy button. 6. In the Name field, type Allow-All. 7. In the Action field, type iot:*. 8. In the Resource ARN field, type “*” 9. Select the Allow checkbox. 10. Click the Create button. 11. Verify the policy document is as follows:

{ "Version": "2012-10-17",

"Statement": [ {

"Effect": "Allow", "Action": "iot:*", "Resource": "*"

}

] }

12. Click the back arrow.

2.7.4 Creating a Thing and its Security Certificate Create a Thing to represent the SKB/EVB in the AWS IoT Registry. AWS IoT allows to create a certificate and keys for the SKB/EVB, as well as assign an access policy during the process of creating a Thing. Download the Certificate and the key files created during this process to install in the SKB/EVB later.

Following is the procedure to create a Thing, create its security certificate, download the certificate and key files, and assign an access policy:

1. Sign in to the AWS console. 2. Select AWS IoT from the Services menu. 3. Click Registry in the AWS IoT navigation panel. 4. Click Things. 5. Click the Register a thing button or the Create button, whichever appears. 6. In the Name field, enter the device identifier of the SKB/EVB. The device identifier is the

MAC address of the SKB/EVB and is printed on the GS2200M/GS2101M module label. 7. Click the Create thing button. 8. Click the Security item on the navigation panel. By default, Certificates section will be

highlighted. Click the Create button on the right-hand corner of the page. This will navigate to Create Certificate page.

9. Click the Create certificate button.

http://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html


1VV0301461 Rev. 1.1 of 36 2017-09-15

Figure 10: Create Certificate

10. Download each of the three-device key and certificate files to your PC.

NOTE: Save them in a location where it is not LOST, since there is no way to retrieve the private key file from AWS IoT later.

11. Right-click the Download Link, and click Save as.. / Save Link As to save the CA cert, appending “.crt” to the file name. For example,

“VeriSign-Class 3-Public-Primary-Certification-Authority-G5.pem.crt”.

Figure 11: Download link of Root CA for AWS IoT

12. Click the Activate button. 13. Click the Attach a policy button. 14. Select the Allow check box. 15. Click Done.

2.7.5 Obtaining the Host Name for Your AWS IoT Server

The host name of the AWS IoT Server is required to configure the SKB/EVB later.

Following is the procedure to obtain the host name for the AWS IoT server:

1. Sign in to the AWS console. 2. Select AWS IoT from the Services menu. 3. Click the Registry in the AWS IoT navigation panel. 4. Click the Things. 5. Click Thing Name (MAC Address of Thing, create in Step6 of Section 2.5.4), listed in

the main window. 6. Click Interact.


1VV0301461 Rev. 1.1 of 36 2017-09-15

7. Copy the host name listed under HTTPS. For example,

“abcxyz12345678.iot.us-west-2.amazonaws.com”

8. Save the host name away for later use.

2.8 PREPARING CREDENTIAL FILES FOR INSTALLATION ON THE

SKB/EVB

The certificate files must be converted to DER format and named with specific names before installing them on the SKB/EVB.

To prepare the credentials files for installation:

1. Using Windows Explorer, navigate to the folder where the credential files are downloaded. 2. Generate a root CA certificate file in DER format.

a) Double-click on the root CA certificate (its name starts with “VeriSign”) to open the certificate in the Windows Certificate tool. (Note: The Windows Certificate tool comes with Windows, so installation is not required and a simple double click on the certificate file would open the tool. If by double clicking the file, if certificate tool does not open. Verify the file has a “.crt” extension. If not, rename it to append this extension.)

b) Click the Details tab. c) Click Copy to File…. icon. d) Click Next. e) Select DER encoded binary X.509 (.CER) and click Next. f) Enter the file name as "Root CA" (any name can be used) and click Next. g) Click Finish and OK. h) Close the certificate tool window.

3. Generate a client certificate file in DER format. a) Remove .txt extension in the certificate file name (its name starts with a big hexadecimal

number ex: 926b40a079-certificate.pem.crt.txt). b) Double-click on the client certificate (its name starts with a big hexadecimal number) to

open the certificate in the Windows Certificate tool. c) Click the Details tab. d) Click Copy to File…. e) Click Next. f) Select DER encoded binary X.509 (.CER) and click Next. g) Enter the file name “client-cert” (any name can be used) and click Next. h) Click Finish and OK. i) Close the certificate tool window.

4. Duplicate the client private key file and name the new copy “client-priv.key”. a) Select the key file with “private” in its name. b) Rename the file name to “client-priv.key” (any name can be used).


1VV0301461 Rev. 1.1 of 36 2017-09-15

2.9 CONFIGURING THE SKB/EVB TO CONNECT TO AWS IOT

2.9.1 For SKB To connect to AWS IoT, the credentials must be installed and the host name and port number of the AWS IoT server must be configured on the SKB.

1. Setup an access point with WPA-Personal or open security. (Note: This access point must provide access to the internet).


3. Switch your SKB’s power switch (SW5) to “ON”. 4. Observe the debug output terminal window. 5. Verify the output in the debug terminal window which is as follows:

**********


**********

[TLS]SSID = GS_PROV_TLS-95e2f3. Channel =

1 [TLS]IP Address - 192.168.240.1

6. If it is not displayed, press and hold the “WAKE” button for more than 3 seconds before releasing it.

This will cause the board to reset in provisioning mode with output as indicated in the previous step.

7. Associate your PC to the wireless network name beginning with “GS_PROV_TLS”. 8. Enter the case sensitive security key “GS_<last6DigitsOfNetworkName>” when

prompted. The <last6DigitsOfNetworkName> are the last six digits of the SKB wireless network name.

For example, for the network named “GS_PROV_TLS_95e2f3” enter “GS_95e2f3” as the security key.

9. Using your PC’s web browser, browse to: 192.168.240.1/gsprov.html. A page (as captured below) will be displayed.


1VV0301461 Rev. 1.1 of 36 2017-09-15

10. Click the option IoT Settings and the following page is displayed:

11. Enter the host name obtained earlier against “API Endpoint” 12. Enter the server port Number (8883) 13. Click CA Certificate and choose the root CA certificate named Root CA generated

earlier (refer section 2.8Preparing Credential Files for Installation on the SKB/EVB) 14. Click Client Certificate and choose the client certificate generated named client-cert

earlier (refer section 2.8Preparing Credential Files for Installation on the SKB/EVB) 15. Click Client Key and choose the client private key generated named client-priv earlier

(refer section 2.8Preparing Credential Files for Installation on the SKB/EVB) 16. Click Save and Apply to upload all three files and configuration. 17. Upon success, “IoT configuration completed” message will be displayed for a short

duration. 18. Click Back for going back to the Device Setup page. 19. Click Client Settings. 20. Click Select an Existing Network. 21. Click the Select button next to the name of the wireless network to which the SKB will

connect. 22. Enter the passphrase, if required. 23. Click Next, Save and Apply Settings. 24. Verify debug messages as shown in the following display terminal window. Upon

successfully connecting AWS IoT message broker, take note of the IP address the SKB is using.

**********

APP NCM started in STA mode

**********

[TLS] Set the device name 3CA06758750E

[TLS] SSID = << YourNetworkName>>. Channel = 11

[TLS] IP Address - 192.168.23.118

[TLS] SNTP server name = 0.pool.ntp.org

[TLS] SNTP server address = 206.71.252.18

[TLS] App_TimeSyncDoneCb

[TLS] Date and time Fri, 21 Jul 2017 03:17:14 GMT

[TLS] Led state restored :0

[TLS] Device Identifier: 3CA06758750E

[TLS] AWS IoT SDK Version 2.1.1-

[TLS] Connecting to a3f3fh47ywiwev.iot.us-

east-2.amazonaws.com:8883


1VV0301461 Rev. 1.1 of 36 2017-09-15

[TLS] Connected successfully to AWS IoT server

[TLS] Subscribing to topic: device/3CA06758750E/status

[TLS] Shadow Init : done status [0]

[TLS] Subscribing to topic: device/3CA06758750E/message

[TLS] [App_NetworkServicesStart] Entered

[TLS] [AppHttpd_Start] Entered

**********

HTTP: httpd server start in normal mode

**********

[TLS] [App_ConfigCb] Entered

[TLS] [AppOtafu_Init] Entered

[TLS] Shadow connect : done status [0]

[TLS] Shadow auto reconnect : done status [0]

[TLS] Shadow register delta [status:0], [led0:0]

Congratulations! the SKB is now connected to AWS IoT.

2.9.2 For EVB Following is the procedure to connect to AWS IoT, the credentials must be installed and the host name and port number of the AWS IoT server must be configured on the EVB.

1. Setup an access point with WPA-Personal or open security.

(Note: This access point must provide access to the internet.)

2. Verify “SW7” on the EVB is in the “PROGRAM” position and the power switch (SW1) is in the “OFF” position.

3. Switch your EVB’s power switch (SW1) to “ON”. 4. Observe the debug output terminal window. 5. Verify the output in the debug terminal window which is as follows:

**********


**********

[TLS]SSID = GS_PROV_TLS-95e2f3. Channel = 1

[TLS]IP Address - 192.168.240.1

6. If not displayed, press and hold the “ALARM2” button for more than 3 seconds before releasing it.

This will cause the board to reset in provisioning mode with output as indicated in the previous step.

7. Associate the PC to the wireless network name beginning with “GS_PROV_TLS”. 8. Enter the case sensitive security key “GS_<last6DigitsOfNetworkName>” when

prompted. The <last6DigitsOfNetworkName> are the last six digits of the EVB wireless network name.

For example, for the network named “GS_PROV_TLS_95e2f3” enter “GS_95e2f3” as the security key.


1VV0301461 Rev. 1.1 of 36 2017-09-15

9. Using the PC’s web browser, browse to: 192.168.240.1/gsprov.html. As shown in the following figure:

10. Click the option IoT Settings and the following page will be displayed:

10. Enter the host name obtained earlier against “API Endpoint” 11. Enter the server port Number (8883) 12. Click CA Certificate and choose the root CA certificate generated earlier (refer section

2.8Preparing Credential Files for Installation on the SKB/EVB) 13. Click Client Certificate and choose the client certificate generated earlier (refer section

2.8Preparing Credential Files for Installation on the SKB/EVB) 14. Click Client Key and choose the client private key generated earlier (refer section

2.8Preparing Credential Files for Installation on the SKB/EVB) 15. Click Save and Apply to upload all three files and configuration. 16. Upon success, “IoT configuration completed” message will be displayed for a short

duration. 17. Click Back for going back to the Device Setup page. 18. Click Client Settings. 19. Click Select an Existing Network. 20. Click the Select button next to the name of the wireless network to which the EVB will

connect. 21. Enter the passphrase, if required. 22. Click Next, Save and Apply Settings. 23. Verify debug messages as shown in the following display terminal window. Upon

successfully connecting AWS IoT message broker, take note of the IP address the EVB is using.


1VV0301461 Rev. 1.1 of 36 2017-09-15

********** APP NCM started in STA mode ********** [TLS] Set the device name 3CA06758750E [TLS] SSID = << YourNetworkName>>. Channel = 11 [TLS] IP Address - 192.168.23.118 [TLS] SNTP server name = 0.pool.ntp.org [TLS] SNTP server address = 206.71.252.18 [TLS] App_TimeSyncDoneCb [TLS] Date and time Fri, 21 Jul 2017 03:17:14 GMT [TLS] Led state restored :0 [TLS] Device Identifier: 3CA06758750E [TLS] AWS IoT SDK Version 2.1.1- [TLS] Connecting to a3f3fh47ywiwev.iot.us-east-

2.amazonaws.com:8883 [TLS] Connected successfully to AWS IoT server [TLS] Subscribing to topic: device/3CA06758750E/status [TLS] Shadow Init : done status [0] [TLS] Subscribing to topic: device/3CA06758750E/message [TLS] [App_NetworkServicesStart] Entered [TLS] [AppHttpd_Start] Entered ********** HTTP: httpd server start in normal mode ********** [TLS] [App_ConfigCb] Entered [TLS] [AppOtafu_Init] Entered [TLS] Shadow connect : done status [0] [TLS] Shadow auto reconnect : done status [0] [TLS] Shadow register delta [status:0], [led0:0]

Congratulations! the EVB is now connected to AWS IoT.

2.10 MONITORING THE SKB/EVB FROM AWS IOT CONSOLE

Following is the procedure to monitor SKB/EVB via the AWS IoT console. Interaction with SKB/EVB using the AWS IoT console’s test feature.

2.10.1 Monitoring Status Messages The reference application publishes sensor history data by publishing status messages to the topic:

“device/<deviceIdentifier>/status”

For example, “device/ABCDEF123456/status”

The topic name is displayed on the terminal when the SKB/EVB first connects to the AWS IoT server:

[TLS] Subscribing to topic: device/ABCDEF123456/status

To use AWS Console for subscribing the device’s status topic to receive and display these messages:


1VV0301461 Rev. 1.1 of 36 2017-09-15

1. Sign in to the AWS Console. 2. Select AWS IoT from the Services menu. 3. Click the Test item in the AWS IoT navigation panel. 4. Power on the SKB/EVB if not already ON. 5. Copy and paste the “…/status” topic into the Subscription topic field. 6. Click the Subscribe to topic button. 7. The topic will appear under the “Subscriptions” column. 8. Messages published by the SKB/EVB will be displayed every 5 seconds. The

messages are in JSON format and is as shown below. Sensor readings are displayed within the message-as highlighted. The units of the sensor values are: temperature – degrees C, light – lux, battery – millivolts and RSSI – dBm.

{

"source": " ABCDEF123456",

"id": 93,

"type": "status",

"message": {

"status": [

{

"time": 1481081490,

"values": [

{

"id": "temp1",

"value": "24"

},

{

"id": "light1",

"value": "446"

},

{

"id": "batt1",

"value": "1092"

},

{

"id": "rssi1",

"value": "-50"

}

]

},

{

"time": 1481081495,

"values": [

{

"id": "temp1",

"value": "24"

},

{

"id": "light1",

"value": "446"

},

{


1VV0301461 Rev. 1.1 of 36 2017-09-15

"id": "batt1",

"value": "1089"

},

{

"id": "rssi1",

"value": "-52"

}

]

}

]

}

}

9. Click the “x” next to the topic to unsubscribe from it.

NOTE: Device also subscribes to the topic “device/<deviceIdentifier>/message” to receive status messages from AWS IoT.

The following debug message is displayed on the terminal when the SKB/EVB connects to the AWS IoT message broker:

[TLS] Subscribing to topic: device/ABCDEF123456/message

2.11 CONTROLLING THE SKB/EVB FROM AWS IOT DEVICE

SHADOW

2.11.1 Controlling an LED on the SKB/EVB Device The LED status on the SKB/EVB device can be controlled by using the AWS IoT Console MQTT Client posting a JSON formatted message to shadow topic of the SKB/EVB.

Topic to update the Device Shadow: $aws/things/thingName/shadow/update

For Example: $aws/things/001DC91B9ED5/shadow/update

NOTE: Thing Name is the Mac Address of the SKB/EVB. It is also displayed on the console output when the device starts up. It is similar to the following. [TLS] Device Identifier: 001DC91B9ED5


1VV0301461 Rev. 1.1 of 36 2017-09-15

To post the device update using the AWS Console:

1. Sign in to AWS IoT console 2. Select AWS IoT from the AWS Console Services menu. 3. Click the Test item in the navigation panel 4. Power on the SKB/EVB if not already ON. 5. From the Registry>Things>Click the thing name displayed on the screen. In the

multiple options window, select Shadow. 6. From the Shadow, copy and paste $aws/things/<Mac Address>/shadow/update in to

the Publish to topic field. 7. In the Publish to topic field, copy and paste the following message

{"state" : {"desired" : {"led1" : 1} } }

Figure 12: Post Device Update Using AWS Console

8. Click the Publish to topic 9. Observe “Led1” on the SKB. 10. Finally, the SKB/EVB updates the LED status to AWS IoT Device Shadow.

Figure 13: Shadow Response from Publish to topic


1VV0301461 Rev. 1.1 of 36 2017-09-15

Figure 15: Controllable LED in GS2200MIZ SKB module

Figure 14: Topic Response from Publish to topic

2.11.2 Controlling an LED on the SKB through Button Press

2.11.2.1 For SKB:

1. Short press “wake” key. (Note: short press duration less than 3 seconds) 2. Observe the change in “Led1” state (ON <-> OFF) 3. The same will get reflected in the AWS IoT Device shadow.


1VV0301461 Rev. 1.1 of 36 2017-09-15

2.11.2.2 For EVB:

Figure 16: Controllable LED in GS2101MIP EVB module

Figure 17: Controllable LED in GS2200MIZ EVB module

1. Short press “ALARM2” key. (Note: short press duration less than 3 seconds) 2. Observe the change in LED state:

• For GS2101 EVB check D8 (Refer Error! Reference source not found.)

• For GS2200 EVB check D3 (Refer Error! Reference source not found.)

3. The same will get reflected in the AWS IoT Device shadow.


1VV0301461 Rev. 1.1 of 36 2017-09-15

2.12 REVERTING THE SKB/EVB CONFIGURATION TO FACTORY

DEFAULT CONFIGURATION

2.12.1 For SKB: To re-provision the SKB, revert to the factory default configuration:

1. Power ON the SKB. 2. Press and hold the “WAKE” button for at least 3 seconds.

After the SKB reboots into provisioning mode, re-provision it as described in earlier sections. You will also need to reinstall the certificates and keys and configure the host name and port of the AWS IoT message broker.

2.12.2 For EVB: To re-provision the EVB, revert to the factory default configuration:

1. Power ON the EVB. 2. Press and hold the “ALARM2” button for at least 3 seconds.

After the EVB reboots into provisioning mode, re-provision it as described in earlier sections. You will also need to reinstall the certificates and keys and configure the host name and port of the AWS IoT message broker.

GS2K Application Development Kit (ADK) for AWS IoT User Guide · 2018-02-02 · GS2K Application...

Documents

Transcript of GS2K Application Development Kit (ADK) for AWS IoT User Guide · 2018-02-02 · GS2K Application...