Help Center> IoT Device Access> SDK Reference> Old SDKs> AgentLite API Reference (Android)> Managing an Indirectly Connected Device> Adding a Device
View PDF

Adding a Device

API Function

This API is used to add a device that accesses the IoT platform through a gateway. After the device is connected to the IoT platform, the IoT platform will assign a unique logical ID to the device.

API Description

1
 
public static boolean addDevice(int cookie, IotaDeviceInfo deviceInfo);

Class

HubService

Parameter Description

Parameter

Mandatory or Optional

Type

Description

cookie

Optional

int

The value ranges from 1 to 65535.

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 IoT 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 profile.
  • 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 IoT 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 API calling results. For example, the return value true indicates that the API is called successfully but does not indicate that the device is added successfully. The device is added successfully only after the TOPIC_ADDDEV_RSP broadcast is received.

Output

Broadcast Name

Broadcast Parameter

Member

Description

TOPIC_ADDDEV_RSP

IotaMessage

(Obtained by using intent.getSerializableExtra(HubService.HUB_BROADCAST_IE_IOTAMSG))

HUB_IE_RESULT

Device adding result.

HUB_IE_DEVICEID

Identifier of a device. If the device is added successfully, the device ID is returned.

HUB_IE_COOKIE

The value ranges from 1 to 65535.

HUB_IE_RESULT:

Enumerated Item

Value

Type

Description

HUB_RESULT_SUCCESS

0

N/A

The device is added or deleted.

HUB_RESULT_DEVICE_EXIST

1

N/A

The device already exists.

HUB_RESULT_DEVICE_NOTEXIST

2

N/A

The device does not exist.

HUB_RESULT_DEVICE_FAILED

255

N/A

The execution fails.

Example

1
2
 
//Call this API to add a device.
HubService.addDevice(29011, new IotaDeviceInfo("nodeId", "manufacturerId", "deviceType", "model", "protocolType"));

The device waits for the result.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
 
//java code 
//Register a broadcast receiver to process the device adding result.
BroadcastReceiver mAdddeviceRsp;
mAdddeviceRsp = new BroadcastReceiver() {
    @Override 
        public void onReceive(Context context, Intent intent) {
        //Do Something 
        IotaMessage iotaMsg = (IotaMessage)intent.getSerializableExtra(HubService. HUB_BROADCAST_IE_IOTAMSG);
        int result = iotaMsg.getUint(HubService.HUB_IE_RESULT, 0);
        String deviceId = iotaMsg.getString(HubService.HUB_IE_DEVICEID);
        int cookie = iotaMsg.getUint(HubService.HUB_IE_COOKIE, 0);
        return;
    }
};
mLocalBroadcastManager = LocalBroadcastManager.getInstance(this);
IntentFilter filterAddDev = new IntentFilter(HubService.TOPIC_ADDDEV_RSP);
mLocalBroadcastManager.registerReceiver(mAdddeviceRsp, filterAddDev);