Help Center> IoT Device Access> SDK Reference> Old SDKs> AgentLite API Reference (C)> Access of Directly Connected Devices> Connecting a Device
View PDF

Connecting a Device

API Function

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

API Description

1
 
HW_INT IOTA_Login();

Return Value

For details, see Function Return Values.

Return values only show the API call result. For example, the 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

The connection or reconnection is successful.

IOTA_TOPIC_DISCONNECT_NTY

HW_MSG object

EN_ULGN_IE_ERR_REASON

The connection fails or the device is disconnected from the platform.

EN_IOTA_LGN_REASON_TYPE:

Enumerated Item

Value

Description

EN_IOTA_LGN_REASON_NULL

0

The reason is not specified.

EN_IOTA_LGN_REASON_CONNCET_ERR

1

A connection error occurs.

EN_IOTA_LGN_REASON_SERVER_BUSY

2

The server is busy.

EN_IOTA_LGN_REASON_AUTH_FAILED

3

The authentication fails. You need to reconnect the device to the platform.

EN_IOTA_LGN_REASON_NET_UNAVAILABLE

5

The network is unavailable.

EN_IOTA_LGN_REASON_DEVICE_NOEXIST

12

The device does not exist. You need to reconnect the device to the platform.

EN_IOTA_LGN_REASON_DEVICE_RMVED

13

The device is deleted. You need to reconnect the device to the platform.

EN_IOTA_LGN_REASON_UNKNOWN

255

Unknown reason.

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 SDK.

Suggestions:

  1. If the connection is successful, the gateway reports the status of indirectly connected devices and cached data.
  2. If the connection fails, the gateway records the device status. If an indirectly connected device reports data, the data is cached and reported until the connection is successful.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
 
// 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;
}
// 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;
}
// 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);

Once the login is successful, the device is connected to the platform.

If the device is disconnected from the platform due to network or server faults, the AgentLite SDK will automatically attempt to reconnect the device to the 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.