Documentation

Appearance

Gateway Sub-device API ​

Gateway Sub-device API Overview ​

FunctionDescription
Ql_iotConfigSetSubDevEventCB()Registers the callback function for the interaction event between the sub-device and the gateway.
Ql_iotSubDevConn()Connects sub-device to gateway or authenticates sub-device.
Ql_iotSubDevDisconn()Disconnects the sub-device from the gateway.
Ql_iotSubDevPassTransSend()Sends transparent tranmission data of the sub-device to Developer Center.
Ql_iotSubDevPassTransSend_ex()Sends transparent tranmission data of the sub-device to Developer Center.
Ql_iotSubDevTslReport()Sends TSL data of sub-device to Developer Center.
Ql_iotSubDevTslReport_ex()Sends TSL data of sub-device to Developer Center.
Ql_iotSubDevTslAck()Replies to TSL data requested by Developer Center to the sub-device.
Ql_iotSubDevDeauth()De-registers the sub-device.
Ql_iotSubDevHTB()Refreshes the last interaction time between sub-device and gateway.
Ql_iotGwDevInfoReport()Report Sub-device Information.
Ql_iotGwDevOtaReq()Request Sub-device OTA Upgrade Pla.
Ql_iotGwDevOtaUpdate()Configure Sub-device OTA Upgrade Operations.
Ql_iotGwDevOtaRead()Read Sub-device OTA Firmware Data.
Ql_iotGwDevLocReport()Report Sub-device Location Data.

API Description ​

Ql_iotConfigSetSubDevEventCB ​

This function registers the callback function for the interaction event between the sub-device and the gateway. Subsequent interaction events between the sub-device and the gateway are notified through this callback function.

Prototype

c
void Ql_iotConfigSetSubDevEventCB(void (*eventCb));

Parameter

  • Callback function
    • void *  eventCb: Callback function for the interaction events between the sub-device and the gateway after the sub-device connects to the gateway.

      • Prototype

        c
        typedef void (*eventCb)(quint32_t event, qint32_t errcode, const char *subPk, const char *subDk ,const void *value, quint32_t valLen)
        • Input
          • quint32_t    event: Event identifier.
          • quint32_t    errcode: Event code.
          • const char * subPk: ProductKey generated when a product is created on Developer Center.
          • const char *  subDk: Unique identifier of the sub-device.
          • const void * value: Callback data.
          • quint32_t     valLen: Length of the callback data.

Return Value

None

NOTE

Example

c
Ql_iotConfigSetSubDevEventCB(Ql_iotSubEventCB);

Ql_iotSubDevConn ​

This function connects a sub-device to a gateway or authenticates a sub-device. The connection/authentication result is notified by the sub-device and gateway callback event. When subDS is set to NULL, it means to authenticate the sub-device; when subDS is specified, it means to connect the sub-device to the gateway.

Prototype

c
qbool Ql_iotSubDevConn(const char *subPk, const char *subPs, const char *subDk, const char *subDs, quint8_t sessionType, quint16_t keepalive)

Parameter

  • Input
    • const char *  subPk: ProductKey generated when a product is created on Developer Center.
    • const char *  subPs: ProductSecret generated when a product is created on Developer Center.
    • const char *  subDk: Unique identifier of the sub-device.
    • const char *   subDs: The device secret of the sub-device.
    • quint8_t    sessionType: Encryption method of data interaction of the sub-device.
      • 0: Not encrypted.
      • 1: Encrypted.
    • quint16_t    keepalive: Keepalive time of the sub-device.

Return Value

  • True: Successful execution
  • False: Failed execution

NOTE

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

Example

c
mp_buffer_info_t pro_keyinfo = {0};
mp_buffer_info_t pro_secretinfo = {0};
mp_buffer_info_t dev_keyinfo = {0};
mp_buffer_info_t dev_secretinfo = {0};
int session_type_val;
int keepalive_val;
qbool ret = Ql_iotSubDevConn((const char *)pro_keyinfo.buf, (const char *)pro_secretinfo.buf, (const char *)dev_keyinfo.buf, (const char *)dev_secretinfo.buf, session_type_val, keepalive_val);

Ql_iotSubDevDisconn ​

This function disconnects the sub-device from the gateway.

Prototype

c
qbool Ql_iotSubDevDisconn(const quint8_t *subPk, const quint8_t *subDk)

Parameter

  • Input
    • const quint8_t *  subPk: ProductKey generated when a product is created on Developer Center.
    • const quint8_t *  subDk: Unique identifier of the sub-device.

Return Value

  • True: Successful execution
  • False: Failed execution

NOTE

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

Example

c
mp_buffer_info_t pro_key = {0};
mp_buffer_info_t dev_key = {0};
qbool ret = Ql_iotSubDevDisconn((const char *)pro_key.buf, (const char *)dev_key.buf);

Ql_iotSubDevDeauth ​

This function de-registers the sub-device.

Prototype

c
qbool Ql_iotSubDevDeauth(const char *subPk, const char *subPs, const char *subDk, const char *subDs)

Parameter

  • Input
    • const char *  subPk: ProductKey generated when a product is created on Developer Center.
    • const char *  subPs: ProductSecret generated when a product is created on Developer Center.
    • const char *  subDk: Unique identifier of the sub-device.
    • const char *  subDs: The device secret of the sub-device.

Return Value

  • True: Successful execution
  • False: Failed execution

NOTE

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

Example

c
mp_buffer_info_t pro_key = {0};
mp_buffer_info_t pro_secret = {0};
mp_buffer_info_t dev_key = {0};
mp_buffer_info_t dev_secret = {0};
qbool ret = Ql_iotSubDevDeauth((const char *)pro_key.buf, (const char *)pro_secret.buf, (const char *)dev_key.buf, (const char *)dev_secret.buf);

Ql_iotSubDevPassTransSend ​

This function sends transparent transmission data of the sub-device to Developer Center. (It is recommended to call Ql_iotSubDevPassTransSend_ex.)

Prototype

c
qbool Ql_iotSubDevPassTransSend(const quint8_t *subPk, const quint8_t *subDk, quint8_t *payload, quint16_t payloadlen)

Parameter

  • Input
    • const quint8_t *  subPk: ProductKey generated when a product is created on Developer Center.
    • const quint8_t *  subDk: Unique identifier of the sub-device.
    • quint8_t *     payload: Pointer to the transparent transmission data to be reported.
    • quint16_t *     payloadlen: Length of the transparent transmission data to be reported.

Return Value

  • True: Successful execution
  • False: Failed execution

NOTE

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

Example

c
char *subPk;
char *subDk;
Ql_iotSubDevPassTransSend(subPk, subDk, "hello world", HAL_STRLEN("hello world"));

Ql_iotSubDevPassTransSend_ex ​

This function sends transparent transmission data of the sub-device to Developer Center.

Prototype

c
qint32_t Ql_iotSubDevPassTransSend_ex(const quint8_t *subPk, const quint8_t *subDk, quint8_t *payload, quint16_t payloadlen)

Parameter

  • Input
    • const quint8_t *  subPk: ProductKey generated when a product is created on Developer Center.
    • const quint8_t *  subDk: Unique identifier of the sub-device.
    • quint8_t *     payload: Pointer to the transparent transmission data to be reported.
    • quint16_t *     payloadlen: Length of the transparent transmission data to be reported.

Return Value

  • -1: Failed execution
  • 1–65535: The message txid reported when the function is executed successfully.

NOTE

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

Example

c
char *subPk;
char *subDk;
Ql_iotSubDevPassTransSend_ex(subPk, subDk, "hello world", HAL_STRLEN("hello world"));

Ql_iotSubDevTslReport ​

This function sends TSL data of sub-device to Developer Center. (It is recommended to call Ql_iotSubDevTslReport_ex.)

Prototype

c
qbool Ql_iotSubDevTslReport(const char *subPk, const char *subDk, const void *ttlvHead)

Parameter

  • Input
    • const char *  subPk: ProductKey generated when a product is created on Developer Center.
    • const char *  subDk: Unique identifier of the sub-device.
    • const void *  ttlvHead: Pointer to TTLV data chain header.

Return Value

  • True: Successful execution
  • False: Failed execution

NOTE

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

Example

c
void *ttlvHead = NULL;
char *subPk = NULL;
char *subDk = NULL;
Ql_iotSubDevTslReport(subPk,subDk,ttlvHead);

Ql_iotSubDevTslReport_ex ​

This function sends TSL data of sub-device to Developer Center.

Prototype

c
qint32_t Ql_iotSubDevTslReport_ex(const char *subPk, const char *subDk, const void *ttlvHead)

Parameter

  • Input
    • const char *  subPk: ProductKey generated when a product is created on Developer Center.
    • const char *  subDk: Unique identifier of the sub-device.
    • const void *  ttlvHead: Pointer to TTLV data chain header.

Return Value

  • -1: Failed execution
  • 1–65535: The message txid reported when the function is executed successfully.

NOTE

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

Example

c
void *ttlvHead = NULL;
char *subPk = NULL;
char *subDk = NULL;
Ql_iotSubDevTslReport_ex(subPk,subDk,ttlvHead);

Ql_iotSubDevTslAck ​

This function replies to TSL data requested by Developer Center to the sub-device.

Prototype

c
qbool Ql_iotSubDevTslAck(const char *subPk, const char *subDk, quint16_t pkgId, const void *ttlv Head)

Parameter

  • Input
    • const char *  subPk: ProductKey generated when a product is created on Developer Center.
    • const char *  subDk: Unique identifier of the sub-device.
    • quint16_t    pkgId: The replied TTLV package ID. The ID is obtained through the event.
    • const void *  ttlvHead: Pointer to TTLV data chain header.

Return Value

  • True: Successful execution
  • False: Failed execution

NOTE

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

Example

c
char *subPk = NULL;
char *subDk = NULL;
quint16_t pkgId ;
void *ttlvHead = NULL;
Ql_iotSubDevTslAck(subPk, subDk, pkgId, ttlvHead);
Ql_iotTtlvFree(&ttlvHead);

Ql_iotSubDevHTB ​

This function refreshes the last interaction time between a sub-device and a gateway.

Prototype

c
qbool Ql_iotSubDevHTB(const char *subPk, const char *subDk)

Parameter

  • Input
    • const char *  subPk: ProductKey generated when a product is created on Developer Center.
    • const char *  subDk: Unique identifier of the sub-device.

Return Value

  • True: Successful execution
  • False: Failed execution

NOTE

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

Example

c
mp_buffer_info_t pro_key = {0};
mp_buffer_info_t dev_key = {0};
qbool ret = Ql_iotSubDevHTB((const char *)pro_key.buf, (const char *)dev_key.buf);

 

Ql_iotGwDevInfoReport ​

This function reports the sub-device information.

Prototype

c
qbool Ql_iotGwDevInfoReport(const char *subPk, const char *subDk, const char *subVer)

Parameter

  • Input
    • const char * subPk: ProductKey generated when a product is created.
    • const char * subDk: The unique ID of a sub-device.
    • const char * subVer: Sub-device version.

Return Value

  • True: Successful execution
  • False: Failed execution

NOTE

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

Example

c
qbool ret = Ql_iotGwDevInfoReport("p1112k","12345678");

 

Ql_iotGwDevOtaReq ​

This function requests a sub-device OTA upgrade plan.

Prototype

c
qbool Ql_iotGwDevOtaReq(const char *subPk,const char *subDk,const char *subVer, quint8_t mode)

Parameter

  • Input
    • const char * subPk: ProductKey generated when a product is created.
    • const char * subDk: The unique ID of a sub-device.
    • const char * subVer: Sub-device version.
    • quint8_t mode: Sub-device communication mode.
      • 0 : – Neither SHA256 information nor an outgoing URL is required.
      • 1 : – SHA256 information is required, but no outgoing URL is required.
      • 2 : – No SHA256 information is required, but an outgoing URL is required.
      • 3 : – Both SHA256 information and an outgoing URL are required.

Return Value

  • True: Successful execution
  • False: Failed execution

NOTE

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

Example

c
qbool ret = Ql_iotGwDevOtaReq("p1112k","12345678","1_0_0",0);

 

Ql_iotGwDevOtaUpdate ​

This function configures the sub-device OTA upgrade operations.

Prototype

c
qbool Ql_iotGwDevOtaUpdate(const char *subPk, const char *subDk, const char *subVer, quint8_t action)

Parameter

  • Input
    • const char * subPk: ProductKey generated when a product is created.
    • const char * subDk: The unique ID of a sub-device.
    • const char * subVer: Sub-device version.
    • quint8_t action: Sub-device OTA upgrade operations.
      • 0– Refuse the upgrade
      • 1– Confirm the upgrade
      • 3– Report the status of "Upgrading"
      • 4– Report the status of "Upgraded"
      • 5– Report the status of "Upgrade Failed"

Return Value

  • True: Successful execution
  • False: Failed execution

NOTE

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

Example

c
qbool ret = Ql_iotGwDevOtaUpdate("p1112k","12345678","1_0_0",1);

 

Ql_iotGwDevOtaRead ​

This function downloads the sub-device firmware data according to the URL provided by the platform and transfers the data to users.

Prototype

c
qint32_t Ql_iotGwDevOtaRead(const char *subPk, const char *subDk, quint32_t startAddr, quint16_t size, quint8_t *buff)

Parameter

  • Input
    • const char * subPk: ProductKey generated when a product is created.
    • const char * subDk: The unique ID of a sub-device.
    • const char * startAddr: The start address of downloading the firmware.
    • quint8_t size: Maximum length of the firmware data read this time.
    • quint8_t buff: Buffer pointer of the firmware data read this time.

Return Value

NOTE

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

Example

c
quint8_t buff[1024] = {0};
qbool ret = Ql_iotGwDevOtaRead("p1112k","12345678",0,1024,buff);

 

Ql_iotGwDevLocReport ​

This function reports the sub-device location data.

Prototype

c
qbool Ql_iotGwDevLocReport(const char *subPk, const char *subDk,const void *ttlvHead)

Parameter

  • Input
    • const char * subPk: ProductKey generated when a product is created.
    • const char * subDk: The unique ID of a sub-device.
    • const char * ttlvHead: Location data in TTLV format.

Return Value

  • True: Successful execution
  • False: Failed execution

NOTE

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

Example

c
void *ttlvHead = NULL;
Ql_iotTtlvIdAddString(&ttlvHead,0,"$GPGGA,042523.0,3413.610533,N,10854.063257,E,1,05,2.6,438.5,M,-28.0,M,,*78");
qbool ret = Ql_iotGwDevLocReport("p1112k","12345678",ttlvHead);
Ql_iotTtlvFree(&ttlvHead);