The content of this page has been automatically translated by AI. If you encounter any problems while reading, you can view the corresponding content in Chinese.

Customizing MCU+ MQTT AT Module (Cellular) Access Guide

Last updated: 2025-05-14 16:27:59

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_WIFI
if(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);
}
}
#else
if(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);
}
}
#endif

return 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_USED

static 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_CERT
static 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";
#else
char 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.
For more details, see Data Template Protocol.

SDK Usage Reference