# Fundamentum Edge Daemon

[![Crates.io][crate-badge]][crate-url]
[![License][licence-badge]][licence-url]
[![Build Status][build-badge]][build-url]
[![Docs.rs][doc-badge]][doc-url]

[Website][website-url] | [Docs][doc-url]

[crate-badge]: https://img.shields.io/crates/v/fundamentum-edge-daemon.svg
[crate-url]: https://crates.io/crates/fundamentum-edge-daemon
[licence-badge]: https://img.shields.io/badge/license-apache_2.0-blue.svg
[licence-url]: https://bitbucket.org/amotus/fundamentum-edge-daemon/src/master/LICENSE
[build-badge]: https://img.shields.io/bitbucket/pipelines/amotus/fundamentum-edge-daemon/master
[build-url]: https://bitbucket.org/amotus/fundamentum-edge-daemon/pipelines
[doc-badge]: https://docs.rs/fundamentum-edge-daemon/badge.svg
[doc-url]: https://docs.rs/fundamentum-edge-daemon
[website-url]: https://www.dimonoff.com/services/fundamentum-iot-platform-paas

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:

 -  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:50051 \
        com.fundamentum.edge.v1.Actions.UpdateStatus
    # ...
    ```

[grpcurl]: https://github.com/fullstorydev/grpcurl

#### 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/


## Development setup

Please see the [development setup guide](doc/development-setup.md).

## Releases

All official versions of this component are published to
[crates.io/crates/fundamentum-edge-daemon][crates-io-pkg]. A list of all
published versions is available under the [versions
tab][crates-io-pkg-versions].

Detailed release notes are available in this repo at [`CHANGELOG.md`][changelog].

[crates-io-pkg]: https://crates.io/crates/fundamentum-edge-daemon
[crates-io-pkg-versions]: https://crates.io/crates/fundamentum-edge-daemon/versions
[changelog]: ./CHANGELOG.md


## License

Licensed under Apache License, Version 2.0 [LICENSE](LICENSE).