Version 1.0
Updated on 05 October 2023
This IoTConnect DotNet SDK package will show you how to install and run the firmware file.
| Date |
Name |
Download |
| 05 October 2023 |
DotNet SDK V1.0 |
Download  |
Getting started
Prerequisites
Before you install and run the firmware file, we recommend to check with the following set up requirements:
- .net 6.0
- Visual studio IDE
Installation
- Extract the “iotconnect-sdk-dotnet-core-v1.14.0.zip“
- Follow the steps given below to import our SDK as a library
- Open Visual Studio 2022, Create new .net core Console App.
- Extract (get “nupkg” file from “iotconnect-sdk-dotnet-core-v1.14.0.zip”) the zip file
- 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 file into program.cs file in newly created project.
- 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 above
- 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 above in SDK Options otherwise leave it as it is.
Run
- Press the “F5” button in Visual Studio IDE.
Explanation
Prerequisite configuration
string cpId = "<cpid>";
string uniqueId = "<deviceUniqueId>";
string env = "<env>";
string sId = "<sId>";
string platform = "<platform>"
- cpId : It need to get from the IoTConnect platform “Settings->Key Vault”.
- uniqueId : Your device uniqueId
- env : It need to get from the IoTConnect platform “Settings->Key Vault”.
- SId : It is the company code. You can get it from the IoTConnect UI portal “Settings -> Key Vault -> SDK Identities -> select language DotNet and Version 1.0”
- platform : It is either aws or az
Notes:
Set either SID or CPID, As one of it is optional.
SdkOptions
It is for the SDK configuration and need to parse in SDK object initialize call. You need to manage the below configuration as per your device authentications.
SDKOptions sdkOptions = new SDKOptions();
sdkOptions.Certificate.CACertificatePath = "<>/cert.pfx";
sdkOptions.Certificate.PrivateKeyCertificatePath = "<>/cert.pfx";
sdkOptions.Certificate.Password = "******";
//For Offline Storage only
sdkOptions.OfflineStorage.AvailSpaceInMb = <>; //size in MB, Default value = unlimited
sdkOptions.OfflineStorage.FileCount = <>; // Default value = 1
sdkOptions.OfflineStorage.Disabled = <<true/false>>; // //default value = false, false = store data, true = not store data
sdkOptions is mandatory for “certificate” X.509 device authentication type.
Certificate
It requires the path of the certificate file. Mandatory for X.509/SSL device CA-signed or self-signed
authentication type.
"Certificate.CACertificatePath": It is indicated to define the path of the device certificate file. Mandatory for X.509/Device CA signed or self-signed authentication type only.
"Certificate.PrivateKeyCertificatePath": It is indicated to define the path of the private key certificate file. Mandatory for X.509/Device CA signed or self-signed authentication type only.
"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
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 in MB
- fileCount: Number of files need to create for offline data
Notes:
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
To Initialize the SDK object and connect to the cloud
sdkClient = new SDKClient();
sdkClient.Init(cpId, uniqueId, sId, env, platform, sdkOptions, FirmwareDelegate, ShadowUpdateCallBack);
To receive the command from Cloud to Device(C2D)
private static async Task OnDeviceCommandCallback(string arg)
{
await CancelWhileLoopTask();
Console.WriteLine("FIRMWARE ::: Device command received : " + arg);
Console.WriteLine("\n4 = Failed, \n5 = Executed, \n6 = Executed ACK, \n7 = Success");
var command = JsonConvert.DeserializeObject<DeviceCommand>(arg);
if (command.Ack.HasValue && command.Ack.Value != Guid.Empty)
{
Console.WriteLine("Enter command ack status: ");
var status = Console.ReadLine();
Console.WriteLine("Enter command ack message: ");
var msg = Console.ReadLine();
if (!string.IsNullOrWhiteSpace(command.ChildId))
client.SendAckCmd(command.Ack.Value, Convert.ToInt32(status), msg, command.ChildId);
else
client.SendAckCmd(command.Ack.Value, Convert.ToInt32(status), msg);
}
else
Console.WriteLine("FIRMWARE ::: No acknowledgement required.");
isCallbackCompleted = true;
}
To receive the twin from Cloud to Device(C2D)
private static Task ShadowUpdateCallBack(string arg)
{
Console.WriteLine($"FIRMWARE ::: Shadow update received :::: {arg}");
try
{
Console.WriteLine("Shadow : " + arg);
dynamic results = JsonConvert.DeserializeObject<dynamic>(arg);
JObject shadow = (JObject)JToken.FromObject(results);
if (shadow.Count > 0)
{
Dictionary<string, object> shadowDict = new Dictionary<string, object>();
var version = shadow.Children<JProperty>().Where(a => a.Name.Equals("$version")).FirstOrDefault()?.Value;
foreach (JProperty item in shadow.Children<JProperty>())
{
if (item.Name.Equals("$version", StringComparison.CurrentCultureIgnoreCase))
continue;
client.UpdateShadow(item.Name, item.Value, Convert.ToString(version), PostShadowUpdateCallback);
}
}
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
}
return Task.CompletedTask;
}
This is the standard data input format for Gateway and non Gateway device to send the data on IoTConnect cloud(D2C).
1. For Non Gateway Device
String deviceData = "[{
'uniqueId': '<< Device UniqueId >>',
'time' : '<< date >>',
'data': {}
}]";
2. 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);
Notes:
Date time will be in ISO 8601 format as “YYYY-MM-DDTHH:MM:SS.sssZ”. Example: “2019-12-24T10:06:17.857Z”
“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 send the command acknowledgment
var command = JsonConvert.DeserializeObject<DeviceCommand>(arg);
client.SendAckCmd(command.Ack.Value, 6, "Ack done.!!!");
"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 = "0x01" device command, 11 = "0x02" Firmware OTA command)
Note : (*) indicates the mandatory element of the object.
To disconnect the device from the cloud
sdkClient.Dispose();
To get the shadow property Desired and Reported
sdkClient.GetShadows();
To get the all attributes
sdkClient.GetAttributes();
