README.md

Astarte Device SDK Rust  

Warning: this SDK is experimental, correctness and API stability are currently not guaranteed

The Astarte Device SDK for Rust is a ready to use library that provides communication and pairing primitives to an Astarte Cluster.

See the Astarte documentation for more information regarding Astarte and the available SDKs.

Basic usage

use std::error::Error as StdError;

use astarte_device_sdk::{
    builder::DeviceBuilder,
    transport::mqtt::MqttConfig,
    error::Error,
    prelude::*,
    store::sqlite::SqliteStore,
};

async fn run_astarte_device() -> Result<(), Box<dyn StdError>> {

    let realm = "realm_name";
    let device_id = "device_id";
    let credentials_secret = "device_credentials_secret";
    let pairing_url = "astarte_cluster_pairing_url";

    // Initializing an instance of a device can be performed as shown in the following three steps.

    // 1. (optional) Initialize a database to store the properties
    let db = SqliteStore::connect_db("/var/lib/astarte/store.db").await?;

    // 2. Initialize device options and mqtt config (the ".database(db)" is not needed if 1 was skipped)
    let mut mqtt_config = MqttConfig::with_credential_secret(realm, device_id, credentials_secret, pairing_url);
    mqtt_config.ignore_ssl_errors();

    // 3. Create the device instance
    let (mut client, mut connection) = DeviceBuilder::new()
        .interface_directory("./examples/interfaces")?
        .store(db)
        .connect(mqtt_config).await?
        .build().await;

    // Publishing new values can be performed using the send and send_object functions.

    // Send individual datastream or set individual property
    let data: i32 = 12;
    client.send("interface.name", "/endpoint/path", data).await?;

    // Send aggregated object datastream
    use astarte_device_sdk::AstarteAggregate;
    // If the derive feature is not enabled
    #[cfg(not(feature = "derive"))]
    use astarte_device_sdk_derive::AstarteAggregate;

    #[derive(Debug, AstarteAggregate)]
    struct MyAggObj {
        endpoint1: f64,
        endpoint2: i32
    }

    let data = MyAggObj {endpoint1: 1.34, endpoint2: 22};
    client.send_object("interface.name", "/common/endpoint/path", data).await?;

    // Receive a server publish from the event channel
    tokio::spawn(async move {
        loop {
          match client.recv().await {
              Ok(data) => (), // Handle data
              Err(err) => (), // Handle errors
          }
        }
    });

    // Blocking call for the device event loop
    connection.handle_events().await?;

    Ok(())
}

Building the library

You can build the library using:

cargo build

Examples

Check out how to start with the SDK using one of the included examples.