Documentation

Appearance

Product Configuration API ​

Product Configuration API Overview ​

FunctionDescription
Ql_iotInit()Initializes configurations and enables QuecThing.
Ql_iotConfigSetEventCB()Sets a callback function for device and Developer Center interaction event.
Ql_iotConfigSetConnmode()Sets the connection mode between the device and Developer Center.
Ql_iotConfigGetConnmode()Gets the connection mode between the device and Developer Center.
Ql_iotGetWorkState()Gets the connection status between the device and Developer Center.
Ql_iotConfigSetPdpContextId()Configures PDP context ID used by device to connect to Developer Center.
Ql_iotConfigGetPdpContextId()Gets the PDP context ID used by device to connect to Developer Center.
Ql_iotConfigSetServer()Sets server information.
Ql_iotConfigGetServer()Gets server information.
Ql_iotConfigSetLifetime()Sets device lifetime.
Ql_iotConfigGetLifetime()Gets device lifetime.
Ql_iotConfigSetProductinfo()Sets product information.
Ql_iotConfigGetProductinfo()Gets product information.
Ql_iotConfigSetMcuVersion()Sets MCU ID and the corresponding version number.
Ql_iotConfigGetMcuVersion()Gets MCU ID and the corresponding version number.
Ql_iotConfigSetSessionFlag()Enables or disables encryption mode for the connection between the device and Developer Center.
Ql_iotConfigGetSessionFlag()Queries the encryption mode of the connection between the device and Developer Center.
Ql_iotConfigSetAppVersion()Sets device software version ID.
Ql_iotConfigGetSoftVersion()Gets device software version ID.
Ql_iotConfigSetDkDs()Sets the customized DeviceKey and DeviceSecret.
Ql_iotConfigGetDkDs()Gets the customized DeviceKey and DeviceSecret.

API Description ​

Ql_iotInit ​

This function initializes configurations and enables QuecThing.

Prototype

c
void Ql_iotInit(void)

Parameter

None

Return Value

None

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Ql_iotConfigSetEventCB ​

This function sets callback function for the device and Developer Center interaction event (The callback function must be registered before you connect the device to Developer Center).

Prototype

c
void Ql_iotConfigSetEventCB(void (*eventCb)(quint32_t event, qint32_t errcode, const void *v
alue, quint32_t valLen))

Parameter

Return Value

None

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
Ql_iotConfigSetEventCB(Ql_iotEventCB);

Ql_iotConfigSetConnmode ​

This function sets the connection mode between the device and Developer Center. You can configure the connection mode before enabling QuecThing or while QuecThing is running.

Prototype

c
void Ql_iotConfigSetConnmode(QIot_connMode_e mode)

Parameter

  • Input

Return Value

None

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
Ql_iotConfigSetConnmode(1);

Ql_iotConfigGetConnmode ​

This function gets the connection mode between the device and Developer Center.

Prototype

c
QIot_connMode_e Ql_iotConfigGetConnmode(void)

Parameter

None

Return Value

Connection mode. See QIot_connMode_e for details.

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
QIot_connMode_e ConnMode = Ql_iotConfigGetConnmode();

Ql_iotGetWorkState ​

This function gets the connection status between the device and Developer Center.

Prototype

c
QIot_state_e Ql_iotGetWorkState(void)

Parameter

None

Return Value

Connection status. See QIot_state_e for details.

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
QIot_state_e status = Ql_iotGetWorkState();

Ql_iotConfigSetProductinfo ​

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

Prototype

c
qbool Ql_iotConfigSetProductinfo(const char *pk, const char *ps)

Parameter

  • Input
    • 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

  • True: Successful execution
  • False: Failed execution

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
qbool ret = Ql_iotConfigSetProductinfo("pxxxxS", "VnhyxxxxxxxxSTFh");

Ql_iotConfigGetProductinfo ​

This function gets product information.

Prototype

c
qbool Ql_iotConfigGetProductinfo(char **pk, char **ps, char **ver)

Parameter

  • Output
    • char **  pk: ProductKey generated when you create the product on Developer Center.
    • char **  ps: ProductSecret generated when you create the product on Developer Center.
    • char **  ver: Protocol version used during the device authentication process.

Return Value

None

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
char *pk, *ps, *ver;
qbool ret = Ql_iotConfigGetProductinfo(&pk, &ps, &ver);

Ql_iotConfigSetServer ​

This function sets server information.

Prototype

c
qbool Ql_iotConfigSetServer(QIot_protocolType_t type, const char *server_url)

Parameter

  • Input

    • QIot_protocolType_t  type: Protocol type. Optional parameter. See QIot_protocolType_t for details.

    • const char *      server_url: Server address (domain name and port of Developer Center). Optional parameter.

      • Default : "mqtt://iot-south.acceleronix.io:1883"
      regionserver URL
      Non-encrypted in Chinamqtt://iot-south.quectelcn.com:1883
      Encryption in Chinamqtts://iot-south.quectelcn.com:8883
      Non-encrypted in Europemqtt://iot-south.acceleronix.io:1883
      Encryption in Europemqtts://iot-south.acceleronix.io:8883

Return Value

  • True: Successful execution
  • False: Failed execution

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
qbool ret = Ql_iotConfigSetServer(1,"xxx");

Domain name in China: mqtt://iot-south.quectelcn.com:1883
Domain name in Europe: mqtt://iot-south.acceleronix.io:1883

Ql_iotConfigGetServer ​

This function gets server information.

Prototype

c
void Ql_iotConfigGetServer(QIot_protocolType_t *type, char **server_url)

Parameter

  • Output
    • QIot_protocolType_t *  type: Protocol type. See QIot_protocolType_t for details.
    • char **          server_url: Server URL.

Return Value

None

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
QIot_protocolType_t type;
char *url;
Ql_iotConfigGetServer(&type, &url);

Ql_iotConfigSetLifetime ​

This function sets device lifetime.

Prototype

c
qbool Ql_iotConfigSetLifetime(quint32_t lifetime)

Parameter

  • Input
    • quint32_t  lifetime: Device lifetime. Unit: second. Optional parameter. Default value is used if this parameter is omitted. Range: 1–65535; Default value: 120.

Return Value

  • True：Successful execution
  • False：Failed execution

NOTE

  • This function is supported in SDK version 2.3.3 and above. The API does not check input value validity.

Example

c
qbool ret = Ql_iotConfigSetLifetime(120);

Ql_iotConfigGetLifetime ​

This function gets device lifetime.

Prototype

c
quint32_t Ql_iotConfigGetLifetime(void)

Parameter

None

Return Value

Device lifetime. Unit: second.

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
quint32_t lifetime = Ql_iotConfigGetLifetime();

Ql_iotConfigSetPdpContextId ​

This function configures the PDP context ID used by device to connect to Developer Center.

Prototype

c
qbool Ql_iotConfigSetPdpContextId(quint8_t contextID)

Parameter

  • Input
    • quint32_t  contextID: PDP context ID. Optional parameter. Default value 1 is used if this parameter is omitted.

Return Value

  • True：Successful execution
  • False：Failed execution

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
qbool ret = Ql_iotConfigSetPdpContextId(1);

Ql_iotConfigGetPdpContextId ​

This function gets the PDP context ID used by device to connect to Developer Center.

Prototype

c
quint8_t Ql_iotConfigGetPdpContextId(void)

Parameter

None

Return Value

PDP context ID used by device to connect to Developer Center.

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
quint8_t contextid = Ql_iotConfigGetPdpContextId();

Ql_iotConfigSetSessionFlag ​

This function enables or disables encryption mode for the connection between the device and Developer Center.

Prototype

c
qbool Ql_iotConfigSetSessionFlag(qbool flag)

Parameter

  • Input
    • qbool  flag: Enable or disable encryption mode of the session between the device and Developer Center. Optional parameter. Default value is used if this parameter is omitted.
      • FALSE: Disable (Default)
      • TRUE: Enable

Return Value

  • True：Successful execution
  • False：Failed execution

NOTE

  • This function is supported in SDK version 2.7.2 and above.

Example

c
qbool ret = Ql_iotConfigSetSessionFlag(1);

Ql_iotConfigGetSessionFlag ​

This function queries whether the encryption mode of the connection between the device and Developer Center is enabled.

Prototype

c
qbool Ql_iotConfigGetSessionFlag(void)

Parameter

None

Return Value

  • True: Enabled
  • False: Disabled

NOTE

  • This function is supported in SDK version 2.7.2 and above.

Example

c
qbool ret = Ql_iotConfigGetSessionFlag();

Ql_iotConfigSetAppVersion ​

This function sets device software version ID.

Prototype

c
qbool Ql_iotConfigSetAppVersion(const char *appVer)

Parameter

  • Input
    • const char *  appVer: Device software version ID.

Return Value

  • True：Successful execution
  • False：Failed execution

NOTE

  • This function is supported in SDK version 2.8.1 and above.

Example

c
qbool ret = Ql_iotConfigSetAppVersion("app");

Ql_iotConfigGetSoftVersion ​

This function gets device software version ID.

Prototype

c
char *Ql_iotConfigGetSoftVersion(void)

Parameter

None

Return Value

Device software version ID.

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
char *ver = Ql_iotConfigGetSoftVersion();

Ql_iotConfigSetMcuVersion ​

This function sets MCU ID and the corresponding version number, which should be configured by the external MCU.

Prototype

c
qbool Ql_iotConfigSetMcuVersion(const char *compno, const char *version)

Parameter

  • Input
    • const char *  compno: MCU ID. Maximum length: 32 bytes.
    • const char *  version: Version number corresponding to the MCU ID. Maximum length: 64 bytes.

Return Value

  • True：Successful execution
  • False：Failed execution

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
qbool ret = Ql_iotConfigSetMcuVersion("MCU","1_0_0");

Ql_iotConfigGetMcuVersion ​

This function gets MCU ID and the corresponding version number.

Prototype

c
quint32_t Ql_iotConfigGetMcuVersion(const char *compno, char **version)

Parameter

  • Input

    • const char *  compno: MCU ID. All configured MCU information will be acquired if this parameter is set to NULL.

  • Output

    • char **   version: Version number corresponding to the MCU ID. Maximum length: 64 bytes.

Return Value

The string length of the version number corresponding to the MCU ID.

NOTE

  • This function is supported in SDK version 2.3.3 and above.

Example

c
char *arg[]
char *oldVer = NULL;
quint32_t ret = Ql_iotConfigGetMcuVersion(arg[0], &oldVer);

Ql_iotConfigSetDkDs ​

This function sets the customized DeviceKey and DeviceSecret.

Prototype

c
qbool Ql_iotConfigSetDkDs(const char *dk, const char *ds)

Parameter

  • Input
    • 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 DA, and use the default configurations. In that case, the device needs to be reauthenticated by Developer Center.
    • const char *   ds: DeviceSecret generated after device authentication. The length is fixed to 32 bytes. DS can be configured only upon customizing DK.

Return Value

  • True：Successful execution
  • False：Failed execution

NOTE

  • This function is supported in SDK version 2.8.1 and above.

Example

c
qbool ret = Ql_iotConfigSetDkDs("B07xxxxxx2A3","VnhyXXXXXXSTFh");

Ql_iotConfigGetDkDs ​

This function gets the customized DeviceKey and DeviceSecret. This function only queries the DeviceKey customized by Ql_iotConfigSetDkDs().

Prototype

c
qbool Ql_iotConfigGetDkDs(char **dk, char **ds)

Parameter

  • Output
    • char ** dk: Customized DK.
    • char **   ds: Customized DS.

Return Value

  • True：Successful execution
  • False：Failed execution

NOTE

  • This function is supported in SDK version 2.8.1 and above.

Example

c
char *dk = NULL, *ds = NULL;
Ql_iotConfigGetDkDs(&dk, &ds);

Enumeration ​

  • QIot_state_e (Connection status between the device and Developer Center)

    Enumeration Definition

    c
    typedef enum { 
QIOT_STATE_UNINITIALIZE = 0, 
QIOT_STATE_INITIALIZED, 
QIOT_STATE_AUTHENTICATING, 
QIOT_STATE_AUTHENTICATED, 
QIOT_STATE_AUTHENTICATE_FAILED, 
QIOT_STATE_CONNECTING, 
QIOT_STATE_CONNECTED, 
QIOT_STATE_CONNECT_FAIL, 
QIOT_STATE_SUBSCRIBED, 
QIOT_STATE_SUBSCRIBE_FAIL, 
QIOT_STATE_DISCONNECTING, 
QIOT_STATE_DISCONNECTED, 
QIOT_STATE_DISCONNECT_FAIL
} QIot_state_e;

    Member

    NumberMemberDescription
    0QIOT_STATE_UNINITIALIZEUninitialized
    1QIOT_STATE_INITIALIZEDInitialized
    2QIOT_STATE_AUTHENTICATINGAuthenticating
    3QIOT_STATE_AUTHENTICATEDAuthenticated
    4QIOT_STATE_AUTHENTICATE_FAILEDAuthentication failed
    5QIOT_STATE_CONNECTINGRegistering
    6QIOT_STATE_CONNECTEDRegistered and is waiting to subscribe
    7QIOT_STATE_CONNECT_FAILRegistration failed
    8QIOT_STATE_SUBSCRIBEDSubscribed and data can be sent
    9QIOT_STATE_SUBSCRIBE_FAILSubscription failed
    10QIOT_STATE_DISCONNECTINGDeregistering
    11QIOT_STATE_DISCONNECTEDDeregistered
    12QIOT_STATE_DISCONNECT_FAILDeregistration failed

  • QIot_connMode_e (Connection mode between the device and Developer Center)

    Enumeration Definition

    c
    typedef enum { 
	QIOT_CONNMODE_IDLE, /* Log out from or do not connect to Developer Center */ 
	QIOT_CONNMODE_REQ, /* Request to connect to Developer Center*/ 
} QIot_connMode_e;

    Member

    MemberDescription
    QIOT_CONNMODE_IDLELog out from or do not connect to Developer Center
    QIOT_CONNMODE_REQRequest to connect to Developer Center

  • QIot_protocolType_t (Protocol type)

    Enumeration Definition

    c
    typedef enum
{
  QIOT_PPROTOCOL_COAP = 0,
	QIOT_PPROTOCOL_MQTT = 1,
} QIot_protocolType_t;

    Member

    MemberDescription
    QIOT_PPROTOCOL_MQTTMQTT