48
September 2016 Getting Started Guide AT&T IoT Starter Kit Getting Started Guide

AT&T IoT Starter Kit Getting Started Guide - Amazon S3 · Getting Started Guide AT&T IoT Starter Kit Getting Started Guide. ... Jasper Account ... The Patient Developer’s Guide

Embed Size (px)

Citation preview

September 2016

Getting Started Guide

AT&T IoT Starter Kit Getting Started Guide

2 AT&T

AT&T IoT Starter Kit

6

6

8

8

9

11

CONTENTS

Introduction

Inside the AT&T IoT Starter Kit

NXT FRDM-K64F Development

Board Avnet Cellular Shield

Developer resources and support

Assembling the Starter Kit

AT&T IoT Services 12

12AT&T M2X

AT&T Flow 13

Sample IoT Project 14

14IoT Project Approaches with Flow and

M2X Account Setup 16

16

19

20

AT&T M2X Account

Jasper Account (SIM Card Registration)

ARM mbed.org Account

Optional: Cloudconnectkits.org Account 21

The Patient Developer’s Guide to Creating the Flow Application 23

23

24

26

32

Accessing The Flow Dashboard

Forking the Existing Project

Configure the Flow Application to Access Your M2X

Account Executing the M2X Setup Flow

Deploying the Project Firmware to the Development Board 34

34

35

39

Hardware Setup

Software Modification

Monitoring Activity

The Impatient Developer’s Guide to Creating the Flow Application 43

43

44

Flow & M2X Configuration

Executing the M2X Setup Flow

Deploying the Project Firmware to the Development Board 44

44

45

Hardware Setup Software

Modification Monitoring

Activity 46

Firmware Application Modifications 48

3July 2017

Getting Started Guide

4 AT&T

AT&T IoT Starter Kit

6

7

9

9

10

11

11

11

11

12

14

15

16

17

18

19

19

20

21

21

22

23

24

25

25

26

27

27

28

29

29

30

31

32

33

33

34

35

FIGURES

Figure 1 – AT&T IoT Starter Kit Options

Figure 2 – AT&T IoT Starter Kit: Hardware + SIM Kit Contents

Figure 4 – AT&T IoT Starter Kit Home: Quickstart Page

Figure 3 – AT&T IoT Starter Kit Home Page

Figure 5 – Avnet AT&T IoT Starter Kit Home Page

Figure 6 – Development Board (bottom) and Cellular Shield

(top) Figure 7 – Connecting the Development Board and Cellular

Shield Figure 8 – ISK Cellular Antennas

Figure 9 – Completed Assembly

Figure 10 – M2X Feature Summary & Pricing

Figure 11 – Sending Data to AT&T M2X

Figure 12 – Sending Data to AT&T M2X Through AT&T Flow

Figure 13 – AT&T M2X Home Page

Figure 14 – AT&T M2X Registration Page

Figure 15 – AT&T M2X Registration: GitHub Authorization

Figure 16 – AT&T IoT Starter Kit Home Page

Figure 17 – AT&T IoT Starter Kit Dashboard

Figure 18 – ARM mbed Developer Home Page

Figure 19 – Cloudconnectkits.org Home Page

Figure 20 – Cloudconnectkits.org Registration

Figure 21 – ISK Serial Kit Number

Figure 22 – AT&T Flow Dashboard

Figure 23 – Starter Kit Reference Project

Figure 24 – Forking the Flow Project

Figure 25 – Flow IDE

Figure 26 – M2X Account Settings

Figure 27 – M2X Master Keys

Figure 28 – Flow Application Configuration

Figure 29 – Flow Function Code Editor

Figure 30 – Flow IDE Bottom Tab

Figure 31 – Flow Project Endpoints

Figure 32 – Setting base_hostname and base_uri

Figure 33 – Changes Waiting to be Deployed

Figure 34 – Initializing M2X

Figure 35 – Flow Debug Output

Figure 36 – Automatically Registered Virtual Device in M2X

Figure 37 – Windows Explorer Exploring the Development Board

Figure 38 – ARM mbed Firmware Project Page

Figure 39 – mbed IDE Import Dialog 36

5July 2017

Getting Started Guide

36

37

38

39

40

42

Figure 40 – mbed IDE

Figure 41 – AT&T Flow IDE: Climate GET Endpoint Figure

42 – AT&T M2X Starter Kit Device Page

Figure 43 – Windows Device Manager

Figure 44 – Terminal: Initializing the Cellular Shield

Model Figure 46 – AT&T Flow Debug Console

Figure 47 – AT&T M2X Graphing Sensor Data 42

6 AT&T

AT&T IoT Starter Kit

INTRODUCTIONThe AT&T IoT Starter Kit (ISK) is a collection of hardware components selected to help developers begin using the AT&T network and IoT Platforms in their Internet of Things projects. The ISK includes a programmable single board computer (SBC), a compatible LTE module (for cellular connectivity), an AT&T data subscriber identity module (SIM), plus the necessary antennas, USB cables and a power module required to create a single node in a wireless IoT project.

The purpose of this guide is to introduce you to the ISK hardware and the software tools AT&T provides for building and managing IoT projects. The guide will walk you through assembling the ISK hardware, creating the necessary online accounts needed to work with the hardware and software, and building a starter application that exercises the ISK.

INSIDE THE AT&T IOT STARTER KITThe AT&T IoT Starter Kit comes in two versions; the differences between the offerings are highlighted in Figure 1:

Figure 1 – AT&T IoT Starter Kit Options

7July 2017

Getting Started Guide

• SIM Only• Hardware + SIM

The SIM Only kit provides developers with an AT&T LTE SIM they can use while building their IoT projects. The SIM will operate in the US and enables developers to consume 300Mb of data plus send and receive 300 SMS messages over a six-month period. The SIM is designed to enable kickstarting your IoT projects, with the expectation that you’ll provisions your production IoT nodes with full AT&T data SIMs after the six-month period ends or when you put your IoT project into production.

The Hardware + SIM version of the ISK includes the data SIM plus the hardware necessary to create a IoT project node (excluding custom sensors); hardware components are shown in Figure 2. The kit includes the following components:

• NXP FRDM K64F development board (specifications)• Avnet Cellular Shield (based on the WNC M14A2A)• AT&T LTE SIM (IoT SIM Starter Pack)• 2 LTE antennas• 2 USB cables• AC power adapter• Quick Start Card

Figure 2 – AT&T IoT Starter Kit: Hardware + SIM Kit Contents

8 AT&T

AT&T IoT Starter Kit

NXT FRDM-K64F DEVELOPMENT BOARD

The NXP FRDM-K64F is the brains of the ISK; it’s a programmable single board computer (SBC); the board has the following specifications:

• MK64FN1M0VLL12 MCU: A Cortex M4 ARM processor core running at 120 MHz with 1 MB of flash memory and 256 KB of RAM

• USB, Serial Port, I2C, and UART interfaces• microSD card slot• Ethernet port• Headers for connecting Bluetooth and 2.4 GHz radio add-on modules• Tri-color LED• 6-axis digital accelerometer• Magnetometer• 2 program accessible push-buttons

The board’s I2C interface is used for communicating with many, common off-board sensors. Its UART interface is used to for communicating with the WNC M14A2A cellular shield. The board overall form-factor conforms with the Arduino R3 pin layout, so compliant Arduino shields, like the WNC M14A2A, can be used with this device.

The board sports an OpenSDAv2 debug circuit, supporting the CMSIS-DAP Interface to allow programming and monitoring software.

AVNET CELLULAR SHIELDArduino-compatible cellular shield built using the Wistron NeWeb Corporation (WNC) M14A2A cellular module. This daughterboard contains the necessary protocol stack needed to establish and maintain a data connection between an Arduino compatible board like the NXT FRDM-K64F and the AT&T LTE network. The board requires an active SIM and data plan to operate on the AT&T LTE network.

The cellular shield utilizes a Type-III interface. The NXT FRDM-K64F communicates with the cellular shield through its UART interface by executing 3GPP call control AT commands.

Note: At power up, the software configures the hardware and initializes the WNC-Shield card which can take up to 60 seconds to complete.

9July 2017

Getting Started Guide

DEVELOPER RESOURCES AND SUPPORT

We want your experience with the ISK to be both pleasant and productive. When you need questions answered, access the official starter kit forum athttp://cloudconnectkits.org/forum/topic/att-cellular-iot-starter-kit.

AT&T publishes a variety of information related to the ISK athttps://marketplace.att.com. There you’ll find this getting started guide, documentation, API guides, tutorials, discussion forums, software updates, FAQ, and more. To access the content, click the Develop button shown on the top of Figure 3.

Figure 3 – AT&T IoT Starter Kit Home Page

Figure 4 – AT&T IoT Marketplace Home: Quickstart Page

10 AT&T

AT&T IoT Starter Kit

Avnet also provides a site where you can access additional information about the kit, hardware manuals, user guides, board schematics, firmware updates, and more at www.cloudconnectkits.org/product/att-cellular-iot-starter-kit.

Figure 5 – Avnet AT&T IoT Starter Kit Home Page

11July 2017

Getting Started Guide

ASSEMBLING THE STARTER KIT

Assembling the ISK is easy, simply mount the cellular shield onto the NXT FRDM-K64F Development Board, attach the antennas the apply power. Figure 6 shows the development and cellular shield boards ready to connect. As you can see from the figure, the Arduino pin layout is designed so that the boards can only align in one orientation. In the lower portion of the figure, notice that the development board has two rows of sockets for each connector.

When mounting the cellular shield on the development board, the pins from the cellular shield will plug into the outside sockets on the development board.

Place the cellular shield on the development board, aligning the pins on the cellular shield with the outside sockets on the development board. With everything aligned, gently press down evenly on the cellular shield to connect the boards. Pushing too hard on the boards may damage the boards.

Note: When you’re finished, there will be a slight gap between the cellular shield and the development board sockets; do not expect the board to be flush with the sockets on the development board.

Attach the cellular antennas (Figure 8) to the Cellular Shield using the metal connectors shown in the lower-left corner of Figure 7. The connection must be tight, so there’s good connectivity between the board and the antenna, but not too tight as you might damage the board or the connector if you tighten it too much.

The ISK comes with two micro-USB cables and a power supply. Connect a USB cable to the micro-USB connector labeled 5V DC on the lower-right corner of the cellular shield board shown in Figure 9. Connect the other end of the cable to the power supply as shown in the figure. Due to the pin configuration of the boards, power supplied to the cellular shield will also power the development board.

Note: The cellular shield has specific voltage requirements, it requires 5V at 2.4A. USB ports and cell phone chargers provide the necessary 5V, but may not provide the required current. If using a different power source than one provided with the ISK, be sure to check the power supply’s output specifications to ensure it provides at least 2.4A current. With-out the correct input power, the modem will not initialize properly.

The other USB cable is used to connect the development board to a PC in order to download firmware updates or custom applications to the board. Connect the USB cable to the development board using the Micro-USB connector on the lower-left corner of the development board shown in Figure 9. Use the connector to the left of the Ethernet port shown in the figure.

Finally, activate the SIM using the instructions provided in ‘Jasper Account (SIM Card’ then insert the SIM into the cellular shield. The socket for the SIM is on the cellular shield, right above the development board’s Ethernet connector shown in Figure 9. Insert the SIM with its metal connectors facing down toward the cellular shield and the end with the cut-off corner into the socket first. The SIM socket will hold the SIM in place, so you must push the SIM all the way into the socket until it clicks before releasing it.

Figure 6 – Development Board (bottom) and Cellular Shield (top)

Figure 7 – Connecting the Development Board and Cellular Shield

Figure 8 – ISK Cellular Antennas

Figure 9 – Completed Assembly

12 AT&T

AT&T IoT Starter Kit

AT&T IOT SERVICES

As a mobile carrier, AT&T has the network, billing, support and other services you’ll need to help guarantee your IoT project’s success. The wireless network used by smartphones and tables is the same network you’ll use to communicate with your IoT devices and for your IoT devices to transmit data. Where the data goes and what you do with it is the true power behind an IoT project.

AT&T offers additional services for developers to help streamline the development of IoT projects and to provide an easy to use storage location for IoT data.

AT&T M2X

AT&T’s M2X is a time-series, cloud-based data storage service and device management toolset customized for the Internet of Things. IoT projects generate a lot of data, and there’s often no need to pull all of that data into the corporate data center.

Instead, IoT data is collected, then analyzed in place and the appropriate insights or meta data is pulled into systems of record or execution engines. Developers use M2X to organize millions of connected devices, gather data in real-time, and translate collected data into meaningful information for quick decisions, automated actions, and strategic analysis.

Figure 10 – M2X Feature Summary & Pricing

The AT&T M2X developer tier is free to use for a maximum of 10 devices and 100,000 data points written to the store. You can learn more about AT&T M2X at m2x.att.com.

13July 2017

Getting Started Guide

AT&T FLOWAT&T Flow development environment tool for IoT projects, based on the open source Node-Red project . With flow, the development environment has been enhanced to enable it to run in the cloud, plus adds the following additional features:

• Applications run in containers for easy cloud distribution• Version control• Support for teams• Sandbox mode• Adds new, enterprise-grade input and output node types• Can utilize AT&T NetBond for secure transmission of data between

device, cloud, and on-premises network avoiding the public Internet

Flow is an intuitive visual tool that enables IoT app developers to create prototypes, iterate and improve through multiple versions, then deploy your application to IoT devices. Flow offers nodes that are pre-configured to allow easy access to multiple data sources, cloud services, device profiles, and communication methods. The integrations are already done for you, so you only have to focus on wiring the building blocks together to create your IoT application. You can learn more about AT&T Flow at flow.att.com.

14 AT&T

AT&T IoT Starter Kit

SAMPLE IOT PROJECT

To show you how to utilize the ISK and AT&T’s IoT cloud services, for the remainder of this guide, you’ll work through setting up and executing a pre-built IoT project using the ISK, AT&T Flow and AT&T M2X. The project takes measurements using the various sensors on the development board then sends the values to AT&T M2X through AT&T Flow. Special commands, in the form of JSON strings, are sent back to the development board from the AT&T Flow application to instruct the device to control on-board components such as the LED.

To create this project, you’ll complete the following steps:

1. Create accounts for the various online services you will use for this project.2. Activate the developer SIM included in the ISK (see ‘Jasper Account (SIM Card

Registration)’).3. Use AT&T Flow to fork the sample project.4. Update the Flow project to use your AT&T account settings.5. Deploy the Flow project in the AT&T cloud environment.6. Configure an mbed firmware application for your AT&T Flow environment.7. Deploy the firmware to the development board.8. Start collecting data.

To gain an understanding of how we’re structuring the sample project, spend some time reviewing ‘IoT Project Approaches with Flow and M2X’ before continuing. You’ll need to use a few online accounts to complete this project, so you’ll find registration instructions in the ‘Account Setup’ section.Regarding creating the project; if you’re the impatient type, and don’t need any hand holding, you’ll find shortcut instructions for this project in ‘The Impatient Developer’s Guide to Creating the Flow Application.’ For beginners, complete, step by step instructions, with pictures, can be found in ‘The Patient Developer’s Guide to Creating the Flow Application.’

IOT PROJECT APPROACHES WITH FLOW AND M2X

In many simple M2X projects, IoT devices collect data using either built-in or connected sensors then uploads the recorded data to M2X as shown in Figure 11. Typically, you’ll code the data collection application on the IoT device and leverage the M2X APIs in the device application to send data to the cloud.

Figure 11 – Sending Data to AT&T M2X

15July 2017

Getting Started Guide

More sophisticated IoT applications will use the capabilities of AT&T Flow to process the collected data in some way; make decisions (in the cloud instead of on the IoT device) about the data and acting somehow, such as discarding banal data or executing a trigger to perform a related action.

For this project, you’ll use a pre-built Flow application to collect data from the ISK device, then process the data before sending the data to M2X. the development board in the ISK includes a variety of sensors, so you can complete the project without needing any additional hardware.

The Flow application takes advantage of its seamless integration with M2X to create the necessary project definition in M2X and prepare a data store. Additionally, the Flow project uses triggers to enable the IoT device to communicate status to the Flow application.

Figure 12 – Sending Data to AT&T M2X Through AT&T Flow

16 AT&T

AT&T IoT Starter Kit

For common M2X and Flow applications, you’ll setup your project using the following steps:

For common M2X and Flow applications, you’ll setup your project using the following steps:

1. Setup M2X environment for your project.2. Create, then deploy a Flow application into the AT&T cloud environment.3. Deploy software to the development board(s).4. Begin data collection.

For our example, the Flow application already exists, and the M2X project setup process is performed by the Flow application, so for this project we’ll use the following workflow:

1. Configure and deploy a Flow application into the AT&T cloud environment.2. Deploy software into the AT&T cloud environment.3. Deploy software to the development board(s).4. Begin data collection.

ACCOUNT SETUP

Before you can start building the project, you’ll need to create some online accounts for the different sites we’ll use. There are five accounts needed to use to complete the project; the following subsections will describe how to register for each.

AT&T M2X ACCOUNT

The core capabilities for this project are provided through AT&T IoT Services; you’ll create an account there and have access to both M2X and Flow. Sign up for an AT&T IoT Services account by pointing your browser of choice to m2x.att.com/signup. as shown in Figure 13. Click the SIGN UP button on the page’s upper-right corner. On the page that appears (see Figure 14), select the registration method that makes the most sense for your particular needs and preferences.

Figure 13 – AT&T M2X Home Page

17July 2017

Getting Started Guide

Figure 14 – AT&T M2X Registration Page

18 AT&T

AT&T IoT Starter Kit

If you select to use your GitHub credentials, you will have to authorize AT&T to access your GitHub credentials as shown in Figure 15

Figure 15 – AT&T M2X Registration: GitHub Authorization

Once you complete the registration process, you will use these same credentials for your AT&T Flow (https://flow.att.com) and AT&T M2X (https://m2x.att.com) accounts.

19July 2017

Getting Started Guide

JASPER ACCOUNT (SIM CARD REGISTRATION)

Before you can use the developer SIM that comes with the ISK, you must first register the SIM with Jasper. Point your browser of choice to marketplace.att.com/app/sim-cards then login to the site from the home page (Figure 16). You can use the AT&T account you created in the previous step to login to this site.

Once you’re logged in, you’ll be taken to the AT&T IoT Starter Kit Dashboard (Figure 17). The SIM page should open automatically, if not, click the SIM Cards tab on the left side of the page. From there, click the plus sign icon to add a SIM card to your account.

Figure 16 – AT&T IoT Marketplace Home Page

Figure 17 – AT&T IoT Marketplace Dashboard

20 AT&T

AT&T IoT Starter Kit

Populate the form with your ISK Developer SIM ICCID (you’ll find the number printed on the face of the SIM card) and give the SIM a nickname (such as ‘Starter Kit’ or ‘ISK’). You’ll have to agree to several terms of service before you can continue.

When the form’s populated and you’ve accepted the terms for all of the agreements, click the ACTIVATE SIM button on the form to save your changes. Once you complete this registration process, you’ll be able to use the SIM for free for six months with access to transmit 300 MB of data and 300 SMS messages.

ARM MBED.ORG ACCOUNT

The project firmware, the custom code that runs on the development board, is already compiled and ready to deploy to your ISK. However, if your device is running an older version of the mbed OS or if you want to make changes to the project’s code, you’ll need access to the ARM mbed web site. To create an account, point your browser of choice to developer.mbed.org. On the site’s home page, click the Log In/Signup button in the header bar (Figure 18) to begin the process.

Figure 18 – ARM mbed Developer Home Page

21July 2017

Getting Started Guide

OPTIONAL: CLOUDCONNECTKITS.ORG ACCOUNT

The AT&T ISK is produced by Avnet, and they’ve created a developer portal with developer resources, sample applications and more. This is not required, but Avnet recommends that you register on their site so you can be notified of any software updates as well as other pertinent information as it becomes available. To register with the Avnet portal, point your browser of choice to www.Cloudconnectkits.org then click the Sign In/Register button shown in the upper-right corner of Figure 19.

As part of the registration process, you’ll be asked for the ISK Serial Kit Number as shown in Figure 20. The serial number is the cellular shield serial number printed on the sticker on top of the metal shield on the cellular shield board highlighted in Figure 21.

Figure 20 – Cloudconnectkits.org Registration

Figure 19 – Cloudconnectkits. org Home Page

22 AT&T

AT&T IoT Starter Kit

Figure 21 – ISK Serial Kit Number

23July 2017

Getting Started Guide

THE PATIENT DEVELOPER’S GUIDE TO CREATING THE FLOW APPLICATION

The AT&T Flow application for this project already exists; you’ll use this existing application by copying it into your AT&T Flow workspace and modifying it to suit your account’s configuration and ISK hardware. Each AT&T account has unique account keys that the Flow application needs to operate, so you’ll be copying them into the existing application project so it can work within your AT&T IoT Services account.

ACCESSING THE FLOW DASHBOARD

To access the AT&T Flow dashboard, open your browser of choice and navigate to http://flow.att.io; you’ll see a page similar to the one shown in Figure 22. Spend a few minutes looking around the IDE to get comfortable.Note: Flow will automatically time-out a session after a specific amount of time, so even though you may have logged in previously, you may have to login again to access the system.

Figure 22 – AT&T Flow Dashboard

For this project, we’re going to use an existing Flow project; because of the version control capabilities of Flow, we’ll copy the project by forking it.

24 AT&T

AT&T IoT Starter Kit

FORKING THE EXISTING PROJECT

To fork the starter kit project, in the browser, navigate to the following URL: https://flow.att.io/starter-kit-core/starter-kit-base/home; you’ll see a page similar to the one shown in Figure 23. Next, complete the following steps

1. Click the Fork button highlighted in the figure to create a copy of the project for your exclusive use.

Figure 23 – Starter Kit Reference Project

25July 2017

Getting Started Guide

2. In the pop-up dialog that appears (Figure 24), Flow provides you with an opportunity to rename the project as part of the forking process. The dialog shows the original project name as both the source and target name for this project. If you want to use a different name for your project (recommended), click the target file name and the target file name will change into an input field as shown in Figure 24. Enter the new name for the project then click the Fork button to complete the process.

Figure 24 – Forking the Flow Project

At this point, the forked (and potentially renamed) project will open in the Flow IDE as shown in Figure 25.

Figure 25 – Flow IDE

26 AT&T

AT&T IoT Starter Kit

3. When you first execute a Flow project in AT&T’s cloud environment, the initial execution container setup takes a few minutes. So, to save time, click the Deploy button shown in the upper-right corner of Figure 25 to start the provisioning process. This will compile and activate your project in the Flow cloud environment. As you make changes to the project and re-deploy, subsequent deployments will take mere seconds.

CONFIGURE THE FLOW APPLICATION TO ACCESS YOUR M2X ACCOUNT

The Flow application is configured to send measurement data to M2X, but the application doesn’t know how to do that for your M2X account. So, the next step is to add your M2X account details to the Flow application. You’ll be copying information between M2X and Flow, so you’ll want to have either two browser windows open or two tabs, one open to M2X and the other to Flow.

1.In M2X, click the ‘Hello, USERNAME’ button in the upper-right corner of the M2X console then select Account Settings (Figure 26).

Figure 26 – M2X Account Settings

27July 2017

Getting Started Guide

2. Highlight the Master Key (Figure 27) and copy it to the clipboard.

3. Switch to the Flow console window (or tab) and open your copy of the sample project (Figure 28). Select Data tab on the upper-left side of the IDE (1) then locate the Configuration FUNCTION element (2).

Figure 27 – M2X Master Keys

Figure 28 – Flow Application Configuration

28 AT&T

AT&T IoT Starter Kit

Figure 29 – Flow Function Code Editor

4. Double-click the Configuration function (highlighted as #2 in Figure 28); the Flow IDE will open the code editing window shown in Figure 29. Paste M2X account Master Key you copied in step 2 into the code editor, replacing the ‘<get from M2X>’ text highlighted in the figure. Click the OK button to continue.

29July 2017

Getting Started Guide

5. At the bottom of the Flow project’s IDE Window are two tabs: Info and Endpoints (Figure 30). Click the Endpoints tab to continue.

Figure 30 – Flow IDE Bottom Tab

A panel will open that lists the endpoints for the project (Figure 31). To finish the Flow application configuration, we’ll need the Base URL shown in the figure. Click the Copy button to the right of the Base URL to copy the value to the clipboard.

Figure 31 – Flow Project Endpoints

Note: The project’s endpoints are generated when the application is deployed into the AT&T cloud environment. If your Endpoints tab is empty, try deploying the application and trying again. To deploy the application, click the Deploy button in the upper-right corner of the Flow IDE.

30 AT&T

AT&T IoT Starter Kit

6. Double-click the Configuration function (highlighted as #2 in Figure 28) to open the Flow code editor. The Base URL copied in the previous step is used to update two variables in the project’s Configuration function. Using the Base URL shown in Figure 31 as an example (for this step, you’ll want to use the value you copied from the Endpoints tab):

https://run-east.att.io/01020304050/998877665544332211/in/flow

The Configuration function’s base_hostname variable is the hostname portion of the Base URL (without the https://): run-east.att.io. The Configuration function’s base_uri value is everything after the host name (including the trailing forward slash): /01020304050/998877665544332211/in/flow.

In the editor, look for the following code (shown in Figure 32):

var base_hostname = “<get from Base URL>”; var base_uri = “<get from Base URL>”;

Update the code with the appropriate values from your Base URL as described above. So, for the example endpoint used above, you would modify the

var base_hostname = “run-east.att.io”;var base_uri = “/01020304050/998877665544332211/in/flow”;

Click the OK button when you have completed making the change.

Figure 32 – Setting base_hostname and base_uri

31July 2017

Getting Started Guide

7. With the configuration updated, a blue dot will appear on the upper-right corner of the Configuration function element as shown in Figure 33. This indicates that the element’s configuration has changed but has not yet been deployed. Click the IDE’s Deploy button to deploy the application and resolve this issue.

Figure 33 – Changes Waiting to be Deployed

32 AT&T

AT&T IoT Starter Kit

EXECUTING THE M2X SETUP FLOW

The Flow application will automatically create a virtual device for the project in M2X; all you’ll have to do is kick off the process. This is a one-time operation that has to be performed.

In the Flow IDE (Figure 34), click on the Virtual Device tab (1) at the top of the IDE. Locate the project’s Initialize component (2) in the lower-left corner of the canvas. Click once on the button to the left of the Initialize element (3).

Figure 34 – Initializing M2X

There’s no direct indication in Flow whether the initialization succeeded or failed. Notice the green Debug components in the flow application at the bottom of Figure 34; they’re used to write content to the debug console. Click the Debug tab shown on the bottom of the figure and Flow will open the Debug pane shown in Figure 35. Here you can see the message payload data passed to the Debug component. In this case, the initialization failed because the initialization process ran a second time and the virtual device already existed.

33July 2017

Getting Started Guide

Figure 35 – Flow Debug Output

Verify the component has been created in the M2X environment by returning to your M2X window and clicking Devices. Your virtual device should appear as shown in Figure 36. If you expand it by clicking the + sign to its left, you will see the different M2X streams that have been created for it.

Figure 36 – Automatically Registered Virtual Device in M2X

34 AT&T

AT&T IoT Starter Kit

DEPLOYING THE PROJECT FIRMWARE TO THE DEVELOPMENT BOARD

At this point, you’re ready to deploy the data collection app to the development board. The NXP FRDM-K64F SBC runs the ARM mBed operating system. ARM provides operating system updates and and platform development tools. Developers code applications for the board using a web browser (e.g., Firefox, Chrome, or Explorer) and removes the need to install tools on an individual’s PC. We’ll be using some of these tools in this section. Be sure to setup an account on the ARM mbed web site before continuing; you can find account setup instructions at ‘ARM mbed.org Account.’

Hardware Setup

1. Mount the cellular shield to the development board using the instructions provided in ‘Assembling the Starter Kit’ then connect the antennas to the cellular shield.

2. The cellular shield requires 5V power supplied by the included power adapter. It is not recommended to use a desktop or laptop USB port as a power source due to the limited current delivered by most USB ports. Plug a micro USB cable into the 5V USB shield power (X5) on the Cellular shield and connect the other end of the cable to the provided power supply. The green LED on the cellular shield (LED1) and the yellow LED on the development board’s Ethernet port will illuminate.

3. Plug a micro USB cable into the SDA USB (J26) port on the FRDM-K64F board. Connect the other end of the cable to a USB port on your laptop or desktop computer. Your computer should recognize the device as a standard USB drive and install the necessary communications software to work with it (Figure 37).

Figure 37 – Windows Explorer Exploring the Development Board

35July 2017

Getting Started Guide

4. Verify the development board’s firmware is at version 0226 or higher byopening the DETAILS.TXT file shown in Figure 37. The current firmwareversion is listed in the file and is shown below:

Version: 0226Build: Aug 24 2015 17:06:30Git Commit SHA: 27a236b9fe39c674a703c5c89655fbd26b8e27e1Git Local mods: Yes

If the firmware version shown is lower than 0226, update it to the latest version using the instructions found at https://developer.mbed.org/handbook/Firmware-FRDM-K64F. If the details.txt file doesn’t exist, the version information can be found in the mbed.html file; open the file in a text editor to view version information.\

Note: Be sure to disconnect the cellular shield before attempting the development board firm-ware update.

Software Modification

Like what you did for the Flow application, you must copy the base firmware project in order to customize it for your AT&T IoT Services environment.

1. Open a new browser window then navigate tohttps://developer.mbed.org/teams/Demo-Software-for-AvnetATT-IoT-kit/code/AvnetATT_shape_hackathon/. On the page that appears, click the Import into Compiler button highlighted in Figure 38. The development environment will open start the import process.

Figure 38 – ARM mbed Firmware Project Page

36 AT&T

AT&T IoT Starter Kit

2. During the import process, you will be prompted to update settings that control the import process (Figure 39); accept the default settings then click the Import button, optionally changing the project name during the process if you wish.

Figure 39 – mbed IDE Import Dialog

Figure 40 – mbed IDE

37July 2017

Getting Started Guide

3. Before you can compile the software, you’ll have to change some constants defined within the application to match your project configuration. In the mbed IDE Program Workspace window shown on the left side of Figure 40, click the config_me.h file to open it in the editor. With the file open in the editor, look for the following code:

// This is the server’s base URL name. Example “www.google.com”// Note that when you Fork a Flow, it will typically assign either// “run-east.att.io” or “run-west.att.io”, so be sure to check this.static const char * MY_SERVER_URL = “run-west.att.io”;

// These are Flow fields from the Endpoints tab:#define FLOW_BASE_URL “/1e464b19cdcde/774c88d68202/86694923d5bf 28a/in/flow”#define FLOW_INPUT_NAME “/climate”

// This identifier specifies with which Flow device you are communicating. // If you only have one device there then you can just leave this as is.// Once your Flow device has been initialized (Virtual Device Initialize clicked), // the Virtual Device will show up in M2X. This is its “DEVICE SERIAL” field#define FLOW_DEVICE_NAME “vstarterkit001”To configure the application, you’re going to change the following values:

• MY_SERVER_URL• FLOW_BASE_URL• FLOW_DEVICE_NAME

The values you use here are different than the ones you used earlier. The values for MY_SERVER_URL and FLOW_BASE_URL are for a Flow application endpoint, just like you worked with before, but they’re for a specific endpoint in the Flow application.Switch back to the Flow IDE and click the Data tab on the top of the IDE window. Using Figure 41 as a guide, select the Climate GET component (1) then click the Endpoints tab at the bottom of the window and click the Copy button next to the Base URL (2) to copy the value to the clipboard.

Figure 41 – AT&T Flow IDE: Climate GET Endpoint

38 AT&T

AT&T IoT Starter Kit

In the mbed IDE, populate the MY_SERVER_URL constant in the code with the hostname from the URL you copied in the previous step. Populate the FLOW_ BASE_URL value in quotes with the remainder of the copied Base URL.

To determine the value for FLOW_DEVICE_NAME, open the M2X browser window and click on the device that the Flow application created earlier then copy the Device Serial number highlighted in Figure 42.

Figure 42 – AT&T M2X Starter Kit Device Page

Based on the example provided above, the configuration values should look something like the following, but using values from your project configuration:

static const char * MY_SERVER_URL = “run-east.att.io”;#define FLOW_BASE_URL “/123456789/112233445566778899/in/flow”#define FLOW_DEVICE_NAME “some_device_id”

In the mbed IDE, click the Save button along the top toolbar. Next, click the Compile button. After the source code compiles, the IDE will start to download the compiled binary. Keep track of the download file name (and location) as you’ll need the file later.

4. Disconnect the development board from your computer, wait a few seconds, then reconnect. Once the development board boots and your computer recognizes it as a drive, drag the compiled binary you just downloaded onto the drive (the disk drive representing the development board). This will program the non-volatile flash memory on the development board with the updated application firmware. Programming should take about 10 seconds, during which time the board’s green LED will flash repeatedly.

5. Disconnect the development board from the computer and remove the 5V power from the cellular shield. Then reconnect the cables, connecting the 5V USB power cable to the power adapter first, followed by the SDA USB cable to your computer system.

At this point, the development board will boot and begin executing the data collection app you just installed on the device. If all goes well, data will be collected and uploaded to M2X through the Flow application.

39July 2017

Getting Started Guide

At this point, the development board will boot and begin executing the data collection app you just installed on the device. If all goes well, data will be collected and uploaded to M2X through the Flow application.

Monitoring Activity

The User LED on the FRDM-K64F board should be RED when the wireless connection is first powered on. It will turn BLUE when it successfully connects to the AT&T network and then either green, magenta or turquoise, depending on the response from the Flow project implementation. The data being sent can be monitored through the terminal connection that was described in the previous section.

There’s not much else to see while the application runs. The device collects data from its sensors and uploads it to the AT&T IoT cloud. As developers, we all know that nothing ever works as expected the first time, so there’s probably the need to be able to see what’s happening on the development board. Unfortunately, the board doesn’t offer a video connection, so there’s no way to plugin in a monitor and watch the code at work. On the other hand, the application firmware writes to the console, so you can remotely monitor the console to view program output. Your desktop or laptop computer will communicate with the development board through its serial port. Windows, Macintosh and Linux computers are supported.

Windows users will have to install some additional software to get this working. To install the software, follow the instructions at https://developer.mbed.org/handbook/Windows-serial-configuration. After the serial drivers have been installed, determine which COM port is being used by opening the device manager and looking for the COM port information highlighted in Figure 43.

Figure 43 – Windows Device Manager

40 AT&T

AT&T IoT Starter Kit

You will need to use a terminal application to monitor the output from the development board. The default terminal installed on your development system won’t work for this purpose, so follow the instructions at https://developer.mbed.org/handbook/Terminals to install the necessary software.

Linux and Macintosh systems will automatically register a connected development board as a remote device, so there’s no special steps to perform to configure connectivity for those OS. Windows users must configure the terminal session following the instructions provided through the previous link. Default terminal configuration settings should be:

• Baud = 115200 • Stop Bits = 1 • Parity = None • Data bits = 8 • Flow Control = none • COM port set appropriately (Figure 43)

With everything installed and operating, you should be able to see the firmware application’s output in the terminal window as shown in Figure 44. In this example, the development board has just powered up and it is initializing the cellular shield.

Figure 44 – Terminal: Initializing the Cellular Shield Model

41July 2017

Getting Started Guide

Once the modem initializes, the app will start sending data to AT&T M2X through AT&T Flow. Figure 45 shows application output as it sends sensor data to the cloud. In the figure, you can see the AT commands sent to the modem by the application as well as the results of the HTTP call to the AT&T cloud.

To verify messages from the board are arriving in Flow, open the Flow project, and then click the Debug tab at the bottom of the IDE window. The Flow application sends debug messages to this console from many parts of the application, you can see some example output in Figure 46. Look for green Debug components in the Flow application to see all the places that write to the debug console.

42 AT&T

AT&T IoT Starter Kit

Figure 46 – AT&T Flow Debug Console

To verify messages from the board are arriving in Flow, open the Flow project, and then click the Debug tab at the bottom of the IDE window. The Flow application sends debug messages to this console from many parts of the application, you can see some example output in Figure 46. Look for green Debug components in the Flow application to see all the places that write to the debug console.

Figure 47 – AT&T M2X Graphing Sensor Data

43July 2017

Getting Started Guide

THE IMPATIENT DEVELOPER’S GUIDE TO CREATING THE FLOW APPLICATION

The AT&T Flow application for this project already exists; you’ll use this existing application by copying it into your AT&T Flow workspace and modifying it to suit your account’s configuration and ISK hardware. Each AT&T account has unique account keys that the Flow application needs to operate, so you’ll be copying them into the existing application project so it can work within your AT&T IoT Services account.

FLOW & M2X CONFIGURATION

1. Open your default browser, then navigate to the following URL: https://flow. att.io/starter-kit-core/starter-kit-base/home. Click the Fork button to create a copy of the project for your exclusive use.

2. To save time, click the Deploy button to start the provisioning process. This will compile and activate your project in the Flow cloud environment. As you make changes to the project and re-deploy, subsequent deployments will take mere seconds.

3. The Flow application is configured to send measurement data to M2X, but the application doesn’t know how to do that for your M2X account. So, the next step is to add your M2X account details to the Flow application. You’ll be copying information between M2X and Flow, so you’ll want to have either two browser windows open or two tabs, one open to M2X and the other to Flow.

In M2X, click the ‘Hello, USERNAME’ button in the upper-right corner of the M2X console then select Account Settings. Copy the Master Key to the clipboard.

4. Switch to the Flow console window (or tab) and open your copy of the sample project. Select Data tab on the upper-left side of the IDE (1) then locate the Configuration FUNCTION element (2).

5. Double-click the Configuration function, the Flow IDE will open the code editing window. Paste M2X account Master Key you copied in step 2 into the code editor, replacing the ‘<get from M2X>’ text. Click the OK button to continue.

6. At the bottom of the Flow project’s IDE Window are two tabs: Info and Endpoints. Click the Endpoints tab to continue. A panel will open that lists the endpoints for the project. To finish the Flow application configuration, we’ll need the Base URL. Click the Copy button to the right of the Base URL to copy the value to the clipboard.

Note: The project’s endpoints are generated when the application is deployed into the AT&T cloud environment. If your Endpoints tab is empty, try deploying the application and trying again. To deploy the application, click the Deploy button in the upper-right corner of the Flow IDE.

7. Double-click the Configuration function again to open the Flow code editor. The Base URL copied in the previous step is used to update two variables in the project’s Configuration function. Using the Base URL as an example (for this step, you’ll want to use the value you copied from the Endpoints tab):

https://run-east.att.io/01020304050/998877665544332211/in/flow

The Configuration function’s base_hostname variable is the hostname portion of the Base URL (without the https://): run-east.att.io. The Configuration function’s base_uri value is everything after the host name (including the trailing forward slash): /01020304050/998877665544332211/in/flow.

44 AT&T

AT&T IoT Starter Kit

In the editor, look for the following code:

var base_hostname = “<get from Base URL>”; var base_uri = “<get from Base URL>”;

Update the code with the appropriate values from your Base URL as described above. So, for the example endpoint used above, you would modify the

var base_hostname = “run-east.att.io”;var base_uri = “/01020304050/998877665544332211/in/flow”;

Click the OK button when you have completed making the change.

8. With the configuration updated, a blue dot will appear on the upper-right corner of the Configuration function component. This indicates that the element’s configuration has changed but has not yet been deployed. Click the IDE’s Deploy button to deploy the application and resolve this issue.

EXECUTING THE M2X SETUP FLOW

The Flow application will automatically create a virtual device for the project in M2X; all you’ll have to do is kick off the process. This is a one-time operation that has to be performed. In the Flow IDE, click on the Virtual Device tab at the top of the IDE. Locate the project’s Initialize component in the lower-left corner of the canvas. Click once on the button to the left of the Initialize element.

There’s no direct indication in Flow whether the initialization succeeded or failed. Notice the green Debug components in the flow application; they’re used to write content to the debug console. Click the Debug tab and Flow will open the Debug pane. Here you can see the message payload data passed to the Debug component. In this case, the initialization failed because the initialization process ran a second time and the virtual device already existed.

Verify the component has been created in the M2X environment by returning to your M2X window and clicking Devices. Your virtual device should appear in the list. If you expand it by clicking the + sign to its left, you will see the different M2X streams that have been created for it.

DEPLOYING THE PROJECT FIRMWARE TO THE DEVELOPMENT BOARDAt this point, you’re ready to deploy the data collection app to the development board. The NXP FRDM-K64F SBC runs the ARM mBed operating system. ARM provides operating system updates and and platform development tools. Developers code applications for the board using a web browser (e.g., Firefox, Chrome, or Explorer) and removes the need to install tools on an individual’s PC. We’ll be using some of these tools in this section. Be sure to setup an account on the ARM mbed web site before continuing; you can find account setup instructions at ‘ARM mbed.org Account.’

Hardware Setup

1. Mount the cellular shield to the development board using the instructions provided in ‘Assembling the Starter Kit’ then connect the antennas to the cellular shield.

2. The cellular shield requires 5V power supplied by the included power adapter. It is not recommended to use a desktop or laptop USB port as a power source due to the limited current delivered by most USB ports. Plug a micro USB cable into the 5V USB shield power (X5) on the Cellular shield and connect the other end of the cable to the provided power supply. The green LED on the cellular shield (LED1) and the yellow LED on the development board’s Ethernet port will illuminate.

45July 2017

Getting Started Guide

3. Plug a micro USB cable into the SDA USB (J26) port on the FRDM-K64F board. Connect the other end of the cable to a USB port on yourlaptop or desktop computer. Your computer should recognize thedevice as a standard USB drive and install the necessarycommunications software to work with it.

4. Verify the development board’s firmware is at version 0226 or higherby opening the DETAILS.TXT; the current firmware version is listed inthe file. If the firmware version shown is lower than 0226, update it tothe latest version using the instructions found at https://developer.mbed. org/handbook/Firmware-FRDM-K64F.

Note: Be sure to disconnect the cellular shield before attempting the development board firmware update.

Software Modification

Like what you did for the Flow application, you must copy the base firmware project in order to customize it for your AT&T IoT Services environment.

1. Open a new browser window then navigate to https://developer.mbed.org/teams/Demo-Software-for-AvnetATT-IoT-kit/code/AvnetATT_shape_hackathon/. On the page that appears, click the Import into Compiler button. The development environment will open start the import process.

2. During the import process, you will be prompted to update settings that control the import process; accept the default settings then click the Import button, optionally changing the project name during the process if you wish.

3. Before you can compile the software, you’ll have to change some constants defined within the application to match your project configuration. In the mbed IDE Program Workspace window, click the config_me.h file to open it in the editor. With the file open in the editor, look for the following code: // This is the server’s base URL name. Example “www.google.com”// Note that when you Fork a Flow, it will typically assign either// “run-east.att.io” or “run-west.att.io”, so be sure to check this.static const char * MY_SERVER_URL = “run-west.att.io”;

// These are Flow fields from the Endpoints tab:#define FLOW_BASE_URL “/1e464b19cdcde/774c88d68202/866949 23d5bf28a/in/flow”#define FLOW_INPUT_NAME “/climate”

// This identifier specifies with which Flow device you are communicating. // If you only have one device there then you can just leave this as is.// Once your Flow device has been initialized (Virtual Device Initialize clicked),// the Virtual Device will show up in M2X. This is its “DEVICE SERIAL” field #define FLOW_DEVICE_NAME “vstarterkit001”

To configure the application, you’re going to change the following values:

• MY_SERVER_URL• FLOW_BASE_URL• FLOW_DEVICE_NAME

46 AT&T

AT&T IoT Starter Kit

The values you use here are different than the ones you used earlier. The values for MY_SERVER_URL and FLOW_BASE_URL are for a Flow application endpoint, just like you worked with before, but they’re for a specific endpoint in the Flow application.

Switch back to the Flow IDE and click the Data tab on the top of the IDE window. Select the Climate GET component then click the Endpoints tab at the bottom of the window and click the Copy button next to the Base URL to copy the value to the clipboard.

In the mbed IDE, populate the MY_SERVER_URL constant in the code with the hostname from the URL you copied in the previous step. Populate the FLOW_ BASE_URL value in quotes with the remainder of the copied Base URL.

To determine the value for FLOW_DEVICE_NAME, open the M2X browser window and click on the device that the Flow application created earlier then copy the device ID.

Based on the example provided above, the configuration values should look something like the following, but using values from your project configuration:

static const char * MY_SERVER_URL = “run-east.att.io”;#define FLOW_BASE_URL “/123456789/112233445566778899/in/flow”#define FLOW_DEVICE_NAME “some_device_id”

In the mbed IDE, click the Save button along the top toolbar. Next, click the Compile button. After the source code compiles, the IDE will start to download the compiled binary. Keep track of the download file name (and location) as you’ll need the file later.4. Disconnect the development board from your computer, wait a few seconds, then reconnect. Once the development board boots and your computer recognizes it as a drive, drag the compiled binary you just downloaded onto the drive (the disk drive representing the development board). This will program the non-volatile flash memory on the development board with the updated application firmware. Programming should take about 10 seconds, during which time the board’s green LED will flash repeatedly.

5. Disconnect the development board from the computer and remove the 5V power from the cellular shield. Then reconnect the cables, connecting the 5V USB power cable to the power adapter first, followed by the SDA USB cable to your computer system.

At this point, the development board will boot and begin executing the data collection app you just installed on the device. If all goes well, data will be collected and uploaded to M2X through the Flow application.

Monitoring Activity

The User LED on the FRDM-K64F board should be RED when the wireless connection is first powered on. It will turn BLUE when it successfully connects to the AT&T network and then either green, magenta or turquoise, depending on the response from the Flow project implementation. The data being sent can be monitored through the terminal connection that was described in the previous section.

There’s not much else to see while the application runs. The device collects data from its sensors and uploads it to the AT&T IoT cloud. As developers, we all know that nothing ever works as expected the first time, so there’s probably the need to be able to see what’s happening on the development board. Unfortunately, the board doesn’t offer a video connection, so there’s no way

47July 2017

Getting Started Guide

to plugin in a monitor and watch the code at work. On the other hand, the application firmware writes to the console, so you can remotely monitor the console to view program output. Your desktop or laptop computer will communicate with the development board through its serial port. Windows, Macintosh and Linux computers are supported.

Windows users will have to install some additional software to get this working. To install the software, follow the instructions at https://developer.mbed.org/handbook/Windows-serial-configuration. After the serial drivers have been installed, determine which COM port is being used by opening the device manager and looking for the COM port information.

You will need to use a terminal application to monitor the output from the development board. The default terminal installed on your development system won’t work for this purpose, so follow the instructions at https://developer.mbed.org/handbook/Terminals to install the necessary software.

With everything installed and operating, you should be able to see the firmware application’s output in the terminal window. To verify messages from the board are arriving in Flow, open the Flow project, and then click the Debug tab at the bottom of the IDE window. The Flow application sends debug messages to this console from many parts of the application. Look for green Debug components in the application to see all the places that write to the debug console. Finally, when you switch to M2X, and click on the virtual device the Flow application created for you, you can view the collected data.

48 AT&T

AT&T IoT Starter Kit

FIRMWARE APPLICATION MODIFICATIONS

The sample application has been created for you, but that doesn’t mean you have to run it like it was written. In this section, you’ll learn some simple tweaks to change the application’s behavior.

The data collection application’s reporting frequency is configured to upload sensor measurements to AT&T’s Flow environment every 5 seconds. To adjust the update frequency, open the mbed IDE and update the application’s config_ me.h file.

Look for lines that say:

// This constant defines how often sensors are read and sent up to FLOW#define SENSOR_UPDATE_INTERVAL_MS 5000; //5 seconds

The value for SENSOR_UPDATE_INTERVAL_MS specifies the number of milliseconds between sensor readings. So, for example, a value of 1000 would instruct the application to read the sensors every 1 second. Change the value for SENSOR_UPDATE_INTERVAL_MS to a new value that’s appropriate for your needs. To read the sensors every minute, for example, you’d change the value to 60000. Make the appropriate change to this value, save your changes the compile and deploy the updated application to the development board.

You can also tweak which sensor values are collected. Look through the config_ me.h file for the following entries:

// Specify here how many sensor parameters you want reported to Flow.// You can use only the temperature and humidity from the shield HTS221// or you can add the reading of the FXO8700CQ motion sensor on the FRDM-K64F board

// or if you have a SiLabs PMOD plugged into the shield, you can add its// proximity sensor, UV light, visible ambient light and infrared ambient // light readings// If you run the Windows “Sensor Simulator” utility, 8 additional virtual// sensors can also be made available via USB.#define TEMP_HUMIDITY_ONLY 1#define TEMP_HUMIDITY_ACCELEROMETER 2#define TEMP_HUMIDITY_ACCELEROMETER_GPS 3

4#define TEMP_HUMIDITY_ACCELEROMETER_PMODSENSORS#define TEMP_HUMIDITY_ACCELEROMETER_PMODSENSORS_ VIRTUALSENSORS 5//modify this to change your selectionstatic int iSensorsToReport = TEMP_HUMIDITY_ACCELEROMETER;

The sensor measurements that are collected are controlled by the application’s iSensorsToReport constant. Modify the value assigned to the constant, using one of the defines listed in the example above, to change which sensors are read. Make the appropriate change to this value, save your changes the compile and deploy the updated application to the development board.