fundamentum_edge_daemon/

lib.rs

//! The supported way to access Fundamentum's ecosystem from linux devices.
//!
//! # Usage
//!
//! ## Launching the daemon
//!
//! ```sh
//! $ cargo run
//! # ..
//! ```
//!
//! -  The *gRPC server* will bind to `127.0.0.1:8080`.
//! -  A default version of the *configuration file* (`config.toml`) will be
//!    created in the *current working directory* if it does not already exists.
//! -  The *current working directory* will be used as the *state directory*.
//!    Here's a list of state files you might encounter:
//!
//!     -  `provisioning.json` and `rsa_(public|private).pem` will be created
//!        upon first successful provisioning.
//!
//!
//! You can override these defaults using the available CLI options. Those can
//! be listed as follow:
//!
//! ```sh
//! $ cargo run -- --help
//! # ..
//! ```
//!
//! Further customizations are also possible through the *configuration file*
//! (`config.toml`).
//!
//! ## Accessing exposed services via the gRPC interface
//!
//! The various Fundamentum services are made available through a *gRPC
//! interface* (see [`fundamentum-edge-proto` repository][proto-repo]).
//!
//! In order to be able to use most of the gRPC services (the most notable
//! exception being the `Provisioning` service), your device will need to be
//! *provisioned*. In order to do so, a good place to start would be the
//! [provisioning procedure][prov-proc].
//!
//! [proto-repo]: https://bitbucket.org/amotus/fundamentum-edge-proto
//! [prov-proc]: ./doc/provisioning-procedure.md
//!
//! ### Through the CLI
//!
//! It is possible to use the [`grpcurl`][grpcurl] CLI tool to interact with the
//! daemon.
//!
//!  >  **Note**: All of the example commands below assume a TCP [*network
//!  >  socket*][net-sock] transport. If your Edge Daemon uses a [*Unix Domain
//!  >  Socket* (UDS)][uds] instead, see [Using `grpcurl` over a *Unix Domain
//!  >  Socket* (UDS)][grpcurl-over-uds] for instructions on adapting these commands
//!  >  to your use case.
//!
//!  -  To provision the device:
//!
//!     ```sh
//!     $ grpcurl \
//!         -plaintext \
//!         -d '{
//!             "api_base_url": "https://devices.fundamentum-iot.com",
//!             "project_id": 1,
//!             "region_id": 2,
//!             "registry_id": 3,
//!             "serial_number": "device1",
//!             "asset_type_id": 4,
//!             "access_token": "TOKEN"
//!         }' \
//!         127.0.0.1:8080 \
//!         com.fundamentum.edge.v1.Provisioning.Provision
//!     # ...
//!     ```
//!
//!  -  To publish telemetry data:
//!
//!     ```sh
//!     $ grpcurl \
//!         -plaintext \
//!         -d '{
//!             "sub_topic": "test",
//!             "qos": 0,
//!             "payload": "SGVsbG8sIFdvcmxkIQ=="
//!         }' \
//!         127.0.0.1:8080 \
//!         com.fundamentum.edge.v1.Telemetry.Publish
//!     # ...
//!     ```
//!
//!  -  To get the device configuration:
//!
//!     ```sh
//!     $ grpcurl \
//!         -plaintext \
//!         127.0.0.1:8080 \
//!         com.fundamentum.edge.v1.Configuration.Get
//!     # ...
//!     ```
//!
//!  -  To subscribe to configuration updates:
//!
//!     ```sh
//!     $ grpcurl \
//!         -plaintext \
//!         127.0.0.1:8080 \
//!         com.fundamentum.edge.v1.Configuration.UpdateStream
//!     # ...
//!     ```
//!
//!  -  To publish states data:
//!
//!     ```sh
//!     $ grpcurl \
//!         -plaintext \
//!         -d '{
//!             "states": {
//!                 "status": "ok",
//!                 "alarms": [
//!                     "alarm1",
//!                     "alarm2"
//!                 ]
//!             },
//!             "sub_devices": [
//!                 {
//!                     "serial_number": "device1",
//!                     "states": {
//!                         "rssi": 50,
//!                         "battery_level": 75,
//!                         "temperature": 25
//!                     }
//!                 }
//!             ]
//!         }' \
//!         127.0.0.1:8080 \
//!         com.fundamentum.edge.v1.StatesEvent.PublishJson
//!     # ...
//!     ```
//!
//!  -  To subscribe to incoming actions:
//!
//!     ```sh
//!     $ grpcurl \
//!         -plaintext \
//!         127.0.0.1:8080 \
//!         com.fundamentum.edge.v1.Actions.Subscribe
//!     # ...
//!     ```
//!
//!  -  To update the status of an action:
//!
//!     ```sh
//!     $ grpcurl \
//!         -plaintext \
//!         -d '{
//!             "id": 123,
//!             "serial_numbers": ["device1", "device2"],
//!             "ongoing": {"progress": 50},
//!             "message": "In progress...",
//!             "payload": "SGVsbG8sIFdvcmxkIQ=="
//!         }' \
//!         127.0.0.1:8080 \
//!         com.fundamentum.edge.v1.Actions.UpdateStatus
//!     # ...
//!     ```
//!
//!  -  To subscribe to firmware update requests:
//!
//!     ```sh
//!     $ grpcurl \
//!         -plaintext \
//!         127.0.0.1:8080 \
//!         com.fundamentum.edge.v1.FirmwareUpdate.Subscribe
//!     # ...
//!     ```
//!
//!  -  To update the status of an firmware update:
//!
//!     ```sh
//!     $ grpcurl \
//!         -plaintext \
//!         -d '{
//!             "id": 123,
//!             "serial_numbers": ["device1", "device2"],
//!             "ongoing": {"progress": 50},
//!             "message": "Update in progress...",
//!         }' \
//!         127.0.0.1:8080 \
//!         com.fundamentum.edge.v1.FirmwareUpdate.UpdateStatus
//!     # ...
//!     ```
//!
//! [grpcurl]: https://github.com/fullstorydev/grpcurl
//! [uds]: https://en.wikipedia.org/wiki/Unix_domain_socket
//! [net-sock]: https://en.wikipedia.org/wiki/Network_socket
//! [grpcurl-over-uds]:
//!     https://bitbucket.org/amotus/fundamentum-edge-daemon/src/master/doc/grpcurl-over-uds.md
//!
//! ### Through language specific bindings
//!
//! For more serious use cases, we provide specific support for the following
//! languages:
//!
//!  -  Rust: [source][proto-rust-repo] / [crates.io][proto-rust-pkg] /
//!     [examples][proto-rust-examples]
//!  -  Python: [source][proto-python-repo] / [pypi][proto-python-pkg]
//!
//! Please make sure that you use a binding library version compatible with your
//! edge daemon service.
//!
//! Note that in case your language is not already officially supported, it is
//! still possible to use the [protocol buffer compiler][protoc] on the [*gRPC*
//! `*.proto` files][proto-repo] to generate a bindings library for *almost any
//! language*.
//!
//! [protoc]: https://grpc.io/docs/protoc-installation
//! [proto-rust-repo]: https://bitbucket.org/amotus/fundamentum-edge-proto-rust
//! [proto-rust-pkg]: https://crates.io/crates/fundamentum-edge-proto
//! [proto-rust-examples]:
//! https://bitbucket.org/amotus/fundamentum-edge-proto-rust/src/master/examples
//! [proto-python-repo]:
//! https://bitbucket.org/amotus/fundamentum-edge-proto-python
//! [proto-python-pkg]: https://pypi.org/project/fundamentum-edge-proto/
//!
#![doc = document_features::document_features!()]
#![cfg_attr(test, allow(clippy::unwrap_used))]

mod app_core;
pub use app_core::{AppConfig, AppCore, AppCoreError, state};

mod services;
pub use services::grpc;

pub mod utils;