AT&T IoT Starter Kit Quick Start Guide€¦ · AT&T IoT Starter Kit Quick Start Guide 1 AT&T IoT Starter Kit (1st Generation) LTE/LTE-M Getting Started Guide . Document revision 2.1

AT&T IoT Starter Kit Quick Start Guide 1

AT&T IoT Starter Kit (1st Generation) LTE/LTE-M Getting Started Guide Document revision 2.1 (Feb 11, 2018)

ABSTRACT

This Getting Started Guide provides step-by-step instructions for getting your AT&T IoT Starter Kit talking to the Cloud – specifically, the Flow and M2X services in AT&T’s IoT Platform.

The IoT Starter Kit consists of a hardware platform comprised of an NXP FRDM-K64F single-board computer (SBC) and an Avnet Arduino-compatible WNC Cellular modem shield mounted on top. The WNC modem sends/receives data via AT&T’s cellular LTE or LTE-M networks.

The provided software examples let you take measurements using various sensors and send the values to the AT&T M2X/Flow cloud servers.

This guide starts out with a brief introduction to the Internet of Things (IoT). Next the kit options and contents are described, along with the required items needed for the following exercises:

Exercise 1 – is about getting the board assembled and running code. Along the way, we’ll register the board and SIM card, download binary code to the board, use the serial port to talk with your computer, and use the online ARM mbed tools to write and build code.

Exercise 2 – uses the Cellular Shield to connect your FRDM-K64F board to the cloud. We begin by importing an AT&T Flow project, which quickly helps us config our cloud resources and communicate to the K64F.

This introduction to the IoT Starter Kit does not require any significant programming experience with microcontrollers or the cloud. Though, some knowledge of C/C++ would be helpful.

If you don’t have the Starter Kit hardware you can purchase one at https://marketplace.att.com. (A description of the supported kits can be found on page 5.)

WINDOWS 8/10 WARNING

The AT&T Starter Kits covered by this guide include the NXP Freedom microcontroller development board (FRDM-K64F). This board is supported by the ARM mbed software platform and tools.

Unfortunately, the Storage Services features found in Windows 8 and Windows 10 may corrupt the mbed PC interface port found on this board. (Mac and Linux users are not affected by this problem.)

ARM recommends that you either use Windows 7 or disable the Windows Storage Services feature while using this board. Once the firmware for the board and bootloader are updated to the latest version (v0243 or later), you should be able to use Windows 8 or 10 with the Storage Services feature enabled. See the following blog post from ARM for further details:

https://os.mbed.com/blog/entry/DAPLink-bootloader-update/

https://marketplace.att.com/



TABLE OF CONTENTS

Abstract ........................................................................................................................................... 1

Windows 8/10 Warning .............................................................................................................. 1

IoT Background ............................................................................................................................... 3

Hardware and Software Requirements .......................................................................................... 5

Starter Kits................................................................................................................................... 5

Other Requirements / Downloads .............................................................................................. 7

Related Tutorials (for further study): .......................................................................................... 7

Exercise 1 – Getting Started with the NXP Freedom Board (FRDM-K64F) ..................................... 8

Part I. Assemble & Register the IoT Starter Kit ........................................................................... 8

Part II. Program the NXP FRDM-K64F board............................................................................. 13

Part III. Establish Serial Connection to Your PC ........................................................................ 15

Part IV. Modify and Execute FRDM-K64F mbed application .................................................... 17

After concluding Exercise 1 You Have… .................................................................................... 20

Exercise 2 – Connecting to the Cloud ........................................................................................... 21

AT&T IoT Platform Tools – Flow & M2X ................................................................................... 21

Part I. Configuring the AT&T IoT Platform ................................................................................ 22

Part II. Programming the Device ............................................................................................... 29

Part III. Running the Example Program ..................................................................................... 33

Part IV. Digging Deeper into Flow and M2X ............................................................................. 36

Next Steps ..................................................................................................................................... 44

Extending Shield Card Capabilities with External Sensors ........................................................ 44

Suggested FRDM-K64F Software Modifications ....................................................................... 45

Avnet ARM mbed C++ Libraries and Example Programs .......................................................... 46

Other Tutorials and References ................................................................................................ 46


IOT BACKGROUND

We often think of IoT as a combination of three elements: Device, Connectivity, and Cloud.

With that in mind, the AT&T IoT Starter Kit provides you with a “Device” that can be used to experiment with IoT. The included SIM card lets you access AT&T’s LTE or LTE-M networks. And finally, AT&T’s IoT Platform makes it easy to get something running in the cloud quickly. And if you need to connect to other 3rd party cloud services, that support is available too, although not covered by this guide.

Let’s look briefly at each of the three components in the Internet of Things.

IOT DEVICE

For this guide, the IoT Starter Kit acts as the hardware IoT device for your system. The code (provided for you) running on the IoT Starter Kit’s microcontroller board reads the temperature, humidity, and accelerometer every 5-seconds and sends it over the AT&T cellular network via the Starter Kit’s Cellular Modem board.

The IoT Starter Kit includes the NXP Freedom microcontroller board (FRDM-K64F) which is based on the ARM Cortex-M4F CPU. This microcontroller is supported by ARM’s mbed toolset. The provided example software lets you take measurements using various sensors and send the values to cloud. Commands, in the form of JSON strings, are sent back to the IoT Starter Kit from the cloud and instruct the device how to control on-board components such as the LED.

The first exercise in this guide walks you through getting the K64F microcontroller up and running. In the second exercise, you’ll connect your kit to the cloud.


CONNECTIVITY

For connectivity, the IoT Starter Kits include a Cellular Modem board along with an IoT SIM card (Subscriber Identity Module). After registering your SIM card and plugging it into the Cellular Modem board, you can communicate over one of AT&T’s cellular networks.

Your data is transmitted across either the AT&T LTE network or the AT&T LTE-M IoT network depending upon which firmware is installed in the Cellular Modem board. In short, LTE provides faster speeds and connections while LTE-M offers lower power and extended range. You can learn more about LTE-M here. For updating the cellular shield, or changing between LTE and LTE-M, view the Firmware Upgrade guide here.

Each SIM card contains a unique ICCID serial number (Integrated Circuit Card Identifier). Before you can communicate over the cellular network, you will need to “provision” (i.e. register) your SIM card by logging into the AT&T IoT Marketplace and entering the ICCID number printed on your SIM. Once this is done, the AT&T network will be able to recognize your device. Step-by-step instructions for registering your SIM card are found in Exercise 1.

CLOUD

The cloud (i.e. Internet) provides almost limitless services to your application - whether you need data processing, communication, or to store data streaming from your device.

Within this guide we’ll explore two services found on the AT&T IoT Platform: M2x and Flow. M2X provides device registration in the AT&T cloud, as well as time-series storage of your data. Flow, based on Node-Red (running in NodeJS), is a graphical, cloud-side development environment. Flow makes it easy to get the cloud-side of your IoT experience up-and-running quickly.

Exercise 2 begins with configuring Flow and M2X. Then, it will help you get your Starter Kit connected and sending data to the cloud.

https://www.business.att.com/enterprise/Service/internet-of-things/networks/lte-m/

https://s3-us-west-2.amazonaws.com/starterkit-assets/LTE-M.Firmware.Upgrade.Guide.pdf


HARDWARE AND SOFTWARE REQUIREMENTS

STARTER KITS

This guide describes how to use the following kits. Each of these kits contains the same basic hardware with minor variations:

• AT&T IoT Starter Kit (LTE-M) (shown in the photo)

The AT&T LTE-M IoT Starter Kit includes the FRDM-K64F microcontroller board which lets you write programs that can read from sensors and send the data via the attached Avnet Cellular Shield. The Cellular Shield, which accepts an AT&T IoT micro-SIM, lets you send data across the AT&T LTE-M cellular network.

LTE-M is a variation on the 4G LTE used by most cellular phones which has been enhanced to better serve IoT applications. Click here to learn more about LTE-M.

• AT&T IoT Starter Kit Powered by AWS

The AWS (Amazon Web Services) version of the starter kit includes the same hardware found in the previous starter kit, but also includes a micro SD memory card which can be used with the associated connector found on the FRDM-K64F board. The micro SD card is a convenient place to store the certificate strings required when communicating with AWS.

Additionally, since this kit ships ready to transmit over the AT&T LTE network, two antennas have been provided, as this is required by 4G LTE communications.

Each of these kits contain the following hardware:

• NXP Freedom Microcontroller board (FRDM-K64F) • IoT Starter Kit Cellular Shield • IoT Starter Kit Cellular Shield Power Supply (2.4A A/C to 5V USB adaptor) • Two Micro USB 2.0 Cables • One (or two) antennas, depending upon which kit you purchased

https://marketplace.att.com/products/att-iot-starter-kit-lte-m


https://marketplace.att.com/products/att-iot-starter-kit-aws


NXP FREEDOM MICROCONTROLLER BOARD (FRDM-K64F)

The NXP FRDM-K64F SBC is the host development and operational platform (the controller). The elements used by the IoT Kit are as follows:

• MK64FN1M0VLL12 MCU (120 MHz, 1 MB flash memory, 256 KB RAM, USB) which is based on a Cortex M4 ARM processor core

• RGB LED

• The OpenSDAv2 debug circuit supporting the CMSIS-DAP Interface to allow programming and monitoring software

• Serial port interface

• I2C interface for communicating with off-board sensors

• UART interface for communicating with the WNC-Shield card

WNC-SHIELD CELLULAR BOARD

Avnet has produced an Arduino Shield with a Wistron NeWeb Corporation (WNC) M14A2A cellular module.

This module contains all necessary protocol stack functionality needed to establish and maintain a data connection in an LTE network.

The WNC cellular module is controlled/managed via AT commands exchanged using a serial port connection to the FRDM-K64F. This is referred by WNC as a Type III interface to allow support for the 3GPP defined AT commands plus proprietary AT commands.

This module can operate over LTE or LTE-M cellular networks depending upon which firmware it contains.

Refer to the AT&T IoT Starter Kit Firmware Update Guide for more information. Note: The WNC 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 IoT Starter Kit, be sure to check the power supply’s output specifications to ensure it provides at least 2.4A current. Without the correct input power, the modem will not initialize properly.



OTHER REQUIREMENTS / DOWNLOADS

The following hardware and software are required to complete the firmware upgrade process.

COMPUTER & INTERNET

Computer with either Windows 7/8/10, Mac, or Linux operating system

o Must have an available USB port

o Network adaptor (wired or wireless)

Internet connection

The following hands-on exercises require internet access

SOFTWARE DOWNLOADS

Later steps in this tutorial will describe how to install and use these files and programs.

All Users

Download: Getting Started with NXP FRDM-K64F binary

Windows Users only (Mac & Linux natively contain the required drivers and serial terminal)

Download: mbedWinSerial_16466.exe

The mbed serial port works by default on Mac and Linux, but Windows needs a driver.

Download: Your favorite serial terminal (e.g. RealTerm, Putty, Tera Term and Termite)

You can skip downloading a serial terminal program if you already have one installed. See the Windows Serial Configuration mbed page for more information.

RELATED TUTORIALS (FOR FURTHER STUDY):

• For further info about the FRDM-K64F development board see the FRDM-K64F mbed page

• ARM mbed Windows 8/10 blog post

• AT&T IoT Starter Kit Firmware Update Guide

https://s3-us-west-2.amazonaws.com/starterkit-assets/Getting_Started_with_NXP_FRDM-K64F.zip

https://os.mbed.com/media/downloads/drivers/mbedWinSerial_16466.exe

https://sourceforge.net/projects/realterm/

http://www.putty.org/

https://ttssh2.osdn.jp/index.html.en

https://www.compuphase.com/software_termite.htm

https://os.mbed.com/handbook/Windows-serial-configuration

https://developer.mbed.org/platforms/FRDM-K64F/




EXERCISE 1 – GETTING STARTED WITH THE NXP FREEDOM BOARD (FRDM-K64F)

The first exercise is aimed at getting your Freedom microcontroller board (FRDM-K64F) up and running. We will not use it to connect to the internet in this exercise, rather, that will be the goal of Exercise 2 – Connecting to the Cloud (page 21).

Exercise 1 is broken down into 4 different parts:

Part I. Assemble & Register the IoT Starter Kit

Part II. Program the NXP FRDM-K64F board

Part III. Establish Serial Connection to Your PC

Part IV. Modify and Execute FRDM-K64F mbed application

PART I. ASSEMBLE & REGISTER THE IOT STARTER KIT

Some assembly is required to connect the various boards and items from the kit. Here is a picture of the kit contents.

Note that the items pictured here applies to all IoT Starter Kits with the following exceptions: (1) The LTE-M kit only contains one antenna; (2) the AWS version also includes a microSD memory card in addition to what is pictured.


CONSTRUCT THE DEMO HARDWARE

Even though we will not use the Avnet Cellular Shield to communicate to the cloud in the first exercise, let’s go ahead and put all the hardware together so it will be ready when we need it.

1. Plug the Avnet Cellular Shield onto the Arduino connectors on the FRDM-K64F board.

2. Insert the micro-SIM card into the Cellular Shield.

Pop the supplied AT&T micro-SIM card from the plastic holder and plug it into the SIM socket (X3) on the Cellular Shield board. (Do not insert a Nano-SIM into the socket as it may get stuck and ruin the socket.)

Extracting and Inserting micro-SIM card

3. Write down the 20-digit ICCID number printed on the SIM card.

ICCID: _____________________________________________________________________

You will need this number later to provision your SIM card in an upcoming step.


4. Connect the antenna(s).

Connect an antenna to the "Primary" connector (X1) provided on the Cellular Shield. If you are using one of the LTE based kits, connect the second antenna to the "Diversity" (X2) connector.

5. The Cellular Shield requires 5V power supplied by the included AC/DC power adapter.

Do not use a laptop or PC USB port to power the Cellular Shield since it requires more power than most computers provide. Instead, connect the 5V USB power connector (X5) on the Cellular Shield to the provided AC/DC power supply using one of the micro-USB cables. LED1 on the Cellular Shield will illuminate green when powered.

Note that the other USB port on the Cellular Shield will not be used during this lab exercise. This port lets you connect it to a Windows PC to update the board’s firmware.

5V/DC USB Power Connector

Power LED

https://github.com/attiot/starterkit-tutorials/raw/master/images/cellular-shield-firmware-upgrade/firmware-01.png


6. Connect the NXP FRDM-K64F board to your computer.

Plug a micro-USB cable into the SDA USB (J26) port on the FRDM-K64F board. Then connect the other end of the cable to a USB port on your PC/laptop.

CAUTION - Windows 8/10 may corrupt the MBED USB drive interface. (For more details, see the ARM mbed blog.)

The kit should enumerate as a standard mbed USB drive. The board should appear as a new “drive” with the name “MBED” or “DAPLINK”. In the example below, our board shows up as DAPLINK and contains two files which describe the interface.



SETUP (I.E. PROVISION) YOUR SIM CARD

While we won’t use cellular communications, which is enabled by the SIM card, until the next exercise, let’s go ahead and get it registered ahead of time.

7. Create an AT&T account and provision (i.e. register) your SIM card.

Go to https://marketplace.att.com/activate to activate your SIM card. Sign in if you already have an account or go ahead and create one. This is where you will manage your SIM cards.

Follow the directions on the Marketplace website to authorize your SIM card. Note that you will need the 20-digit number from step 3.

8. Register your IoT Starter Kit.

To be notified of any firmware/software updates, register your kit at:

http://www.cloudconnectkits.org

Log into your account or create a new one. When asked for the Serial Kit Number, use the WNC Serial Number (S/N) as shown below:

https://marketplace.att.com/activate

http://www.cloudconnectkits.org/


PART II. PROGRAM THE NXP FRDM-K64F BOARD

STARTER BINARY PROGRAM

The microcontroller on the FRDM-K64F board requires software to do something. This part of our hands-on exercise familiarizes us with downloading software to the board. Throughout most of Exercise 1 we will be using a pre-compiled “binary” program; Part IV will show you how to build a binary program from source files.

9. FRDM-K64F Out-of-Box (OOB) software program.

The Freedom microcontroller ships from NXP with a software program already loaded into its internal Flash memory. If you just opened a new kit, it should have the be loaded with the "bubble level" demo that leverages the on-board accelerometer. When the board is flat, the RGB LED is turned off, and when the board is tilted, the red or blue LEDs gradually illuminate based on the degree of tilt on the X- and Y-axis.

If your board was not brand new from the box, this program may not be resident in Flash memory as any time a new program is written to the board it replaces the previous one. Don’t worry if the demo doesn’t run, we’ll replace it with one of our own in the next step.

10. Download the Exercise 1 binary program.

If you have not already downloaded the Getting Started with NXP FRDM-K64F binary go ahead and do so now. If the file downloads as a ZIP file, unzip it to extract the binary file.

https://s3-us-west-2.amazonaws.com/starterkit-assets/Getting_Started_with_NXP_FRDM-K64F.zip


WRITE THE BINARY PROGRAM TO THE NXP FRDM-K64F

Writing an MBED binary program to the board is a simple copy/paste and then hitting the reset button.

11. Verify the Starter Kit is connected to your computer and shows up as an mbed USB drive.

As mentioned in Step 6, the FRDM-K64F shows up on your PC as an USB drive named MBED or DAPLINK when plugged into the USB port.

12. Copy the binary (.bin) to the MBED (e.g MBED or DAPLINK) drive.

Using Drag-and-Drop or Copy-and-Paste, copy the program from wherever you downloaded it to the mbed drive. The "copy" should initiate the binary program being written into Flash memory on the FRDM-K64F target microcontroller.

13. Push the reset button on the FRDM-K64F board to run the new binary program.

Push the reset button to start the new program and observe its execution.

o You should see the LED blinking Green o Button 2 (SW2) turns the blinking on/off o Button 3 (SW3) changes the LED’s color

This program also communicates over the UART serial connection with your PC through the USB debug cable We’ll explore this next.


PART III. ESTABLISH SERIAL CONNECTION TO YOUR PC

To view information generated by the NXP Freedom microcontroller (FRDM-K64F) on our computer, we will use the serial port connection that exists over the USB debug cable. This connection requires four things (see the step-by-step instructions to follow):

o A serial hardware connection. In this case, the serial data will be sent across the USB cable that you already connected between the K64F board and your computer.

o Your computer must have the necessary serial driver. This is standard for Mac and Linux, but Windows users may need to install it.

o Your computer needs a serial terminal program.

o The serial connection must be configured with the correct parameters.

FOR WINDOWS, VERIFY SERIAL COM PORT (AND INSTALL DRIVER, IF NEEDED)

14. Write down Windows COM Port number. (Mac & Linux users can skip this step)

Windows computers randomly assign a communications (COM) port number the first time you connect a device. You can figure out which port number is used by Windows by running the Windows Device Manager.

a. Open the "Run" dialog by jointly pressing the Windows+R (+R) keys for "Run" b. Type devmgmt.msc and hit Enter c. Write down the COM port number for future reference: ___________

Note: If you don’t see the “mbed Serial Port”, try installing the Windows driver. 1. Download the ARM mbed Windows serial port driver. (If you didn’t download this earlier.) 2. Close all Explorer windows showing the MBED or DAPLINK drive. 3. Run the installer. This may take some time or display a few "unsigned driver" warnings.

If needed, you can refer to ARM mbed page for more information.

http://os.mbed.com/media/downloads/drivers/mbedWinSerial_16466.exe

https://os.mbed.com/handbook/Windows-serial-configuration


INSTALL A SERIAL TERMINAL PROGRAM (IF YOU DON’T HAVE ONE)

15. Verify you have a serial terminal program or install one.

Windows computers do not normally include a serial terminal application. You will need to download and install one on your computer. This tutorial uses RealTerm, but other favorites include Putty, Tera Term, and Termite.

Mac/Linux computers often come with serial terminal programs, although you might prefer a third-party application. (I personally use CoolTerm on my Mac.)

CONFIGURE SERIAL TERMINAL AND ENABLE THE CONNECTION

16. Configure the settings for your serial terminal application. These include:

a. Port number (Windows users, you figured out a couple of steps ago.) b. The remaining serial connection parameters are (9600:N:8:1).

17. Reset the K64F board and view serial terminal.

After connecting starting and connecting your terminal program to your board’s serial port, press the RESET button on the FRDM board and then…

… after pressing Reset the terminal should print out the following information. (Note that we pressed SW3, then SW2, to get this output from the board.)

https://sourceforge.net/projects/realterm/

http://www.putty.org/

https://ttssh2.osdn.jp/index.html.en

https://www.compuphase.com/software_termite.htm

https://www.macupdate.com/app/mac/31352/coolterm


PART IV. MODIFY AND EXECUTE FRDM-K64F MBED APPLICATION

In the first three parts of this exercise, we downloaded and ran a pre-compiled, binary application. This gave us the opportunity to explore the FRDM-K64F development board without having to write any code. In this last part of our first exercise, we will:

• Tweak the code used in the previous project

• Compile the new project

• Test our application

Therefore, at the completion of this exercise, you will have created your own software program using the online ARM mbed tools.

IMPORT AN ARM MBED PROJECT

18. Create or sign-in to your ARM mbed account.

Before you can work with the tools, you need to have a free ARM mbed developer account.

a) Go to: os.mbed.com

b) Click the “Log in/Sign up” button to either create and/or sign into your own account.

19. Import original mbed starter project.

Navigate to the project source for the program we downloaded earlier. https://os.mbed.com/teams/EmbeddedAdvantage/code/LED_and_GPIO_Interrupt_example_for_K64F/

and click the “Import into Compiler” button:

http://os.mbed.com/

https://os.mbed.com/teams/EmbeddedAdvantage/code/LED_and_GPIO_Interrupt_example_for_K64F/


20. Accept the Import Program dialog default settings.

You are welcome to change the name of the project, but otherwise, take the default settings and click the Import button.

After clicking the Import button, the development environment opens and the code for the FRDM-K64F board is imported. You should see the project added to your online mbed compiler page.

While this project looks big, with seven source files, most of these files are very short. We separated the configuration and handling code out for each of the components used in this program: LED’s, Buttons, and Serial ports.

21. Build the imported project by clicking on the “Compile” button in the toolbar.

We recommend that you build the project once before making any edits. This assures us that the project imported correctly.


MODIFY, BUILD AND RUN AN ARM MBED PROJECT

While there are changes we could make to any of the files, we suggested making two simple changes to main.cpp, just so that you can see the evidence of your work in the final program.

22. Open “main.cpp”.

Click on main.cpp in the “Program Workspace” pane and you should see the file open into the right pane.

23. Here’s a look at main.cpp and the two suggested edits.

We recommend that you change the color of the first LED event as well as the first string the program sends to the PC. This should help you verify that you are running the program modified and built by you.

Also notice that this program calls the function myLeds_setLedColor() from the myLeds.cpp file. Main also references two global variables from the myLeds, as well. Conversely, the “buttons” work in-the-background, so main() only calls a function to initialize them.


24. Compile the project.

When you are done editing main.cpp, compile the program. Do this by clicking the Compile button in the toolbar.

25. Debug and re-compile as necessary until the program builds without error and the binary is downloaded to your computer.

Once the program compiles without error, the online mbed compiler will automatically download the binary executable to your computer.

26. Copy the binary to your FRDM-K64F board and verify that it runs correctly.

If you cannot remember how to complete these steps, please refer to steps 12 – 17.

AFTER CONCLUDING EXERCISE 1 YOU HAVE…

• Created and/or signed into three accounts:

o AT&T Marketplace – and registered your SIM card o Avnet Cloudkits.org o ARM mbed Developers Account

• Assembled your IoT Starter Kit

• Written a binary program to the NXP FRDM-K64F board by copying a .bin file to the board using your systems file manger (e.g. Windows Explorer, Mac Finder)

• Configured your computer to view status information coming from a program running on the FRDM-K64F development board

• Imported, build, and executed a source program using ARM’s online mbed tools


EXERCISE 2 – CONNECTING TO THE CLOUD

After learning how to use the FRDM-K64F microcontroller board throughout Exercise 1, it’s time to use the Avnet Cellular Shield (plug-on board) to access the cloud over AT&T’s LTE or LTE-M network.

On the device side, our new mbed project will utilize software libraries that will send communication requests via the serial port from the FRDM-K64F to the Cellular Shield. The Cellular modem on the shield will then transmit these over AT&T’s cellular network.

On the cloud side, the AT&T IoT Platform will receive the data coming from your device and store it to M2X servers. Finally, you can view the incoming data in the M2X dashboard.

This exercise requires us to set up both the Cloud and Device such that they can talk together. We will begin by configuring the AT&T cloud services, then we will turn our attention back to programming the FRDM-K64F.

Configure: (1) AT&T Flow / M2x then (2) FRDM-K64F

We configure them in this order because our FRDM-K64F program will need the cloud endpoints (i.e. Internet addresses – or you can think of them as ‘input’ ports). After configuring the AT&T IoT Platform tools, we’ll then have the information needed to complete the K64F device programming.

Note that AT&T IoT Starter Kits, as well as the cellular network, can also talk with other popular cloud services such as AWS and Azure, but this exercise focuses on the AT&T platform. Please refer to additional tutorials on the AT&T Marketplace tutorials page for further support.

AT&T IOT PLATFORM TOOLS – FLOW & M2X

This lab exercise utilizes two tools from the AT&T IoT Platform called M2X and Flow.

M2X provides a variety of services, but the two we’ll concentrate on are:

• Registering devices and streams • Time-series data storage

Flow is a GUI-based IoT development tool based on Node Red (NodeJS). It allows for data input and output along with user defined rules. Data flows to be set up with drag-and-drop ease of use; data will flow through nodes from left to right, as seen when viewing a Flow.

In fact, Flow can even be used to set up and configure the M2X service, which is a trick we’ll utilize in the upcoming lab exercise.

To learn more about Flow, check out the their Getting Started tutorial at flow.att.com/start.

https://flow.att.com/start


PART I. CONFIGURING THE AT&T IOT PLATFORM

1. Let’s start by logging into the AT&T Flow service.

The IoT Platform tools utilize the same account you set up when registering your kit (and SIM card) with the AT&T Marketplace, therefore, you should not have to create a new account when working with the IoT Platform.

Log into flow.att.io

Note that Flow times out after a few minutes of inactivity. When this happens, simply click the Log In button to log back in.

DUPLICATE (FORK) AN EXISTING FLOW PROJECT.

As with Exercise 1, we will start our Cloud experience by copying a reference Flow design and modifying it. Since each Flow design is unique in terms of its endpoint addresses and account keys, we will edit these unique parameters as we work through the step-by-step instructions.

2. On the lower left side of the Flow IDE, click Resources > Projects Library.

3. Search for the “Avnet Starter Kit” project.

In the top middle, under Search Projects, enter Avnet Starter Kit.

4. Create your own copy of the Avnet Avnet Starter Kit project.

Click Avnet Starter Kit dev, then click the Fork button in the upper-right corner. This creates a Flow project for your exclusive use.

http://flow.att.io/


5. Change the name of the project to something unique.

Hover your curser to the right of the new name and click the pencil to change the name to something unique (e.g., Paul’s Starter Kit Dev). Then click the Fork button on the dialog.

Your Flow project will looking something like this when it opens. This is a fairly involved project with many nodes. We’ll examine a number of them as we go through these steps. Again, if you’re new to Flow, you may want to check out their starter tutorial.

6. Once the project is Forked (i.e. copied), click the “Deploy” button.

This compiles and activates your project. Basically, you’ve just deployed a server-based application. This step can take a couple of minutes the first time. Subsequent deploy actions will be quicker.

When the Flow project is built and deployed, we now have the endpoint information needed to complete our device software program, but before we do that, we still need to finish configuring our cloud-side tools – specifically, we need to set up M2X and connect it to our Flow project.

https://flow.att.com/start


LOG INTO M2X AND CONNECT IT TO YOUR FLOW PROJECT

M2X provides a convenient way to register our devices and data streams on the AT&T IoT Platform. In our case, the Starter Kit will be our “device” and we’ll have a data stream for each datum we plan to send to the cloud, for example “temperature” and “humidity”.

As we stated earlier, we can use Flow to create the necessary M2X devices and streams, but we will need to look up our M2X credentials and plug them into Flow.

7. Open up M2X in a separate browser window.

Navigate to m2x.att.com or access it from within your AT&T IoT Marketplace Account.

At this point, it’s easier t to have two browser windows open (one for M2X and one for Flow) to make it easier to copy-and-paste the M2X master key into the Flow Configuration.

8. Once logged into M2X, copy the Master Key from your account settings to the clipboard.

The Master Key provides the credentials needed to interact with your M2X account. Copy it to the clipboard by going to your account settings:

In M2X, click the Manage button on the top right and select Account Settings:

Then, highlight the Master Key and copy it to the clipboard.

https://m2x.att.com/


9. Return to Flow and paste your Master Key into the “Configuration” function.

In Flow, navigate to the Data tab and find the Configuration function.

Double-click the Configuration function to view and edit its JavaScript. Paste your M2X key into the ‘M2X-Key’ field and click Done. (It may take a while for the script to update.)


CREATE M2X DEVICE AND DATA STREAMS USING FLOW

After adding the endpoint URL information to the configuration node, we can use Flow to establish our Starter Kit device and streams.

10. Copy the Base URL info from the Endpoints panel.

At the bottom of the canvas (where the Configuration node is located), click the Endpoints tab where the Base URL field is located. Click the Copy button.

In our example, the Base URL is:

http://runm-west.att.io /123abc456def789g/111222333444/034034fcd034555f8/in/flow

11. Re-Open the “Configuration” function and update the endpoint information.

The two fields we need to update include along with the values from our example:

base_hostname base_uri


12. Caution – go back and double-check that your copy/paste was done correctly!

The number one cause for errors in this lab is due, oddly enough, to copy and paste errors. It’s worth taking an extra minute to make sure you’ve done the previous step correctly.

(Hint: Mine failed the first time because I missed including the leading “/” for base_uri.)

13. Re-deploy your modified Flow.

With the configuration updated, a blue dot appears on your function graphic. This indicates it has changed but not yet deployed. Click the Deploy button to resolve this.

14. Create the M2X device using Flow.

Our Flow project can automatically create a Virtual Device in M2X for you. You only need to do this step once, as once the device is created, it should continue to exist (as long as you don’t manually delete it from M2X).

a) In Flow, go to the Virtual Device tab of the canvas and find the Initialize node towards the bottom-left.

b) Click once on the node’s toggle button (i.e. solid bubble to the left of the node) to kick-off the Initialize segment of your flow. This should create our M2X device with streams.

Note that the toggle button (i.e. trigger) found on some node types is just one of many ways to initiate a Flow segment to execute. Later, the data coming from our Starter Kit will be kick-off other portions of this Flow.


By the way, if you want to see the stream that were set up in M2X, as well as the Flow used to create them, look at the Registration tab.

15. Verify that your M2X device was created.

You can verify the component has been created in the M2X environment by returning to your M2X window and clicking Devices. Your virtual device should appear.

Expand the device by clicking the plus sign (+). This will show you the different M2X streams that have been created for it.

Note: If your Device does not appear, please double-check the values you modified in the Configuration node. These must be entered exactly correct.


PART II. PROGRAMMING THE DEVICE

To program the device for this exercise, you will import a starter cellular application project into your mbed environment and tweak a few data variables. We learned how to import a project at the end of the first exercise, although we will quickly take you through those steps again.

In this exercise, we will need to edit our imported program to use the Endpoint information correlated with our own, unique Flow.

IMPORT THE STARTER PROJECT

16. Log into your mbed.org account, if you don’t already have it open.

17. Import the starter cellular application project.

Navigate to: https://developer.mbed.org/teams/Avnet/code/Avnet_ATT_Cellular_IOT and click the Import into Compiler button.

When the Import dialog box you may change the name and accept the remaining defaults.

https://developer.mbed.org/teams/Avnet/code/Avnet_ATT_Cellular_IOT


18. Quickly review the starter cellular application.

This application reads data from a variety of sensors and sends the data to your Flow endpoint. Once the data has been sent, you can view it from the M2X dashboard.

Some of the files and libraries in this project support reading the sensors: sensors.cpp, xadow_gps.cpp, hts221_driver.cpp, FX0S8700CQ.

Others support access to the cellular network:

• wnc_control.cpp • cell_modem.cpp • MODSERIAL (since the K64F microcontroller talks to the cell modem over a serial port)

The hardware.h file defines a few hardware specific values, such as the LED colors.

Finally, the config_me.h file contains many required configuration parameters for our application. In fact, this is the file we must update to include our unique endpoint value.


MODIFY STARTER PROJECT TO REFLECT YOUR UNIQUE ENDPOINT

19. Update “config_me.h” with your specific information.

The following three defines need to be updated to match the specifications in your cloud projects.

Looking back to step 10, we see that the Endpoint provided by Flow was:

This will help us fill in the first two items – of course, you will need to substitute the values found for your unique Flow endpoint:

MY_SERVER_URL = base_hostname

FLOW_BASE_URL = base_uri

And the third item can be found as part of your M2X device settings. Go to the M2X device list and click on your device. This takes you to the device info screen shown here

Our value was set by the Flow program and will be “vstarterkit001” unless you changed its within M2X.

FLOW_DEVICE_NAME = vstarterkit001


While we don’t need to modify them, two other noteworthy fields in config_me.h include:

o FLOW_INPUT_NAME: The HTTP IN port in the Flow project where we send sensor data. In the default Flow project, this input is inside the Climate GET node port and is named “/climate”.

o SENSOR_UPDATE_INTERVAL_MS: The update period for sending sensor data to Flow. The default for this is 5 seconds.

20. After completing the config_me.h updates, save the file.

21. Caution – go back and check your work.

Make sure you have not introduced any copy/paste errors. Once again, this is the biggest reason the lab fails to work.

22. Finally, Compile your project.

Debug as necessary. The mbed compiler will download the binary proram once it has been successfully built. The file name downloaded to your computer is based on what you named your mbed project. If you left the default name when importing the starter project, you should find Avnet_ATT_Cellular_IOT.bin in your downloads folder.


PART III. RUNNING THE EXAMPLE PROGRAM

PREPARING THE FRDM-K64F

23. Write the new binary program to your FRDM-K64F board.

Using your computers file browser, write the new bin file to your K64F microcontroller. (Please refer to page 14 if you need a quick refresher on how to accomplish this.)

24. Verify your board is properly assembled and connected.

This will be the first time we use the Cellular Modem Shield, so let’s double-check we have it all set up correctly.

Notes:

• Make certain to power the cellular shield using the 5V 2.4A adaptor (A/C to USB) that came with your Starter Kit.

• If using Cellular Shield is using LTE firmware, you need to use both antennas. LTE-M only requires the Primary antenna to be connected.

25. Open the serial port terminal program and re-configure it with new settings.

The starter cellular project uses a different baud rate, so you will need to change the settings for your serial terminal:

o Baud = 115200 o Stop Bits = 1 o Parity = None o Data bits = 8 o Flow Control = none


RUNNING THE IOT FLOW AND M2X DEMO

The final step is running the IoT Flow/M2X programs and checking to see if everything works.

26. Verify the FRDM-K64F is plugged in and operating.

During operation, the user LED on the FRDM-K64F board should be:

o RED when the wireless connection is first powered on.

o It turns BLUE when it successfully connects to the AT&T network

o Then either green, magenta or turquoise, depending on the response from the Flow project implementation. (The value will change, for example, based on the acceleration values sent to the cloud.)

Hint: The data being sent can also be monitored through the serial terminal connection.

Note: A cloud connection takes longer to establish when the Cellular Shield was using LTE-M. We saw it take one to two minutes to make the initial connection. If it doesn’t connect in that time, try resetting the K64F board to restart the program.

Once again, watching the serial port feedback is very helpful during this step!

27. Observe the data sent from the AT&T IoT Starter Kit in Flow.

Flow/M2X Operation: To verify messages from the board are arriving in Flow, go to the Flow project and click the Debug tab at the bottom of the canvas.

Because the board is doing an HTTP GET, data currently enters the Flow design through the HTTP IN node. Incoming messages with sensor information should start appearing in the Debug tab.

As shown above, there are debug messages being printed from both the input and output debug ports. You can enable/disable these debug messages by clicking the solid part to the right of the port.


28. You can also see the data in the M2X dashboard.

This is one of the benefits of the time-series data storage feature of M2X as well as its associated dashboard.

The above chart shows the incoming X-axis acceleration data. You can see charts for the other streams by selecting them on the left. You can also click on “Values Log” if you just want to see a simple data listing.


PART IV. DIGGING DEEPER INTO FLOW AND M2X

USING FLOW TO PROCESS DATA

29. Examine how you can process data with Flow.

When sensor data is sent from the Cellular Shield to Flow, it enters via the HTTP-IN (“Climate GET”) node. From here, it traverses a series of nodes until it’s posed to M2X in the “M2X POST” node. The node just before the data is posted builds the message for M2X, ash shown highlighted below.

Double-click the “M2X lead-in” node to open it; then scroll to the bottom of the JavaScript content. This is the function that composes the POST message for M2X. It does this by reformatting the sensor values extracted from the incoming payload.

Note: If attempting to POST to an M2X stream that does not exist, an error is generated.


M2X DASHBOARDS

Within M2X you can select the Dashboards to create widgets to view multiple streams, even across different devices.

For example, it is possible to draw a graph of Temperature vs. Humidity by clicking Dashboards at the top of the screen and selecting different dashboards using customizable widgets that can be embedded elsewhere using the provided URL.


M2X TRIGGERS

Triggers can be created for M2X devices. Triggers can send callback notifications based upon changes to your device’s data streams.

In our IoT Kit project, click our Flow M2X initialization automatically created two triggers; one called Hot Temp and the other Cold Temp.

30. Examine the triggers that were created for you.

Viewing your device in M2x, select the Triggers tab:

Devices > Virtual Starter Kit > Overview >Triggers

Your display should look similar to that shown above. In our case, since our temperature data appeared to be closer to 90, rather than 20, we changed the conditions for the Hot Temp trigger. Let’s try that in the next step…


31. To edit “Hot Temp” trigger, click the edit pencil to the right of it.

Click the “pencil” icon to the right of Hot Temp, as circled in the preceding diagram.

We decided to change the threshold and reset condition values as mentioned in the previous step. We also removed the humidity condition (by clicking the red ‘X’ next to its condition). Finally, clicked the button to save our changes.

By the way, the Callback URL was already set when the original M2X trigger settings were configured by Flow. You can find the “trigger” endpoint used here in the list of Endpoints at the bottom of the Flow canvas.

In total fairness, we couldn’t get M2X to save our modifications. Rather, we deleted the “Hot Temp” condition and recreated it using the “Add Trigger” button. Not sure why we had to do this, but it was easy to recreate the trigger with our new values.


32. Once your trigger settings are configured, you can view a trigger event log from within the M2X device window.

If your board is running and the temperatures exceed the trigger thresholds, you can view a trigger event log right there in M2X.

33. What happens when you drive the temperature of your Starter Kit over the trigger threshold and the trigger occurs?

If you said the Callback URL is notified, you would be correct. Look back to the previous page and you can see the Callback URL field in the M2X trigger configuration.

In our case, the Callback URL was set when the original M2X initialization was created by Flow in step 14 (on page 27).

(Once again, you can find the “trigger” endpoint URL used in your configuration by looking for the trigger endpoint in the Endpoints tab at the bottom of the Flow canvas.)


34. Where does the callback notification show up? Open Flow to view the M2X Trigger callback input.

In Flow, if you click over to the Trigger tab you can see the Trigger (HTTP-IN) node which receives the callback notification. The logic following the input decides how to update the Starter Kit LED based upon the incoming triggers.

By clicking the button highlighted to the right of the trigger command request debug node, trigger messages will begin showing up in the Debug log at the bottom of the Flow canvas.

35. Start the IoT Starter Kit running again, if it was stopped and view the Flow debug log.

Looking at the log below, you can see the effect of the preceding changes. (By the way, a hair dryer came in handy to quickly reach these warmer temperatures.)

From the log, we can see that HTTP trigger commands are being created, but if you closely observe your K64F board, you will notice they are not being received and acted upon.

Why is that?


UNSOLICITED DATA

The current starter kit project that we imported does not support unsolicited messages, which is why the M2X trigger posts are not received. There are many reasons for this, for example, the security risk of allowing anyone to send a message to your device at any time (i.e. unsolicited).

That said, the LED color is being controlled by the Cloud, so does that info get to my Kit?

Well, the trick is that this incoming data wasn’t “unsolicited”. Rather, the data is sent from the Cloud as part of a return request solicited (i.e. expected) by the device’s program.

36. How does the Cloud (i.e. AT&T Flow) send decide which data to send to the device? Open the “Set Board Function” and look.

You can see what determines the LED color command sent to the FRDM-K64F by examining the “Set Board LED” node in Flow. (This node is just to the left of the “LED Debug” node highlighted above.)

Notice that this JavaScript function node calculates the color to send back to the board based on the received temperature and accelerometer values.

This is then packaged into the return message payload which is sent back in the HTTP RESPONSE node.


37. Open main.cpp in the IoT mbed project.

Looking at the other side of the IoT transfer, let’s look at how the device uses the incoming “color” information returned by Flow.

Scan down through main.cpp until you find the parse_JSON() function. Here you can see they use a switch statement to determine how to act upon the color data sent from the Cloud.

Of course, the Flow program could be edited to send back trigger information in a similar way. There is obviously more than one way to achieve the same effect. Hopefully we’ve given you some things to consider for your own designs.


NEXT STEPS

EXTENDING SHIELD CARD CAPABILITIES WITH EXTERNAL SENSORS

By default, the mbed project sends the following sensor data to Flow:

• Temperature and humidity from the HTS221 device on the Cellular shield

• Accelerometer X, Y and Z-axis readings from the FXOS8700CQ motion sensor located on the FRDM-K64F board

In addition to the above, other sensor inputs can be provided via the PMOD connector on the WNC Shield.

Here are two examples of I2C sensors:

• Silicon Labs PMOD Sensor Auxiliary Board

This is a sensor module that measures proximity, UV light, ambient visible and infrared light using a Si1145 sensor.

• Seeed Studio Xadow v2 GPS module

This GPS module has a built-in chip antenna and provides standard GPS outputs such as latitude, longitude, altitude and speed.

Please visit www.cloudconnectkits.org or marketplace.att.com/tutorials for more information and implementation details.

https://marketplace.att.com/tutorials


SUGGESTED FRDM-K64F SOFTWARE MODIFICATIONS

Here are two suggested modifications you can make to the FRDM-K64F program. Make sure that after any source modifications, you recompile the IoT Starter Kit software and reprogram the board. After the IoT Kit is powered up and connected to Flow, you can view the new data under the Debug tab (shown in the image below).

REPORTING FREQUENCY

By default, the FRDM-K64F board uploads sensor measurements to AT&T’s Flow environment every 5 seconds. You can adjust how often you want to do this by editing the SENSOR_UPDAT_INTERVAL_MS value in the config_me.h header file.

WHICH ON-BOARD SENSORS TO REPORT?

The sensor measurements that are reported can be changed by altering the iSensorsToReport parameter.

The default assignment is: iSensorsToReport = TEMP_HUMIDITY_ACCELEROMETER;

With this setting, the board reports readings from the HTS221 temperature & humidity sensor and 3-axis accelerometer readings from the FXOS8700CQ motion sensor. These values are sent to the Flow “HTTP IN /climate” node with field names: temp, humidity, accelX, accelY, and accelZ.

• Temperature is in degrees Fahrenheit. • Humidity is a percentage (%). • Acceleration is measured in G’s (the gravitational constant) and is useful if you want to

know the stationary position of the board with regards to gravity or its acceleration when in motion.

As document about adding External Sensors to the kit can be found at www.cloudconnectkits.org. It discussed how the assignment of the iSensorsToReport variable can be changed to report a different set of sensor readings to Flow.


AVNET ARM MBED C++ LIBRARIES AND EXAMPLE PROGRAMS

All v5 mbed compatible libraries and examples may be found here:

https://developer.mbed.org/teams/Avnet/

Includes the following:

• WncInterface

o mbed C++ class that can be used in place of mbed’s v5 EthInterface class

• WncControllerLibrary

o A C++ class that directly controls the 14A2A. Hint, study it to learn AT cmds WncControllerK64F

o A C++ class that controls the 14A2A from the K64F Freedom Board

• The original Out of the Box demo with the old controller method can also now be found here

• Several other examples, such as: HTTPClient, M2X, Bluemix, MQTT and TLS Client

Note, only use code pulled from release labels of these libraries. The tip revisions are not always guaranteed to work!

OTHER TUTORIALS AND REFERENCES

• For further info about the FRDM-K64F development board see the FRDM-K64F mbed page

• ARM mbed Windows 8/10 blog post

• AT&T IoT Starter Kit Firmware Update Guide

• You can learn more about LTE-M here

• Find other tutorials on the support page or in the Documents tab of your product in the AT&T IoT Marketplace

• Explore AT&T IoT data plans here

• Check out the AT&T IoT Starter Kit (2nd generation) kit in the AT&T Marketplace. With the 2nd generation kit, the applications processor and the LTE cellular modem are integrated into a single, small-footprint module. This is not only a handy kit for learning IoT, but being pre-certified, it’s also an easy way to add cellular connections to your end-products.

• To download additional information on the kit, including board schematics, firmware updates, etc., visit: avnet.me/avnetattcellulariotkit

• Check out the support forum:

http://cloudconnectkits.org/forum/topic/att-cellular-iot-starter-kit

https://developer.mbed.org/teams/Avnet/

https://developer.mbed.org/platforms/FRDM-K64F/




https://marketplace.att.com/tutorials

https://marketplace.att.com/products?tags=connectivity&tags=sim

https://marketplace.att.com/products/att-iot-starter-kit-2nd-gen

http://cloudconnectkits.org/forum/topic/att-cellular-iot-starter-kit