Crate hub_sdk

Geeny Hub SDK

Introduction

The Geeny Hub SDK provides an abstraction over APIs and communication interfaces necessary to connect physical or virtual devices to the Geeny Cloud. The Hub SDK can be used in one of two ways: as a Rust library crate, or as a standalone binary that can be used by applications written in other languages by providing an interprocess communication (IPC) interface.

For developers with an existing Hub Device, such as a Smart Home Gateway, the standalone Geeny Hub Service may be used to provide a single local interface to communicate with Geeny Cloud Services to enable device provisioning, sending messages to the cloud, and receiving messages from the cloud. The Geeny Hub Service may be installed as a package, or included as part of a firmware generation process such as Buildroot or Yocto. When used as a service, no knowledge of Rust development is necessary.

For developers building a new Hub Device, the Geeny Hub SDK may be used as a library (or crate), and can be tightly integrated into a Rust-based application. This allows developers to interact with the Geeny Cloud through an idiomatic Rust library interface, rather than having to implement REST, MQTT, and other communication protocols.

Components

Usage - As a Library Crate

extern crate hub_sdk;

use hub_sdk::{HubSDK, HubSDKConfig};

fn main() {
    let sdk_cfg = HubSDKConfig::default();

    // Begin running the SDK. The hub_sdk handle may be used to interact with
    // the SDK. This handle may be cloned and given to multiple consumers.
    let hub_sdk = HubSDK::new(sdk_cfg);

    let msgs = hub_sdk.receive_messages("ABC123")
        .expect("No known device with that serial number.");

    println!("Messages: {:?}", msgs);
}

Documentation

Full library documentation may be found on [Geeny's Documentation Site] (https://docs.geeny.io/sdk/), or it can be generated and displayed locally using cargo doc --open.

Usage - As a standalone service

# (Optional) Install the recommended version of the Rust toolchain
rustup install nightly-2018-04-08

# Move to Service Project directory
cd services/rest_api/rocket_api

# Create a valid config file for this service
cp ./geeny_hub_service.mvdb.json.example ./geeny_hub_service.mvdb.json

# Run the service, serving a REST IPC on localhost:9000
cargo +nightly-2018-04-08 run --release

Documentation

For more information regarding the REST IPC interface, please see [this Swagger API specification] (https://github.com/geeny/linux-hub-sdk/blob/release/docs/rest-ipc/swagger.json) for more information.

Requirements

The Geeny Hub SDK Library may be used on stable or nightly builds of Rust. We currently test the library with stable version 1.25, and with nightly version nightly-2018-04-08.

The Geeny Hub SDK Binary Service requires a nightly build of Rust. We currently test the service with nightly version nightly-2018-04-08.

Installation & Configuration

As a library

In your Cargo.toml, add the following lines:

[dependencies]
hub-sdk = "0.5"

In your main project file (likely lib.rs or main.rs), add the following line:

extern crate hub_sdk;

As a service

See the Usage - As a standalone service section above.

Testing

Unit tests may be run with cargo test.

License

Copyright (C) 2017-2018 Telefónica Germany Next GmbH, Charlottenstraße 4, 10969 Berlin.

This project is licensed under the terms of the Mozilla Public License Version 2.0.

Contact: devsupport@geeny.io

Third Party Components

This crate makes use of the following third party components with the following licenses:

License	Count	Dependencies
Apache-2.0	2	openssl, thread-id
Apache-2.0/MIT	76	antidote, backtrace, backtrace-sys, base64, bitflags, bitflags, cfg-if, coco, cookie, core-foundation, core-foundation-sys, custom_derive, dtoa, either, env_logger, error-chain, foreign-types, futures, gcc, httparse, hyper-native-tls, idna, isatty, itoa, lazy_static, libc, log, mqtt-protocol, native-tls, num-traits, num_cpus, ordermap, pear, pear_codegen, percent-encoding, pkg-config, quick-error, quote, rand, rayon, rayon-core, regex, regex, regex-syntax, regex-syntax, reqwest, rocket, rocket_codegen, rocket_contrib, rustc-demangle, scopeguard, security-framework, security-framework-sys, serde, serde_derive, serde_derive_internals, serde_json, serde_urlencoded, state, syn, synom, tempdir, thread_local, thread_local, threadpool, time, toml, traitobject, unicode-bidi, unicode-normalization, unicode-xid, unreachable, url, uuid, vcpkg, yansi
BSD-3-Clause	3	adler32, magenta, magenta-sys
MIT	21	advapi32-sys, conv, crypt32-sys, dbghelp-sys, hyper, kernel32-sys, language-tags, libflate, matches, mime, mvdb, openssl-sys, redox_syscall, schannel, secur32-sys, typeable, unicase, version_check, void, winapi, winapi-build
MIT OR Apache-2.0	1	safemem
MIT/Unlicense	9	aho-corasick, aho-corasick, byteorder, byteorder, memchr, memchr, rumqtt, utf8-ranges, utf8-ranges
MPL-2.0	2	geeny-api, smallvec
Other*	2	ring, untrusted

* Please see ring's license for more information regarding ring and untrusted's licensing.

Re-exports

pub extern crate geeny_api;

Modules

errors

Geeny Hub SDK Error Types

Structs

HubSDK	Interface handle for a HubSDK instance
HubSDKConfig	Configuration structure for a HubSDK instance
PartialThingMessage	Structure to contain a message to be sent to or received from the Geeny Cloud