Gizwits IoT Cloud is an open platform dedicated to cloud services for IoT and smart devices. Gizwits IoT Cloud concentrates on providing intelligent cloud services and IoT software and hardware solutions to help traditional device vendors upgrade their products and quickly realize product intelligence. In order to realize the hardware intelligence, in addition to the elaborative work on the hardware itself, each domain of the intelligent cloud platform, mobile Apps, networking modules needs a professional team to support. Gizwits IoT Cloud offers a complete solution that allows vendors and developers to focus solely on their own product hardware to realize hardware intelligence with minimal cost and risk and maximum added value. This document describes the basic process of device connecting to Gizwits IoT Cloud.
Take an air conditioner as an example. When the air conditioner manufacturer develops the air conditioner electrical control board, using a Wi-Fi/GPRS module with Gizwits GAgent, the air conditioner will be connected to Gizwits Cloud. The basic data flow between the device and Gizwits IoT Cloud is shown below.
Take “Water Purifier” as an example to introduce the entire process of connecting a device to Gizwits IoT Cloud.
Go to the Developer Center of Gizwits IoT Cloud, and sign up for the developer account following the instructions.
The Water Purifier product has been successfully created on Gizwits IoT Cloud, which generated the Product Key and Product Secret for the product. The Product Key needs to be written by the developer to the device MCU (device main control board) , which will notify the Wi-Fi/GPRS module when logging into Gizwits IoT Cloud. Gizwits IoT Cloud will identify the product with the Product Key. The Product Secret is used when Apps connecting to Gizwits IoT Cloud.
The Data Point refers to the functionality abstraction of a device product, which describes the product’s capabilities and its parameters. After Data Points are created, the data format of the device and the cloud communication can be determined, and the device and Gizwits IoT Cloud can mutually recognize the data exchanged between the device and Gizwits IoT Cloud.
The basic content of a Data Point definition includes: display name, identification name, read/write type, data type and remarks. The overview is as follows:
1.1 Display name: Customize the Data Point name.
1.2 Identification name: Used for application layer transmission, which is required for client or cloud development and follows variables naming conventions of standard development languages, such as containing English letters, numbers, and underscores, starting with an English letter.
1.3 Read/write type
1.4 Data Types
1.5 Remarks: Optional, a piece of text used to describe the function and definition of the current Data Point with no restrictions on the character format. It is only used to improve the readability of a Data Point. If the team collaboration is required, it is recommended to use it.
1.6 Ratio and offset conversion for numeric type Data Points
As mentioned above, when defining numeric type Data Points, the value range includes values that are not uint type, including decimals and negative numbers. Developers familiar with embedded development know that these values are not supported on the device side.
In order to make the Data Point definition simpler and WYSIWYG, Gizwits has developed an algorithm for converting the numeric value input by the user into a uint that can be recognized by devices. The core formula of this algorithm is: y=kx+ m.
y means “display value”, which is the final value visible to the user, and is also the value entered by users when the Data Point is defined as Ymin (minimum) and Ymax (maximum).
x means “transport value”, which is the value used for transmission in actual commands, and the value received by the cloud/clients. x must be uint format, which also includes Xmin and Xmax.
k stands for the “ratio”, which is the ratio of the user input value, which determines the value step.
m means “value offset”. The algorithm offsets the y value by the m value according to the uint format requirement of x-value. The m value defaults to Ymin, ensuring Xmin=0.
Let’s take an electronic thermometer to illustrate the conversion process.
The Data Point value range: -30 (Ymin) ~ 50 (Ymax), ratio: 0.1
According to the formula: y=kx+m, m defaults to Ymin -30.
Xmin = (-30+30) / 0.1 = 0
Xmax = (50+30) / 0.1 = 800
The product requirement of “Water Purifier” is to synchronize the switch state and color combination of the RGB_LED light to the App, and control the light with the App remotely.
The automatically generated MCU code implements the packet encapsulation and parsing of the Gizwits communication protocol, the conversion logic of sensor data and communication data. All of these functions are integrated into a simple API set. When the device receives data from the cloud or the App, the program converts the data into corresponding events and notifies the application layer. You only needs to add the sensor control function to the corresponding event handler to complete the product development.
Here choose the standalone MCU Scheme. In the hardware platform drop-down list, select STM32f103c8x.
Then Gizwits IoT Cloud will generate the device-side project code for STM32f103c8x.
As shown in the figure below, the files with comments in black text to the right are for the STM32f103cx8 hardware platform development. The files with comments in green text are for connecting Gizwits IoT Cloud and hardware drivers, such as the serial port driver, the timer driver, the key driver. Developers can write hardware actions directly in gizwits_product.c and gizwits_product.h.
The following table is the description of key code files.
|gizwits_product.c||This file contains product-related processing functions, like gizEventProcess(), and platform-related hardware initialization, such as serial ports, timers, etc.|
|gizwits_product.h||This file is the header file of gizwits_product.c, which contains product-related macro definitions such as HARDWARE_VERSION, SOFTWARE_VERSION.|
|gizwits_protocol.c||This file is for function definitions of the SDK API.|
|gizwits_protocol.h||This file is the header file of gizwits_protocol.c, which contains the function declarations of the SDK API.|
The following table is the introduction to the SDK API.
|void gizwitsInit(void)||The Gizwits protocol initialization API. Users can call this API to complete the protocol-related initialization (including protocol-related timers and serial port initialization).|
|void gizwitsSetMode(unit8_t mode)||The parameter mode[in] only accepts 0, 1, and 2 and other input is invalid. When the parameter is set to 0, the module will load manufacture defaults. When the parameter is set to 1, the module will enter SoftAP mode. When the parameter is set to 2, the module will enter AirLink mode.|
|void gizwitsHandle(dataPoint_t *dataPoint)||Parameter dataPoint[in] is for Data Points. This function is responsible of processing the protocol data relating to data reporting.|
|int8_t gizwitsEventProcess(eventInfo_t info,uint8_t data,uint32_t len)||The user data processing function, handling Wi-Fi status update events and control-type events. Parameter info[in] is for the event queue. Parameter data[in] is for the data. Parameters len [in] is the data length. a) The Wi-Fi status update events start with WIFI_. The parameter data is only valid for WIFI_RSSI, whose value is RSSI, the type is uint8_t, and the range is 0~7. b) The control-type events are related to the Data Points. This version of the SDK will print the relevant event information and users only need to perform the specific execution of the control-type protocol.|
Location：main() function in main.c
|SystemInit()||Platform related hardware initialization. It is not a MCU SDK API. The function name may differ on different platforms.|
|userInit()||User related initialization, such as peripheral initialization, serial port initialization for print. It is not a MCU SDK API. The function name may differ on different platforms.|
|gizwitsInit()||Platform and protocol initialization, such as user timer initialization, serial port initialization for communication. It is a MCU SDK API.|
|userHandle()||Callback function for user events. Users can customize the events in this function to complete the corresponding protocol processing. It is not a MCU SDK API. The function name may differ on different platforms.|
|gizwitsHandle()||Protocol related main function. It is a MCU SDK API.|
From the MCU code directory structure, there is no RGB_LED driver in the automatically generated MCU code. We can go to the Download Center of Gizwits Developer Center to download other projects containing the RGB_LED driver and port the driver to your own project. Take the WeChat Pet House RGB_LED driver as an example as following.
Unpack the WeChat Pet House project package we just downloaded, and go into the following directory. You can see that there is a Hal_rgb_led driver folder. Copy the folder to your own auto-generated MCU driver directory.
Go back to your own MCU code project and add the rgb_led driver file to the driver directory.
Add #include “Hal_rgb_led/Hal_rgb_led.h” to main.c and gizwits_product.c
Location: userInit() function in main.c
The device needs to enter the configuration mode to be connected to the network and communicate with the cloud. In the project, the MCU SDK is triggered through pressing the keys to enter the corresponding configuration mode. Here, we choose to make the module enter the AirLink mode and the LED will light up.
A. Enter SoftAP mode: short press on key2.
B. Enter AirLink mode: long press on key2. The blue LED will light up.
C. Reset module: long press on key1.
The following figure is the flowchart of function calls related to control-type protocol.
|protocolIssuedProcess||The function is called by gizwitsHandle, receiving the protocol data issued from the Cloud or App side. It can be ignored as it is handled by the MCU SDK.|
|ACTION_CONTROL_DEVICE||Process the control-type protocol. It is handled by the MCU SDK. Developers can refer to its code for further understanding.|
|gizDataPoint2Event||Generate the control-type events according to the protocol and perform data type conversion. It is handled by the MCU SDK. Developers can refer to its code for further understanding.|
|gizwitsEventProcess||Handle the generated control-type events including the corresponding driver function implementation. It needs to be implemented by developers.|
The related code location: gizwitsEventProcess() function in …\Gizwits\gizwits_product.c
Description: Handle the events for writeable peripherals.
The following figure is the flowchart of function calls related to reporting device states.
|userHandle||Get the data to be reported from the user area. It need to be implemented by developers.|
|gizCheckReport||Determine whether to report the current status data. It can be ignored as it is handled by the MCU SDK.|
|gizDataPoints2ReportData||Complete the conversion of user area data to the data to be reported. It can be ignored as it is handled by the MCU SDK.|
|gizReportData||Send the converted data to the Wi-Fi module through the serial port. It can be ignored as it is handled by the MCU SDK.|
The related coce location: userHandle() function in …\User\main.c
Description: This function gets the data to be reported from the user area. Developers only need to read and assign the data to the current device state data structure in the user area. Then the data structure is reported to the cloud through the gizwitsHandle, and developers does not need to pay attention to the device’s state changes as well as its periodic report.
After the product is deployed in the production environment, Gizwits will allocate a separate cloud operating environment for your devices for free, keeping your devices connected for 24/7. You will enjoy more free value-added services provided by Gizwits, including statistical analysis for your smart devices, data presentation and various meticulous technical support services.
How to request for the product release? The specific steps are as follows:
End-of-line test is an important part of the production process to assure the product quality and enhance the product image. The Gizwits End-of-line test tool provides a convenient and quick module and MCU testing method for mass-produced products, which ensures that the modules and MCUs can be used normally. Your product must be deployed first before using the End-of-line test tool. The product creator can ask Gizwits for release. Gizwits will provide you with manual review and rigorous testing for free. For details, click here.