Skip to main content

Using Data Orchestrator/MQTT through Data Orchestrator SDK

If you are using one of Data Orchestrator's SDK, the Pairing routine is entirely managed, and you won't need to do any of the aforementioned steps. Just make sure your Credentials Secret is passed as the apiKey configuration key, to allow the SDK to perform automatically the Pairing routine when needed.

The SDK does a number of automated things under the hood. Its flow is:

  1. The SDK verifies if a SSL certificate for connecting to the broker is present.
  2. If it is, it attempts connecting to the Transport.
  3. If the Transport doesn't accept the connection due to an SSL error, it queries Pairing API about its certificate status.
  4. If Pairing API returns a problem with the certificate or, in general, the certificate isn't valid, the certificate is erased and the Pairing procedure begins.
  5. The SDK invokes Pairing API until it manages to obtain a valid Certificate for the Transport.

The SDK considers a Device successfully paired when it has a valid certificate and manages to connect to the Transport. Once in this state, the Device can start exchanging data.

Note: the Pairing procedure is secure as long as Pairing API is queried using HTTPS. Plain HTTP installations are vulnerable to a number of different attacks and should NEVER be used in production.

Interfaces and Introspection​

A Device must have some installed interfaces to be capable of exchanging data. These interfaces must be made known to the SDK and installed in the Device's Realm, as previously explained.

The SDK expects the user to provide a directory containing a set of valid interfaces. It then takes care of making Data Orchestrator aware of its registered interfaces through a process called Introspection. Introspection is a special control message in Data Orchestrator's protocol which makes Data Orchestrator aware of a list of Interfaces and relative versions which are installed on the Device.

Again, Data Orchestrator's SDK, given a directory, is capable of performing the correct procedures for keeping Introspecting in sync correctly without any kind of user intervention. Data Orchestrator's SDK also takes care of updating a Device's Introspection if its interfaces change.

Exchanging data​

When a Device connects successfully, it must then subscribe to its server Interfaces. The SDK takes care of this detail and exposes a higher level interface. For example, using the Qt5 SDK:

{
m_sdk = new AstarteDeviceSDK(QStringLiteral("/path/to/transport-astarte.conf"), QStringLiteral("/path/to/interfaces"), deviceId);
connect(m_sdk->init(), &Hemera::Operation::finished, this, &AstarteStreamQt5Test::checkInitResult);
connect(m_sdk, &AstarteDeviceSDK::dataReceived, this, &AstarteStreamQt5Test::handleIncomingData);
}

void AstarteStreamQt5Test::handleIncomingData(const QByteArray &interface, const QByteArray &path, const QVariant &value)
{
qDebug() << "Received data, interface: " << interface << "path: " << path << ", value: " << value << ", Qt type name: " << value.typeName();
}

Applications can simply connect to the handleIncomingData signal and have data correctly formatted and delivered as it runs through the transport. On the other hand, for sending data:

m_sdk->sendData(interface, path, value);

The SDK will check if data is coherent with its introspection, and send data onto the transport in the correct way.

Reliability, retention and persistency in the SDK​

Data Orchestrator's SDK has an internal concept of persistency, depending on the behaviour defined in its installed Interfaces. The retention parameter, specifically, tells Data Orchestrator's SDK how hard it should try to send a specific message. In case the Transport is unreachable, the SDK might try to persist, either in memory or on disk, and send the message when the connection is available again.

Please note that these parameters declared in Interfaces are to be considered on a best effort basis. In case your SDK does not support persistency or has persistency disabled, a number of warranties requested by an Interface might not be satisfied. Make sure your SDK is configured correctly before moving to production.