GS2K SKB and Host MCU Interface Application Note

GS2K SKB and Host MCU Interface Application Note

80560NT11607A Rev. 1.0 – 2017-08-18


80560NT11607A Rev. 1.0 Page 2 of 35 2017-08-18

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.


80560NT11607A Rev. 1.0 Page 3 of 35 2017-08-18

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.


80560NT11607A Rev. 1.0 Page 4 of 35 2017-08-18

APPLICABILITY TABLE

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

PRODUCT

GS2K based Modules


80560NT11607A Rev. 1.0 Page 5 of 35 2017-08-18

Revision History

Version Date Remarks

1.0 Aug 2017 Initial Release


80560NT11607A Rev. 1.0 Page 6 of 35 2017-08-18

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. PURPOSE ...................................................................................................................... 9 1.2. SCOPE .......................................................................................................................... 9 1.3. OVERVIEW..................................................................................................................... 9 1.4. TERMINOLOGY ............................................................................................................. 10

CHAPTER 2. FEATURES AND CAPABILITIES ................................................................... 11

2.1 STM32 MCU NUCLEO ................................................................................................. 11 2.2 STM32 CUBE .............................................................................................................. 11 2.3 HOST INTERFACE ......................................................................................................... 11

CHAPTER 3. ARCHITECTURE ............................................................................................ 12

3.1 THEORY OF OPERATION ............................................................................................... 12 3.1.1 Non-Thread Model ........................................................................................... 13 3.1.2 Thread execution Model .................................................................................. 14

3.2 HARDWARE ................................................................................................................. 15 3.3 SOFTWARE .................................................................................................................. 22

CHAPTER 4. APPLICATION PROGRAM INTERFACE (API) .............................................. 23

4.1 ATLIB LAYER APIS ...................................................................................................... 23 4.2 DRIVERIF LAYER APIS ................................................................................................. 24 4.3 DRIVER LAYER APIS .................................................................................................... 25

CHAPTER 5. API/AT COMMAND REFERENCE TO FUNCTIONALITIES ........................... 26

5.1 VERIFIED PROVISIONING .............................................................................................. 26 5.2 AUTO NCM ................................................................................................................. 27

CHAPTER 6. REFERENCE APPLICATION ......................................................................... 28

6.1 MQTT WITH TELIT CLOUD CONNECTIVITY ..................................................................... 28 6.2 HTTP WITH TELIT CLOUD CONNECTIVITY ...................................................................... 29

APPENDIX A APPENDIX A AT COMMAND BASED APIS ................................................ 31

REFERENCE LINKS ................................................................................................................. 34


80560NT11607A Rev. 1.0 Page 7 of 35 2017-08-18

List of Figures Figure 1: STM32 Cube Architecture ........................................................................................ 11

Figure 2: Non RTOS model ..................................................................................................... 13

Figure 3: Thread execution Model ........................................................................................... 14

Figure 4: ZI pinout for UART ................................................................................................... 17

Figure 5: ST 767 ZI pinout for SPI ........................................................................................... 18

Figure 6: SKB pinout for UART ............................................................................................... 19

Figure 7: SKB pinout for SPI ................................................................................................... 20

Figure 8: Final Set-up .............................................................................................................. 21

Figure 9: MQTT Reference Application ................................................................................... 30


80560NT11607A Rev. 1.0 Page 8 of 35 2017-08-18

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

Table 2: List of all supported APIs based on AT command ..................................................... 31


80560NT11607A Rev. 1.0 Page 9 of 35 2017-08-18

Chapter 1. Introduction

1.1. PURPOSE

The purpose of this document is to define an architecture for the development of Host application in S2W modules.

1.2. SCOPE

This document provides an overview to Thread based and non-Thread based architecture that can be ported on any platform. It also provides with an overview of the execution flow in the system. This document also tells about the Application Program Interface (APIs) that would be provided for AT commands and Functionalities. As an example, Application Verified Provisioning and Auto NCM would be showcased.

1.3. OVERVIEW

The document also tells the details about the sample Host environment that can be used for the development. The STM32F767ZI is the STM MCU that would be used for the demo. The UART and SPI (command & response) are the initial interface that would be used. The development would be done in IAR IDE environment.


80560NT11607A Rev. 1.0 Page 10 of 35 2017-08-18

1.4. TERMINOLOGY

The following table lists the different terminologies used in this document.

Table 1: Glossary of Terms

Term Explanation

AP Access Point

API Application Programmer’s Interface

S2W Serial to Wi-Fi

IP Internet Protocol

HTTP Hypertext Transfer Protocol

UART Universal Asynchronous Receiver/Transmitter

SPI Serial Peripheral Interface

MQTT Message Queue Telemetry Transport

NCM Network Connection Manager

STA Station mode or Client mode

Limited AP Limited Access Point mode

WPA Wi-Fi Protected Access

https://en.wikipedia.org/wiki/Universal_Plug_and_Play


80560NT11607A Rev. 1.0 Page 11 of 35 2017-08-18

Chapter 2. Features and Capabilities

The Host MCU used is STM32F767ZI. It comes as Nucleo-F767ZI development board. STMCube is software solution from ST, available as freeware which support Low Level Driver, Hardware Abstraction Layer & Middleware (like FreeRTOS). STM CubeMX is the tool for configuring the STMCube software

2.1 STM32 MCU NUCLEO

The affordable STM32 Nucleo boards allow to quickly create prototypes with any STM32 MCU. STM32 Nucleo boards can easily be extended with a large number of specialized application hardware add-ons (Nucleo-64 include Arduino Uno rev3 & ST morpho connectors, Nucleo-32 include Arduino Nano connectors). NUCLEO-F767ZI is a STM32 Nucleo-144 development board with STM32F767ZI MCU, supports Arduino, ST Zio and morpho connectivity.

2.2 STM32 CUBE

The STM32Cube is a comprehensive software solution, combining embedded software bricks with the power of a PC based software development tool, STM32CubeMX. Embedded software not only covers all STM32 microcontrollers with highly portable Hardware Abstraction Layer (HAL) and performance oriented Low-Layer (LL) low-level drivers, but comes with a collection of middleware components such as RTOS, USB, TCP/IP, touch sensing, file system or graphics.

Figure 1: STM32 Cube Architecture

2.3 HOST INTERFACE

The supported Host interface would be

• Universal asynchronous receiver transmitter (UART)

• Serial Peripheral Interface (SPI)


80560NT11607A Rev. 1.0 Page 12 of 35 2017-08-18

Chapter 3. Architecture

The basic block diagram of the set-up is as shown as below:

3.1 THEORY OF OPERATION

The architecture is divided into following layers:

• ATLib (AT Library)

This layer consists of the core AT command APIs, Received data parser and asynchronous event handlers. This layer should not be changed irrespective of any platform or environment. This layer shouldn't be dependent on underlying driver used.

• Driver Interface (Abstraction Layer AL)

This layer contains all the environment dependent APIs. Changes should be done in this layer based on the environment based dependencies like OS specific handling otherwise non-RTOS (Bare metal) environment. Implementation at this layer depends on the underlying driver and makes the AT Lib independent of driver used. This is the only layer that is dependent on RTOS non-RTOS based design.

• Driver (HAL layer) This layer contains the hardware specific code. This layer mainly consists of common driver APIs provided by MCU vendor.

The implementation of these layers is done based on the underlying environment which could be:

• Non-Thread model

• Thread execution model

GS SKB BOARD

HOST MCU

TELIT CLOUD

S2W SPI/UART

Wi-Fi

AP


80560NT11607A Rev. 1.0 Page 13 of 35 2017-08-18

3.1.1 Non-Thread Model

Figure 2: Non RTOS model

Above diagram describes the different entities in this model. Following are the design specific details for it:

1. Application will first initialize the hardware and OS specific configurations to be used.

2. Application will be registering callbacks with the ATLib layer to receive notification for synchronous,

asynchronous messages to handle the messages.

3. Application context will be using the ATLib APIs to generate the data (e.g. AT command) to be sent.

4. Application context will be used for sending(Tx) data to the underlying interface (e.g UART/SPI). It will

be using the Abstraction Layer APIs to transmit the data generated.

5. Interrupt handlers will be calling HAL layer driver APIs to read data received from the hardware buffers.

Received data will be put into the circular buffer which will be consumed by the Application context for

parsing.

6. Application context will be waiting on the data to be put into the circular buffer. Once data is received

it will use ATLib APIs to parse the received data.

7. Parsed data will be handled by application based on the type of the message received.


80560NT11607A Rev. 1.0 Page 14 of 35 2017-08-18

3.1.2 Thread execution Model

Figure 3: Thread execution Model

Above diagram describes the different entities in this model. Following are the design specific details for it:

1. In this model, there will be a dedicated thread created to process the incoming data read from the

driver.

2. Application will first initialize the Rx process thread and registers hardware and OS specific

configuration to be used.

3. Application will be registering callbacks with the ATLib layer to receive notification for synchronous,

asynchronous messages to handle it accordingly.

4. Application context will be using the ATLib APIs to generate the data (e.g. AT command) to be sent.

5. Application context will be used for sending(Tx) data to the underlying interface (e.g UART/SPI). It will

be using the Abstraction Layer APIs to transmit the data generated.

6. Interrupt handlers will be calling HAL layer driver APIs to read data received from the hardware buffers.

Received data will be put into the circular buffer which will be consumed by the Rx process thread.

7. Rx process thread will be calling the ATLib APIs to parse the received data.

8. Parsed data will be passed to the respective application based on type of data received. It will be calling

application registered callbacks to notify the application.


80560NT11607A Rev. 1.0 Page 15 of 35 2017-08-18

3.2 HARDWARE

Hardware connection

The current reference application supports

1. UART interface

2. SPI interface

Connect the interface between HOST MCU(ST32F767ZI) and GainSpan 2000 module as below:

External Reset Functionality (mandatory)

Functionality ST Board Pin GainSpan Module Pin

GPIO_OUT PE14 EXT_RESET_N

UART interface with Hardware Flow Control


USART6 Rx PG9 UART0_Tx

USART6 Tx PG14 UART0_Rx

USART6 CTS PG15 UART0_RTS

USART6 RTS PG8 UART0_CTS

SPI interface


SPI1_MOSI PA7 SPI0_DIN

SPI1_MISO PA6 SPI0_DOUT

SPI1_SCK PA5 SPI0_CLK

SPI1_CS PD14 SPI0_CS

GPIO_OUT PD15 SDIO_DAT1_INT (HOSTWAKEUP)


80560NT11607A Rev. 1.0 Page 16 of 35 2017-08-18

Debug prints using UART

Functionality ST Board Pin TTL Cable Pin

UART2 Tx PA2 UART_Tx (Pin no 5)

UART2 Rx PA3 UART_Rx (Pin no 4)

GND GND GND (Pin no 1)

Note:

For pinout of ST32F767, refer User manual.


80560NT11607A Rev. 1.0 Page 17 of 35 2017-08-18

ZI pinout for UART

Figure 4: ZI pinout for UART


80560NT11607A Rev. 1.0 Page 18 of 35 2017-08-18

ST 767 ZI pinout for SPI

Figure 5: ST 767 ZI pinout for SPI


80560NT11607A Rev. 1.0 Page 19 of 35 2017-08-18

Similarly, pin config for the SKB Is as follows:

SKB pinout for UART:

Figure 6: SKB pinout for UART


80560NT11607A Rev. 1.0 Page 20 of 35 2017-08-18

SKB pinout for SPI:

Figure 7: SKB pinout for SPI


80560NT11607A Rev. 1.0 Page 21 of 35 2017-08-18

The final set-up is as shown below:

Figure 8: Final Set-up

ST 767 ZI with SKB connection using SPI interface


80560NT11607A Rev. 1.0 Page 22 of 35 2017-08-18

3.3 SOFTWARE

• Embedded Firmware Application: An embedded application that runs on the GainSpan SKB board which is the source of the data to be sent to Telit cloud.

• Host MCU reference project.

• IAR embedded workbench version 7.70.1.11471


80560NT11607A Rev. 1.0 Page 23 of 35 2017-08-18

Chapter 4. Application Program Interface (API)

4.1 ATLIB LAYER APIS

The implementation of APIs belonging to this layer will remain same irrespective of underlying environment or hardware. Following table will provide high level details about the main APIs to be implemented inside the ATLib layer.

API Name Description

AtLibGs_Init() 1. Initializes the ATLib layer. 2. Stores the application callback for asynchronous event notification.

AtLibGs_ProcessRxEvent() 1. Called by DrvIf(AL)_Run when data is available from host. 2. This API maintains state machine. 3. Calls Application callback when it receives asynchronous events.

AtLibGs_CommandSendString() 1. Form AT command string 2. Call GSAL_Write() 3. Return status of write API.


80560NT11607A Rev. 1.0 Page 24 of 35 2017-08-18

4.2 DRIVERIF LAYER APIS

The implementation of APIs belonging to this layer will be different based on underlying environment or hardware. This is adaption layer where all the environment and platform specific changes should be done. Following table will provide high level details about the main APIs to be implemented inside the DriverIf layer. Behaviour for each environment and underlying hardware is mentioned separately.

RTOS Non RTOS

UART SPI SDIO UART SPI SDIO

GSAL_Init 1. Does basic

initialization. 2. Registers callbacks with

the HAL layer.

Same as UART (RTOS)

Same as UART (RTOS)

Same as UART (RTOS) Same as UART (RTOS)

Same as UART (RTOS)

GSAL_Write 1. Calls

GSHAL_DriverWrite() 2. Wait on semaphore.

Same as UART (RTOS)

Same as UART (RTOS)

1. Calls GSHAL_DriverWrite().

2. Calls GSAL_Read ()

Same as UART (Non

RTOS)

Same as UART (Non RTOS)

GSAL_Read 1. Runs in a thread. 2. On receiving bytes

from circular read buffer, processes it by calling Run API.

3. In Run API it calls ATLib_BufProcess and based on the return it releases the semaphore acquired by GSAL_Write().

Same as UART (RTOS)

Same as UART (RTOS)

1. The Read API is a loop waiting bytes from circular read buffer, processes it by calling Run API.

2. In Run API it calls ATLib_BufProcess and based on the return it resumes the loop or breaks out of it.




80560NT11607A Rev. 1.0 Page 25 of 35 2017-08-18

4.3 DRIVER LAYER APIS

This layer implements the hardware specific functionalities. Following table will provide high level details about the expected set of APIs to be implemented in this layer. DriverIf layer will be calling these APIs to communicate with the driver layer.

API Name Description

GSHAL_DriverWrite() Sends data to the underlying interface (UART/SPI/DMA)

GSHAL_CircBufCreate() Configures circular buffer to be used for reading

GSHAL_CircBufRead() To read incoming data from the interface


80560NT11607A Rev. 1.0 Page 26 of 35 2017-08-18

Chapter 5. API/AT Command Reference to Functionalities

This section tells about usage of API/AT command for reference functionalities:

• Verified Provisioning and

• Auto NCM

5.1 VERIFIED PROVISIONING

Verified provisioning is similar to normal provisioning with an additional verification step to check whether a node has been successfully provisioned or not. Verified provisioning uses concurrent mode for verification purposes and performs the following:

1. Provisioning - A node is started in concurrent mode and both interfaces (STA interface and AP interface) are initialized. The STA interface is the one which is finally provisioned and verified and the provisioning and verification information between the STA interface and the user (smartphone/laptop) is exchanged via the AP interface. The user (smartphone/laptop) connects to the AP interface and opens the provisioning page (IP address/gsprov.html). After the provisioning information is submitted to the AP interface, it gets applied to the STA interface, and the STA interface connects to the provisioned standard Access Point in the vicinity.

2. Verification - After this point,

• STA interface sends information about status of provisioning to AP interface and the same is conveyed to the host (IP Address of STA) as well as user (laptop/smartphone).

• This step is performed with a specific HTTP POST (client-verify) done by user (laptop/smartphone) to the AP interface after sending the provisioning data. The AP interface returns the provisioned information such as SSID, BSSID, Channel, IP Address, and so on to the user.

• After successful provisioning, the system boots up in single interface mode being an STA, connected to the configured Access Point in the provisioning step. In cases of failure, the AP interface remains intact for further provisioning to be done.

Example Use-Case:

• Enable concurrent mode in the node.

• Configure index 0 for the client interface and index 1 for the AP interface.

• Configure the node to use a fixed IP address (in this example, 192.168.91.1).

• Configure the GainSpan node as a limited access point (in this example, setting it up with the SSID= GS_LAP and operating in WiFi channel 11).

• Enable the GainSpan node’s DHCP server so that clients that associate to the DHCP server can obtain an IP address automatically.

• Enable the GainSpan provisioning webserver.

• Configure “storeOption”=2 (For sending the provisioned information to the serial interface and for storing the provisioned information in the GainSpan profile).

• Enable NCM auto connection so that once the system resets, it automatically connects to the provisioned AP settings.


80560NT11607A Rev. 1.0 Page 27 of 35 2017-08-18

“AtLibGs_VerifyProvision” is the API for the verified provisioning, which internally call the

API’s

• AtLibGs_ConcurrentMode,

• AtLibGs_NIF,

• AtLibGs_Mode,

• AtLibGs_EnableRadio,

• AtLibGs_IPSet,

• AtLibGs_Assoc,

• AtLibGs_EnableDHCPServer and

• AtLibGs_WebProv Below is the corresponding AT command for the Verified Provisioning

AT+NIFCMODE=1 AT+NIF=0 AT+WM=0 AT+NIF=1 AT+WM=2 AT+WRXACTIVE=1 AT+NSET=192.168.91.1,255.255.255.0,192.168.91.1 AT+WA=GS_LAP,,11 AT+DHCPSRVR=1 AT+NSTAT=? AT+WEBPROV=,,0,2,,1

5.2 AUTO NCM

The network connection manager which manages WLAN (L2), IP/Network (L3), and Transport layer (L4) level connections. The parameters for L2, L3 and L4 layers can be configured using AT commands.

The Auto NCM allows to store configuration settings in non-volatile memory and modify according to the parameter value in the command; the resulting change (if any) takes effect on the next reboot, or the next issuance of an ATA command.

“AtLibGs_AutoNCM” is the API for the Auto NCM feature, which internally call the API’s

• AtLibGs_ConcurrentMode,

• AtLibGs_NIF,

• AtLibGs_Mode,

• AtLib_APConf

• AtLibGs_IPSet,

• AtLibGs_EnableDHCPServer,

• AtLibGs_StoreWAutoConn,

• AtLibGs_StoreNAutoConn,

• AtLibGs_EnableAutoConnect,

• AtLibGs_SaveProfile,

• AtLibGs_StartAutoConnect/ AtLibGs_Reset Below is the corresponding AT command for the Auto NCM in Limited AP mode

AT+WM=2 AT+APCONF=1 AT+NSET=192.168.21.1,255.255.255.0,192.168.21.1 AT+DHCPSRVR=1 AT+WAUTO=2,GainSpanAP,,6 AT+NAUTO=1,1,,4001 ATC1 AT&W0 ATA/AT+RESET/Power cycle the node


80560NT11607A Rev. 1.0 Page 28 of 35 2017-08-18

Chapter 6. Reference Application

6.1 MQTT WITH TELIT CLOUD CONNECTIVITY

This application connects the GS2000 device to the Telit Cloud using MQTT and transfers the Light value (read from SKB) to the Telit Cloud.

This application is enabled in Host Application by enabling the macro “APP_MQTT_TELIT_CLOUD” in <preinclude.h>

Method 1:

Step 1: This step is needed if GS2000 device not Provisioned

The provisioning can be done by 2 different procedures:

a. AUTONCM

o Enable the “AutoNCM” macro in <preinclude.h>

o Enter the AP connection details for the flowing macros (GS_CLIENT_SSID and

GS_CLIENT_PASSPHRASE)

o Build the Host MCU Project, download and run the source

b. Verified Provisioning

o Enable the “APP_VERIFIED_PROV” macro in <preinclude.h>


o The GS2000 device comes up as Limited AP mode (SSID: GS_PROV_)

o The Tera Term logs “Do verified provisioning from the Mobile APP”

o Now in the smart phone, connect to this SSID and start provisioning.

o Once provisioning is done, the GS2000 device reboots

Step 2: Once GS2000 device is Provisioned, the GS2000 device connects to the AP and then MQTT connection is established to transfer the Light values. The MQTT connection is established based on following parameters in <preinclude.h>

• TELIT_HOST_NAME

• MQTT_SERVER_PORT

• MQTT_CLIENT_ID

• MQTT_CLIENT_USER_NAME

• MQTT_CLIENT_PASSWORD

Method 2:

In case the GS2000 device is already provisioned, enable only “APP_MQTT_TELIT_CLOUD” in <preinclude.h> Build the Host MCU Project, download and run the source.The GS2000 device connects to the AP and then MQTT connection is established to transfer the Light values. The MQTT connection is established based on following parameters in <preinclude.h>

• TELIT_HOST_NAME

• MQTT_SERVER_PORT

• MQTT_CLIENT_ID

• MQTT_CLIENT_USER_NAME

• MQTT_CLIENT_PASSWORD


80560NT11607A Rev. 1.0 Page 29 of 35 2017-08-18

6.2 HTTP WITH TELIT CLOUD CONNECTIVITY

This application connects the provisioned GS2000 device to the Telit Cloud using HTTP and transfer the Temperature value to the Telit Cloud.

This application is enabled in Host Application by enabling the macro “APP_HTTP_TELIT_CLOUD” in <preinclude.h>

Method 1:

Step 1: This step is needed if GS2000 device not Provisioned

The provisioning can be done by 2 different procedures:

a. AUTONCM

o Enable the “AutoNCM” macro in <preinclude.h>

o Enter the AP connection details for the flowing macros (GS_CLIENT_SSID and

GS_CLIENT_PASSPHRASE)


b. Verified Provisioning

o Enable the “APP_VERIFIED_PROV” macro in <preinclude.h>


o The GS2000 device comes up as Limited AP mode (SSID: GS_PROV_)

o The Tera Term logs “Do verified provisioning from the Mobile APP”

o Now in the smart phone, connect to this SSID and start provisioning.

o Once provisioning is done, the GS2000 device reboots

Step 2: Once GS2000 device is Provisioned, the GS2000 device boots in station mode, connects to the AP and then HTTP connection is established to transfer the Temperature values. The HTTP connection is established based on following parameters in <preinclude.h>

• TELIT_HOST_NAME

• HTTPS_PORT

• DATE

• TIME

Method 2:

In case the GS2000 device is already provisioned, enable only “APP_HTTP_TELIT_CLOUD” in <preinclude.h>. Build the Host MCU Project, download and run the source. The GS2000 device boots in station mode, connects to the AP and then HTTP connection is established to transfer the Temperature values. The HTTP connection is established based on following parameters in <preinclude.h>

• TELIT_HOST_NAME

• HTTPS_PORT

• DATE

• TIME


80560NT11607A Rev. 1.0 Page 30 of 35 2017-08-18

MQTT based Telit cloud is the refence application discussed below.

The following are the steps:

1) Set up GS2K node in Limited AP mode from Host MCU by sending the AT commands. 2) Host MCU send the verified provisioning commands to GS2K node. 3) Successful provisioning will connect the GS2K node to the provisioned AP. 4) Initiate MQTT connection to the Telit cloud. 5) Send Light data periodically to Telit cloud from GS2K 6) GS2K reads Light data periodically from Telit cloud

Figure 9: MQTT Reference Application

Set GS2K node in LAP mode

Provision station interface

(Verified Provisioning)

Establish MQTT

connection to Telit Cloud

Publish / Send Light

Data to Telit cloud

Subscribe / Read Light

Data from Telit cloud

Exit

GainSpan Node

UART Interface

ST Micro Controller GS2K Node


80560NT11607A Rev. 1.0 Page 31 of 35 2017-08-18

Appendix A APPENDIX A AT Command based APIs

These APIs are direct one-one mapping APIs with corresponding AT commands.

Note:Refer the S2W Adaptor guide (GS2xxxx S2W Adapter Command Reference Guide.pdf) for the detailed AT commands supported in S2W.

Below are the set of APIs based on AT command which are planned to be supported:

Table 2: List of all supported APIs based on AT command

Host MCU API AT Command AT command functionality

ATLIBGS_AT AT Link Check

ATLIBGS_RESETNormal AT+RESET=1 GsNode Normal Reset

ATLIBGS_RESETFactory AT+RESET=2 GsNode Factory Reset

ATLIBGS_NSTAT AT+NSTAT=? Gets GsNode current Network Status

ATLIBGS_ATE ATE Echo Enable / Disable

ATLIBGS_ASYNCMSGFMT AT+ASYNCMSGFMT Enable / Disable enhanced asynchronous notification method

ATLIBGS_WM AT+WM Sets Wireless mode and related parameters

ATLIBGS_WRXACTIVE AT+WRXACTIVE Enable / Disable the 802.11 radio receiver

ATLIBGS_NSET AT+NSET Sets network parameters statically.

ATLIBGS_WA AT+WA Creates or Joins an infrastructure network

ATLIBGS_NIFCMODE AT+NIFCMODE Enable / Disable concurrent mode

ATLIBGS_NIF AT+NIF Set / Get Interface Info

ATLIBGS_WAUTO AT+WAUTO Sets the wireless parameters for auto connection


80560NT11607A Rev. 1.0 Page 32 of 35 2017-08-18

ATLIBGS_WWPA AT+WWPA Sets the WPA-PSK and WPA2-PSK passphrase

ATLIBGS_WSEC AT+WSEC Configures the GS node with different security configuration

ATLIBGS_NDHCP AT+NDHCP Enable/Disable DHCP client support for IPv4 network

ATLIBGS_DHCPSRVR AT+DHCPSRVR Start / Stop DHCP server

ATLIBGS_NCMAUTO AT+NCMAUTO Start/Stop the network connection manager

ATLIBGS_NCMAUTOStatusGet AT+NCMAUTO=? Gets NCM status

ATLIBGS_NCTCP AT+NCTCP Creates a TCP client connection for a remote server with IPv4 address

ATLIBGS_NXSETSOCKOPT AT+NXSETSOCKOPT Configures a socket which is identified by a CID.

ATLIBGS_ATW AT&W To write to profile settings

ATLIBGS_DGPIO AT+DGPIO Set / Reset GPIO

ATLIBGS_SETTIME AT+SETTIME Sets GS node’s system time

ATLIBGS_NMACGet AT+NMAC=? Gets MAC address

ATLIBGS_SSLCONF AT+SSLCONF Used to configure the SSL parameters

ATLIBGS_WLCALEN AT+WLCALEN Enable / Disable live calibration

ATLIBGS_WLCALSTATUS AT+WLCALSTATUS=? Gets status of live calibration

ATLIBGS_WLCALERASE AT+WLCALERASE Erases live calibration

ATLIBGS_WLCALSTART AT+WLCALSTART=1 Starts live calibration

ATLIBGS_BDATA AT+BDATA Enable / Disable the bulk mode data transfer

ATLIBGS_ATK AT&K Enable / Disable UART Software Flow Control


80560NT11607A Rev. 1.0 Page 33 of 35 2017-08-18

ATLIBGS_ATR AT&R Enable / Disable UART hardware Flow Control

ATLIBGS_HTTPCONF AT+HTTPCONF Configures HTTP client

ATLIBGS_HTTPOPEN AT+HTTPOPEN Opens HTTP client connection

ATLIBGS_HTTPCLOSE AT+HTTPCLOSE Closes HTTP client connection

ATLIBGS_HTTPSEND AT+HTTPSEND Get/Post HTTP data on the HTTP client

ATLIBGS_MDNSSTART AT+MDNSSTART Starts mDNS

ATLIBGS_MDNSANNOUNCE AT+MDNSANNOUNCE Announces the mDNS services

ATLIBGS_MDNSHNREG AT+MDNSHNREG Registers or gives a unique name to each of the nodes for mDNS

ATLIBGS_MDNSSRVREG AT+MDNSSRVREG Registers the services to the mDNS.

ATLIBGS_I2CCONF AT+I2CCONF Configures the I2C driver

ATLIBGS_I2CSTART AT+I2CSTART Starts I2C Driver

ATLIBGS_I2CWRITE AT+I2CWRITE I2C driver write

ATLIBGS_I2CREAD AT+I2CREAD I2C driver read

ATLIBGS_I2CSTOP AT+I2CSTOP Stops I2C Driver

ATLIBGS_WEBPROV AT+WEBPROV Provisions through web page

ATLIBGS_MQTTCONNECT AT+MQTTCONNECT Connects to an MQTT Server

ATLIBGS_MQTTPUBLISH AT+MQTTPUBLISH Sends application messages from client to the server

ATLIBGS_MQTTSUBSCRIBE AT+MQTTSUBSCRIBE Sends subscribe Packet from the Client to the Server to create one or more subscriptions

ATLIBGS_MQTTDISCONNECT AT+MQTTDISCONNECT Closes the MQTT client connection identified by the CID


80560NT11607A Rev. 1.0 Page 34 of 35 2017-08-18

Reference Links GS2000 based module EVB Hardware/Started Kit Board(SKB)

http://www.gainspan.com/products/product_overview/modules

STM32 Nucleo-144 development board with STM32F767ZI MCU

http://www.st.com/content/ccc/resource/technical/document/user_manual/group0/26/49/90/2e/33/0d/4a/da/DM00244518/files/DM00244518.pdf/jcr:content/translations/en.DM00244518.pdf

CubeMx Tool for STM32F7 MCU

http://www.st.com/content/st_com/en/products/embedded-software/mcus-embedded-software/stm32-embedded-software/stm32cube-embedded-software/stm32cubef7.html

STM32F 767ZI datasheet

http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32-high-performance-mcus/stm32f7-series/stm32f7x7/stm32f767zi.html

http://www.gainspan.com/products/product_overview/modules










Documents

GS2K SKB and Host MCU Interface Application Note