.NET Client library reference

You can see some examples that show the basic concepts of the different Client interfaces. Besides the examples you will find links that navigate to the full documentation of the client interfaces. The examples on this page will guide you through the base “melody” of the client libraries so that you can easily understand the dry documentation.

For the most detailed and straightforward explanation of the Client usage please check the integration tests in the IoT.Client.DotNet.IntegrationTests project and the IoT.Loadtester project which does load testing as it’s name suggests.

Management Client

As it was mentioned in the Management API Reference page, it is used to manage users, companies, services, networks, devices and telemetry data sinks. The full documentation of the management client is available here: Management client.

The following example demonstrates how to create a device along with the enclosing company, service and network:

var managementClient = new ManagementClient(ManagementApi);

managementClient.User.Register(new Register {
	Email = "email@address.that.has.to.be",
	Name = "User's full name",
	Password = "QuiteC0mplEXPwd#"
});
var companyId = managementClient.Company.Create(new Company {
	Name = "company"
});
var serviceId = managementClient.Service.Create(new Service {
	CompanyId = companyId,
	Name = "service"
});
var networkId = managementClient.Network.Create(new Network {
	CompanyId = companyId,
	ServiceId = serviceId,
	Name = "network"
});
var deviceId = managementClient.Device.Create(new Device {
	CompanyId = companyId,
	ServiceId = serviceId,
	NetworkId = networkId,
	Name = "device"
});

The following example demonstrates that an already registered user creates a service, queries the available telemetry data sinks and sets up the azure sink:

var managementClient = new ManagementClient(ManagementApi);
managementClient.User.Login(new Login {
	Email = email, 
	Password = password
});
var companyId = managementClient.Company.Create(new Company { 
	Name = "company" 
});
var serviceId = managementClient.Service.Create(new Service { 
	CompanyId = companyId, 
	Name = "service" 
});
var telemetryDataSinksMetadata = managementClient.TelemetryDataSinksMetadata.Get();
// Show telemetryDataSinksMetadata list to the users
...
// Select the default Azure sink for current data and an user-defined one for telemetryDataSinks set the required parameters:
var telemetryDataSinkParameters = new List
{
	new TelemetryDataSinkParameters
	{
		SinkName = "localAzureData",
		Parameters = new Dictionary<string, string>()
	},
	new TelemetryDataSinkParameters
	{
		SinkName = "azureTimeSeries",
		Parameters = new Dictionary<string, string>()
		{
			{"ConnectionString", "AZURE_TABLE_STORAGE_CONNECTIONSTRING"},
			{"Table", "TimeSeries"}
		}
	}
};

managementClient.Service.UpdateIncomingTelemetryDataSinks(serviceId, telemetryDataSinkParameters);

 

For more detailed documentation please refer to the Management client reference.

Platform API

To use the platform services there are two APIs available. There is an Occasionally connection client that employs a REST API behind the scenes and a Persistently connection client which uses Websockets and maintains a constantly open connection between the device and the service.

Occasionally connected client

The Occasionally connected client should be used in the following scenarios:

  1. The device records telemetry data occasionally (e.g. measures something once every minute and send the data to the service)
  2. The device control other devices occasionally (e.g. send messages to other devices occasionally)
  3. The device needs to receive messages from other devices quite rarely and it’s not requirement to receive the message ASAP

In the following examples let’s assume that the devices are already set up with all telemetry data sinks and other parameters:

var ocassionalConnectionClient = new OccasionallyConnectionClient(PlatformApi, _deviceId, _apiKey);

ocassionalConnectionClient.RecordTelmetryData(string.Format("{\"Temperature\": {0}, \"Humidity\": {1}}", temperature, humidity));

 

Sending message:

var ocassionalConnectionClient = new OccasionallyConnectionClient(PlatformApi, _deviceId, _apiKey);

ocassionalConnectionClient.SendMessageTo(_deviceId2, "OPEN");

When the SendMessageTo function succeeds you can be sure that the message has been recorded in Thriot. Now it’s the receiver’s responsibility to get the message.

There are two ways of receiving a message:

  1. Receive the message and forget it
  2. Peek and commit the message

The first one provides a QoS 0-level reliability which means that the message is received at most once so if there is some communication or application error while receiving the message it can be lost. The second option provides QoS 1-level reliability where you will receive the message for sure however it’s not guaranteed that you will receive the message only once, the main point is that message can’t be lost.

Send message to an other. Later receive and forget message:

var ocassionalConnectionClient = new OccasionallyConnectionClient(PlatformApi, _deviceId, _apiKey);
ocassionalConnectionClient.SendMessageTo(_deviceId2, "OPEN");

// while on the other device
// happens the following
var ocassionalConnectionClient2 = new OccasionallyConnectionClient(PlatformApi, _deviceId2, _apiKey2);

var result = ocassionalConnectionClient2.ReceiveAndForgetMessage();

if(result == "OPEN") 
{
	OpenDoor();
}

Send message to an other. Later peek and commit the message:

var ocassionalConnectionClient = new OccasionallyConnectionClient(PlatformApi, _deviceId, _apiKey);
ocassionalConnectionClient.SendMessageTo(_deviceId2, "OPEN");

// while on the other device
// happens the following
var ocassionalConnectionClient2 = new OccasionallyConnectionClient(PlatformApi, _deviceId2, _apiKey2);

var result = ocassionalConnectionClient2.PeekMessage();
if(result == "OPEN") 
{
	OpenDoor();
}
ocassionalConnectionClient2.CommitMessage();

 

For more detailed API description please refer to the following documentation:  Occasionally connected client.

Persistently connected client

Persistently connected client should be used in the following scenarios:

  1. The device wants to record telemetry data or send messages to other devices quite often (several messages every second). This will unlikely happened.
  2. There is a requirement to receive the messages ASAP sent to the device.

It’s important to regularly (by default once in every minute) run the Spin method that basically sends heartbeat messages to the server otherwise the websocket connection would be dropped by the server.

Record telemetry data:

var persistentConnection = new PersistentConnectionClient(PlatformWebSocketApi);

persistentConnection.Login(_deviceId, _apiKey);

while(!End())
{
    // measure temperature and humidity
    persistentConnection.RecordTelemetryData(string.Format("{\"Temperature\": {0}, \"Humidity\": {1}}", temperature, humidity));

    persistentConnection.Spin();
}

Send message to an other device:

var persistentConnection = new PersistentConnectionClient(PlatformWebSocketApi);

persistentConnection.Login(_deviceId, _apiKey);

while(!End())
{
    // do some business logic here

    persistentConnection.SendMessageTo(_otherDeviceId, "OPEN");

    persistentConnection.Spin();
}

If you want to receive messages you need to subscribe to the incoming messages.

Receive and forget mode (QoS 0-level):

var persistentConnection = new PersistentConnectionClient(PlatformWebSocketApi);

persistentConnection.Login(_otherDeviceId, _apiKey);

persistentConnection.Subscribe(SubscriptionType.ReceiveAndForget, message => { 
	if(message == "OPEN")
	{
		OpenDoor();
	}
});

// Run the application here for ages
while(!End())
{
    // ... and ages and do some business logic if needed
    persistentConnection.Spin();
}

// unsubscribe if you stop the application
persistentConnection.Unsubscribe();

Peek and commit mode (QoS 1-level)

var persistentConnection = new PersistentConnectionClient(PlatformWebSocketApi);

persistentConnection.Login(_otherDeviceId, _apiKey);

persistentConnection.Subscribe(SubscriptionType.PeekAndCommit, message => { 
	if(message == "OPEN")
	{
		OpenDoor();
	}
});

// Run the application here for ages
while(!End())
{
    // ... and ages and do some business logic if needed
    persistentConnection.Spin();
}

// and unsubscribe if you stop the application
persistentConnection.Unsubscribe();

For more detailed API description please refer to the following documentation:  Persistently connected client

Reporting client

Using the Reporting client one can retrieve data recorded as telemetry data. There are two types of reports:

  1. Current data – The latest recorded telemetry data
  2. Time series data – All data entries recorded at different times in a timeframe

The reporting capabilities for a device depends on the telemetry data sink that is/was used by the device at the time of recording telemetry data. It means that if you have current data and telemetry data set up for a device you will reach both kind of reports otherwise if you set up only one of them then the reporting will work only for that telemetry data sink.

Reports can be generate at device level and network level. At network level all devices in the network will be queried by the report. The output format can be JSON and CSV.

Device report examples:

var reportingClient = new ReportingClient(ReportingApi);

reportingClient.Device.SetDevice(_deviceId, _deviceKey);

var sinks = reportingClient.Device.GetSinks();

var currentDataSink = sinks.First(s => s.SinkType == SinkType.CurrentData).SinkName;
var timeSeriesDataSink = sinks.First(s => s.SinkType == SinkType.TimeSeries).SinkName;

var currentDataReport = reportingClient.Device.GetCurrentData(currentDataSink);

// Process current data report

// the time series report is always generated for a whole day. Specify a time value in the day of interest.
timeSeriesReport = reportingClient.Device.GetTimeSeriesReport(timeSeriesDataSink, DateTime.UtcNow.AddDays(-1));

// Process time series report

timeSeriesReportCSV =  reportingClient.Device.GetTimeSeriesReportCsv(timeSeriesDataSink, DateTime.UtcNow.AddDays(-1));

 

Network report examples:

var reportingClient = new ReportingClient(ReportingApi);

reportingClient.Network.SetNetwork(_networkId, _networkKey);

var sinks = reportingClient.Network.GetSinks();

var currentDataSink = sinks.First(s => s.SinkType == SinkType.CurrentData).SinkName;
var timeSeriesDataSink = sinks.First(s => s.SinkType == SinkType.TimeSeries).SinkName;

var currentDataReportForNetwork = reportingClient.Network.GetCurrentData(currentDataSink);

// The other methods are also similar to their device-pair

For more detailed API description please refer to the following documentation: Reporting client

 

Advertisements