Client Libraries & SDKs

Dotnet C# SDK

Version 3.0

Updated On 04/21

Sample Code for Microsoft .NET Core

#	Date	Name	Download
1	04/09/2021	Standard authorized firmware sample v3.0	Download

How to build Dotnet sample code?

Prerequisite tools:

1. .net core 2.0
2. Visual studio IDE

Installation 

1. Extract the “iotconnect-sdk-dotnet-core-v3.0.zip“ (You can download SDK file from here)
2. Follow the steps given below to import our SDK as a library:
   • Open Visual Studio 2017/2019, Create new .net core Console App.
     
   • Get “nupkg” file from extracted the zip file and Create new folder called Nuget and place IOTConnect SDK Nuget package.
     
   • Open Nuget Package Manager of Console App and click on Settings for Package source.
     
   • Add new Package source, name it as LocalPackage and in source give path of Nuget folder created in step #2
     
   • Install package from server/local nuget manager.
     
   • Copy content from Firmware.cs file into program.cs file in newly created project.
     
3. You can take the firmware file from the above location and update the following details
   • Prerequisite input data as explained in the usage section as below
   • Update sensor attributes according to added in IoTConnect cloud platform.
   • If your device is secure then need to configure the x.509 certificate path such as given below in SDK Options otherwise leave it as it is.
4. Run Sample File:
   • Press the “F5” button in Visual Studio IDE.
     

Public Method and Implementations

To initialize the SDK object need to import below sdk package

using IOTConnectSDK;

Prerequisite Configuration

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

• uniqueId : Its device ID which register on IotConnect platform and also its status has Active and Acquired.
• cpId : It need to get from the IoTConnect platform “Settings->Key Vault”.
• env : It need to get from the IoTConnect platform “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 json format for the “sdkOptions” is as below:

SDKClientOption sdkOptions = new SDKClientOption();
//For SSL CA signed and SelfSigned authorized device only
options.SSL.Certificate = "<>/cert.pfx";
options.SSL.Password = "certificate password";
//For Offline Storage only
sdkOptions.OfflineStorage.AvailSpaceInMb = <>;
sdkOptions.OfflineStorage.FileCount = <>;
sdkOptions.OfflineStorage.Disabled = <>;

• 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.
  • SSL.Certificate : your device certificate/li>
  • SSL.Password: certificate password
• 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. 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 SDKClient(cpId, uniqueId, DeviceCallback, TwinUpdateCallBack, sdkOptions, env);

To receive the command from Cloud to Device(C2D)

private static Task DeviceCallback(string message)
{
	try
	{
		var commandData = JsonConvert.DeserializeObject(message);

		DeviceAckModel ackDetails = new DeviceAckModel()
		{
			AckId = commandData.AcknowledgeId,
			ChildId = ""
		};

		isOta = commandData.CommandType.Equals("0x02", StringComparison.CurrentCultureIgnoreCase);
		int msgType = 5;
		if (isOta)
		{
			//TODO : download and save ota file from url [commandData.Command]
			ackDetails.Msg = "OTA updated successfully.";
			ackDetails.Status = 7;
			msgType = 11;
		}
		else
		{
			ackDetails.Msg = "Device command received successfully.";
			ackDetails.Status = 6;
			msgType = 12;
		}

		var dataOta = JsonConvert.SerializeObject(ackDetails);

		sdkClient.SendAck(dataOta, msgType);
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.Message);
	}

	return Task.CompletedTask;
}

To receive the twin from Cloud to Device(C2D)

private static Task TwinUpdateCallBack(string arg)
{
	Console.WriteLine("Twin Update received.");
	Console.WriteLine("Twin : " + arg);
	
	return Task.CompletedTask;
}

To get the list of attributes with the respective device.

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);

• time : Date format should be as defined //”2021-01-24T10:06:17.857Z”
• data : JSON data type format // {“temperature”: 15.55, “gyroscope” : { ‘x’ : -1.2 }}

To update the Twin Property

sdkClient.UpdateTwin(key,value);

• 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 = ""; 
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();