# Provisioning

An important concept to understand is that in order for our daemon to
interract with most cloud-side services, it first needs to be authorized to
do so.

This is what we call *provisioning* your device.

As long as your device is not provisioned, the only gRPC endpoint you will be
able to successfully / reliably use is
[`com.fundamentum.edge.v1.Provisioning.Provision`][provision-endpoint]. As its
name suggests, this gRPC endpoint is exactly the tool you need in order to
*provision* your device.

A very simple way to provision your device could be via the [`grpcurl`][grpcurl]
CLI tool. This tool is available as part of the [nix developer shell
environment][dev-setup].

Assuming your edge daemon is running locally and exposes its gRPC interface via
the default tcp socket (which is usually the case when launched via `$ cargo
run`), a provisioning operation would look like:

```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": "MYLONGTOKEN"
    }' \
    127.0.0.1:8080 \
    com.fundamentum.edge.v1.Provisioning.Provision
# ...
```

As you most likely guessed, the above values won't work out of the box and
you'll need to obtain values for your specific case.

The gist of it is that in order to obtain the proper value for the above fields,
you'll need the following:

 1. Gain access to the proper [Fundamentum Hub][fcp-hub-prod] *project*.

    This usually implies the creation of an account and requesting access to a
    priviledged user.

 2. Navigate to the proper *registry* within this *project*.

 3. From the *registry* page, hit the *Download Token file* button.

    In this file you will find the values for the following fields:
    `"project_id"`, `"region_id"`, `"registry_id"` and `"access_token"` (called
    `"token"` therein).

 4. Identify the proper `"asset_type_id"`.

     1. From the same *registry* page:
         1. Under the *Device Limit* section, you'll find a table in which you
            should be able to locate a *row* for the *device type* matching the
            device you're provisioning.

            If none exists, this registry don't accept this type of device. You
            should probably discuss this with your team / hub admin so that it
            gets added.

         2. Now, in this *row*, take note of the number under the *Id* column.

     2. From the *Device Types* tab / page:
         1. In one of the presented tables, locate the *row* whose *Id* column
            matches the *Id* you identified in the previous step.
         2. Now, in this *row*, look under the *Asset Type ID (ati)* column to
            find the value you'll use as `"asset_type_id"`.

 5. Give your device a unique name via the `"serial_number"` field.

 6. Optionally, you can target a different cloud environment through the
    `"api_base_url"`.

    Note that if you change this field, you also need to use the proper
    *Fundamentum Hub* instance (impacts above \#1 step).

    Here's a couple of typical values for this field:

     -  For the [production hub][fcp-hub-prod], use:
        `"https://devices.fundamentum-iot.com"` (the default when unspecified).
     -  For the [development hub][fcp-hub-dev], use:
        `"https://devices.fundamentum-iot-dev.com"`.
     -  For a [locally run cloud environment][fcp-hub-local] (internal
        developers only), you'll typically use:
        `"http://devices-gateway.fundamentum.test"`


Upon successful provisioning (no error returned by the gRPC endpoint), you
should see the `provisioning.json` and `rsa_(public|private).pem` files appear
in your edge daemon's *state directory*.

[provision-endpoint]:
    https://bitbucket.org/amotus/fundamentum-edge-proto/src/master/provisioning.proto#lines-11
[grpcurl]: https://github.com/fullstorydev/grpcurl
[dev-setup]: ./development-setup.md
[fcp-hub-prod]: https://hub.fundamentum-iot.com
[fcp-hub-dev]: https://hub.fundamentum-iot-dev.com
[fcp-hub-local]: https://hub.fundamentum.test