Help Center> IoT Device Access> SDK Reference> Old SDKs> AgentLite API Reference (Android)> Connecting 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, you need to call the API Configuring the Binding Relationship 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 waits for a while and tries 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.TOPIC_BINDDEVICE_RSP 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.

Output

Broadcast Name

Broadcast Parameter

Member

Description

TOPIC_BINDDEVICE_RSP

IotaMessage object

(Obtained by using intent.getSerializableExtra(BindService.BIND_BROADCAST_MSG_IE_IOTAMSG))

BIND_IE_RESULT

Binding result.

BIND_IE_DEVICEID

Logical device ID assigned by the platform.

BIND_IE_DEVICESECRET

Authentication secret for a device to access the platform.

BIND_IE_APPID

Identifier of an application.

BIND_IE_HA_ADDR

IP address of the HA server.

BIND_IE_LVS_ADDR

IP address of the LVS server.

BIND_IE_RESULT:

Enumerated Item

Value

Type

Description

BIND_RESULT_SUCCESS

0

N/A

The binding is successful.

BIND_RESULT_DEV_NOT_BIND

1

N/A

The device is not bound.

BIND_RESULT_VERIFYCODE_EXPIRED

2

N/A

The verification code has expired.

BIND_RESULT_FAILED

255

N/A

Other failures.

Example

Call this API to bind a device.

1
 
BindService.bind(new IotaDeviceInfo("nodeId", "manufacturerId", " Gateway", "model", "protocolType"));

Receive a device binding response.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
 
// 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.
BroadcastReceiver mBindRsp; 
mBindRsp = new BroadcastReceiver() { 
    @Override 
    public void onReceive(Context context, Intent intent) { 
    //Do Something 
    IotaMessage iotaMsg = (IotaMessage)intent.getSerializableExtra(BindService.BIND_BROADCAST_MSG_IE_IOTAMSG); 
    int result = iotaMsg.getUint(BindService.BIND_IE_RESULT, 0); 
    String deviceId = iotaMsg.getString(BindService.BIND_IE_DEVICEID); 
    String Secret = iotaMsg.getString(BindService.BIND_IE_DEVICESECRET); 
    String Appid = iotaMsg.getString(BindService.BIND_IE_APPID); 
    String haAddr = iotaMsg.getString(BindService.BIND_IE_HA_ADDR); 
    String lvsAddr = iotaMsg.getString(BindService.BIND_IE_LVS_ADDR); 
    return;  
    } 
}; 
mLocalBroadcastManager = LocalBroadcastManager.getInstance(this); 
IntentFilter filterBind = new IntentFilter(BindService.TOPIC_BINDDEVICE_RSP); 
mLocalBroadcastManager.registerReceiver(mBindRsp, filterBind);