Help Center> IoT Device Access> SDK Reference> Old SDKs> AgentLite API Reference (Java)> 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 this API 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 BindConfig.setConfig to set the IP address and 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 will wait for a while and try again.

API Description

1
 
public static boolean bind(String verifyCode, IotaDeviceInfo deviceInfo);

Class

BindService

Parameter Description

Parameter

Mandatory or Optional

Type

Description

verifyCode

Mandatory

String

Verification code for device binding.

  • If a device is registered using the IoTDA console, set verifyCode to the preSecret used during device registration.
  • If a device is registered using the Developer Center, set verifyCode to the nodeId used during device registration.

deviceInfo

Mandatory

IotaDeviceInfo

Device information.

IotaDeviceInfo:

Parameter

Mandatory or Optional

Type

Description

nodeId

Mandatory

String

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

name

Optional

String

Name of the device.

description

Optional

String

Description of the device.

manufacturerId

Mandatory

String

Identifier of a manufacturer.

manufacturerName

Optional

String

Name of the manufacturer.

mac

Optional

String

MAC address of the device.

location

Optional

String

Location of the device.

deviceType

Mandatory

String

Type of the device.

model

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.

swVersion

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.

fwVersion

Optional

String

Firmware version.

hwVersion

Optional

String

Hardware version.

protocolType

Mandatory

String

Protocol type (Z-Wave).

bridgeId

Optional

String

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

status

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

mute

Optional

String

Whether the device is muted.

  • TRUE
  • FALSE

Return Value

Return Value

Description

true

Success

false

Failure

Return values only show the API call result. For example, the return value true indicates that the API is called successfully but does not indicate that the binding is successful. The binding is successful only after the BindService broadcast is received.

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

Example

Call this API to bind a device.

1
2
3
 
String verifyCode =   "123456"  ;
deviceInfo = new IotaDeviceInfo(nodeId,manufactrueId,deviceType,model,protocolType);
BindService.bind(verifyCode,deviceInfo);

Implement the observer API provided by the AgentLite SDK before calling this API.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
 
// Call bindService.registerObserver(this) to register the observer for receiving the binding result callback and obtaining callback parameters, which are used in connection configuration.
public class AgentliteBind implements MyObserver{
    public Subscribe (Observable bindService) {
        bindService. registerObserver (this);
    }
}
//Override the update method in the AgentliteBind.
@Override
public void update(IotaMessage arg0) {
    System.out.println("BindManager receives a binding notification:" + arg0);
    int status = arg0.getUint(BindService.BIND_IE_RESULT, -1);
    System.out.println("status is :" + status);
    switch (status) {
        case 0:
        saveBindParaAndGotoLogin(arg0);
        break;
        default:
        System.out.println("============= binding failure ==============")
        bindAction();
        break;
    }
}

Receive a device binding response.

1
2
3
4
5
6
7
8
9
 
// After a device is bound, the AgentLite SDK will return the parameters shown in the following output. You must store and configure these parameters on the device before connecting it to the platform.
// Save the parameters carried in the device binding response.
private void saveBindParaAndGotoLogin(IotaMessage iotaMsg) {
    String appId = iotaMsg.getString(BindService.BIND_IE_APPID);
    String deviceId = iotaMsg.getString(BindService.BIND_IE_DEVICEID);
    String secret = iotaMsg.getString(BindService.BIND_IE_DEVICESECRET);
    String haAddress = null, lvsAddress = null;
    saveGatewayInfo(appId, deviceId, secret, haAddress, lvsAddress);
}