gs2k provisioning adk application note - telit · gs2k provisioning adk application note...

GS2K Provisioning ADK Application Note

80560NT11585A Rev. 1.0 – 2016-06-19


80560NT11585A Rev. 1.0 of 48 2016-06-19

NOTICE

COPYRIGHTS

COMPUTER SOFTWARE COPYRIGHTS

SPECIFICATIONS ARE SUBJECT TO CHANGE WITHOUT NOTICE

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

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

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

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


80560NT11585A Rev. 1.0 of 48 2016-06-19

USAGE AND DISCLOSURE RESTRICTIONS

I. License Agreements

II. Copyrighted Materials

III. High Risk Materials

IV. Trademarks

V. Third Party Rights

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

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

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

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

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

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

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


80560NT11585A Rev. 1.0 of 48 2016-06-19

APPLICABILITY TABLE

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

PRODUCT

GS 2000 based modules

SW Version

5.1.7/5.2.1 onwards


80560NT11585A Rev. 1.0 of 48 2016-06-19

Revision History

Version Date Remarks

1.0 June, 2016 Initial release


80560NT11585A Rev. 1.0 of 48 2016-06-19

Table of Contents

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

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

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

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

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

CHAPTER 1. INTRODUCTION ............................................................................................... 9

1.1 SCOPE ........................................................................................................................... 9 1.2 OVERVIEW ..................................................................................................................... 9 1.3 TERMINOLOGY ............................................................................................................. 10 1.4 STANDARDS AND CONCEPTS ........................................................................................ 11

CHAPTER 2. FEATURES AND CAPABILITIES .................................................................. 12

CHAPTER 3. THEORY OF OPERATION ............................................................................. 13

CHAPTER 4. ARCHITECTURE ............................................................................................ 14

4.1 GS NODE CONFIGURATIONS ........................................................................................ 16 4.2 PROVISIONING PROCEDURE ......................................................................................... 16

4.2.1 Get Information about GS node ...................................................................... 17 4.2.2 Set New Configuration ..................................................................................... 20 4.2.3 Apply New Configurations on GS Node .......................................................... 23

4.3 COMPONENTS .............................................................................................................. 25 4.3.1 Hardware ......................................................................................................... 25 4.3.2 Software ........................................................................................................... 25

4.4 TASKS ......................................................................................................................... 26 CHAPTER 5. EMBEDDED APPLICATION EXECUTION SEQUENCE ............................... 28

5.1 BOOT UP AND INITIALIZATIONS ...................................................................................... 28 5.2 PROVISIONING INITIATION ............................................................................................. 32

CHAPTER 6. NATIVE APPLICATION AND EXECUTION SEQUENCE ............................. 42


80560NT11585A Rev. 1.0 of 48 2016-06-19

List of Figures

Figure 1: Provisioning ADK in Limited AP Mode ..................................................................... 14

Figure 2: Provisioning ADK in Station Mode ........................................................................... 15

Figure 3: Mobile device gets information from GS node ......................................................... 17

Figure 4: Mobile device sets new configuration in GS node ................................................... 20

Figure 5: Mobile device applies new configurations on GS node ........................................... 23

Figure 6: Provisioning ADK Task Architecture ........................................................................ 26

Figure 7: Connection establishment between Mobile device and GS node ........................... 42

Figure 8: Network connection details ...................................................................................... 43

Figure 9: mDNS service discovery .......................................................................................... 43

Figure 10: Client settings ......................................................................................................... 44

Figure 11: Wireless network scan ........................................................................................... 44

Figure 12: List of wireless networks ........................................................................................ 45

Figure 13: Passphrase ............................................................................................................. 45

Figure 14: Network settings ..................................................................................................... 46

Figure 15: Save configurations ................................................................................................ 46

Figure 16: Apply new settings.................................................................................................. 47

Figure 17: Success notification ................................................................................................ 47


80560NT11585A Rev. 1.0 of 48 2016-06-19

List of Tables

Table 1: Glossary of Terms ..................................................................................................... 10

Table 2: Software Components ............................................................................................... 25


80560NT11585A Rev. 1.0 of 48 2016-06-19

Chapter 1. Introduction

1.1 SCOPE

This document provides an overview about the GainSpan GS2000® based Provisioning Application Development Kit (ADK) and describes the software and hardware architecture, network topology, functional features, API’s, Application execution sequence of the Embedded and Mobile applications.

This document briefs the architecture and provides with necessary information required to understand the Provisioning ADK. This document assumes that the reader is generally familiar with GainSpan products, Internet Protocol (IP) networks and the operation of 802.11 wireless devices.

1.2 OVERVIEW

GainSpan Provisioning ADK is a development platform enabling customers to build products those can be easily provisioned easily by GainSpan’s proprietary provisioning method.

NOTE:

GainSpan SDK is mandatory for any development on Provisioning ADK.


80560NT11585A Rev. 1.0 of 48 2016-06-19

1.3 TERMINOLOGY

Following table lists the different terminologies used in this document.

Term Explanation

AP Access Point

API Application Programmer’s Interface

DIN Data Input

DOUT Data Output

IP Internet Protocol

SPI Serial Peripheral Interface

UART Universal Asynchronous Receiver/Transmitter

TCP Transmission Control Protocol

UDP User Datagram Protocol

HTTP Hypertext Transfer Protocol

Table 1: Glossary of Terms

NOTE:

The term ‘Task’ also means thread in this document.


80560NT11585A Rev. 1.0 of 48 2016-06-19

1.4 STANDARDS AND CONCEPTS

Standards

Generic

• HTTP

• mDNS

•

ADK Specific

• Provisioning

Concepts

Provisioning is used to connect a device to an infrastructure (i.e. Access Point) network. This feature allows users to scan, choose, and connect to a Wi-Fi Access Point using a web browser on PC or using a native application on Android or iOS device.


80560NT11585A Rev. 1.0 of 48 2016-06-19

Chapter 2. Features and Capabilities

This section provides the features and capabilities of GainSpan’s Provisioning ADK:

Features

• Multicast Domain Name System

• Provisioning

Capabilities

• Limited-AP mode provisioning

• Station mode provisioning


80560NT11585A Rev. 1.0 of 48 2016-06-19

Chapter 3. Theory of Operation

Provisioning ADK is used to connect GS node to an infrastructure (i.e. Access Point) network. Upon boot up, GS node comes up as Limited-AP and starts its webserver. Mobile device or PC associates to the GS node and connects to the webserver. User uses the Provisioning application or web browser and configures Wireless LAN settings and Network settings for GS node. After receiving all the configuration information, GS node saves the data in its configuration file. After the system reset, GS node reads the configuration file and sets the configuration information in the next boot.


80560NT11585A Rev. 1.0 of 48 2016-06-19

Chapter 4. Architecture

GS node operates in two modes:

• Limited AP mode.

• Station mode.

Provisioning feature is enabled in both modes.

Limited AP Mode

Figure 1: Provisioning ADK in Limited AP Mode

In this mode, GS node acts as Limited AP and starts the webserver for provisioning. Mobile device or PC connects to GS node as Station, opens its web client, and communicates with webserver running on the GS node. User sets the required credentials (SSID, Passphrase, and so on) as per requirement. For example, user sets the webserver username and password in case of webserver settings, AP (Access Points) credentials such as Passphrase in case of client settings, and so on. After providing the required credentials, this information is sent as XML data to the webserver running on the GS node. GS node saves this information and uses the saved information in next boot.


80560NT11585A Rev. 1.0 of 48 2016-06-19

Station Mode

Figure 2: Provisioning ADK in Station Mode

In this mode, GS node acts as Station, connects to Access Point (AP), and starts the webserver for provisioning feature. Mobile device or PC connects to the AP (to which GS node is connected) as Station, opens its web client, and communicates with webserver running on GS node. User configures the required credentials (SSID, Passphrase, and so on) as per requirement. For example, user sets webserver username and password in case of webserver settings, AP credentials such as Passphrase in case of client settings, and so on. After providing required credentials, the information is sent as XML data to the webserver running on the GS node. GS node saves this information and uses the saved information in next boot.


80560NT11585A Rev. 1.0 of 48 2016-06-19

4.1 GS NODE CONFIGURATIONS

User is supported to configure the following GS node configurations:

1. Client Settings: It is divided into two sections - WLAN settings and IP settings.

WLAN Settings: User can configure SSI, CHANNEL, SERCURITY TYPE, WEP, PASSPHRASE, EAP TYPE, EAP USER NAME, and EAP PASSWORD

IP Settings: User can configure IP Type (DHCP/STATIC), IP Address, SUBNET MASK, GATE WAY, DNS ADDR Using these settings user can configure GS node’s station mode settings.

2. Limited AP Settings: Using there setting user can configure GS node’s Limited AP mode settings.

3. Operation Mode Selection: User can configure GS node’s operation mode which can either Station mode or Limited AP mode.

NOTE: Both modes can be used simultaneously when the Concurrent mode feature is enabled.

4. Administrator Settings: Web server settings such as authentication credentials (username and password of the webserver).

4.2 PROVISIONING PROCEDURE

Similar procedure is followed to save all settings provided in GS Node Configurations. Client setting is the most commonly used configuration setting among all the settings. Following are the three basic steps involved in Client settings configuration.

1. Get information about GS node.

2. Set new configuration.

3. Save and apply new configurations on GS node.


80560NT11585A Rev. 1.0 of 48 2016-06-19

4.2.1 Get Information about GS node

Figure 3: Mobile device gets information from GS node

Webserver is one of the important components in Provisioning ADK. As soon as GS node comes up either in Station mode or Limited AP, webserver is started automatically. The URIs in Webserver is registered with specific callback functions. If the webserver receives any HTTP request on a specific URI, the pre-registered callback function handles the request and provides the required HTTP response.

Following are the HTTP GET requests handled by the GS node Webserver. These requests are sent either by Native Provisioning application or gsprov.html page from the Web browser.


80560NT11585A Rev. 1.0 of 48 2016-06-19

1. Mobile device requests the GEPS version from GS node by sending GET request on URI “/gainspan/system/api/version”. GS node responds with following XML content.

<version>

1.0.0

</version>

2. Mobile device requests for GS node capabilities by sending the GET request on URI “/gainspan/system/capabilities”. GS node responds with following XML content.

<capabilities>

<bridge>false</bridge>

<concurrent_mode>false</concurrent_mode>

</capabilities>

3. Mobile device requests for GS node’s network information (including WLAN information) by sending the GET request on URI “/gainspan/system/config/network”. GS node responds with following XML content.

<network>

<mode>client</mode>

<ap_mode>user-ap</ap_mode>

<client>

<wireless>

<channel>10</channel>

<ssid>AE_Kiran01</ssid>

<security>wpa-personal</security>

<wepauth></wepauth>

<password>GainSpan01</password>

<eap_type></eap_type>

<eap_username></eap_username>

<eap_password></eap_password>

</wireless>

<ip>

<ip_type>dhcp</ip_type>

<ip_addr>192.168.1.3</ip_addr>

<subnetmask>255.255.255.0</subnetmask>

<gateway>192.168.1.1</gateway>

<dns_addr>192.168.1.1</dns_addr>

</ip>

</client>

<ap>

<wireless>


<beacon_interval>100</beacon_interval>

<ssid>GainSpanProv</ssid>

<security>none</security>

<password></password>

</wireless>

<ip>

<ip_addr>192.168.240.1</ip_addr>



<dhcp_server_enable>true</dhcp_server_enable>

<dhcp_start_addr>192.168.240.2</dhcp_start_addr>


80560NT11585A Rev. 1.0 of 48 2016-06-19

<dhcp_num_addrs>64</dhcp_num_addrs>

<dns_server_enable>true</dns_server_enable>

<dns_domain>config.gainspan</dns_domain>

</ip>

</ap>

<mac_addr>00:1d:c9:16:6e:b3</mac_addr>

<ip>

<ip_addr>192.168.1.3</ip_addr>

</ip>

<reg_domain>fcc</reg_domain>

</network>


80560NT11585A Rev. 1.0 of 48 2016-06-19

4.2.2 Set New Configuration

To set new configuration, Mobile device sends HTTP GET requests to GS node. Following figure shows the message exchange between mobile device and GS node while configuring the client settings.

Figure 4: Mobile device sets new configuration in GS node

When user selects Client setting on Provisioning application or webpage, the following HTTP GET request will be sent to GS node.


80560NT11585A Rev. 1.0 of 48 2016-06-19

1. Mobile device requests for firmware versions on GS node by sending GET request on URI “/gainspan/system/firmware/version”. GS node responds with following XML content.

Note: In case of Three- firmware model, information about three firmware’s along with chip information is sent. In case of Two-firmware model, information about two firmware’s along with chip information is sent.

<version>

<current>

<wlan>5.2.0.34</wlan>

<geps>5.2.0.17</geps>

<app>5.2.0.17</app>

</current>

<backup>

<wlan>0.0.0.0</wlan>

<geps>0.0.0.0</geps>

<app>0.0.0.0</app>

</backup>

<backup-1>

<wlan>0.0.0.0</wlan>

<geps>0.0.0.0</geps>

<app>0.0.0.0</app>

</backup-1>

<chip>gs2000</chip>

</version>

2. Mobile device requests for WPS capabilities of GS node by sending the GET request on URI “/gainspan/system/prov/wps”. GS node responds with following XML content.

<wps>

<enabled>false</enabled>

<mode>none</mode>

<pin></pin>

</wps>

3. User clicks on Client settings and the following options are displayed:

a. WPS Pin

b. WPS Push

c. Select from Existing network

d. Manual configuration.

The primary goal in this step is to configure the GS node for client settings using “Select from Existing network”. By selecting this option, Mobile device requests for available APs by sending HTTP GET request on URI “/gainspan/system/prov/ap_list” to GS node. GS node responds with following XML content.

<ap_list>

<ap>

<index>1</index>


80560NT11585A Rev. 1.0 of 48 2016-06-19

<ssid>D-Link_DIR-600M</ssid>

<rssi>54</rssi>

<nw_type>infra</nw_type>



</ap>

<ap>

*

*

<\ap>

*

*

<\ap_list>

4. User chooses an AP from the AP list. Upon selection of AP, user is prompted to enter required credentials. In case of WPA/WPA2 security, user needs to enter the Passphrase in the Password field. Once credentials are provided, Mobile device sends the credentials to GS node by sending a POST request as explained in the next section.


80560NT11585A Rev. 1.0 of 48 2016-06-19

4.2.3 Apply New Configurations on GS Node

Following messages are exchanged between Mobile device and GS node to save and apply the credentials provided by the User.

Figure 5: Mobile device applies new configurations on GS node

1. When user taps or clicks on the Save button, Mobile device sends the user configured client settings to GS node by sending POST request on URI “gainspan/system/config/network” with the following newly configured XML data.

<network>

<client>

<wireless>




80560NT11585A Rev. 1.0 of 48 2016-06-19



<wepauth></wepauth>

</wireless>

<ip>


</ip>

</client>

</network>

2. Upon receiving the POST request, GS node saves the user configured client setting sin its configuration file and responds the following XML data.

<status>ok</status>

3. When user taps or clicks on Apply button, Mobile device requests the GS node to apply the settings by sending a POST request on URI “gainspan/system/config/network” with the following XML data.

<network>

<mode>client</mode>

</network>

4. Upon receiving the POST request, GS node applies the saved configuration, sends the following XML data, and resets the system.

<status>ok</status>


80560NT11585A Rev. 1.0 of 48 2016-06-19

4.3 COMPONENTS

4.3.1 Hardware

All the GS2000 based modules support Provisioning ADK.

4.3.2 Software

Provisioning ADK uses the following software components.

Component Description

HTTP Server

This component is responsible for creating and HTTP server, and accepting connections from the clients. And also serving the requests from the HTTP client. This Server is responsible for serving different URI’s by executing the registered call back for each of the URI.

Table 2: Software Components


80560NT11585A Rev. 1.0 of 48 2016-06-19

4.4 TASKS

Following task diagram shows the major threads involved in Provisioning ADK project.

Figure 6: Provisioning ADK Task Architecture

1. AppMainCtx_ThreadEntry: This thread is used for handling major events. Two of the major system events are:

• Network Connection Manager (NCM) Start event - APP_EVENT_NW_START_NCM

• Network Connection Manager (NCM) Success event - APP_EVENT_NW_CONNECT_DONE

Network Connection Manager (NCM) Start event - APP_EVENT_NW_START_NCM:

On reception of this event, GS node establishes the L2 connection either in Limited AP mode or Station Mode, starts the L3 connection for getting IP address by starting DHCP client in case of Station mode or DHCP Server in case of Limited AP mode.

Network Connection Manager (NCM) Success event - APP_EVENT_NW_CONNECT_DONE:

This event is generated by NCM on successful establishment of L2 and L3 connections and it starts HTTP Server threads.


80560NT11585A Rev. 1.0 of 48 2016-06-19

2. App_HttpdStart:

This is a function that creates an HTTPD thread “Httpd_Server” in GEPS. The priority of this thread is 16. On successful creation of this thread, different callbacks are registered for handling different requests with unique URIs. When HTTP server receives request from the HTTP client on specific URI, it calls the registered callback.

For example, GS node’s webserver uses a callback named “config_network_cb” registered with URI “/gainspan/system/config“to handle configuration related events. This callback is registered for both HTTP POST and GET request.

HTTP server generates the following events on reception of any HTTP GET or POST requests:

• TM_HTTPD_EVENT_BODY_RECV

• TM_HTTPD_EVENT_SEND_READY

• TM_HTTPD_EVENT_CON_CLOSE

3. config_network_cb:

This call back handles all the events generated by GET or POST requests. “/gainspan/system/config/” is the base URI and when any URI matches this string HTTP server calls “config_network_cb”. Following are different SUB URI’s handled by different functions.

No SUB URI ON HTTP POST REQUEST ON HTTP GET REQUEST

1 BASE-URI/network GsnHttpdApiConfig_SetValuesNetwork GsnHttpdApiConfig_GetValuesNetwork

2 BASE-URI/httpd GsnHttpdApiConfig_SetValuesHttpd GsnHttpdApiConfig_GetValuesHttpd

3 BASE-URI /id GsnHttpdApiConfig_SetValuesSysId GsnHttpdApiConfig_GetValuesSysId

• When GS node receives any GET request, HTTP server generates “TM_HTTPD_EVENT_SEND_READY” event. On reception of this event, GS node sends response in XML format to the Mobile device or PC using “GsnHttpd_SendBuffer” method. For sending the last chunk in response, GS node uses “GsnHttpd_SendBufferAndLastChunk” method.

• When GS node receives any POST request, HTTP server generates “TM_HTTPD_EVENT_BODY_RECV” event. On reception of this event, GS node decodes the received data from XML format, saves the information, and sends a response “<status>ok</status>” to Mobile device or PC.


80560NT11585A Rev. 1.0 of 48 2016-06-19

Chapter 5. Embedded Application Execution Sequence

5.1 BOOT UP AND INITIALIZATIONS

On system boot up, Boot ROM starts the main task AppMainCtx_ThreadEntry (). AppMainCtx_ThreadEntry () performs the following required initializations and waits on a ‘msg queue’ to handle systems events.

1. Initializes following GS node initializations o Initializes WIF message system o Initializes WIF System Control Message Handler o Initializes Soft Timer o Initializes File system o Gives boot request to WLAN o Initializes Default configuration o Initializes WDD Message Handler o Initializes NW stack o Initializes WPA Supplicant o Checks or waits for first time calibration to complete o Starts NCM (for L2 and L3 connections)

2. Handles system events

o All the system events are handled by AppSm_MsgProcess. o These events are posted by different threads to the AppMainCtx_ThreadEntry via

AppMainCtx_TaskNotify method. o Following are the events defined in App_events.h

App_events.h

typedef enum APP_EVENTS

{

APP_EVENT_INVALID,

APP_EVENT_NW_START_NCM,

APP_EVENT_NW_CONNECT_DONE,

APP_EVENT_NW_DISCONNECT_DONE,

APP_EVENT_NW_CONNECT_FAILED,

APP_EVENT_NW_DISCONNECT_FAILED,

APP_EVENT_SYNC_LOSS_DISCONNECT_DONE,

APP_EVENT_WLAN_DISCONNECT_INDICATION,

APP_EVENT_BATT_CHK_INITIATED,

APP_EVENT_BATT_CHK_INDICATION,

APP_EVENT_STA_DISCONNECT_DONE,

APP_EVENT_STA_WPS_INITIATE,

APP_EVENT_FWUP_COPY_TO_INT_FLASH,

APP_EVENT_NCM_EXECUTE,

APP_EVENT_MDNS_EXECUTE,

APP_EVENT_STAT_OUT,

APP_EVENT_STANDBY,

APP_EVENT_DAB_INDIACTION,

APP_EVENT_FWUP_SUCCESS,

APP_EVENT_STA_WPS_IN_PROGRESS,

APP_EVENT_SPI_READ,

APP_EVENT_SPI_RXCB_IND,

APP_EVENT_SPI_RX_DONE_IND,

APP_EVENT_SPI_TXCB_IND,

APP_EVENT_SPI_RX_1K_DONE_IND,

APP_EVENT_DOORBELL_PRESSED,

APP_EVENT_WLAN_LIVECAL_STATUS_VERIFY,

APP_EVENT_SPI_CLOSE,

} APP_EVENTS_T;


80560NT11585A Rev. 1.0 of 48 2016-06-19

3. Upon successful establishment of L2 and L3 connections, NCM generates the APP_EVENT_NW_CONNECT_DONE event. The following code snippet shows how this event is handled:

App_Sm.c:

AppSm_MsgProcess(APP_MAIN_CTX_T *pAppCtx,

APP_MAINTASK_MSG_T msg )

{

switch ( msg.msgId )

{

*

*

*

case APP_EVENT_NW_CONNECT_DONE:

AppSm_ConnectSuccessProcess(pAppCtx);

Break;

*

*

*

}

}

4. Once AppSm_ConnectSuccessProcess(pAppCtx) method generates APP_EVENT_NW_CONNECT_DONE event it starts the following servers:

▪ DNS server: For Domain Name

▪ HTTP server: For web services such as Provisioning and Over the Air Firmware Update.

▪ mDNS server: For announcing the Provisioning service. At this point, only mDNS is initialized.


80560NT11585A Rev. 1.0 of 48 2016-06-19

App_sm.c:

AppSm_ConnectSuccessProcess(APP_MAIN_CTX_T *pAppCtx)

{

*

if (pApCfg->dnsServerEnable)

{

*

*

GsnDnsSrvr_Start(&pAppCtx->if0.dnsServerHndl,

NULL,

&dnsInitParams);

*

*

}

App_NetworkServicesStart(pAppCtx);

*

}

App_network_services.c:

App_NetworkServicesStart(APP_MAIN_CTX_T *pAppCtx)

{

*

*

App_HttpdStart(pAppCtx);

#ifdef APP_MDNS_ENABLE

App_MdnsInit(pAppCtx);

#endif

*

*

}

App_httpd.c

App_HttpdStart(APP_MAIN_CTX_T *pAppCtx)

{

*

*

#ifdef ADK_PROV_ENABLE

GsnHttpdApi_ConfigInit(App_ConfigCb);

memset(&provConfig, 0x0, sizeof(provConfig));

provConfig.pWdd = &pAppCtx->if0.wddCtx;

provConfig.domain = appWlanRegDomain;

#ifdef ADK_PROV_WPS_ENABLE

provConfig.pWpsCbFn = (GSN_HTTPD_PROV_WPS_CB_FN_T) AppWps_CbFn;

#endif /* ADK_PROV_WPS_ENABLE */

GsnHttpdApi_ProvInit(&provConfig);

#endif /* ADK_PROV_ENABLE */

*

*

}

5. Provisioning feature is required to serve multiple URI requests such as network related information, firmware version, scanning information, and so on. In Gsn_httpd_config.c file, “GsnHttpdApi_ConfigInit” function registers the callback function on URI "/gainspan/system/config". This is the base URI for configuration information and

the common callback registered is “config_network_cb”. All the SUB URIs related to

configuration URI is handled in this callback function. SUB URIs for different configurations are:

• /gainspan/system/config/network

• /gainspan/system/config/httpd


80560NT11585A Rev. 1.0 of 48 2016-06-19

• /gainspan/system/config/id

6. There is one Application callback function “App_ConfigCb” is passed as an argument to GsnHttpdApi_ConfigInit function. “App_ConfigCb” function is responsible for saving new configurations sent over HTTP into the file system.

Gsn_httpd_config.c:

GsnHttpdApi_ConfigInit(GSN_HTTPD_API_CONFIG_CB_FN cb_fn)

{

*

*

if (cb_fn)

httpdConfigCbFn = cb_fn;

sysConfig.sysConfigChangeApply = 0;

sysConfig.networkConfig.regDomain =

GSN_WLAN_REG_DOMAIN_UNKNOWN;

if (httpdConfigCbFn)

(*httpdConfigCbFn)(&sysConfig, GSN_HTTPD_URI_METHOD_GET);

GsnHttpd_UriHandlerConfig("/gainspan/system/config",

GSN_HTTPD_URI_METHOD_GET_POST,

"Network Configuration",

config_network_cb,

GSN_HTTPD_CONTENT_APP_XML);

*

*

}

7. URI “gainspan/system/prov" is the base URI for provisioning. This URI is registered with “GsnHttpdApi_cb” callback function. All the SUB URIs related to provisioning URI are handled in this call back function. SUB URIs for different configurations are:

• "/gainspan/system/prov/ap_list"

• "/gainspan/system/prov/scan_params"

• “/gainspan/system/prov/wps"

GsnHttpdApi_ProvInit(GSN_HTTPD_PROV_CONFIG_T *pConfig)

{

*

*

GsnWlanScan_Init(pConfig->pWdd);

GsnHttpd_ScanConfigInit(pConfig->domain);

GsnHttpd_WpsInit(pConfig->pWpsCbFn);

GsnHttpd_UriHandlerConfig("/gainspan/system/prov",

GSN_HTTPD_URI_METHOD_GET_POST, "Provisioning API",

GsnHttpdApi_cb, GSN_HTTPD_CONTENT_APP_XML);

}


80560NT11585A Rev. 1.0 of 48 2016-06-19

5.2 PROVISIONING INITIATION

1. On successful initialization of Provisioning, GS node’s webserver is ready with mDNS and ready to accept the requests from the web clients.

When a mobile device connects to GS node’s network and starts the Provisioning application (Android / iOS App), native application sends mDNS request for provisioning service. GS node responds with mDSN response, so that mobile device displays the Provisioning service on screen. Following figures show the mDNS message exchange between the GS node and Mobile device.

2. Tapping on Provisioning service establishes the HTTP connection between GS node and Mobile device, and control goes to Client configuration page. On this page, Mobile device sends the following HTTP GET request to GS node.

3. There are two GET request specific to the configuration. URI’s “/gainspan/system/config/network” and “/gainspan/system/config/id” are handling by the registered call back function “config_network_cb”.

Gsn_httpd_config.c:

config_network_cb()

{

switch (event)

{

case TM_HTTPD_EVENT_BODY_RECV:

*

*

break;

case TM_HTTPD_EVENT_SEND_READY:

*

if (GsnHttpd_GetHttpMethod(conHandle) ==

TM_HTTP_METHOD_GET)

{

if (!strcmp(uri,

"/gainspan/system/config/network"))

{

GsnHttpdApiConfig_GetValuesNetwork();

GsnXml_Encode((GSN_XML_COMPLEX_OBJ_T

*)&xml_network_settings,

(UINT8*)&network_settings,(UINT8*) buffer,

maxSize, &encodedSize);

}


80560NT11585A Rev. 1.0 of 48 2016-06-19

else if (!strcmp(uri,

"/gainspan/system/config/id"))

{

GsnHttpdApiConfig_GetValuesSysId();

GsnXml_Encode((GSN_XML_COMPLEX_OBJ_T

*)&xml_sys_id_settings,

(UINT8*)&sys_id_settings,(UINT8*)

buffer, maxSize,

&encodedSize);

}

*

*

GsnHttpd_SendBufferAndLastChunk(conHandle,

buffer, encodedSize, TM_BLOCKING_ON,

&errorCode);

}

break;

*

*

}

}

4. There is one GET request for provisioning “/gainspan/system/prov/wps” which is handled by GEPS.

GSN_HTTPD_STATUS_T GsnHttpdApi_cb(ttHttpdUserEvent event, const char*

uri,

ttHttpdUserConHandle conHandle)

{

*

*

*

else if ((!strcmp(uri, "/gainspan/system/prov/wps")) &&

GsnHttpd_WpsCbFn)

return GsnHttpd_WpsCb(event, uri, conHandle);

*

}


80560NT11585A Rev. 1.0 of 48 2016-06-19

5. Other URI requests related to API, firmware, and time are handled in GEPS. Following table lists the HTTP GET request and responses for GEPS API version, capability information, and network information of GS node:

HTTP Request HTTP Reponses GET

/gainspan/system/config/network

HTTP/1.1

Host: 192.168.240.1:80

Connection: keep-alive

Accept-Encoding: gzip, deflate

User-Agent: Provisioning/1.12

CFNetwork/758.0.2 Darwin/15.0.0

Accept-Language: en-us

Accept: */*

HTTP/1.1 200 OK

Date: Thu, 1 Jan 1970 00:40:22 GMT

Server: $ProjectRevision: 6.0.1.29 $

Content-Type: application/xml

Cache-Control: no-cache

Cache-Control: no-store

Transfer-Encoding: chunked

042A

<network>

<mode>limited-ap</mode>

<ap_mode>user-ap</ap_mode>

<client>

<wireless>


<ssid>GainSpanDemo_IOT</ssid>


<wepauth></wepauth>


<eap_type></eap_type>

<eap_username></eap_username>

<eap_password></eap_password>

</wireless>

<ip>


<ip_addr>192.168.3.99</ip_addr>



<dns_addr>192.168.3.1</dns_addr>

</ip>

</client>

<ap>

<wireless>


<beacon_interval>100</beacon_interval>

<ssid>TLS_GS2K-ad0a3a</ssid>


<password>gainspan</password>

</wireless>

<ip>

<ip_addr>192.168.240.1</ip_addr>



<dhcp_server_enable>true</dhcp_server_enable>

<dhcp_start_addr>192.168.240.2</dhcp_start_add

r>

<dhcp_num_addrs>8</dhcp_num_addrs>

<dns_server_enable>true</dns_server_enable>

<dns_domain>config.gainspan.local</dns_domain>

</ip>

</ap>

<mac_addr>20:f8:5e:ad:0a:3a</mac_addr>

<ip>

<ip_addr>192.168.240.1</ip_addr>

</ip>

<reg_domain>fcc</reg_domain>

</network>

0 GET /gainspan/system/config/id

HTTP/1.1

HTTP/1.1 200 OK

Date: Thu, 1 Jan 1970 00:40:22 GMT


80560NT11585A Rev. 1.0 of 48 2016-06-19

HTTP Request HTTP Reponses Host: 192.168.240.1:80





Accept-..X`...e: en-us

Accept: */*






003C

<id><name>TLS_GS2K-

ad0a3a</name><uid>20f85ead0a3a</uid></id>

0

GET /gainspan/system/api/version

HTTP/1.1

Host: 192.168.240.1:80






Accept: */*

HTTP/1.1 200 OK

Date: Thu, 1 Jan 1970 00:40:22 GMT






0018

<version>1.0.0</version>

0

GET /gainspan/system/prov/wps

HTTP/1.1

Host: 192.168.240.1:80






Accept: */*

HTTP/1.1 200 OK

Date: Thu, 1 Jan 1970 00:40:22 GMT






003F

<wps>

<enabled>false</enabled>

<mode>none</mode>

<pin></pin>

</wps>

0

GET

/gainspan/system/firmware/versio

n HTTP/1.1

Host: 192.168.240.1:80






Accept: */*

HTTP/1.1 200 OK

Date: Thu, 1 Jan 1970 00:40:22 GMT






<version>

<wlan>5.1.6.32</wlan>

<geps>5.1.6</geps>

<app>TLS_GS2K-5.1.6.7</app>

<chip>gs2000</chip>

</version>

GET /gainspan/system/time

HTTP/1.1

Host: 192.168.240.1:80






Accept: */*

HTTP/1.1 404 Not Found

Date: Thu, 1 Jan 1970 00:40:22 GMT


Content-Length: 0

6. The next step in Provisioning is to get information about Wireless networks. Go to

Client configuration settings screen on Mobile device or PC. Options are available for


80560NT11585A Rev. 1.0 of 48 2016-06-19

WPS Push Button, WPS Pin, Select from Existing Network, and Manual Configuration method. Choose any of the options as per requirement.

If Select from Existing Network method is selected, then Mobile device sends request to GS node for scanning the Wireless networks. The GET Request goes on URI “/gainspan/system/prov/ap_list”.

Gsn_httpd_prov.c:

GSN_HTTPD_STATUS_T GsnHttpdApi_cb(ttHttpdUserEvent event, const char*

uri,


{

*

*

*

if (!strcmp(uri, "/gainspan/system/prov/ap_list"))

return GsnHttpd_ApListCb(event, uri, conHandle);

*

*

}

7. Upon reception of this request, GS node sends a request to WLAN for a list of Access Points. Upon successful scan, GS node frames the XML data for AP list and sends it to the Mobile device.

Gsn_httpd_prov.c:

GsnHttpd_ApListCb(ttHttpdUserEvent event, const char* uri,


{

*

*

switch (event)

{


break;


GsnHttpd_Scan_And_Send_Response(conHandle,buffer);

break;

}

*

*

return GSN_HTTPD_SUCCESS;

}


80560NT11585A Rev. 1.0 of 48 2016-06-19

The following figure shows the wireless sniffer capture for AP list scan:

8. Access Point configuration information will be in the following XML tags. Where, index

indicates the AP number. <ap>

<index>1</index>


<rssi>54</rssi>




</ap>

Following table lists the HTTP GET request and responses for AP list:

HTTP Request HTTP Reponses

GET /gainspan/system/prov/ap_list

HTTP/1.1

Host: 192.168.240.1:80






Accept: */*

HTTP/1.1 200 OK

Date: Thu, 1 Jan 1970 01:23:26 GMT






<ap_list>

<ap>

<index>1</index>


<rssi>54</rssi>




</ap>

<\ap_list>

9. User selects the wireless network from the scan list and provides the credentials related to the Passphrase for the selected AP. User has provision to choose the static or dynamic IP address

10. After entering the required credentials, the Mobile device displays SAVE button on the Provisioning page for saving the configuration information in GS node.

11. Tapping on the SAVE button sends HTTP Post request to GS node with configuration data as XML content.

Following figure shows wireless sniffer for the HTTP POST request sent to GS node.


80560NT11585A Rev. 1.0 of 48 2016-06-19

Following table shows the HTTP POST request and responses for Client configuration settings:

HTTP Request HTTP Reponses

POST

/gainspan/system/config/network?t=1445253678470

HTTP/1.1

Host: 192.168.240.1


Content-Length: 213

Origin: http://192.168.240.1

User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64)

AppleWebKit/537.36 (KHTML, like Gecko)

Chrome/46.0.2490.71 Safari/537.36

Content-Type: text/xml

Accept: */*

Referer: http://192.168.240.1/gsprov.html


Accept-Language: en-US,en;q=0.8,hi;q=0.6

<network>

<client>

<wireless>

<ssid>AE_Kiran</ssid>

<password>GainSpan01</password>


<security>wpa-Prsonal</security>

<wepauth></wepauth></wireless>

<ip>


</ip>

</client>

</network>

HTTP/1.1 200 OK

Date: Thu, 1 Jan 1970 00:11:37

GMT

Server: $ProjectRevision:

6.0.1.29 $





0013

<status>ok</status>

0

1. On reception of HTTP POST on URI “/gainspan/system/config/network” following code snippet is executed. For ease of understanding, these steps are divided into sub steps.

a. Decode the XML content and save the extracted information in to Current Profile. Gsn_httpd_config.c:

config_network_cb()

{

switch (event)

{


if (!strcmp(uri, "/gainspan/system/config/network"))

{

GsnXml_Decode(ParentNodeStart, ParentNodeEnd,

(GSN_XML_COMPLEX_OBJ_T

*)&xml_network_settings,

(UINT8 *)&network_settings);

GsnHttpdApiConfig_SetValuesNetwork();

}

break;


80560NT11585A Rev. 1.0 of 48 2016-06-19


*

*

break;

*

*

}

}

b. “GsnHttpdApiConfig_SetValuesNetwork” sets the received network information

into the local data structures. Gsn_httpd_config.c:

void

GsnHttpdApiConfig_SetValuesNetwork()

{

*

*

sysConfig.sysConfigChangeApply = 0;

GsnHttpdApiConfig_SetValuesMacAddress();

GsnHttpdApiConfig_SetValuesNetworkMode();

GsnHttpdApiConfig_SetValuesApMode();

GsnHttpdApiConfig_SetValuesClientConfig();

GsnHttpdApiConfig_SetValuesAPConfig();

return;

}

c. HTTP server generates “TM_HTTPD_EVENT_SEND_READY” event and it is used to

send response to Mobile device. Gsn_httpd_config.c:

config_network_cb()

{

switch (event)

{


*

break;


*

else

{

sprintf(buffer, "<status>ok</status>");

GsnHttpd_SendBufferAndLastChunk(conHandle,

buffer, strlen(buffer), TM_BLOCKING_ON,

&errorCode);

if (GsnHttpd_GetHttpMethod(conHandle) ==

TM_HTTP_METHOD_POST)

{

if (httpdConfigCbFn)

(*httpdConfigCbFn)(&sysConfig,

GSN_HTTPD_URI_METHOD_POST);

}

}

break;


80560NT11585A Rev. 1.0 of 48 2016-06-19

*

*

}

}

d. After sending the response to Mobile device, GS node saves the current profile information into the configuration file. This configuration file is located in the module flash under Dynamic file system. This is done by “httpdConfigCbFn” which is assigned with “App_ConfigCb” during the initialization.

App_httpd_cb.c

VOID App_ConfigCb(GSN_SYS_CONFIG_T *pConfig, UINT8 method)

{

*

*

if (method == GSN_HTTPD_URI_METHOD_POST)

{

AppConfig_Save(pConfig);

App_ApplySysConfig(pConfig);

}

*

*

return;

}

App_cfg.c:

AppConfig_Save(APP_CONFIG_T *pConfig)

{

*

*

f_delete(APP_CONFIG_FILE);

fp = f_open(APP_CONFIG_FILE,"w+");

f_write(pConfig, 1, sizeof(APP_CONFIG_T), fp);

f_close(fp);

*

*

}

e. On receiving response from GS node, Mobile device prompts the user to apply the settings using the Apply button.

On clicking Apply settings, following HTTP POST request is sent on URI “/gainspan/system/config/network”


80560NT11585A Rev. 1.0 of 48 2016-06-19

Following table lists the POST request and response for changing operation mode:

HTTP Request HTTP Reponses POST

/gainspan/system/config/network?t=144525835083

9 HTTP/1.1

Host: 192.168.240.1

User-Agent: Mozilla/5.0 (Windows NT 6.1;

WOW64; rv:41.0) Gecko/20100101 Firefox/41.0

Accept:

text/html,application/xhtml+xml,application/xm

l;q=0.9,*/*;q=0.8

Accept-Language: en-US,en;q=0.5


Content-Type: text/xml; charset=UTF-8

Referer: http://192.168.240.1/gsprov.html

Content-Length: 38


Pragma: no-cache


<network><mode>client</mode></network>

HTTP/1.1 200 OK

Date: Thu, 1 Jan 1970

01:29:29 GMT

Server: $ProjectRevision:

6.0.1.29 $

Content-Type:

application/xml




0013

<status>ok</status>

0

f. On reception of Apply setting, the mode information is sent to GS node. GS node decodes the XML data, saves the information locally, sends the response to Mobile device, and resets the system.

App_httpd_cb.c:

PRIVATE VOID App_ApplySysConfig(GSN_SYS_CONFIG_T *pConfig)

{

if (pConfig->sysConfigChangeApply)

{

App_MdnsDeInit();

App_Reboot(TRUE);

}

}

g. In the next boot, GS node loads new configuration file from the Dynamic file system and boots up.


80560NT11585A Rev. 1.0 of 48 2016-06-19

Chapter 6. Native Application and Execution Sequence

This section describes how Mobile application works along with Provisioning ADK. Native provisioning applications are developed in Apple and Android devices.

Following section provides the execution sequence of native application in Apple device. Provisioning feature is available for both Host based and Hostess Embedded Applications we have considered Hostless TLS application for our demonstration.

Steps to be performed for demo:

1. Upon system boot up, GS node comes us a Limited-AP. Using Mobile device (Apple device in this example), connect to the GS node. Following figure shows the connection establishment between Mobile device and GS node.

Figure 7: Connection establishment between Mobile device and GS node


80560NT11585A Rev. 1.0 of 48 2016-06-19

2. Launch the Provisioning application. It displays the network to which the mobile device is being connected. Tap on Continue to see the next screen.

Figure 8: Network connection details

3. Mobile device starts looking for mDNS service tag of “Prov” on “_http._tcp.local” by sending mDNS query. GS node has three services “prov”, “tls” and “otafu” on “_http._tcp.local”. Upon reception of mDNS query, GS node responds with mDNS reply with all the three services. As the Native application is only interested in “prov” tag, it is displayed on the page as mDSN provisioning service. Tap on the displayed mDNS service.

Figure 9: mDNS service discovery


80560NT11585A Rev. 1.0 of 48 2016-06-19

4. Tapping on the mDNS service establishes HTTP connection with GainSpan webserver and the default Client Setting page is loaded as shown in the following figure.

Here, User can see four ways to configure client settings. Choose Select an Existing Network and tap on Next button.

Figure 10: Client settings

5. Tapping on Next button sends request to GS node for getting Wireless network information. While scanning is happening, a pop-up is displayed to convey the information to user.

Figure 11: Wireless network scan


80560NT11585A Rev. 1.0 of 48 2016-06-19

6. After successful scanning of Wireless networks, GS node sends the scan results to Mobile device, and the Mobile device lists the results as shown in the following figure.

Figure 12: List of wireless networks

7. User chooses the network of their interest and provides the required credentials. On the above page, User is requested to enter the Passphrase for the selected network “AE_Kiran”. After entering the Passphrase which is GS_ followed by last 6-digits of MAC address of the GS2000 based device, tap on “Done”. This saves the “Wireless configuration” information of the selected AP in the Mobile device, and pops up the following screen.

Figure 13: Passphrase


80560NT11585A Rev. 1.0 of 48 2016-06-19

8. Following page requests the user for “Network configuration”. By default, DHCP is selected, but user has the provision to select Static IP address. Tapping on Next saves the “Network configuration” locally in mobile device and the next popup displays “Confirm configuration Settings”.

Figure 14: Network settings

9. By tapping on Save button, all the locally saved Wireless configuration and Network configuration information is saved in GS node as XML data. In this step, HTTP POST is sent to GS node.

Figure 15: Save configurations


80560NT11585A Rev. 1.0 of 48 2016-06-19

10. A popup is displayed prompting the user to apply the saved configuration. Tapping on Apply sends the HTTP POST to GS node for applying the setting. After successfully applying the setting GS node sends a success response to the Mobile device.

Figure 16: Apply new settings

11. On reception of success message from GS node, Mobile device displays the following screen. This indicates the user to connect the Mobile device to GS node’s network. Tap on OK to confirm.

Figure 17: Success notification

gs2k provisioning adk application note - telit · gs2k provisioning adk application note...

Documents