APPLICATION NOTE

AT07925: Connecting Wireless Networks to the Internet using the ioBridge Technology

Atmel ATmega256RFR2

Description

This application note exhibits techniques to connect IEEE® 802.15.4 wireless networks to the Internet. This example uses the Atmel® ATmega256RFR2 Xplained Pro demo boards as Wireless Edge Devices on a wireless sub-network. The Atmel® Low-Cost Ethernet-to-Wireless Gateway [1] serves as a bridge between the wireless sub-network and conventional Ethernet LAN infrastructure. ioBridge’s cloud services tie the system together with remote control applications on the World Wide Web. This document describes how to start quickly with the provided sample applications and how to modify them for a specific need.

Features

• Remote Control of XPRO demo boards using the Internet

• Sample firmware for ATmega256RFR2 XPRO Remote Nodes

• Sample firmware for Atmel Low-Cost Gateway Reference Board

• Sample ioBridge web application for control

• ATmega256RFR2-XPRO Wireless Edge Devices

Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

2

1 Introduction The provided example shows ioBridges’s embedded C library running on the ATmega256RFR2 passing messages from Wireless Edge Devices to ioBridge’s cloud service. The Low-Cost gateway reference design [1] is the bridge between the wireless sub-network and conventional Ethernet LAN.

This particular implementation uses the Atmel Lightweight Mesh as the wireless sub-network. The ATmega256RFR2 supports several IEEE 802.15.4 wireless network protocols including ZigBee® Pro, ZigBee Light Link, ZigBee HA, IEEE 802.15.4 MAC, and 6LoWPAN. This example exists in the user application layer and is not dependent on the lower layers of the wireless sub-network. In other words this solution can be ported to other IEEE 802.15.4 networks as needed.

The sub-network and basic application are derived from Atmel application note AT03755 Android demo application to control IEEE 802.15.4 devices [2]. For demonstration purposes, AT03755 implements a simple indicator LED and GPIO button detection using a local Wi-Fi connection to an Android Remote Control. In this application note the ioBridge technology extends the Remote Control domain to internet enabled devices; the Wireless Edge Devices can be monitored and controlled from anywhere on the web. In practical applications, Wireless Edge Devices can take various forms such as battery powered sensors, actuators, indicators, lights, thermostats, control panels and so forth. The firmware used on the ATmega256RFR2-XPRO Edge Device was not modified and is documented in AT03755 [2]. Details on modification to the Gateway Application firmware are detailed in this document.

Figure 1-1. Block Diagram

1.2 Features and Benefits of RealTime.io • Real-time, two-way connectivity to gateway and Wireless Edge Devices via ioBridge’s RealTime.io

Platform for the Internet-of-Things • Secure and encrypted communication links between cloud and gateway • Stable, tested, and patented embedded and cloud software by ioBridge

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

3

• Automatic tracking of dynamic IP addresses • Plug and play connectivity – no port forwarding or network configuration changes are required • RealTime.io Cloud handles 100k’s of gateways simultaneously lowering cost to support gateway

connectivity • Authenticated API access to the gateway via the RealTime.io Cloud • Mobile app modules for Android and iOS for the RealTime.io Cloud API • Out-of-the-box support for the ATmega256RFR2 Xplained Pro (end node)

2 Physical Setup The Atmel Low-Cost Gateway is a reference design. Documentation for this design is available from Atmel as the AT01030 [1] application note. This design features the ATmega256RFR2 SoC, which combines the AVR® CPU and a high-performance IEEE802.15.4 Radio into a monolithic IC. The Ethernet interface is implemented with a WizNet W5200 Embedded TCP/IP Controller. Additional features include serial data flash memory for field upgrades and secure EEPROM for IP address and credential storage.

Figure 2-1. Low-cost Gateway

2.2 Power the Gateway The Low-Cost gateway uses a Micro-B USB Dedicated Charge Port (DCP) for power. It can be powered by any USB host such as the USB ports on a Wi-Fi Access Port or common “wall-wart” phone charger. Regular, and power-only, Micro-B USB cables can be used. The maximum power consumed is far less than 500mA. When connected to power, the green Power Good indicator will be lit.

2.3 Programming the Gateway Gateway included with the demo kit may be pre-programmed. Try your gateway before attempting to program it. To program the Low-Cost Gateway you will need a JTAGICE3 or equivalent programmer. Unpack the software source code released with this app note. Use Atmel studio to launch LcGw_ATmega256rfr2.atsln solution. Use the tools|device Programmer utility to verify the programmer connection to the ATmega256RFR2 and the fuse settings. The fuses should be 0xC2, 0x9D, 0xFE.

In the View|Solution Explorer utility to find the file appEthernet.c. In this file you need to enter the ioBridge credentials.

#define REALTIME_SERIAL

#define REALTIME_KEY

These values can be obtained from your Atmel FAE, or ioBridge. Compile the project and load it into the ATmega256RFR2 on the Low-Cost Gateway.

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

4

2.4 Connect Gateway to Network The Atmel Low-cost Ethernet-to-Wireless Gateway requires a CAT5 Ethernet connection to a router which is connected to an Internet Service Provider. Once connected, the gateway will establish a secure communication link to the RealTime.io platform.

2.5 Connect Wireless End Nodes The Wireless edge devices are implemented using ATmega256RFR2 Xplained Pro boards (ordering code ATMEGA256RFR2-XPRO). The Xplained Pro boards are low-cost evaluation boards available from the Atmel web site. They include a button and LED indicator. Using this solution the LED and Button can be monitored and controlled remotely via a mobile app or API.

Figure 2-2. ATmega256RFR2 XPRO

To build the application, use the provided Atmel Studio solution (XplainedPro_ATmega256rfr2.atsln) or provided Makefile (Makefile_XplainedPro_ATmega256rfr2). Refer to the respective development environment documentation for the information on how to compile, program, and debug projects.

Note that each Edge Device image must have a unique value for the APP_ADDR parameter (see Section 3.2). The APP_ADDR is the network address. This parameter should always be set to a unique value for each device in the network. This parameter is defined in the config.h file. The solution also includes pre-compiled binary images for five devices.

Before programming the chip, make sure that AVR fuses are set to the correct values:

• Extended: 0xFE • High: 0x9D • Low: 0xC2

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

5

3 Cloud Setup Now that you have the Atmel Low-Cost Ethernet Gateway powered up and connected, you need to create a RealTime.io application that will demonstrate the features of the gateway by providing real-time control and monitoring of wireless end nodes connected to the gateway.

3.1 Create a RealTime.io User Account If you have never used ioBridge.com or RealTime.io in the past, you will need to set up a user account. Visit atmel.realtime.io/admin and click Sign Up.

3.2 Register a Device In order to get started, you need to register a device. This process will authenticate you as the owner of an Iota-device or client, and will give you the ability to create API Keys to access the device.

• Sign In to RealTime.io • Click Devices • Select Register Device • Enter the Serial Number of your Atmel Gateway and click Next • If the authentication process succeeds, enter an easy to remember label for your device, and click Finish

The registration process automatically creates an API Key that you can use to access this device from the RealTime.io web service. The API Key is found under the API Keys tab.

3.3 Create an Application An application builder and editor are built into RealTime.io. This allows you to create applications directly on the RealTime.io servers and share them with other users. We are going to use this to create a RealTime.io application from a template for the Iota Wi-Fi Evaluation Board.

• Click on Apps, then Create App • Select Template App and click Next • Select Atmel Low-cost Ethernet Gateway Demo and click Finish • Enter the API Key and click Save • Enter Serial Number and click Save

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

6

3.4 RealTime.io Application Manager The RealTime.io App Manager allows you to create, develop, and share apps. If you want to run the app on your smart phone, scan the QRCode and it will open in your phone’s web browser. The default app templates are responsive for smaller screens.

Figure 3-1. RealTime.io Application Manager

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

7

3.5 RealTime.io Application Editor The RealTime.io App Editor allows you to write and customize apps directly in the browser. RealTime.io Apps are written in HTML, JavaScript, and CSS, so you don’t have to learn any proprietary programming languages. The editor features code coloring, line numbering, and save notifications. The main application code is contained in the “index.html” file. Click Edit next to index.html in the App Manager to make modifications to the demo app.

Figure 3-2. RealTime.io Application Editor

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

8

4 Using the Demo Application In order to use the demo application you created, you need to open it in a web browser of your choice or on a mobile phone. We provided a QRCode that you can scan to easily open in a mobile device’s web browser. This demo application allows you to control the LEDs and monitor the state of the push button ATmega256RFR2 Xplained Pro boards. The demo app uses the RealTime.io API to control and monitor the wireless endpoints. Each wireless end node will be displayed on the demo app as they are connected. Press the push button on the ATmega256RFR2 Xplained Pro board and the app will change the state of the green button icon. Click on the light bulb icon in the app to control the LED on the ATmega256RFR2 Xplained Pro board.

Figure 4-1. Demo User Interface

4.2 Cloud API To extend the functionality of the demo app, you can send commands to an ioBridge-powered Atmel Low-cost Ethernet to Wireless Gateway via the RealTime.io API. This API may also be used to integrate gateway functionality in to backend systems, mobile apps, and desktop applications.

4.3 Device Stream Devices connected to RealTime.io are able to produce a real-time stream of data that the gateway receives from wireless end nodes and serial data input. The Device Stream API allows web browser and mobile applications to access device streams. As data from devices enters a RealTime.io server, it is redistributed to a “stream”. Streaming connections are established with an HTTP GET that includes an API Key. The API Key establishes the set of devices for which data will be present. This type of HTTP connection delivers the data asynchronously. As data is being received from devices, RealTime.io will immediately resend the message to an authorized stream. Each piece of data in a stream is wrapped in a JSON object to identify its origin.

Resource URL

http://api.realtime.io/v1/stream?apikey=[apikey]

Method HTTP GET

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

9

Required Parameters apikey

Authenticated token that represents one device or many devices

Optional Parameters callback=[callback]

Add a JavaScript callback function to the streaming response

script=true

Wraps the streaming response in HTML script tags

chunksize=[padding_size]

Adds the number of spaces specified by padding_size to the end of each streaming response. This will help with some browser implementations. By default the padding size is set to 4096 spaces.

encoding=[plain / base64]

Converts all data from device to base64 encoding, otherwise data will be plain. Note that some characters sent from a device can break the JSON object.

Response The initial response to a stream request using a valid API Key will include the callback function name or HTML script tags if specified. After that, additional JSON objects will be delivered as data is collected from the device. The data responses will also have callback or script tags if specified.

JSON Object 1 2 3 4 5 6 7 8 9 10

{ "serial": "[serial]", "channel": "[channel]", "status": "[connected / disconnected]", "source": "[source]", "timestamp": "[timestamp]", "ms": "[ms]", "encoding": "[encoding]", "payload": "[payload]" }

JSON Keys • [serial] The serial ID of the device from which the data original data came • [channel] The channel on which the device used to send the data • [status] Connected or Disconnected • [source] ‘remote’ if the data is from a device, ‘server’ if this is an update from the server • [timestamp] Epoch time in seconds of the message’s receipt by the server • [ms] Milliseconds after the timestamp that defines the exact sub-second of message’s receipt • [encoding] ‘plain’ or ‘base64’ • [payload] The actual data

cURL Example curl http://api.realtime.io/v1/stream?apikey=[apikey]

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

10

4.4 Sending Data to a Device Data can be sent to individual devices by using the Send command. The Send command requires the use of an API Key that has write permission. Sending data uses the HTTP POST method with the API Key in the header or as a parameter.

API Command: gateway/send Resource URL

http://api.realtime.io/v1/gateway/send

Optional Parameters callback=[callback]

Add a JavaScript callback function to the response (JSONP)

Method HTTP POST

Header X-APIKEY: [apikey]

Content Type application/json

Body { serial":"[serial]", channel":"[channel]", encoding":"[encoding]", payload":"[payload]" }

• [serial] Serial Number of the target device • [channel] Channel to which the data will be sent • [encoding] Set to ‘plain’ for messages that do not contain any special characters or ‘base64’ for data that

may contain special or non-displayable characters • [payload] Data to be sent to the device

cURL Example curl -H "X-APIKEY: [apikey]" -H "Content-Type: application/json" -X POST -d '{"serial":"[serial]","channel":"[channel]","encoding":"[encoding]","payload":"[payload]"}' http://api.realtime.io/v1/gateway/send

4.5 Requesting the IP Address of a Device If a device is connected to the RealTime.io cloud platform, its remote IP address can be retrieved by sending a request. An API Key with read permission and a serial number is required to request the IP Address.

API Command: gateway/request/ip Resource URL

http://api.realtime.io/v1/gateway/request/ip?apikey=[apikey]&serial=[serial]

Method HTTP GET

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

11

Required Parameters apikey

Authenticated token that represents one device or many devices with at least read permission

serial

Serial number of the target device

Optional Parameters callback=[callback]

Add a JavaScript callback function to the response (JSONP)

cURL Example Curl http://api.realtime.io/v1/gateway/request/ip?apikey=[apikey]&serial=[serial]

4.6 Requesting the Connection State of a Device Applications can use this API command to detect the connection state of a device. A device is either connected or disconnected to a RealTime.io server. An API Key with read permission and a serial number is required to request the connection state.

API Command: gateway/request/state Resource URL

http://api.realtime.io/v1/gateway/request/state?apikey=[apikey]&serial=[serial]

Method HTTP GET

Required Parameters apikey

Authenticated token that represents one device or many devices with at least read permission

serial

Serial Number of the target device

Optional Parameters callback=[callback]

Add a JavaScript callback function to the response (JSONP)

cURL Example curl http://api.realtime.io/v1/gateway/request/state?apikey=[apikey]&serial=[serial]

4.7 RealTime.io ioDP Library Preprocessor Directives RAM Size

#define IODP_RAM_SIZE 1500

Allocate the block of RAM in bytes out of which all the dynamic data will reside.

Using fewer sockets with smaller message sizes means a smaller block can be defined.

Calculate the minimum IODP_RAM_SIZE by using the following:

• Rx = RAM needed for individual IODP socket • Sx = Socket size in bytes of individual IODP socket

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

12

Acking Socket

Rx = 244 + 2 * Sx

Non-Acking Socket

Rx = 192 + 2 * Sx

Minimum RAM size

IODP_RAM_SIZE = R1 + R2 + …. + RN

MAX Sockets #define IODP_MAX_SOCKETS 2

Sets the maximum number of sockets that can be created simultaneously

Tick Second #define TICK_SECOND 1000

Public Prototypes Function: void ioDP_Init

void ioDP_Init(BOOL UseUDP)

• Summary Initializes ioDP • Description Initializes the ioDP engine and the connection type • Precondition None • Parameters UseUDP - TRUE for UDP connection, FALSE for TCP connections • Returns None • Remarks This function is called only once during the lifetime of the application. If the ioDP engine

needs to switch between connection types, this function will need to be called again.

Function: BYTE ioDP_CreateSocket BYTE ioDP_CreateSocket(WORD ReqID, BYTE *Serial, BYTE *uKey, BYTE *gKey, DWORD tServerIP, WORD SerPort, WORD BufferSize, BOOL Acking, BOOL UsePokes);

• Summary Creates an ioDP socket • Description An ioDP socket must be created before it can be used. This dynamically creates an ioDP

socket and allocates the associated memory. • Precondition ioDP_Init() must have been call previously • Parameters ReqID – This is a channel identifier. An ioDP client may make multiple connections to a

server IP:PORT, but each connection must use a unique identifier. 0xFFFF is reserved. – Serial 16-digit hexadecimal serial number of the client device – uKey 16-digit encryption key unique to the client device – gKey 16-digit encryption key for the server – tServerIP The ioBridge ioDP server IP address – SerPort The ioBridge ioDP server Port number – BufferSize The maximum message size. Must be even blocks of 12 bytes. Maximum of 336. – Acking TRUE for acknowledgment mode, FALSE for high-speed no-ack mode – UsePokes If set to TRUE, packets will automatically be sent to the server to maintain the

connection through the firewall. This setting is ignored if the connection type is TCP. • Returns The ioDP socket handle. If 0xFF is returned, then a socket could not be created

Function: void ioDP_DestroySocket void ioDP_DestroySocket(BYTE ToKill)

• Summary Destroys an ioDP socket

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

13

• Precondition ioDP_Init() must have been called previously and a socket must have been created to destroy it

• Parameters: – ToKill The handle of the socket to delete

• Returns None • Remarks Destroying an ioDP socket will release its associated RAM back into the ioDP RAM block.

This means another socket is free to use those resources now.

Function: void ioDP_Enable void ioDP_Disable(BYTE SocketNum)

• Summary Disables a previously enabled socket • Description This function is currently not support • Precondition ioDP_Init() must have been called previously and a socket must have been created • Parameters: SocketNum The ioDP socket handle • Returns None

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

14

5 References [1] AT01030: Low-cost Ethernet to Wireless Gateway with ATmega256RFR2.

[2] AT03755: Android demo application to control IEEE 802.15.4 devices.

[3] AVR2130: Lightweight Mesh Developer Guide.

[4] AVR2131: Lightweight Mesh Getting Started Guide.

[5] http://connect.iobridge.com/docs/realtime-io/atmel-low-cost-ethernet-to-wireless-gateway

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

15

6 Revision History Doc Rev. Date Comments

42285A 04/2014 Initial document release.

AT07925: Connecting Wireless Networks to the Internet using ioBridge Technology [APPLICATION NOTE] Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014

16

Atmel Corporation 1600 Technology Drive, San Jose, CA 95110 USA T: (+1)(408) 441.0311 F: (+1)(408) 436.4200 │ www.atmel.com © 2014 Atmel Corporation. / Rev.:Atmel-42285A-WIRELESS-ioBridge-Connecting-Wireless-Networks-ApplicationNote_042014. Atmel®, Atmel logo and combinations thereof, AVR®, Enabling Unlimited Possibilities®, and others are registered trademarks or trademarks of Atmel Corporation in U.S. and other countries. Other terms and product names may be trademarks of others. DISCLAIMER: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.

SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in connection with any applications where the failure of such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) without an Atmel officer's specific written consent. Safety-Critical Applications include, without limitation, life support devices and systems, equipment or systems for the operation of nuclear facilities and weapons systems. Atmel products are not designed nor intended for use in military or aerospace applications or environments unless specifically designated by Atmel as military-grade. Atmel products are not designed nor intended for use in automotive applications unless specifically designated by Atmel as automotive-grade.