Product Configuration API

API Overview

Function	Description
Qth_configSetProductInfo()	Sets product information.
Qth_configGetProductInfo()	Gets the product information.
Qth_configSetDeviceInfo()	Sets device information.
Qth_configGetDeviceInfo()	Gets the device information.
Qth_configGetAuthType()	Gets the device authentication type.
Qth_configSetODOSInfo()	Sets unique-DeviceSecret-per-device authentication information.
Qth_configSetServer()	Sets server URL and default IP address.
Qth_configGetServer()	Gets the server URL and default IP address.
Qth_configSetLifetime()	Sets MQTT keep alive interval.
Qth_configGetLifetime()	Gets the MQTT keep alive interval.
Qth_configSetEventCb()	Sets user event callback function.
Qth_configGetEventCb()	Gets the user event callback function.
Qth_configSetModuleVer()	Sets module's version number.
Qth_configGetModuleVer()	Gets the module's version number.
Qth_configSetMcuVer()	Sets MCU version number.
Qth_configGetMcuVer()	Gets the MCU version number.
Qth_configSetWifiInfo()	Sets Wi-Fi information.
Qth_configGetWifiInfo()	Gets the Wi-Fi information.
Qth_configClearWifiInfo()	Clears Wi-Fi information.
Qth_configSetNetcfgMode()	Sets Wi-Fi network provisioning mode.
Qth_configGetNetcfgMode()	Gets the Wi-Fi network provisioning mode.

API Description

Qth_configSetProductInfo

This function sets product information. The product information contains ProductKey and ProductSecret, which are generated when you create the product on Developer Center.

Prototype

oprt_ret Qth_configSetProductInfo(const char *pk, const char *ps);

Parameter

Input Parameter
- const char * pk: ProductKey generated when you create the product on Developer Center.
- const char * ps: ProductSecret generated when you create the product on Developer Center.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

Qth_configSetProductInfo("xxxxxx", "xxxxxxxxxxxxxxxx");

Qth_configGetProductInfo

This function gets the product information.

Prototype

oprt_ret Qth_configGetProductInfo(char *pk, char *ps);

Parameter

Input Parameter
- None
Output Parameter
- char * pk: ProductKey generated when you create the product on Developer Center.
- char * ps: ProductSecret generated when you create the product on Developer Center.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

char pk[QTH_PK_MAXSIZE + 1] = {0};
char ps[QTH_PS_MAXSIZE + 1] = {0};

Qth_configGetProductInfo(pk, ps);

Qth_configSetDeviceInfo

This function sets device information.

Prototype

oprt_ret Qth_configSetDeviceInfo(const char *dk, const char *ds);

Parameter

Input Parameter
- const char * dk: DeviceKey is the customized unique identifier of the device. Cellular modules use IMEI as the default identifier, whereas wireless modules, such as Wi-Fi module, use MAC address. Maximum length: 16 bytes. If this parameter is set to an empty string, this function will delete the customized DK and DS, and use the default configurations. In that case, the device needs to be re-authenticated by Developer Center.
- const char * ds: DeviceSecret generated after device authentication. The length is fixed to 32 bytes. Only when DeviceKey is set to a non-empty and non-default value, setting DeviceSecret is allowed. This parameter can be NULL, which means the default DeviceSecret is not set.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

Qth_configSetDeviceInfo("202305091054", NULL);

Qth_configGetDeviceInfo

This function gets the device information.

Prototype

oprt_ret Qth_configGetDeviceInfo(char *dk, char *ds);

Parameter

Input Parameter
- None
Output Parameter
- char * dk: The unique identifier of the device.
- char * ds: DeviceSecret generated after device authentication.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

char dk[QTH_DK_MAXSIZE + 1] = {0};
char ds[QTH_DS_MAXSIZE + 1] = {0};

Qth_configGetDeviceInfo(dk, ds);

Qth_configSetODOSInfo

This function sets unique-DeviceSecret-per-device authentication information.

Prototype

oprt_ret Qth_configSetODOSInfo(const char *pk, const char *ps, const char *dk, const char *ds);

Parameter

Input Parameter
- const char * pk: ProductKey generated when you create the product on Developer Center.
- const char * ps: ProductSecret generated when you create the product on Developer Center.
- const char * dk: String type. The unique identifier of the device. Range: 4–32 bytes.
- const char * ds: String type. DeviceSecret generated after device authentication, with a fixed length of 32 bytes.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

Qth_configSetODOSInfo("p11rbd", "VDcydF****52VFVq", "12345678abcd", "ca13ecbfaf92********12d372b38711");

Qth_configGetAuthType

This function gets the device authentication type.

Prototype

oprt_ret Qth_configGetAuthType(Qth_authType_e *type);

Parameter

Input Parameter
- None
Output Parameter
- Qth_authType_e * type：Device authentication type.
  Value Description
  QTH_AUTHTYPE_OTOS Unique-ProductSecret-per-product authentication
  QTH_AUTHTYPE_ODOS Unique-DeviceSecret-per-device authentication
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Value	Description
QTH_AUTHTYPE_OTOS	Unique-ProductSecret-per-product authentication
QTH_AUTHTYPE_ODOS	Unique-DeviceSecret-per-device authentication

Example

Qth_authType_e type = 0;

Qth_configGetAuthType(&type);

Qth_configSetServer

This function sets server URL and default IP address.

Prototype

oprt_ret Qth_configSetServer(const char *url, const char *ip);

Parameter

Input Parameter
- const char * url: Server URL. Optional. Default value: mqtts://iot-south.quectelcn.com:8883. The default value is used if this parameter is not set.

Region	Server URL
China (Non-SSL)	mqtt://iot-south.quectelcn.com:1883
China (SSL)	mqtts://iot-south.quectelcn.com:8883
Europe (Non-SSL)	mqtt://iot-south.acceleronix.io:1883
Europe (SSL)	mqtts://iot-south.acceleronix.io:8883

const char * ip: Default server IP address. If you set a default IP address, it will be used first to log in to the server. If the login failed, the IP address will be obtained through DNS.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

Qth_configSetServer("mqtts://iot-south.quectelcn.com:8883", NULL);

Qth_configGetServer

This function gets the server URL and default IP address.

Prototype

oprt_ret Qth_configGetServer(char *url, char *ip);

Parameter

Input Parameter
- None
Output Parameter
- char * url: Server URL.
- char * ip: Default server IP address.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

char url[QTH_DNS_HOSTNANE_MAX_LENGHT + 1] = {0};
char ip[QTH_IP_ADDR_MAX_LEN + 1] = {0};

Qth_configGetServer(url, ip);

Qth_configSetLifetime

This function sets MQTT keep alive interval.

Prototype

oprt_ret Qth_configSetLifetime(quint32_t lifetime);

Parameter

Input Parameter
- quint32_t lifetime: Keep alive interval of the MQTT connection. Range: 1–600. Default value: 120. Unit: second.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

Qth_configSetLifetime(120);

Qth_configGetLifetime

This function gets the MQTT keep alive interval.

Prototype

oprt_ret Qth_configGetLifetime(quint32_t *lifetime);

Parameter

Input Parameter
- None
Output Parameter
- quint32_t * lifetime: Keep alive interval of the MQTT connection. Unit: second.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

quint32_t lifetime = 0;

Qth_configGetLifetime(&lifetime);

Qth_configSetEventCb

This function sets user event callback function.

Prototype

oprt_ret Qth_configSetEventCb(Qth_eventCb_t cb);

Parameter

Input Parameter

Qth_eventCb_t cb: User event callback function.

Qth_devEventCb_f devEventCb: Device event callback function.

Prototype

void (*Qth_devEventCb_f)(Qth_devEvent_e event, oprt_ret result);

Input Parameter

Qth_devEvent_e event: Event type.

Value	Description
QTH_DEV_EVENT_WIFI_CONFIG	Network provisioning event.
QTH_DEV_EVENT_WIFI_CONNECT	Router connection event.
QTH_DEV_EVENT_DMP_CONNECT	Platform connection event.
QTH_DEV_EVENT_RESET	Device reset event.
QTH_DEV_EVENT_REMOVE	Device deletion event.
QTH_DEV_EVENT_SLIENT	Idle mode event.

oprt_ret result: Event code. See Error Code List for details.

Qth_ttlvRecvCb_f ttlvRecvCb: Callback function of receiving TTLV data.
- Prototype
  c
```
void (*Qth_ttlvRecvCb_f)(void *ttlvHead);
```
- Input Parameter
  - void * ttlvHead: TSL data in TTLV format.
Qth_ttlvReqCb_f ttlvReqCb: Callback function of requesting TTLV data.
- Prototype
  c
```
void *(*Qth_ttlvReqCb_f)(quint16_t id[], quint32_t idNum);
```
- Input Parameter
  - quint16_t id: Array of TSL IDs to be read.
  - quint32_t idNum: Number of TSL IDs to be read.
Qth_transRecvCb_f transRecvCb: Callback function of receiving transparent transmission data.
- Prototype
  c
```
void (*Qth_transRecvCb_f)(quint8_t *value, quint32_t valLen);
```
- Input Parameter
  - quint8_t * value: Transparent transmission data issued by Developer Center.
  - quint32_t valLen: Length of transparent transmission data issued by Developer Center.
Qth_otaEventCb_t otaEventCb: Callback function of receiving OTA upgrade events.
- Qth_otaPlanCb_f planCb: Callback function of issuing OTA upgrade plans (Old). The return value indicates the OTA upgrade plan confirmation result.
  - Prototype
    c
```
qbool (*Qth_otaPlanCb_f)(Qth_otaPlan_t *planList, quint16_t count);
```
  - Input Parameter
    - Qth_otaPlan_t * planList: Component OTA upgrade plan issued by Developer Center.
    - quint16_t count: Number of components in the OTA upgrade plan issued by Developer Center.
  - Return Value
    - TRUE: The device accepts the OTA upgrade plan.
    - FALSE: The device rejects the OTA upgrade plan.
- Qth_otaPlanExCb_f planExCb: Callback function of issuing OTA upgrade plans (Old). Call Qth_otaPlanConfirm() to confirm the OTA upgrade plan.
  - Prototype
    c
```
void (*Qth_otaPlanExCb_f)(Qth_otaPlan_t *planList, quint16_t count);
```
  - Input Parameter
    - Qth_otaPlan_t * planList: OTA upgrade plan of components issued by Developer Center.
    - quint16_t count: Number of components in the OTA upgrade plan issued by Developer Center.
- Qth_otaDownloadCb_f downloadCb: Callback function of receiving firmware download progress.
  - Prototype
    c
```
void (*Qth_otaDownloadCb_f)(char *identity, quint8_t percent);
```
  - Input Parameter
    - char * identity: Component ID.
    - quint8_t percent: Firmware download progress. Range: 0–100. Unit: percentage.
- Qth_otaResultCb_f resultCb: Callback function of receiving OTA upgrade result.
  - Prototype
    c
```
void (*Qth_otaResultCb_f)(char *identity, qbool result);
```
  - Input Parameter
    - char * identity: Component ID.
    - qbool result: OTA upgrade result.
- Qth_sotaInfoCb_f sotaInfoCb: Callback function of receiving SOTA upgrade firmware.
  - Prototype
    c
```
qbool (*Qth_sotaInfoCb_f)(char *identity, Qth_otaInfo_t *info, Qth_otaDownType_e *type);
```
  - Input Parameter
    - char * identity: Component ID.
    - Qth_otaInfo_t * info: Firmware information of the SOTA upgrade.
  - Output Parameter
    - Qth_otaDownType_e * type: Download type of SOTA upgrades.
      Value Description
      QTH_SOTA_DOWN_TYPE_MODULE The module downloads the MCU firmware for the external MCU.
      QTH_SOTA_DOWN_TYPE_MCU The MCU downloads the MCU firmware by itself.
  - Return Value
    - TRUE: The device accepts the OTA upgrade plan.
    - FALSE: The device rejects the OTA upgrade plan.
- Qth_sotaFileCb_f sotaFileCb: Callback function of issuing SOTA upgrade files.
  - Prototype
    c
```
qbool (*Qth_sotaFileCb_f)(char *identity, quint32_t offset, quint8_t *data, quint32_t dataLen);
```
  - Input Parameter
    - char * identity: Component ID.
    - quint32_t offset: Offset of the firmware block.
    - quint8_t * data: Content of the firmware block.
    - quint32_t dataLen: Size of the firmware block.
  - Return Value
    - TRUE: File saved successfully
    - FALSE: File saving failed

Value	Description
QTH_SOTA_DOWN_TYPE_MODULE	The module downloads the MCU firmware for the external MCU.
QTH_SOTA_DOWN_TYPE_MCU	The MCU downloads the MCU firmware by itself.

Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

void devEventCb(Qth_devEvent_e event, oprt_ret result)
{
    /* do something */
}
void ttlvRecvCb(void *ttlvHead)
{
    /* do something */
}
void *ttlvReqCb(quint16_t id[], quint32_t idNum)
{
    /* do something */
}
void transRecvCb(quint8_t *value, quint32_t valLen)
{
    /* do something */
}
qbool otaPlanCb(Qth_otaPlan_t *planList, quint16_t count)
{
    /* do something */
}
void otaDownloadCb(char *identity, quint8_t percent)
{
    /* do something */
}
void otaResultCb(char *identity, qbool result)
{
    /* do something */
}
qbool sotaInfoCb(char *identity, Qth_otaInfo_t *info, Qth_otaDownType_e *type)
{
    /* do something */
}
qbool sotaFileCb(char *identity, quint32_t offset, quint8_t *data, quint32_t dataLen)
{
    /* do something */
}
otaCb.planCb = otaPlanCb;
otaCb.downloadCb = otaDownloadCb;
otaCb.resultCb = otaResultCb;
otaCb.sotaInfoCb = sotaInfoCb;
otaCb.sotaFileCb = sotaFileCb;
event_cb.devEventCb = devEventCb;
event_cb.ttlvRecvCb = ttlvRecvCb;
event_cb.ttlvReqCb = ttlvReqCb;
event_cb.transRecvCb = transRecvCb;
event_cb.otaEventCb = otaCb;
Qth_configSetEventCb(event_cb);

Qth_configGetEventCb

This function gets the user event callback function.

Prototype

oprt_ret Qth_configGetEventCb(Qth_eventCb_t *cb);

Parameter

Input Parameter
- None
Output Parameter
- Qth_eventCb_t * cb：User event callback function.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example of Invocation

Qth_eventCb_t userEventCb = {0};
Qth_configGetEventCb(&userEventCb);

Qth_configSetModuleVer

This function sets module's version number.

Prototype

oprt_ret Qth_configSetModuleVer(char *version);

Parameter

Input Parameter
- char * version: Module's version number for FOTA upgrades.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example of Invocation

Qth_configSetModuleVer("0.0.1");

Qth_configGetModuleVer

This function gets the module's version number.

Prototype

oprt_ret Qth_configGetModuleVer(char **version);

Parameter

Output Parameter
- char * version: Module's version number.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example of Invocation

char *moduleVer = NULL;

Qth_configGetModuleVer(&moduleVer);

Qth_configSetMcuVer

This function sets MCU version number.

Prototype

oprt_ret Qth_configSetMcuVer(Qth_mcuInfo_t *mcuList, quint16_t count);

Parameter

Input Parameter
- Qth_mcuInfo_t * mcuList: List of MCUs.
  - char * identity: MCU component ID.
  - char * version: MCU component version.
- quint16_t count: Number of MCUs.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example of Invocation

Qth_mcuInfo_t mcuList[2] = {0};
Quos_strcpy(mcuList[0].identity, "MCU1");
Quos_strcpy(mcuList[0].version, "0.0.5");
Quos_strcpy(mcuList[1].identity, "MCU2");
Quos_strcpy(mcuList[1].version, "0.0.6");
Qth_configSetMcuVer(mcuList, sizeof(mcuList) / sizeof(Qth_mcuInfo_t));

Qth_configGetMcuVer

This function gets the MCU version number.

Prototype

oprt_ret Qth_configGetMcuVer(Qth_mcuInfo_t **mcuList, quint16_t *count, char **mcuVer);

Parameter

Output Parameter
- Qth_mcuInfo_t * mcuList: List of MCUs.
  - char * identity: MCU component ID.
  - char * version: MCU component version.
- quint16_t * count: Number of MCUs.
- char * mcuVer: String type. MCU version number.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

Qth_mcuInfo_t *mcuList = NULL;
quint16_t mcuCount = 0;
char *mcuVer = NULL;

Qth_configGetMcuVer(&mcuList, &mcuCount, &mcuVer);

Qth_configSetWifiInfo

This function sets Wi-Fi information.

Prototype

oprt_ret Qth_configSetWifiInfo(const char *ssid, const char *pwd);

Parameter

Input Parameter
- const char * ssid: Wi-Fi SSID.
- const char * pwd: Wi-Fi password. If the password is empty, use "".
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

Qth_configSetWifiInfo("xxxxxxxx", "xxxxxxxxxxxx");

Qth_configGetWifiInfo

This function gets the Wi-Fi information.

Prototype

oprt_ret Qth_configGetWifiInfo(char *ssid, char *pwd);

Parameter

Output Parameter
- char * ssid: Wi-Fi SSID.
- char * pwd: Wi-Fi password.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

char ssid[QTH_WIFI_SSID_MAXSIZE + 1] = {0};
char pwd[QTH_WIFI_PWD_MAXSIZE + 1] = {0};

Qth_configGetWifiInfo(ssid, pwd);

Qth_configClearWifiInfo

This function clears Wi-Fi information.

Prototype

oprt_ret Qth_configClearWifiInfo();

Parameter

Input Parameter
- None
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

Qth_configClearWifiInfo();

Qth_configSetNetcfgMode

This function sets Wi-Fi network provisioning mode.

Prototype

oprt_ret Qth_configSetNetcfgMode(qbool enable, quint16_t timeout);

Parameter

Input Parameter
- qbool enable: If Wi-Fi information is not saved, enable the network provisioning.
- quint16_t timeout: Network provisioning timeout. Range: 180–600 or 0xffff (permanent). Default value: 300. Unit: second. When this parameter is set to 0xffff (permanent), the device will remain in the network provisioning mode until the network provisioning is successful.
Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

Qth_configSetNetcfgMode(TRUE, 300);

Qth_configGetNetcfgMode

This function gets the Wi-Fi network provisioning mode.

Prototype

oprt_ret Qth_configGetNetcfgMode(qbool *enable, quint16_t *timeout);

Parameter

Output Parameter
- qbool * enable: If Wi-Fi information is not saved, enable the network provisioning.
- quint16_t * timeout: Network provisioning timeout. Range: 180–600. Unit: second.

Return Value
- OPRT_OK: Successful execution
- Other values: Failed execution. See Error Code List for details.

Example

qbool enable = FALSE;
quint16_t timeout = 0;

Qth_configGetNetcfgMode(&enable, &timeout);

Error Code List

Enumeration Value	Hexadecimal	Decimal	Description
OPRT_OK	-0x0000	-0	Successful execution.
OPRT_COM_ERROR	-0x0001	-1	General error.
OPRT_INVALID_PARM	-0x0002	-2	Invalid parameter.
OPRT_MALLOC_FAILED	-0x0003	-3	Memory allocation failed.
OPRT_NOT_SUPPORTED	-0x0004	-4	Not supported.
OPRT_NOT_FOUND	-0x0005	-5	Object not found.
OPRT_INDEX_OUT_OF_BOUND	-0x0006	-6	Index out of bounds.
OPRT_EXCEED_UPPER_LIMIT	-0x0007	-7	Exceed upper limit.
OPRT_NOT_EXIST	-0x0008	-8	Not exist.
OPRT_QTH_CONFIG_READ_FAILED	-0x1000	-4096	Reading failed.
OPRT_QTH_CONFIG_WRITE_FAILED	-0x1001	-4097	Writing failed.
OPRT_QTH_CONFIG_SET_DEVINFO_FAILED	-0x1002	-4098	Failed to set device information.
OPRT_QTH_CONFIG_APPVER_STRDUMP_FAILED	-0x1003	-4099	Failed to set App version.
OPRT_QTH_CONFIG_DK_FORMT_FAILED	-0x1004	-4100	Failed to set DeviceKey format.
OPRT_QTH_CONFIG_MAC_GET_FAILED	-0x1005	-4101	Failed to get device MAC address.

MCU Simulator Quick Access

Example

IoT AT Command

Quick Access

Example

QTHSDK API

Quick Access

Example

QTHSDK API

Quick Access

Example

QTHSDK API

MCU Simulator Quick Access

Example

IoT AT Command

OTA Overview

OTA Upgrade Process

User Account

Device Addition

Device Management

Home Management

User Account

Device Addition

Device Management

Home Management

OpenAPI List

OpenAPI List

Product Configuration API ​

API Overview ​

API Description ​

Qth_configSetProductInfo ​

Qth_configGetProductInfo ​

Qth_configSetDeviceInfo ​

Qth_configGetDeviceInfo ​

Qth_configSetODOSInfo ​

Qth_configGetAuthType ​

Qth_configSetServer ​

Qth_configGetServer ​

Qth_configSetLifetime ​

Qth_configGetLifetime ​

Qth_configSetEventCb ​

Qth_configGetEventCb ​

Qth_configSetModuleVer ​

Qth_configGetModuleVer ​

Qth_configSetMcuVer ​

Qth_configGetMcuVer ​

Qth_configSetWifiInfo ​

Qth_configGetWifiInfo ​

Qth_configClearWifiInfo ​

Qth_configSetNetcfgMode ​

Qth_configGetNetcfgMode ​

Error Code List ​

Product Configuration API

API Overview

API Description

Qth_configSetProductInfo

Qth_configGetProductInfo

Qth_configSetDeviceInfo

Qth_configGetDeviceInfo

Qth_configSetODOSInfo

Qth_configGetAuthType

Qth_configSetServer

Qth_configGetServer

Qth_configSetLifetime

Qth_configGetLifetime

Qth_configSetEventCb

Qth_configGetEventCb

Qth_configSetModuleVer

Qth_configGetModuleVer

Qth_configSetMcuVer

Qth_configGetMcuVer

Qth_configSetWifiInfo

Qth_configGetWifiInfo

Qth_configClearWifiInfo

Qth_configSetNetcfgMode

Qth_configGetNetcfgMode

Error Code List