Skip to content

balena-io-examples/cloud-relay

Repository files navigation

Cloud Relay Block

Easily send data to an IoT Cloud provider

Overview

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).

Note: Google has issued a deprecation notice for the Cloud IoT service due to shutdown in August 2023. Cloud Relay's support for GCP IoT Core will not receive further updates. ClearBlade provides a replacement IoT Core product that integrates with GCP Pub/Sub in a similar way. The only differences for Cloud Relay are use of a ClearBlade-specific provisioning tool and network messaging host. Cloud Relay now supports ClearBlade on an experimental basis.

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

We will create a fleet to push system metrics data to the cloud provider and add a device to it. Simply click on the Deploy with balena button below to create a fleet from this docker-compose file.

balena deploy button

Next define fleet variables as described in the Configuration section below. Finally, add a device to the fleet as prompted from the dashboard.

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

Published msg: {'short_uuid': 04166f8, "currentLoad":0.8995528642244212,"cpuTemperature":32.9,"mem":4762161152}
Published msg: {'short_uuid': 04166f8, "currentLoad":0.5756115873115185,"cpuTemperature":32.9,"mem":4762664960}

ClearBlade/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.

Provision-Send

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.

Provider / Cloud Function GitHub project
AWS Lambda aws-iot-provision
Azure Functions azure-iot-provision
GCP Cloud Functions for ClearBlade cb-gcp-iot-provision
GCP Cloud Functions for Google IoT Core (deprecated) gcp-iot-provision

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.

Name Value Notes
PRODUCER_TOPIC default sensors Message topic from data producer. sensors is used by the Sensor block.
CLOUD_PROVIDER AWS, AZURE, or GCP Optional, by default Cloud Relay can determine the provider based on other environment variables as described below. However, explicitly defining the cloud provider is useful for a custom provisioning method.
Use GCP for ClearBlade as well, and see the ClearBlade/GCP section below.

AWS

Name Value Notes
PROVISION_URL like
https://xxxxxxxx.execute-api.<region>.amazonaws.com/default/provision
URL to trigger the provisioning cloud function. See Functions -> provision -> Configuration -> Triggers in the AWS Lambda console.
AWS_DATA_ENDPOINT like
xxxxxxxx-ats.iot.<region>.amazonaws.com
Host name to receive data. See Settings in the AWS IoT console.
CLOUD_CONSUMER_TOPIC default sensors Topic for message sent to AWS.

AWS_CERT and AWS_PRIVATE_KEY variables for each device are generated by the provisioning tool.

Azure

Name Value Notes
PROVISION_URL like
https://xxxx.azurewebsites.net/api/provision
URL to trigger the provisioning cloud function.
AZURE_HUB_HOST like
<iot-hub-name>.azure-devices.net
Host name to receive data. See Overview for the IoT Hub in the Azure portal.
CLOUD_CONSUMER_TOPIC default sensors Cloud Relay creates a topic key with this value in the properties map included in the message to Azure.

AZURE_CERT and AZURE_PRIVATE_KEY variables for each device are generated by the provisioning tool.

ClearBlade / GCP

Name Value Notes
PROVISION_URL like
https://<region>-<projectID>.cloudfunctions.net/provision
URL to trigger the provisioning cloud function.
MESSAGING_HOST default mqtt.googleapis.com Hostname to receive data. The default is for Google IoT Core. See ClearBlade docs for their IoT Core hosts.
CLOUD_CONSUMER_TOPIC default events Topic for message sent to GCP, which expects events as the default telemetry topic. As the docs describe, you also may publish to a subfolder like events/alerts.

GCP_CLIENT_PATH, GCP_DATA_TOPIC_ROOT, GCP_PRIVATE_KEY, and GCP_PROJECT_ID variables for each device are generated by the provisioning tool. The ClearBlade provisioning tool also uses these same variable names.