Client Libraries & SDKs

JAVA SDK

u

Version 3.0

Updated On 03/21

Sample Code for lettest version of SDK

#	Date	Name	Download
1	03/18/2021	Standard authorized firmware sample v3.0	Download

How to run the JAVA sample code?

Prerequisite tools

• Java 8
• Eclipse IDE

Installation

• Extract the “iotconnect-sdk-java-v3.0.zip” (You can download SDK file from here)
• Open Eclipse and create a new JAVA project.
• Create lib folder inside the newly created project.
• Put JAR(You can get JAR file from iotconnect-sdk-java-v3.0.zip) file inside lib
  
• Configure JAR file to the project.Right-click on the project and click on Build Path and then click on Configure Build Path.
  
• Click on Java Build Path and then go to Libraries Tab and then click on Add JARs
• Now Select iotconnect-sdk-java-v3.0.jar from lib folder and then click on OK button.
• Create new Java Class file inside src folder(You can get sample file(Firmware.java) code from iotconnect-sdk-java-v3.0.zip).

Public Method and Implementations

Prerequisite input data

• Get your Environment(ENV) Details
• Get your CPID

uniqueId = <<uniqueId>>;
cpId = <<CPID>>;
env = <<env>>;              

• uniqueId : Its device ID which register on IotConnect platform and also its status has Active and Acquired.
• cpId : It is the company code. It gets from the IoTConnect UI portal “Settings->Key Vault”.
• env : It is the UI platform environment. It gets from the IoTConnect UI portal “Settings->Key Vault”.

SdkOptions is for the SDK configuration and needs to parse in SDK object initialize call. You need to manage the below configuration as per your device authentication type.

• If your device has an authentication type “Key” then no need any configuration. SDK will manage itself from device information.
• To configure the secure SSL/x509 connection follow below step for CA or SelfSiged certificate
• “sdkOptions” is optional. Mandatory for SSL/x509 device authentication type only.
• Standard file format for the “sdkOptions” is as below:

SDKOptions sdkOptions = new SDKOptions();

//For SSL CA signed and SelfSigned authorized device only
sdkOptions.setSSLCaPath("<>/ca.cert.pem");
sdkOptions.setSSLCertPath("<>/cert.pem");
sdkOptions.setSSLKeyPath("<>/key.pem");

//For Offline Storage only
sdkOptions.setAvailSpaceInMb(<>); //size in MB, Default value = unlimited
sdkOptions.setFileCount(<>); // Default value = 1
sdkOptions.setDisabledOfflineStorage(<>);

• certificate : It is indicated to define the path of the certificate file. Mandatory for X.509/SSL device CA signed or self-signed authentication type only.
  • SSLKeyPath : your device key
  • SSLCertPath: your device certificate
  • SSLCaPath : Root CA certificate
• offlineStorage” : Define the configuration related to the offline data storage.
  • disabled : false = offline data storing, true = not storing offline data
  • availSpaceInMb: Define the file size of offline data which should be in (MB)
  • fileCount : Number of files need to create for offline data

Note: sdkOptions is optional but mandatory for SSL/x509 device authentication type only. Define proper setting or leave it NULL. If you do not provide offline storage, it will set the default settings as per defined above. It may harm your device by storing the large data. Once memory gets full may chance to stop the execution.

To Initialize the SDK object and connect to the cloud

SDKClient sdkClient = new SDKClientImpl(cpId, uniqueId, callerClassObject, callerClassObject, sdkOptions, env);

To receive the command from Cloud to Device(C2D)

@Override
public void deviceCallback(D2CResponse d2CResponse) {
	try {
		ObjectMapper ackMapper = new ObjectMapper();
		if(d2CResponse != null && d2CResponse.getD2cData() != null){
			if(d2CResponse.getCmdType().equals("0x01")){        
				// Device Command
			}else if(d2CResponse.getCmdType().equals("0x02")){  
				// Firmware Command
			}else if(d2CResponse.getCmdType().equals("0x16")){
				// Device Connection status (command : true [connected] and command : false [disconnected])
			}
		}
	} catch (Exception e) {
		System.out.println("Error While Sending Acknowledgement to HUB"+ e.getMessage());
	}
}

To receive the twin from Cloud to Device(C2D)

@Override
public void twinUpdateCallback(Map twinProperties) {
	if(twinProperties.size() > 0){
		System.out.println(twinProperties.toString());
	}
}

To get the list of attributes

String attributes = sdkClient.getAttributes();

Note: you can checkout device attribute format with all device type click here

This is the standard data input format for Gateway and non Gateway device to send the data on IoTConnect cloud(D2C)

// For Non Gateway Device 
String deviceData = [{
	"uniqueId": "<< Device UniqueId >>",
	"time" : "<< date >>",
	"data": {}
}];

// For Gateway and multiple child device 
/* String deviceData = [{
	"uniqueId": "<< Gateway Device UniqueId >>", // It should be must first object of the array
	"time": "<< date >>",
	"data": {}
},
{
	"uniqueId":"<< Child DeviceId >>", //Child device
	"time": "<< date >>",
	"data": {}
}]*/

sdkClient.sendData(deviceData);

Note: Date time will be in ISO 8601 format as “YYYY-MM-DDTHH:MM:SS.sssZ”. Example: “2019-12-24T10:06:17.857Z”

To update the Twin Property

Map twinPropertyMap = new HashMap<>();
twinPropertyMap.put("<< Desired property key >>", "<< Desired Property value >>"); 

Example :	
Map twinPropertyMap = new HashMap<>();
twinPropertyMap.put("humidity", "100");
sdkClient.updateTwin(twinPropertyMap);

• key : Desired property key received from Twin callback message
• value : Value of the respective desired property

To send the command acknowledgment from device to cloud.

String ackMsg = "[{'data': {'ackId': '<>','st': <>,'msg':'','childId': ''},'uniqueId':'<>'}]";

String msgType = ""; // 5 ("0x01" device command), 11 ("0x02" Firmware OTA command)
sdkClient.sendAck(ackMsg, msgType);

• ackId(*) : Command Acknowledgment GUID which will receive from command payload (data.ackId)
• st(*) : Acknowledgment status sent to cloud
  4 = Fail
  6 = Device command[0x01]
  7 = Firmware OTA command[0x02])
• msg : It is used to send your custom message
• childId : It is used for Gateway’s child device OTA update only
  0x01 : null or “” for Device command
  0x02 : null or “” for Gateway device and mandatory for Gateway child device’s OTA update.
  How to get the “childId”?
  – You will get child uniqueId for child device OTA command from payload “data.urls[~].uniqueId”
• msgType : Message type
  5 = Device command[0x01]
  11 = Firmware OTA command[0x02]

To disconnect the device from the cloud

sdkClient.dispose();

To get the all twin property Desired and Reported

sdkClient.getAllTwins();