Cloud defines connections to cloud endpoints


Cloud Configuration

Cloud

Referenced By:
EdgeConnectConfig   RecipeDefinition  

Fields

NameTypeDescriptionRequired
connectorsmap of string to CloudConnectorDefines the cloud Connectors to connect to.

A map of unique identifier to a definition of a CloudConnector.

Connectors defined here will be connected to, and can be targeted with publish filters. Depending on CloudConnector
implementation and configuration, they may also subscribe and generate cloud events.
No
tlsTLSConfigNo

Cloud Connectors

azuredps

This cloud connector provides per-device connections to Azure IoT Hub, with connections provisioned by Azure DPS.
Each device that communicates with this cloud connector will get a dedicated connection with authorization from the
Azure DPS service.

Cloud to device messages arrive in pipelines as an event with cloud eventType. The payload is included in the
payload key. If you want the payload to be the top level event map, use the unwrapCloudPayload option.

DirectMethods also fire as cloud eventType events, but they also include a _requestId key. To respond to the
DirectMethod, publish to this cloud connector and make sure to include the _requestId in the event map. The _requestId
doesn't need to be in the actual payload published to Azure, just in the event map that reaches the publish filter.

DirectMethods in Edge Connect only support map/object input and map/object response, not primitives.

Regular telemetry publishes (non-direct method responses) support the _properties key in the event map. If this key
is included and it contains a map of strings, those key/value pairs will be added to the published message as
message properties.

Fields

NameTypeDescriptionRequired
capabilityModelIdKeystringThe key that contains the Capability Model ID of the device.
Example: "urn:rigado:RuuviTag:1"
No
credentialLifetimepositiveDurationcredential lifetime (duration string)No
debugbooleanEnable debug loggingNo
devicesobjectDevice configuration, primarily for translating MAC address to Device IDsNo
directMethodsarrayA list of Direct Methods to subscribe to for all device typesNo
hoststringThe DPS Registration Host URL
Example: "https://global.azure-devices-provisioning.net"
Yes
idScopestringThe ID Scope of the Azure DPS Service. A unique value used by the IoT Hub Device Provisioning Service.Yes
nonPersistentMaxCountintegerIf set to > 0, this will set the maximum number of messages the MQTT memorystore
will hold before dropping messages
Must be used with persistent=false
No
persistentbooleanIf set to true, outbound and inbound MQTT messages are stored on disk instead of in memory, allowing them to be
reloaded upon restart or reboot if they were not yet processed.
No
persistentMaxSizestringIf set to > 0, this will set the maximum size (bytes) on disk that the MQTT filestore
can consume before dropping messages.
Supported suffixes (B, KB, KiB, MB, MiB, GB, GiB,...), max size of 1GiB.
Must be used with persistent=true
Example: "64MB"
No
previewAPIbooleanUse the new preview API of DPSNo
reconnectTimeoutstringHow long to wait before retrying to connect a failed/disconnected device to IOT Hub
This is used when a device is waiting for approval, gets blocked, or gets otherwise disconnected.
Supports durations in the form of 1s 5m 1h etc.
No
registerOnReconnectbooleanRe-register devices with DPS and ask for hub assignment on every reconnect.
Enabling this will slow down reconnect performance but can help with device load balancing and failover on IOT Hub.
Restarting Edge Connect will always cause all devices to request hub assignment.
No
sasKeystringThe Shared Access Signature key to use to generate device keys when authenticating with Azure DPS.
This is required unless x509 is provided or the key dpsDeviceKey is provided for each device in the event map when connecting.
No
subscribeTimeout?This will set the timeout for subscribing/unsubscribing to a topicNo
unwrapCloudPayloadbooleanPut the payload from cloud messages in the top level event map, rather than wrapping them in the "payload" key
Example: true
No
verbosebooleanEnable verbose loggingNo
x509X509No

Example

{
  "service": {
    "cloud": {
      "connectors": {
        "my-dps": {
          "config": {
            "devices": {
              "deviceIdTemplate": "my_device_{{ .mac }}"
            },
            "host": "https://global.azure-devices-provisioning.net",
            "idScope": "0123f0_redacted",
            "sasKey": "abcdf_redacted_abcd"
          },
          "type": "azuredps"
        }
      }
    }
  }
}

azureiot

This cloud connector provides a connection to the Azure IoT Device cloud.

Supports publishing telemetry and receiving cloud commands,
but does not support topic based publishing, or topic based subscriptions.

Cloud to device messages arrive in pipelines as an event with cloud eventType. The payload is included in the
payload key. If you want the payload to be the top level event map, use the unwrapCloudPayload option.

DirectMethods also fire as cloud eventType events, but they also include a requestId key. To respond to the
DirectMethod, publish to this cloud connector and make sure to include the requestId in the event map. The requestId
doesn't need to be in the actual payload published to Azure, just in the event map that reaches the publish filter.

DirectMethods in Edge Connect only support map/object input and map/object response, not primitives.

Fields

NameTypeDescriptionRequired
connectionStringstringThe connection string provided by Azure IoT for the connecting device.
Example: "\u003cazure iot device connection string\u003e"
No
credentialLifetimepositiveDuration
templating
credential lifetime (duration string)No
debugbooleanEnable debug loggingNo
directMethodsarrayDirect Methods to subscribe toNo
nonPersistentMaxCountintegerIf set to > 0, this will set the maximum number of messages the MQTT memorystore
will hold before dropping messages
Must be used with persistent=false
No
persistentbooleanIf set to true, outbound and inbound MQTT messages are stored on disk instead of in memory, allowing them to be
reloaded upon restart or reboot if they were not yet processed.
No
persistentMaxSizestringIf set to > 0, this will set the maximum size (bytes) on disk that the MQTT filestore
can consume before dropping messages.
Supported suffixes (B, KB, KiB, MB, MiB, GB, GiB,...), max size of 1GiB.
Must be used with persistent=true
Example: "64MB"
No
reconnectTimeoutstringHow long to wait before retrying to connect to IOT Hub
Supports durations in the form of 1s 5m 1h etc.
No
subscribeTimeout?This will set the timeout for subscribing/unsubscribing to a topicNo
unwrapCloudPayloadbooleanPut the payload from cloud messages in the top level event map, rather than wrapping them in the "payload" key
Example: true
No
verbosebooleanEnable verbose loggingNo
x509X509No

Example

{
  "service": {
    "cloud": {
      "connectors": {
        "my-azure": {
          "config": {
            "connectionString": "azureiot:connectionstring"
          },
          "type": "azureiot"
        }
      }
    }
  }
}

azureiotcentral

This cloud connector provides per-device connections to the Azure IoT Central Cloud.
Each device that communicates with this cloud connector will get a dedicated connection with authorization from the
Azure DPS service.

Commands fire as cloud eventType events, and include a requestId key. To respond to the
Command, publish to this cloud connector and make sure to include the requestId in the event map. The requestId
doesn't need to be in the actual payload published to Azure, just in the event map that reaches the publish filter.

Commands in Edge Connect only support map/object input and map/object response, not primitives.

Fields

NameTypeDescriptionRequired
capabilityModelIdKeystringThe key that contains the Capability Model ID of the device.
Example: "urn:rigado:RuuviTag:1"
No
credentialLifetimepositiveDurationcredential lifetime (duration string)No
debugbooleanEnable debug loggingNo
devicesobjectDevice configuration, primarily for translating MAC address to Device IDsNo
directMethodsarrayA list of Direct Methods to subscribe to for all device typesNo
idScopestringThe ID Scope of the Azure IOT Central Application. A unique value used by the IoT Hub Device Provisioning Service.
Can be found in the Administration/Device Connection page on the IOT Central site.
Yes
nonPersistentMaxCountintegerIf set to > 0, this will set the maximum number of messages the MQTT memorystore
will hold before dropping messages
Must be used with persistent=false
No
persistentbooleanIf set to true, outbound and inbound MQTT messages are stored on disk instead of in memory, allowing them to be
reloaded upon restart or reboot if they were not yet processed.
No
persistentMaxSizestringIf set to > 0, this will set the maximum size (bytes) on disk that the MQTT filestore
can consume before dropping messages.
Supported suffixes (B, KB, KiB, MB, MiB, GB, GiB,...), max size of 1GiB.
Must be used with persistent=true
Example: "64MB"
No
previewAPIbooleanUse the new preview API of IOT CentralNo
reconnectTimeoutstringHow long to wait before retrying to connect a failed/disconnected device to IOT Central
This is used when a device is waiting for approval, gets blocked, or gets otherwise disconnected.
Supports durations in the form of 1s 5m 1h etc.
No
sasKeystringThe Shared Access Signature key to use to generate device keys when authenticating with Azure IOT Central. Can be
found in the Administration/Device Connection page on the IOT Central site.
Yes
subscribeTimeout?This will set the timeout for subscribing/unsubscribing to a topicNo
unwrapCloudPayloadbooleanPut the payload from cloud messages in the top level event map, rather than wrapping them in the "payload" key
Example: true
No
verbosebooleanEnable verbose loggingNo

Example

{
  "service": {
    "cloud": {
      "connectors": {
        "my-iotcentral": {
          "config": {
            "capabilityModelIdKey": "",
            "devices": {
              "deviceIdTemplate": "my_device_{{ .mac }}"
            },
            "idScope": "0123f0_redacted",
            "sasKey": "abcdf_redacted_abcd"
          },
          "type": "azureiotcentral"
        }
      }
    }
  }
}

digitalTwins

This connector sends sensor telemetry data to Microsoft Azure Digital Twins.
All devices, sensors, matchers, and user defined functions must already be setup in Digital Twins.
The device must also have a role that allows it to update sensor values.
The cloud connector simply authenticates the device (the Gateway) and then routes telemetry data for each sensor over MQTT.

Supports publishing but does not support subscriptions.

Fields

NameTypeDescriptionRequired
baseURLstringThe BaseURL of the digital twins instance to use
Example: "mydigitaltwinsinstance.westcentralus.azuresmartspaces.net"
Yes
debugbooleanEnable debug loggingNo
deviceHardwareIdstringThe device hardwareId in Digital Twins that matches the Gateway running Edge Connect and for which the SAS token is issued.
Example: "C049731826-00010"
Yes
nonPersistentMaxCountintegerIf set to > 0, this will set the maximum number of messages the MQTT memorystore
will hold before dropping messages
Must be used with persistent=false
No
persistentbooleanIf set to true, outbound and inbound MQTT messages are stored on disk instead of in memory, allowing them to be
reloaded upon restart or reboot if they were not yet processed.
No
persistentMaxSizestringIf set to > 0, this will set the maximum size (bytes) on disk that the MQTT filestore
can consume before dropping messages.
Supported suffixes (B, KB, KiB, MB, MiB, GB, GiB,...), max size of 1GiB.
Must be used with persistent=true
Example: "64MB"
No
sasTokenstringA Shared Access Signature that has been generated for this deviceId
Example: "SharedAccessSignature id=D149731826-00310\u0026se=44456789124\u0026kv=1\u0026sig=djmMcgXRRDBdvIIJZCogvxRynxUniyCwGlmUF7vgB6TlLvk%3D"
Yes
sensorHardwareIdKeystringA key in the incoming data that maps to the sensor hardwareId for the particular sensor in Digital Twins
Example: "mac"
Yes
subscribeTimeout?This will set the timeout for subscribing/unsubscribing to a topicNo
verbosebooleanEnable verbose loggingNo

Example

{
  "service": {
    "cloud": {
      "connectors": {
        "my-dt": {
          "config": {
            "baseURL": "mydigitaltwinsinstance.westcentralus.azuresmartspaces.net",
            "deviceHardwareId": "D149731826-00310",
            "sasToken": "SharedAccessSignature id=D149731826-00310\u0026se=44456789124\u0026kv=1\u0026sig=djmMcgXRRDBdvIIJZCogvxRynxUniyCwGlmUF7vgB6TlLvk%3D",
            "sensorHardwareIdKey": "mac"
          },
          "type": "digitalTwins"
        }
      }
    }
  }
}

googlecloudiot

This cloud connector provides a connection to the Google Cloud IoT Core
service.

Supports publishing on topics and subscribing to topics. Also supports Device configuration via linking to a Device Group.

For devices to be attached to a Gateway successfully, they first need to be "bound" in the Google Cloud IOT Core
API/settings. At startup, or when dynamically attached, an "attach" message is sent to Google to let it know the
device is online. This will fail if the device is not already "bound" on the Google side.

Cloud to device messages arrive in pipelines as a cloud eventType. The topic is included in the topic key and the
payload is included in the payload key. If you want the payload to be the top level event map, use the
unwrapCloudPayload option.

Fields

NameTypeDescriptionRequired
connectMessageCloudMessageNo
debugbooleanEnable debug loggingNo
devicesCloudConnectorDevicesNo
gatewayIdstringID of this Gateway in Google Cloud. Required by Google to start with a lowercase character, so if the Gateway
serial number is used, make sure to lowercase it.
Example: "c123456789-12345"
Yes
nonPersistentMaxCountintegerIf set to > 0, this will set the maximum number of messages the MQTT memorystore
will hold before dropping messages
Must be used with persistent=false
No
persistentbooleanIf set to true, outbound and inbound MQTT messages are stored on disk instead of in memory, allowing them to be
reloaded upon restart or reboot if they were not yet processed.
No
persistentMaxSizestringIf set to > 0, this will set the maximum size (bytes) on disk that the MQTT filestore
can consume before dropping messages.
Supported suffixes (B, KB, KiB, MB, MiB, GB, GiB,...), max size of 1GiB.
Must be used with persistent=true
Example: "64MB"
No
privateKeystringPrivate Key that matches the Public Key for this Gateway that was provided to Google.
Example: "base64 encoded private key"
Yes
projectIdstringGoogle Project ID
Example: "iot-project"
Yes
regionstringGoogle Region the project is in
Example: "europe-west1"
Yes
registryIdstringGoogle IOT Registry ID
Example: "my-registry-id"
Yes
subscribeTimeout?This will set the timeout for subscribing/unsubscribing to a topicNo
subscribeTopicsarray
templating
Topics to subscribe to. Incoming messages on these topics will arrive in pipelines as cloud type events.No
unwrapCloudPayloadbooleanPut the payload from cloud messages in the top level event map, rather than wrapping them in the "payload" key
Example: true
No
verbosebooleanEnable verbose loggingNo

Example

{
  "service": {
    "cloud": {
      "connectors": {
        "googlecloud": {
          "config": {
            "gatewayId": "gatewaySerialLowercased",
            "privateKey": "....",
            "projectId": "myproject",
            "region": "uswest",
            "registryId": "myregistry"
          },
          "type": "googlecloudiot"
        }
      }
    }
  }
}

http

This cloud connector represents an HTTP destination using the URL and method specified.

Support publishing but no subscriptions.

Fields

NameTypeDescriptionRequired
castringAdditional CAs to append to system certpool
CA certs must be base64 encoded pem format
No
debugbooleanEnable debug loggingNo
headersobject
templating
Headers contains a map of key and value pairs to place in the headers section of the HTTP request. Typically, these headers would include things like an API key or other authentication data.No
methodstringTells the filter which HTTP command to use to send data. Valid options are POST and PUT.
Example: "PUT"
Yes
persistentbooleanEnable persistent storage for failed requestsNo
retryDelayMultipliernumberRetry delay multiplier, the retry delay will be multiplied by this value on each request errorNo
retryDisablebooleanDisable retrying a request on errorNo
retryInitialDelaystringRetry initial delayNo
retryMaxAttemptsintegerMaximum retry attempts
If either RetryMaxAttempts or RetryTimeout is satisfied the request will be discarded
No
retryMaxDelaystringMaximum delay between any retryNo
retryOfflineDelaystringRetry delay (fixed) when server is unreachableNo
retryTimeoutstringHow long to keep retrying a request when getting an error
If either RetryMaxAttempts or RetryTimeout is satisfied the request will be discarded
No
successfulStatusesarrayDefine the httpStatus codes that are considered successful.No
timeoutintegerA single HTTP request attempt will timeout after this length of time. The timeout is specified as an integer number of seconds. The default timeout is 30 seconds.
Example: 10
No
urlstring
templating
The HTTP url to send data
Example: "https://myserver.net/data"
Yes
verbosebooleanEnable verbose loggingNo

Example

{
  "service": {
    "cloud": {
      "connectors": {
        "my-http": {
          "config": {
            "headers": {
              "AuthToken": "something-secret"
            },
            "method": "POST",
            "url": "http://myserver.com/path"
          },
          "type": "http"
        }
      }
    }
  }
}

mqtt

This cloud connector provides a connection to an MQTT broker.

Support publishing on topics and subscriptions on topics.

Cloud to device messages arrive in pipelines as an event with cloud eventType. The payload is included in the
payload key. If you want the payload to be the top level event map, use the unwrapCloudPayload option.

Fields

NameTypeDescriptionRequired
basestringThe base address of the broker. This is required by some brokers, such as AWS IoT
Example: "/mqtt"
No
clientIdstringThe ClientID to use in the MQTT connection.No
connectMessageCloudMessageNo
credentialsMQTTCredentialsNo
debugbooleanEnable debug loggingNo
devicesCloudConnectorDevicesNo
hoststringThe host address of the broker
Example: "some-host.us-east-1.amazonaws.com"
Yes
keystorePasswordstringNo
nonPersistentMaxCountintegerIf set to > 0, this will set the maximum number of messages the MQTT memorystore
will hold before dropping messages
Must be used with persistent=false
No
passwordstringNo
persistentbooleanIf set to true, outbound and inbound MQTT messages are stored on disk instead of in memory, allowing them to be
reloaded upon restart or reboot if they were not yet processed.
No
persistentMaxSizestringIf set to > 0, this will set the maximum size (bytes) on disk that the MQTT filestore
can consume before dropping messages.
Supported suffixes (B, KB, KiB, MB, MiB, GB, GiB,...), max size of 1GiB.
Must be used with persistent=true
Example: "64MB"
No
portintegerThe port of the broker
Example: 8883
Yes
publishQosintegerMQTT QoS level. Defaults to 1 as that is most widely supported. Valid options are 0,1,2. Note: some brokers
(such as AWS IoT Core) do not support QoS 2.
Example: 1
No
schemestringThe communication protocol of the broker. Options are: tcp, tcps, wss, ssl
Example: "tcps"
Yes
subscribeTimeout?This will set the timeout for subscribing/unsubscribing to a topicNo
subscribeTopicsarray
templating
Topics to subscribe to. Incoming messages on these topics will arrive in pipelines as cloud type events.No
unwrapCloudPayloadbooleanPut the payload from cloud messages in the top level event map, rather than wrapping them in the "payload" key
Example: true
No
usernamestringNo
verbosebooleanEnable verbose loggingNo

Example

{
  "service": {
    "cloud": {
      "connectors": {
        "my-mqtt": {
          "config": {
            "base": "",
            "host": "iothub.myserver.net",
            "port": 8883,
            "scheme": "tcps"
          },
          "type": "mqtt"
        }
      }
    }
  }
}

websocket

This cloud connector represents a websocket connection

Fields

NameTypeDescriptionRequired
binaryModebooleanEnable binary mode for messages to cloud
If false, messages will be sent to the cloud in text mode
No
castringAdditional CAs to append to system certpool
CA certs must be base64 encoded pem format
No
debugbooleanEnable debug loggingNo
headersobjectHeaders contains a map of key and value pairs to place in the headers section of the HTTP request. Typically, these headers would include things like an API key or other authentication data.No
persistentbooleanEnable persistent storage for failed requestsNo
retryDelayMultipliernumberRetry delay multiplier, the retry delay will be multiplied by this value on each request errorNo
retryDisablebooleanDisable retrying a request on errorNo
retryInitialDelaystringRetry initial delayNo
retryMaxAttemptsintegerMaximum retry attempts
If either RetryMaxAttempts or RetryTimeout is satisfied the request will be discarded
No
retryMaxDelaystringMaximum delay between any retryNo
retryOfflineDelaystringRetry delay (fixed) when server is unreachableNo
retryTimeoutstringHow long to keep retrying a request when getting an error
If either RetryMaxAttempts or RetryTimeout is satisfied the request will be discarded
No
urlstringThe websocket url to connect to
Example: "wss://myserver.net/path"
Yes
verbosebooleanEnable verbose loggingNo

Example

{
  "service": {
    "cloud": {
      "connectors": {
        "my-websocket": {
          "config": {
            "headers": {
              "AuthToken": "something-secret"
            },
            "url": "wss://server.com/xyz"
          },
          "type": "websocket"
        }
      }
    }
  }
}

Reference

CloudConnector

Describes the configuration for a cloud connector. CloudConnectors
can publish events to the cloud by being targeted with a publish or publishTopic filter in a pipeline.

Some CloudConnector types also support subscribing for cloud commands/events and subscribing on topics.

Referenced By:
Cloud  

Fields

NameTypeDescriptionRequired
configobjectConfiguration information for the particular type of CloudConnector used. Described in the documentation for each CloudConnector type.No
typestringThe unique type of the CloudConnector, must match the type of one of the available CloudConnectors
Example: "http"
Yes

Example

{
  "service": {
    "cloud": {
      "connectors": {
        "my-mqtt": {
          "config": {
            "host": "iothub.myserver.net",
            "port": "8883",
            "scheme": "tcps"
          },
          "type": "mqtt"
        }
      }
    }
  }
}

CloudConnectorDevices

Device configuration for connectors that support identification of individual devices.

Note: not all cloud connectors support all of these options. Support for each option is documented in the
specific cloud connector.

Referenced By:
googlecloudiot   mqtt  

Fields

NameTypeDescriptionRequired
attachAllbooleanIf set to true, devices simply included in the referenced device group will be attached/subscribed. If set to false (default),
devices will not be attached/subscribed until they are determined to be present.
Example: false
No
connectMessageCloudMessageMessage to send, per attached device, to the cloud when a connection is successfully established or re-establishedNo
detachMissingbooleanIf set to true, devices will be detached/unsubscribed if they are removed from the device group, or if they go missing
from presence tracking. If set to false (default) devices are only detached/unsubscribed when they are removed from
the device group.
Example: false
No
deviceIdTemplatestring
templating
A text template for converting the lowercase mac field to any deviceId that is desired by the cloud configuration.
This template is used to generate a Device ID that is then used to attach to the cloud and subscribe to topics.
If no deviceIdTemplate is supplied, defaults to using the lowercase MAC address of the device.

NOTE: this should not be used if you are using the deviceIdTemplate on the device group that is connected to this.
The Device ID should be generated using that template instead.
Example: "sensor_{{ .mac | ToUpper }}"
No
groupstringDevice Group that contains the devices this cloud connector is concerned with. The connector will attach
and subscribe to topics for devices contained in this group.
Example: "my-devices"
No
subscribeTopicsarray
templating
Per device topics to subscribe to. Incoming messages on these topics will arrive in pipelines as cloud type events.
deviceId is available in the text template.
No

Example

{
  "service": {
    "cloud": {
      "connectors": {
        "my-mqtt": {
          "config": {
            "devices": {
              "attachAll": true,
              "detachMissing": true,
              "deviceIdTemplate": "{{ .mac | ToUpper }}",
              "group": "my-sensors",
              "subscribeTopics": [
                "sensors/sensor_{{ .deviceId }}/commands"
              ]
            },
            "host": "iothub.myserver.net",
            "port": "8883",
            "scheme": "tcps"
          },
          "type": "mqtt"
        }
      }
    }
  }
}

CloudMessage

A statically configured message to send to the cloud. Currently only used by Cloud Connectors that support the connectMessage parameter.

Referenced By:
CloudConnectorDevices   googlecloudiot   mqtt  

Fields

NameTypeDescriptionRequired
messageobjectThe message bodyYes
topicstring
templating
Topic the message is onYes

MQTTCredentials

Referenced By:
mqtt  

Fields

NameTypeDescriptionRequired
cabytesNo
certbytesNo
keybytesNo
keystoreCastringNo
keystoreCertstringNo
keystoreKeystringNo

TLSConfig

Override the default system certificate pool typically at /etc/ssl/certs/ with a user provided set of root CAs. The content
certificates can contain multiple certificates (pem format, encoded in base64)
certificatesDir can contain multiple .pem certificates
If no valid certificate is found in either certificates or certificatesDir, an error will be thrown.

Referenced By:
Cloud  

Fields

NameTypeDescriptionRequired
certificatesstringbase64 certificates to use as rootCAs, will be combined with certificatesDir
Example: "LS0tLS1CRUdJTiB... (truncated)"
No
certificatesDirstringdirectory of certificates to use as rootCAs, will be combined with certificates
Example: "/home/mycerts"
No
insecureSkipVerifybooleanskip TLS certificate verification
Example: true
No

X509

X.509 certificate, private key, and CA

Referenced By:
azuredps   azureiot  

Fields

NameTypeDescriptionRequired
castringYes
certificatestringYes
keystringYes