Example of Sub-device Quick Access

Description

The capability of the gateway is to convert the communication protocols between different devices, allowing sub-devices that do not have networking capabilities to connect to the IoT platform through the gateway. To achieve this purpose, the gateway should connect to Developer Center first, and then you need to add the sub-device to the gateway to establish the connection between the sub-device and Developer Center. This chapter tells you how to connect the sub-devices to Developer Center through the gateway with QuecOpen solution.

Related APIs

Functions	Description
Qth_subDevSetEventCb()	Registers the callback function of the interaction event between the sub-device and the gateway.
Qth_subDevConn()	Connects the sub-device to gateway.
Qth_subDevDisconn()	Disconnects the sub-device from the gateway.
Qth_subDevDeauth()	Deletes the sub-device.
Qth_subDevSendTsl()	Sends TSL data of the sub-device to Developer Center.
Qth_subDevSendTrans()	Sends transparent transmission data of the sub-device to Developer Center.
Qth_subDevLocReport()	Sends location data of the sub-device to Developer Center.
Qth_subOtaUpdateVer()	Reports the sub-device version number.
Qth_subOtaReq()	Requests a sub-device OTA upgrade plan.

Note: See Gateway Sub-device API for details.

Procedures

1. Log in to Developer Center

Log in to Developer Center. If you don't have an account click Register Now to register.

2. Create Product

1) Create a Gateway Product

Creating a gateway product is similar to creating a cellular product. In the "Device Type" option, select Gateway.

2) Create a Sub-device Product

• Device Type: A directly connected device can directly access the network. A gateway device can help sub-devices to connect to Developer Center. A sub-device is a device that relies on the gateway to connect to the network.
• Specified Gateway:
  • Disable: Sub-devices can access Developer Center through any gateway.
  • Enable: Sub-devices can access Developer Center only through the specified gateway.
• Gateway Access Mode: Developer Center authorizes the gateway device.
  • Access Network Only: The sub-device uses the gateway as a channel for Internet access and data forwarding, and it is managed as a directly connected device.
    • Enable Dynamical Gateway Switching: Sub-devices that have connected to Developer Center through a gateway can switch to another gateway to access Developer Center.
    • Disable Dynamical Gateway Switching: Sub-devices that have connected to Developer Center through a gateway cannot switch to another gateway to access Developer Center.
  • Product Integrated: The sub-device is integrated into the gateway and can be queried and controlled by the gateway.

3. Configure Gateway Device

1) Initialize QuecThing SDK

Before development, please complete the initialization of the QuecOpen solution of the project. The function below needs to be called before using the networking service. Initialization refers to completing the basic configuration of the module after the module is powered on to connect to Developer Center.

/* Initialize QuecThing SDK. */
oprt_ret ret = OPRT_OK;

ret = Qth_devInit();
if (OPRT_OK != ret)
{
    Quos_logPrintf(APPS_OPEN, LL_ERR, "sdk init error:%d", ret);
    return;
}

2) Register Callback Function of Gateway Event

The event callback function is simply to add a monitoring task to the event source (component). When the gateway device triggers an event, the listener will process the event. The developer only needs to deal with the event notified by the event callback function.

/* Register QuecThing event callback function. */
Qth_eventCb_t event_cb = {0};
Qth_otaEventCb_t otaCb = {0};
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);

3) Configure Product Info (Required at the First Connection)

The QuecThing SDK provides interfaces and reference implementations for reading and writing device information, which can be customized as needed. During the first connection, the gateway device sends a bootstrap authentication request, and Developer Center will authenticate ProductKey and ProductSecret provided by the device. If the authentication succeeds, Developer Center will issue the required information for your device to connect to and access Developer Center.

/* Configure product info. */
Qth_configSetProductInfo(DEMO_PK, DEMO_PS);

4) Connect to Developer Center

The module initiates the connection to Developer Center, establishes safe and stable communication between Developer Center and the device, and realizes device management, monitoring, control and other operations.

/* Initiates the connection to Developer Center. */
Qth_devStart();

Note: Sub-device messages received by the gateway before it is connected to Developer Center are discarded. Once connected, the gateway device starts forwarding sub-device messages to Developer Center.

4. Sub-device Operation Procedures

The capability of the gateway is to convert the communication protocols between different devices, allowing sub-devices that do not have networking capabilities to connect to the IoT platform through the gateway. To achieve this purpose, you need to add the sub-device to the gateway to establish the connection between the sub-device and the gateway.

1) Register Sub-device Event Callback

The event callback function simply adds a monitoring task to the event source (component). When the sub-device triggers an event, the listener will process the event. The developer only needs to deal with the event notified by the event callback function.

/* Register event callback function. */
Qth_subEventCb_t subEventCb = {0};
Qth_subOtaCb_t subOtaCb = {0};
subOtaCb.planCb = subOtaPlanCb;
subOtaCb.downloadCb = subOtaDownloadCb;
subOtaCb.resultCb = subOtaResultCb;
subOtaCb.infoCb = subOtaInfoCb;
subOtaCb.fileCb = subOtaFileCb;
subEventCb.devEventCb = subDevEventCb;
subEventCb.ttlvRecvCb = subTtlvRecvCb;
subEventCb.ttlvReqCb = subTtlvReqCb;
subEventCb.transRecvCb = subTransRecvCb;
subEventCb.otaEventCb = subOtaCb;
Qth_subDevSetEventCb(subEventCb);

2) Authenticate Sub-device

Connecting to Developer Center for the first time requires sub-device authentication, which can be done through Qth_subDevConn(). After the MCU receives the successful authentication event report, the sub-device will automatically connect to Developer Center. If the authenticated sub-device is not connected to Developer Center, it can be deregistered through Qth_subDevDeauth().

/* Authenticate the sub-device to Developer Center. */
Qth_subDevConn("pxxxxm", VnhyxxxxxxxxSTFh, "123xxxx89", NULL);

Note: This function connects the sub-device to the gateway or authenticates the sub-device. The connection/authentication result is notified by the interaction event between the sub-device and the gateway. If DeviceSecret of the sub-device is set to NULL, it means to authenticate the sub-device; If DeviceSecret of the sub-device is specified, it means to connect the sub-device to the gateway.

5. TSL Data Interaction of Sub-device

For remote control of a smart device, a gateway must report the status of the device, receive and execute commands from the IoT platform. Therefore, data transmission is the core capability of the gateway. The smart LGB light sub-device will be used to illustrate TSL model interaction.

TSL Uplink Data

Sub-devices can adopt different strategies to detect and process data properties based on the service scenarios. For example, sub-devices can read data of the smart LGB light sensor switches through the serial port, and then upload the data read to Developer Center through the gateway.

The TSL data sent is shown in the table below.

ID	Type	Value
1	Bool	true
2	Int	30

Sample code:

void *ttlvHead = NULL;
Quos_ttlvAddIdBool(&ttlvHead, 1, TRUE);
Quos_ttlvAddIdInt(&ttlvHead, 2, 30);
Qth_subDevSendTsl("pxxxxm","123xxxx89",QTH_SEND_AT_LEAST_ONCE,ttlvHead,NULL,NULL);
Quos_ttlvFree(&ttlvHead);

Note: After the TSL node and is added and called, call Quos_ttlvFree(), which will release a memory block pointed to by the pointer to avoid problems such as memory leakage.

TSL Downlink Data

1) Developer Center Issues TSL Service

On the "Device Debug" page of Developer Center, click "Property Debug", select the TSL property to be issued, and click "Send Command" in the lower left corner to issue the TSL property to the sub-device.

2) Sub-device Receives and Processes TSL Data

When the module receives the TSL data, it will automatically enter the sub-device event processing callback function Qth_subDevSetEventCb(), and you can perform data response processing according to the corresponding event.

• The sample code for event callback processing:

  void subTtlvRecvCb(const char *subPk, const char *subDk, void *ttlvHead)
  {
      Quos_logPrintf(APPS_OPEN, LL_DBG, "subPk:%s,subDk:%s", subPk, subDk);
      Quos_ttlvHeadPrintf(ttlvHead);
  }