cloud-relay v0.2.5-provision-url-doc-51129e448e460cba028ba7031b891ab3a8166190

Cloud Relay Block

Easily send data to an IoT Cloud provider

Cloud Relay accepts application data via MQTT and relays it to a cloud provider's IoT Core facility. You only need to provide the data, and Cloud Relay takes care of messaging with the cloud provider. Cloud Relay works with AWS, Azure, and Google Cloud (GCP).

Getting Started

You first must set up the cloud provider's IoT service. Balena also provides cloud functions for AWS, Azure and GCP that expose an HTTP endpoint to initially provision each device. See the Cloud Provisioning section below.

Device

On the balena device, we will use a docker-compose example script that includes containers for generation of WiFi metrics data, an MQTT broker, and the Cloud Relay block itself. First create a multi-container fleet in balenaCloud and provision a device with balenaOS. See the online docs for details.

Next define fleet variables as described in the Configuration section below. Finally push the docker-compose script to the balena builders, substituting your fleet's name for <myFleet> in the commands below.

    git clone https://github.com/balena-io-examples/cloud-relay.git
    cd cloud-relay/doc/wifi-example
    balena push <myFleet>

Cloud Relay first will attempt to provision the device if required, using PROVISION_URL. Once that completes, you should see data flowing through the cloud relay to the provider's MQTT broker, like the log output below.

sensor  publishing sample: {} {'short_uuid': 'ab24d4b', 'quality_value': '70', 'quality_max': 70, 'signal_level': -39.0}
sensor  publishing sample: {} {'short_uuid': 'ab24d4b', 'quality_value': '70', 'quality_max': 70, 'signal_level': -39.0}

GCP Note Cloud Relay publishes only to the telemetry (events) topic. It does not publish to the state topic or subscribe to the configuration or commands topics.

Cloud Provisioning

Cloud Relay triggers secure provisioning of a balena device to the provider's registry before publishing data. This provisioning generates public key credentials as environment variables, which are stored on balenaCloud and passed on to the device. Cloud Relay then uses the credentials to communicate with the provider's IoT Core.

We have developed projects that automate this provisioning, including use of the provider's "cloud function" capability to trigger the provisioning code via HTTP request. See the linked projects in the table below and the environment variables in the Configuration section below.

Configuration

Environment variables, probably common to all devices so may be defined as balena Fleet variables. This section is organized by cloud provider. In all cases Cloud Relay must know the message topic used by the data producer.

AWS

The provisioning tool generates AWS_CERT and AWS_PRIVATE_KEY.

Azure

The provisioning tool generates AZURE_CERT and AZURE_PRIVATE_KEY.

GCP

The provisioning tool generates GCP_CLIENT_PATH, GCP_DATA_TOPIC_ROOT, GCP_PRIVATE_KEY, and GCP_PROJECT_ID.