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

Binding a Device

API Function

A device must be bound to the platform before accessing the platform for the first time. Application calls the API Binding a Device to transfer the device serial number, MAC address, or other device information to bind a device to the platform.

Before binding a device to the platform, call the API Configuring the Binding Relationship to set the IP address (EN_IOTA_CFG_IOCM_ADDR) and port (EN_IOTA_CFG_IOCM_PORT) of the platform.

Before a directly connected device accesses the platform for the first time, you must register the device with the platform and then initiate a binding request on the device. If the device is not registered with the platform, the binding fails. The AgentLite SDK waits for a while and tries again.

API Description

1
 
HW_INT IOTA_Bind(const HW_CHAR *pcVerifyCode, const ST_IOTA_DEVICE_INFO *pstInfo);

Parameter Description

Parameter

Mandatory or Optional

Type

Description

pcVerifyCode

Mandatory

String

Verification code for device binding. The value must end with \0.

  • If a device is registered using the Management Portal, set pcVerifyCode to the preSecret used during device registration.
  • If a device is registered using the Developer Center, set pcVerifyCode to the nodeId used during device registration.

pstInfo

Mandatory

ST_IOTA_DEVICE_INFO

Device information. The value must end with \0.

ST_IOTA_DEVICE_INFO:

Parameter

Mandatory or Optional

Type

Description

pcNodeId

Mandatory

String

Unique identifier of a device managed by the gateway connected to the platform. The identifier is provided by the device itself.

pcName

Optional

String

Name of the device.

pcDescription

Optional

String

Description of the device.

pcManufacturerId

Mandatory

String

Identifier of a manufacturer.

pcManufacturerName

Optional

String

Name of the manufacturer.

pcMac

Optional

String

MAC address of the device.

pcLocation

Optional

String

Location of the device.

pcDeviceType

Mandatory

String

Type of the device.

pcModel

Mandatory

String

Model of the device.

  • For a directly connected device, the value must be the same as the model defined in the product model.
  • For a Z-Wave device, the model is in the hexadecimal format of productType + productId (padded with zeros if required), for example, 001A-0A12.

pcSwVersion

Optional

String

Software version.

For a Z-Wave device, the software version is in the format of major version.minor version, for example, 1.1.

pcFwVersion

Optional

String

Firmware version.

pcHwVersion

Optional

String

Hardware version.

pcProtocolType

Mandatory

String

Protocol type (Z-Wave).

pcBridgeId

Optional

String

Identifier of the bridge through which the device connects to the platform.

pcStatus

Optional

String

Status of the device.

  • ONLINE: The device is online.
  • OFFLINE: The device is offline.

statusDetail

Optional

String

Details about the device status. If pcStatus is specified, this parameter is mandatory.

Value:

  • None
  • CONFIGURATION_PENDING
  • COMMUNICATION_ERROR
  • CONFIGURATION_ERROR
  • BRIDGE_OFFLINE
  • FIRMWARE_UPDATING
  • DUTY_CYCLE
  • NOT_ACTIVE

pcMute

Optional

String

Whether the device is muted.

  • TRUE
  • FALSE

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_BIND_RSP broadcast is received.

If the binding fails, the API automatically binds the device after 30 seconds. If the retry fails for consecutive five times (the total number of attempts is six), the API returns a message indicating that the binding fails and stops the binding. To enable the API to retry again, restart the device.

Output

Broadcast Name

Broadcast Parameter

Member

Description

IOTA_TOPIC_BIND_RSP

HW_MSG object

EN_IOTA_BIND_IE_TYPE

Binding result.

EN_IOTA_BIND_IE_TYPE:

Enumerated Item

Value

Type

Description

EN_IOTA_BIND_IE_RESULT

0

EN_IOTA_BIND_RESULT_TYPE

Binding result.

EN_IOTA_BIND_IE_DEVICEID

1

String

Logical device ID assigned by the platform.

EN_IOTA_BIND_IE_DEVICESECRET

2

String

Authentication secret for a device to access the platform.

EN_IOTA_BIND_IE_APPID

3

String

Identifier of an application.

EN_IOTA_BIND_IE_IOCM_ADDR

4

String

Server IP address.

EN_IOTA_BIND_IE_IOCM_PORT

5

unsigned int

Server port.

EN_IOTA_BIND_IE_MQTT_ADDR

6

String

IP address of the MQTT server.

EN_IOTA_BIND_IE_MQTT_PORT

7

unsigned int

Port number of the MQTT server.

EN_IOTA_BIND_RESULT_TYPE:

Enumerated Item

Value

Description

EN_IOTA_BIND_RESULT_SUCCESS

0

The binding is successful.

EN_IOTA_BIND_RESULT_DEV_NOT_BIND

1

The device is not bound.

EN_IOTA_BIND_RESULT_VERIFYCODE_EXPIRED

2

The verification code has expired.

EN_IOTA_BIND_RESULT_FAILED

255

Other failures.

Example

Bind the device by calling IOTA_Bind().

1
2
3
4
5
6
7
8
9
 
// Call this API to bind a device.
ST_HW_DEVICE_INFO stDeviceInfo 
stDeviceInfo.pcNodeId = "SN Number";
stDeviceInfo.pcManufacturerId = "Huawei";
stDeviceInfo.pcDeviceType = "Gateway";
stDeviceInfo.pcModel = "HW_GW101";
stDeviceInfo.pcProtocolType = "HuaweiM2M";

IOTA_Bind("SN Number", &stDeviceInfo);

After a device is bound, the AgentLite SDK returns the parameters shown in the following output. You must store and configure these parameters on the device before connecting it to the platform.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
// Register the broadcast receive processing function.
HW_BroadCastReg("IOTA_TOPIC_BIND_RSP", Device_RegResultHandler);
// Call this API to register the binding result returned by the function.
HW_iNT Device_RegResultHandler(HW_UiNT uiCookie, HW_MSG pstMsg) 
{
    HW_cHAR *pcDeviceId;
    HW_cHAR *pcDeviceSecret;
    HW_cHAR *pcAppId;
    HW_cHAR *pcIoCMServerAddr;
    HW_UiNT uiIoCMServerPort;
    HW_cHAR *pcMqttServerAddr;
    HW_UiNT uiMqttServerPort;
    If (HW_SUCCESS != HW_MsgGetUint(pstMsg, EN_IOTA_BIND_IE_RESULT, 0)) 
    {
        Return 0;
    }
    pcDeviceId = HW_MsgGetStr(pstMsg, EN_IOTA_BIND_IE_DEVICEID);
    pcDeviceSecret = HW_MsgGetStr(pstMsg, EN_IOTA_BIND_IE_DEVICESECRET);
    pcAppId = HW_MsgGetStr(pstMsg, EN_IOTA_BIND_IE_APPID);
    pcIoCMServerAddr = HW_MsgGetStr(pstMsg, EN_IOTA_ BIND_IE_IOCM_ADDR );
    uiIoCMServerPort = HW_MsgGetUint(pstMsg, EN_IOTA_BIND_IE_IOCM_PORT, 0);
    pcMqttServerAddr = HW_MsgGetStr(pstMsg, EN_IOTA_ BIND_IE_IOCM_ADDR );
    uiMqttServerPort = HW_MsgGetUint(pstMsg, EN_IOTA_BIND_IE_IOCM_PORT, 0);
Config_save("DeviceId", pcDeviceId);
Config_save("DeviceSecret", pcDeviceSecret);
Config_save("AppId", pcAppId);
Config_save("IoCMAddr", pcIoCMServerAddr);
Config_save("IoCMPort", pcIoCMServerPort);
Config_save("MqttAddr", pcMqttServerAddr);
Config_save("MqttPort", pcMqttServerPort);
    return 0;
}