Help Center/ IoT/ API Reference/ AgentLite API Reference (C)/ API Description/ Access of Directly Connected Devices/ Device Login
Updated on 2022-02-24 GMT+08:00
View PDF
Share

Device Login

API Function

This API is used to connect a device to the IoT platform after the device is bound to the IoT platform for the first time or the device restarts.

API Description

1
 
HW_INT IOTA_Login();

Parameter Description

None

Return Value

For details, see 4.2 Function Return Values.

NOTE:

Return values only show API calling results. For example, return value 0 indicates that the API is called successfully but does not indicate that the connection is successful. The connection is successful only after the IOTA_TOPIC_CONNECTED_NTY broadcast is received. Before calling the HW_INT IOTA_Login() API, call the IOTA_SetConfig API to configure relevant parameters.

Output

Broadcast Name

Broadcast Parameter

Member

Description

IOTA_TOPIC_CONNECTED_NTY

HW_MSG object

None

Specifies that the connection or reconnection is successful.

IOTA_TOPIC_DISCONNECT_NTY

HW_MSG object

EN_ULGN_IE_ERR_REASON

Specifies that the connection fails or the device is disconnected from the IoT platform.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
 
Config_Get("DeviceId", pcDeviceId);
Config_Get("DeviceSecret", pcDeviceSecret);
Config_Get("AppId", pcAppId);
Config_Get("HAAddr", pcHAServerAddr);
Config_Get("LVSAddr", pcLVSServerAddr);

IOTA_SetConfig(EN_IOTA_CFG_DEVICEID, pcDeviceId); 
IOTA_SetConfig(EN_IOTA_CFG_DEVICESECRET, pcDeviceSecret); 
IOTA_SetConfig(EN_IOTA_CFG_APPID, pcAppId); 
IOTA_SetConfig(EN_IOTA_CFG_HA_ADDR, pcHAServerAddr); 
IOTA_SetConfig(EN_IOTA_CFG_LVS_ADDR, pcLVSServerAddr); 

IOTA_Login();

The device waits for a connection status broadcast from the AgentLite.

Developers need to register the functions for processing connection status broadcasts in advance. It is recommended that:

  1. Gateways report the status of indirectly connected devices and all the cached data when the connection is successful.
  2. Gateways record the disconnected status of devices and cache the reported data when the connection fails.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
 
//Developers call this API to register the function for subsequent processing after successful connection.
HW_iNT Device_ConnectedHandler(HW_UiNT uiCookie, HW_MSG pstMsg) 
{
    //update device states 
    //send buffer data 
    return 0;
}
//Developers call this API to register the function for subsequent processing after the connection fails.
HW_iNT Device_DisconnectHandler(HW_UiNT uiCookie, HW_MSG pstMsg) 
{
    //stop reporting data 
    return 0;
}
//Developers call this API to bind the broadcast processing function.
HW_BroadCastReg("IOTA_TOPIC_CONNECTED_NTY", Device_ConnectedHandler);
HW_BroadCastReg("IOTA_TOPIC_DISCONNECT_NTY", Device_DisconnectHandler);

After the login is successful, the device is connected to the IoT platform.

If the device is disconnected from the IoT platform due to the network or server fault, the AgentLite will automatically attempt to reconnect the device to the IoT platform and report the real-time status to the third-party application by using the broadcasts IOTA_TOPIC_CONNECTED_NTY and IOTA_TOPIC_DISCONNECT_NTY.