Linux (C++) Client library reference

LinuxCpp

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 tests under the test folder in the Linux client source tree and the app example application which does messaging.

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. Navigate to the Company, User, etc. specific clients from this page for more information.

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

ManagementClient*  managementClient = new ManagementClient(APIURL);

UserManagementClient* userManagementClient = managementClient->User();

string email = getRandomEmail();

RegisterInfo reg;
reg.Name = "Linux test user";
reg.Email = email;
reg.Password = "P@ssw0rd";
int regRetcode = userManagementClient->Register(reg);

if(regRetcode!= 0)
	return NULL;

CompanyManagementClient* companyClient = managementClient->Company();
ServiceManagementClient* serviceClient = managementClient->Service();
NetworkManagementClient* networkClient = managementClient->Network();
DeviceManagementClient* deviceClient = managementClient->Device();
Company company;
company.Name = "test company";
string companyId = companyClient->Create(company);

Service service;
service.CompanyId = companyId;
service.Name = "test service";
string serviceId = serviceClient->Create(service);

Network network;
network.CompanyId = companyId;
network.ServiceId = serviceId;
network.Name = "test network";
string networkId = networkClient->Create(network);

Device device;
device.CompanyId = companyId;
device.ServiceId = serviceId;
device.NetworkId = networkId;
device.Name = "test device";
string deviceId = deviceClient->Create(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:

ManagementClient*  managementClient = new ManagementClient(APIURL);
UserManagementClient* userManagementClient = managementClient->User();

LoginInfo login;

login.Email = email;
login.Password = reg.Password;

userManagementClient->Login(login);

CompanyManagementClient* companyClient = managementClient->Company();
ServiceManagementClient* serviceClient = managementClient->Service();

Company company;
company.Name = "test company";
string companyId = companyClient->Create(company);

Service service;
service.CompanyId = companyId;
service.Name = "test service";
string serviceId = serviceClient->Create(service);

TelemetryDataSinksMetadataClient* telemetryDataSinksMetadataClient = managementClient->TelemetryDataSinksMetadata();
TelemetryDataSinksMetadata telemetryDataSinksMetadata = telemetryDataSinksMetadataClient->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:

vector telemetryDataSinkParameters;
TelemetryDataSinkParameters tdsp1;
tdsp1.SinkName = SINKDATA;
TelemetryDataSinkParameters tdsp2;
tdsp2.SinkName = SINKTIMESERIES;
telemetryDataSinkParameters.push_back(tdsp1);
telemetryDataSinkParameters.push_back(tdsp2);

serviceClient->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:

OccasionallyConnectionClient *occasionallyConnectionClient = new OccasionallyConnectionClient(PAPIURL, deviceId, deviceKey);

int retCode = occasionallyConnectionClient->RecordTelemetryData("{\"Temperature\": 24, \"Humidity\": 50 }");

 

Sending message:

OccasionallyConnectionClient *occasionallyConnectionClient = new OccasionallyConnectionClient(PAPIURL, deviceId, deviceKey);

int retCode = occasionallyConnectionClient->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:

OccasionallyConnectionClient *occasionallyConnectionClient = new OccasionallyConnectionClient(PAPIURL, deviceId, deviceKey);
int retCode = occasionallyConnectionClient->SendMessageTo(deviceId2, "OPEN");

// while on the other device
// happens the following
OccasionallyConnectionClient *occasionallyConnectionClient2 = new OccasionallyConnectionClient(PAPIURL, deviceId2, deviceKey2);

PushedMessage pushedMessage = occasionallyConnectionClient->ReceiveAndForgetMessage();

if(pushedMessage.Payload == "OPEN") 
{
	OpenDoor();
}

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

OccasionallyConnectionClient *occasionallyConnectionClient = new OccasionallyConnectionClient(PAPIURL, deviceId, deviceKey);
int retCode = occasionallyConnectionClient->SendMessageTo(deviceId2, "OPEN");

// while on the other device
// happens the following
OccasionallyConnectionClient *occasionallyConnectionClient2 = new OccasionallyConnectionClient(PAPIURL, deviceId2, deviceKey2);

PushedMessage pushedMessage = occasionallyConnectionClient->PeekMessage();
if(pushedMessage.Payload == "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.

The Spin method should be run regularly since it keeps working the underlying websocket library and sends heartbeat messages (by default once in every minute). If the server doesn’t receive heartbeat messages then it drops the websocket connection.

Record telemetry data:

PersistentConnectionClient *persistentConnectionClient = new PersistentConnectionClient(WSURL);
PlatformOperationResult por = persistentConnectionClient->Login(deviceId, deviceKey);

while(!End())
{
        // do some other BL code and mesurements
        int retCode = persistentConnectionClient->RecordTelemetryData("{\"Temperature\": 24, \"Humidity\": 50 }");

	persistentConnectionClient->Spin();
	usleep(100);
}

Send message to an other device:

PersistentConnectionClient *persistentConnectionClient = new PersistentConnectionClient(WSURL);
PlatformOperationResult por = persistentConnectionClient->Login(deviceId, deviceKey);

persistentConnectionClient->SendMessageTo(_otherDeviceId, "OPEN");
while(!End())
{
        // do some other BL code and mesurements

	persistentConnectionClient->Spin();
	usleep(100);
}

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

Receive and forget mode (QoS 0-level):

void messageReceived(const PushedMessage& pushedMessage)
{
	if(pushedMessage.Payload == "OPEN")
	{
		OpenDoor();
	}
}

// subscription

PersistentConnectionClient *persistentConnectionClient = new PersistentConnectionClient(WSURL);
PlatformOperationResult por = persistentConnectionClient->Login(otherDevice, deviceKey);

persistentConnectionClient->Subscribe(ReceiveAndForget, messageReceived);

// Run the application here for ages
// and ages
// and ages
// ...
while(true)
{
	persistentConnectionClient->Spin();
	usleep(100);
	// exit condition
}

// and unsubscribe if you stop the application
persistentConnectionClient->Unsubscribe();
persistentConnectionClient->Close();

Peek and commit mode (QoS 1-level)

void messageReceived(const PushedMessage& pushedMessage)
{
	if(pushedMessage.Payload == "OPEN")
	{
		OpenDoor();
	}
}

// subscription

PersistentConnectionClient *persistentConnectionClient = new PersistentConnectionClient(WSURL);
PlatformOperationResult por = persistentConnectionClient->Login(otherDevice, deviceKey);

persistentConnectionClient->Subscribe(PeekAndCommit, messageReceived);

// Run the application here for ages
// and ages
// and ages
// ...
while(true)
{
	persistentConnectionClient->Spin();
	usleep(100);
	// exit condition
}

// and unsubscribe if you stop the application
persistentConnectionClient->Unsubscribe();
persistentConnectionClient->Close();

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:

ReportingClient *reportingClient = new ReportingClient(RAPIURL);

DeviceClient* deviceClient = reportingClient->Device();
deviceClient->SetDevice(deviceId, deviceKey);

vector sinks = deviceClient->GetSinks();

// ask the user to select a sink (currentDataSink)

string currentDataJson = deviceClient->GetCurrentDataJson(SINKDATA);

// Process current data report

// the time series report is always generated for a whole day. Specify a time value in the day of interest.
string timeSeriesDataJson = deviceClient->GetTimeSeriesJson(SINKTIMESERIES, time(NULL));

// Process time series report in CSV

string timeSeriesDataCsv = deviceClient->GetTimeSeriesCsv(SINKTIMESERIES, time(NULL));

 

Network report examples:

ReportingClient *reportingClient = new ReportingClient(RAPIURL);
NetworkClient* networkClient = reportingClient->Network();

networkClient->SetNetwork(networkId, networkKey);

vector sinks = networkClient->GetSinks();

// ask the user to select sinks

string currentDataJson = networkClient->GetCurrentDataJson(SINKDATA);

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

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

 

Advertisements