Tencent Cloud IoT has carried out in-depth cooperation with mainstream module manufacturers, porting the core protocol of the SDK to cellular modules (2/3/4/5G). The modules encapsulate unified Tencent Cloud IoT AT instructions externally and provide an AT SDK for use together.
SDK Acquisition
After creating products and devices on the IoT explorer platform, select the development method based on MQTT AT customized module. The AT SDK code on the MCU side will be automatically generated, and the corresponding configuration and initialization code for the data template and event created on the platform will also be generated.
Integration Guides
The integration of MCU+ customized MQTT AT modules (cellular type) into Tencent Cloud IoT Explorer can be divided into the following 4 steps.
Platform Adaptation and Porting
Adapt the porting implementation of the HAL layer APIs corresponding to the hal_export.h header file according to the selected embedded platform. Mainly include APIs for serial port send and receive (interrupt reception), module power on/off, task/thread creation, dynamic memory application/release, delay, print, etc. For detailed operations, please refer to the porting example of AT-SDK based on STM32+FreeRTOS .
For the HAL layer adaptation interfaces that need to be implemented in the porting part, please refer to hal_export.h. Implement the send and receive interfaces (interrupt reception) of the serial port, the delay function, the power on/off of the module and the adaptation of OS-related interfaces (mutex, dynamic memory application/release and thread creation). The adaptation layer interfaces are separately removed and placed in the port directory.
hal_export.h
This source file mainly provides the external API interfaces of the HAL layer and the macro switch control of the HAL layer.
No. | Macro Definition | Description |
1 | PARSE_THREAD_STACK_SIZE | Serial port AT parsing thread stack size. |
2 | OS_USED | Whether to use OS. The current AT-SDK is based on a multithreading framework, so OS is required. |
3 | AUTH_MODE_KEY | Authentication method. Certificate authentication or SSH key authentication. |
4 | DEBUG_DEV_INFO_USED | Enable this macro by default. Use debugging information for device information. Disable this macro during official mass production and implement the device information access API. |
hal_os.c
The source file mainly implements printing, delay, timestamp, lock, thread creation, and device information access.
No. | HAL_API | Description |
1 | HAL_Printf | Print function. log output is required. Optional implementation. |
2 | HAL_Snprintf | Formatted print. JSON data processing is required. Must be implemented. |
3 | HAL_Vsnprintf | Format output. Optional implementation. |
4 | HAL_DelayMs | Millisecond delay. Required implementation. |
5 | HAL_DelayUs | Subtle delay. Optional implementation. |
6 | HAL_GetTimeMs | Retrieve the number of milliseconds. Required implementation. |
7 | HAL_GetTimeSeconds | Acquire a timestamp. Required implementation. The timestamp does not need to be absolutely accurate, but it cannot be repeated. |
8 | hal_thread_create | Thread creation. Required implementation. |
9 | hal_thread_destroy | Thread destruction. Required implementation. |
10 | HAL_SleepMs | Delay in delegating authority. Required implementation. |
11 | HAL_MutexCreate | Mutex creation. Required implementation. |
12 | HAL_MutexDestroy | Mutex termination. Required implementation. |
13 | HAL_MutexLock | Obtain a mutex. Required implementation. |
14 | HAL_MutexUnlock | Release a mutex. Required implementation. |
15 | HAL_Malloc | Dynamic memory request. Required implementation. |
16 | HAL_Free | Dynamic memory release. Required implementation. |
17 | HAL_GetProductID | Retrieve the product ID. Required implementation. |
18 | HAL_SetProductID | Set the product ID. It must be stored on a non-volatile storage medium. Required implementation. |
19 | HAL_GetDevName | Obtain the device name. Required implementation. |
20 | HAL_SetDevName | Set the device name. It must be stored on a non-volatile storage medium. Required implementation. |
21 | HAL_GetDevSec | Obtain the device key. Key authentication is a required implementation. |
22 | HAL_SetDevSec | Set the device key. It must be stored in a non-volatile storage medium. The key authentication method is a required implementation. |
23 | HAL_GetDevCertName | Retrieve the device certificate file name. Certificate authentication method is a required implementation. |
24 | HAL_SetDevCertName | Set the device certificate file name. It must be stored on a non-volatile storage medium. Certificate authentication method is a required implementation. |
25 | HAL_GetDevPrivateKeyName | Retrieve the device certificate private key file name. Certificate authentication method is a required implementation. |
26 | HAL_SetDevPrivateKeyName | Set the device certificate private key file name. It must be stored on a non-volatile storage medium. Certificate authentication method is a required implementation. |
hal_at.c
The source file mainly implements AT serial port initialization, serial port send and receive, and module power on/off.
No. | HAL_API | Description |
1 | module_power_on | Power on the module. Initialize the AT serial port. Required implementation. |
1 | module_power_off | Power off the module. Low-power is required. Optional implementation. |
2 | AT_UART_IRQHandler | Serial port receive interrupt ISR, put the received data into the ring buffer, and the AT parsing thread will parse the data in real time. It is required to be implemented. |
3 | at_send_data | Sending Interface of AT Serial Port. |
module_api_inf.c
The source file mainly implements business adaptation for networking/provisioning APIs and MQTT interaction based on Tencent Cloud IoT AT commands. However, there is one networking/provisioning API (module_register_network) that needs to be adapted according to the module. The code is implemented based on Customized AT Firmware for ESP8266 Tencent Cloud IoT to connect to the network via Wi-Fi direct connection. But a more common scenario is triggering provisioning (softAP/one-click provisioning) based on specific events (for example, a button press). The logic for this part needs to be implemented according to specific business logic.
ESP8266 has factory-installed networking instructions and an example App. For cellular modules, use specific network registration commands. See the module_handshake function application using the AT framework of AT-SDK to add interaction with the module's AT commands.
//Module networking (NB/2/3/4G network registration), wifi configuration (one-click configuration/softAP) is temporarily difficult to unify, users are advised to adapt according to specific modules.// Developers refer to the module_handshake API to use the APIs of the AT framework and interact with modules to achieve adaptation.eAtResault module_register_network(eModuleType eType){eAtResault result = AT_ERR_SUCCESS;#ifdef MODULE_TYPE_WIFIif(eType == eMODULE_ESP8266){#define WIFI_SSID "test_****"#define WIFI_PW "********"// This example transmits the hotspot name and directly connects to the internet. The common approach is that a specific product triggers wifi configuration (one-click configuration/softAP) according to a specific event (for example, a button press).result = wifi_connect(WIFI_SSID, WIFI_PW);if(AT_ERR_SUCCESS != result){Log_e("wifi connect fail,ret:%d", result);}}#elseif(eType == eMODULE_N21){// Module network registration, or wifi configuration requires users to implement according to the selected module.result = N21_net_reg();if(AT_ERR_SUCCESS != result){Log_e("N21 register network fail,ret:%d", result);}}#endifreturn result;}
Equipment Information Modification
During debugging, turn on the device information debugging macro definition in hal_export.h. When in mass production, disable this macro definition to implement the device information access APIs of sequence 17 - 26 in hal-os.
#define DEBUG_DEV_INFO_USED
Modify the device information of the following macro definition, and the system will use debugging information.
#ifdef DEBUG_DEV_INFO_USEDstatic char sg_product_id[MAX_SIZE_OF_PRODUCT_ID + 1] = "03UKN1****";static char sg_device_name[MAX_SIZE_OF_DEVICE_NAME + 1] = "at****";#ifdef AUTH_MODE_CERTstatic char sg_device_cert_file_name[MAX_SIZE_OF_DEVICE_CERT_FILE_NAME + 1] = "YOUR_DEVICE_NAME_cert.crt";static char sg_device_privatekey_file_name[MAX_SIZE_OF_DEVICE_KEY_FILE_NAME + 1] = "YOUR_DEVICE_NAME_private.key";#elsechar sg_device_secret[MAX_SIZE_OF_DEVICE_SERC + 1] = "ttOARy0PjYgzd9OSs1****==";#endif#endif
Upstream and Downstream Business Logic Development
The automatically generated code data_template_usr_logic.c has implemented the common processing logic for data, event sending and receiving, and response. However, the specific business logic for data processing needs to be added by users themselves. The entry functions for adding upstream and downstream business logic are
deal_up_stream_user_logic and deal_down_stream_user_logic respectively.Downstream business logic implementation
// The business logic of downstream data that users need to implement. For pData, except for the string variable, the parsing and assignment of all other variable values have been implemented by users. The business logic is waiting for users to implement.static void deal_down_stream_user_logic(ProductDataDefine * pData){Log_d("someting about your own product logic wait to be done");}
Uplink business logic implementation
/* Business logic for upstream data that users need to implement. This is just an example. */static int deal_up_stream_user_logic(DeviceProperty *pReportDataList[], int *pCount){int i, j;for (i = 0, j = 0; i < TOTAL_PROPERTY_COUNT; i++) {if(eCHANGED == sg_DataTemplate[i].state) {pReportDataList[j++] = &(sg_DataTemplate[i].data_property);sg_DataTemplate[i].state = eNOCHANGE;}}*pCount = j;return (*pCount > 0)?AT_ERR_SUCCESS:AT_ERR_FAILURE;}
Application Development
The Sample directory contains a total of 3 samples. Users can refer to each Sample and perform application development according to the business logic. They are, respectively, mqtt_Sample.c, shadow_Sample.c, and light_data_template_Sample.c.
The descriptions of each Sample are as follows:
No. | Example Name | Description |
1 | mqtt_sample.c | MQTT Sample. This sample introduces how to conveniently integrate with Tencent IoT Platform and send and receive data based on customized AT commands. |
2 | shadow_sample.c | Shadow Example. A shadow protocol further encapsulated based on MQTT protocol implemented by AT. |
3 | light_data_template_sample.c | Introduce how specific products apply data templates and event features in the control scenario of smart lights. |