Product Configuration API

API Overview

Function	Description
Qth.setProductInfo()	Sets the product information.
Qth.setServer()	Sets the server URL.
Qth.setLifetime()	Sets the keep alive interval of the MQTT connection.
Qth.setEventCb()	Sets the event callback function.
Qth.setMcuVer()	Sets the MUC version information.
Qth.setAppVer()	Sets the App (QuecPython script) version Information.

API Description

Qth.setProductInfo

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

Prototype

python

Qth.setProductInfo(pk, ps)

Parameter

Input Parameter
- pk: ProductKey generated when you create the product on Developer Center.
- ps: ProductSecret generated when you create the product on Developer Center.
Output Parameter
- None
Return Value
- True: Successful execution
- False: Failed execution

Example

python

Qth.setProductInfo("xxxxxx", "xxxxxxxxxxxxxxxx")

Qth.setServer

This function sets the server URL.

Prototype

python

Qth.setServer(url)

Parameter

Input Parameter

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
Not-encrypted in China	mqtt://iot-south.quectelcn.com:1883
Encrypted in China	mqtts://iot-south.quectelcn.com:8883
Not-encrypted in Europe	mqtt://iot-south.acceleronix.io:1883
Encrypted in Europe	mqtts://iot-south.acceleronix.io:8883

Output Parameter
- None
Return Value
- True: Successful execution
- False: Failed execution

Example

python

Qth.setServer("mqtts://iot-south.quectelcn.com:8883")

Qth.setLifetime

This function sets the keep alive interval of the MQTT connection.

Prototype

python

Qth.setLifetime(lifetime)

Parameter

Input Parameter
- lifetime: Keep alive interval of the MQTT connection. Range: 21–600. Default value: 120. Unit: second.
Output Parameter
- None
Return Value
- True: Successful execution
- False: Failed execution

Example

python

Qth.setLifetime(120)

Qth.setEventCb

This function sets the event callback function.

Prototype

python

Qth.setEventCb(eventlist)

Parameter

Input Parameter
- eventlist: User’s event callback function.
  - devEvent: Device event callback function.
    - Prototype
      c
      devEventCb(event, result)
    - Input Parameter
      - event: Event type
        Value Description
        1 Network connection event
        2 Device and platform interaction event
        3 Device reset event
      - result: Event code.
        0: Successful execution
        Other values: Failed execution. See Error Code List.
  - recvTsl: Callback function of receiving TSL data.
    - Prototype
      c
      recvTslCb(value)
    - Input Parameter
      - value: Dictionary type. TSL data.
  - readTsl: Callback function of TSL data requests.
    - Prototype
      c
      readTslCb(ids, pkgId)
    - Input Parameter
      - ids: Array type.TSL ID.
      - pkgId: Data packet ID.
  - readTslServer: Callback function of TSL service requests.
    - Prototype
      c
      readTslServerCb(serverId, value, pkgId)
    - Input Parameter
      - serverId: TSL service ID.
      - value: TSL data in JSON format.
      - pkgId: Data packet ID.
  - recvTrans: Callback function of receiving transparent transmission data.
    - Prototype
      c
      recvTransCb(value)
    - Input Parameter
      - value: Transparent transmission data.
  - ota: Callback function of OTA events.
    - otaPlan: Callback function of issuing OTA upgrade plans.
      - Prototype
        c
        otaPlanCb(plans)
      - Input Parameter
        plans: Array type. Issued OTA upgrade plan. Multiple OTA upgrade plans may exist at the same time. The data included in the array is as follows.
        python
        [(Component type, Component ID, Source version, target version, Minimum power required for an OTA upgrade, Disk space required for an OTA upgrade, Minimum signal strength in an OTA upgrade),(Component type, Component ID, Source version, target version, Minimum power required for an OTA upgrade, Disk space required for an OTA upgrade, Minimum signal strength in an OTA upgrade)...]
    - fotaResult: Callback function of OTA upgrade results.
      - Prototype
        c
      fotaResultCb(comp_no, result)
      * __Input Parameter__ * __`comp_no`__: Component ID. * __`result`__: Upgrade result. * `True`: Successful execution * `False`: Failed execution
Output Parameter
- None
Return Value
- None

Value	Description
1	Network connection event
2	Device and platform interaction event
3	Device reset event

Example

python

def App_devEventCb(event, result):
    print('event:', event, result)
    if(2== event and 0 == result):
        Qth.otaRequest()

def App_cmdRecvTransCb(value):
    print('recvTrans:', value)
    ret = Qth.sendTrans(1, value)
    print('sendTrans ret:', ret)

def App_cmdRecvTslCb(value):
    print('recvTsl:', value)
    ret = Qth.sendTsl(1, value)
    print('sendTsl ret:', ret)

def App_cmdReadTslCb(ids, pkgId):
    print('readTsl:', ids, pkgId)
    value = {1:10,2:'hello'}
    Qth.ackTsl(0, value, pkgId)

def App_cmdRecvTslServerCb(serverId, value, pkgId):
    print('recvTslServer:', serverId, value, pkgId)
    Qth.ackTslServer(1, serverId, value, pkgId)

def App_otaPlanCb(plans):
    print('otaPlan:', plans)
    Qth.otaAction(1)

def App_fotaResultCb(comp_no, result):
    print('fotaResult:', comp_no, result)

eventOtaCb={
            'otaPlan':App_otaPlanCb,
            'fotaResult':App_fotaResultCb
            }
eventCb={
    'devEvent':App_devEventCb, 
    'recvTrans':App_cmdRecvTransCb, 
    'recvTsl':App_cmdRecvTslCb, 
    'readTsl':App_cmdReadTslCb, 
    'readTslServer':App_cmdRecvTslServerCb,
    'ota':eventOtaCb
    }
Qth.setEventCb(eventCb)

Qth.setMcuVer

This function sets the MCU version.

Prototype

python

Qth.setMcuVer(comp_no, version, infoCB, resultCB)

Parameter

Input Parameter
- comp_no: MCU component ID.
- version: MCU component version.
- infoCB: Callback function of SOTA upgrade information.
  - Prototype
    c
```
infoCB(comp_no, version, url, md5, crc)
```
  - Input Parameter
    - comp_no: Component ID.
    - version: Target version.
    - url: Firmware download URL.
    - md5: MD5 value of the firmware package (32-byte lowercase letters).
    - crc: CRC32 value of the firmware version (MPEG-2).
- resultCB: Callback function of SOTA upgrade result.
  - Prototype
    c
```
resultCB(comp_no, result)
```
  - Input Parameter
    - comp_no: Component ID.
    - result: Upgrade result.
      - True: Successful execution
      - False: Failed execution
Output Parameter
- None
Return Value
- None

Example

python

def App_sotaInfoCb(comp_no, version, url, md5, crc):
    print('sotaInfo:', comp_no, version, url, md5, crc)
    # After the firmware is downloaded via the URL and the MCU has been updated, Qth.setMcuVer() must be called to get and update the latest version information of the MCU.
    # Qth.setMcuVer('MCU1', 'V1.2', App_sotaInfoCb, App_sotaResultCb)

def App_sotaResultCb(comp_no, result):
    print('sotaResult:',comp_no, result)

Qth.setMcuVer('MCU1', 'V1.1', App_sotaInfoCb, App_sotaResultCb)
Qth.setMcuVer('MCU2', 'V2.1', App_sotaInfoCb, App_sotaResultCb)

Qth.setAppVer

This function sets App (QuecPython script) version information.

Prototype

python

Qth.setAppVer(version, resultCB)

Parameter

Input Parameter
- version: App component version.
- resultCB: Callback function of the App upgrade results.
  - Prototype
    c
```
resultCB(comp_no, result)
```
  - Input Parameter
    - comp_no: Component ID.
    - result: Upgrade result.
      - True: Successful execution
      - False: Failed execution
Output Parameter
- None
Return Value
- None

Example

python

Qth.setAppVer('V1.0.1', App_sotaResultCb)

Error Code List

Enumeration Value	Description
-5888	Exceptions occurred for some server APIs.
-5889	Device messages are limited.
-5890	The device cannot be activated.
-5891	The device has been authenticated.
-5892	No product information is found via the ProductKey.
-5893	Password parsing error.
-5894	Sign error.
-5895	Rand is illegal.
-5896	The passed DeviceKey and ProductKey are inconsistent with those stored in the database.
-5897	DeviceKey is illegal.
-5898	Flag is illegal.
-5899	ClientID is not matched with the password.
-5900	DeviceSecret is incorrect.
-5901	Device information not found.
-5902	The gateway is not associated with the sub-device.
-5903	The sub-device is already online.
-5904	Device offline
-5905	Unknown error
-5906	Static devices cannot be authenticated.
-5907	Reinitiate the connection.
-5908	Actively close the connection.
-4352	Failed to get the configuration.
-4353	Device not authenticated.
-4354	Device connection failed.
-4355	Device reset failed.
-4356	Failed to delete the device.
-4357	Device connected.
-4358	Device reset error (New DeviceSecret has been received for the device with unique-certificate-per-device authentication).
-17920	MQTT internal error.
-17921	MQTT network error.
-17922	MQTT keep-alive interval error.
-17923	MQTT subscription error.
-17924	MQTT connection error.
-17925	Unsupported MQTT protocol.
-17926	MQTT identifier rejected.
-17927	Unavailable MQTT server.
-17928	Incorrect MQTT username or password.
-17929	MQTT unauthorized.
-17930	URL parsing failed.
-17931	Failed to get the module’s IP address.
-17932	Failed to build data packets.
-17933	Failed to send data packets.

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.setProductInfo ​

Qth.setServer ​

Qth.setLifetime ​

Qth.setEventCb ​

Qth.setMcuVer ​

Qth.setAppVer ​

Error Code List ​

Product Configuration API

API Overview

API Description

Qth.setProductInfo

Qth.setServer

Qth.setLifetime

Qth.setEventCb

Qth.setMcuVer

Qth.setAppVer

Error Code List