Skip to content

ESF AWS Greengrass IPC Cloud Endpoint

Prerequisites

The AWS Greengrass IPC Cloud Endpoint is a specific ESF Cloud Connector based on the AWS IoT SDK v2.0 for IPC communication. It requires a Greengrass Component that publishes the following Componente environment variables on a protected UNIX socket:

  • AWS_GG_NUCLEUS_SOCKET_PATH
  • AWS_GG_SVCUID

These variables are read from this Cloud Connection and used to initialize the AWS IoT SDK v2.0 IPC client. A Greengrass component that exposes such variables is detailed at IPC Credentials Provider Component Installation.

AwsGreengrassIPCCloudEndpoint Configuration

The AwsGreengrassIPCCloudEndpoint can be configured to define the AWS IoT Thing Name to which shadow updates are published. This setting has no impact if no Shadow or Iot Core components are used along this connection.

If this field is left empty, then it will defaulted to {iot:thingName}. Greengrass Nucleus by default does not interpolate this variable, refer to the Greengrass merge configuration update documentation for the interpolateComponentConfiguration option.

AwsGreengrassIPCDataService Configuration

Please refer to the DataService Configuration page to get more details on the configuration parameters available for this service. Make the use-case specific changes to the service and click the Apply button to save them.

AwsGreengrassIPCDataTransport Configuration

The AwsGreengrassIPCDataTransport configuration page allows to define the path to the UNIX socket where the Greengrass environment variables are published via the com.eurotech.framework.ipc.credentials.provider socket path option.

The AWS Greengrass Pubsub protocol allows to define whether the subscribers should receive messages from:

  • all the components, including messages from the component that subscribes;
  • only from other components;
  • or a default behavior dependant on the subscribed topic (depends on whether the topic contains an MQTT wildcard).

For more information, refer to the SubscribeToTopic documentation. This behavior can be controlled by selecting an option of the Pubsub Receive Mode setting.

Publish/Subscribe to Local Pubsub Messages

This Cloud Connection allows to create the following Publish/Subscribe components:

  • com.eurotech.framework.aws.ipc.publisher.AwsGreengrassPubsubPublisher
  • com.eurotech.framework.aws.ipc.subscriber.AwsGreengrassPubsubSubscriber

These components allow to send and receive local messages using the Greengrass Pubsub protocol. This protocol is generally used for local communications between greengrass components.

Topic limitations

Internal usage special character: the special character ~ is not allowed in topic names.

IoT Core sync

AwsGreengrassPubsubPublisher and AwsGreengrassPubsubSubscriber cannot be used to publish/subscribe messages to IoT Core, unless a MQTT Bridge is configured to do so. Refer to the Publish/Subscribe to IoT Core Messages section for dedicated components.

Publish/Subscribe to IoT Core Messages

This Cloud Connection allows to create the following Publish/Subscribe components:

  • com.eurotech.framework.aws.ipc.publisher.AwsGreengrassIotCorePublisher
  • com.eurotech.framework.aws.ipc.subscriber.AwsGreengrassIotCoreSubscriber

These components allow to Publish/Subscribe AWS Iot Core MQTT Messages and can be configured to perform Shadow management operations using pre-defined topics (see Supported AWS Device Shadow MQTT Topics). See section Manage Device Shadows for dedicated services.

Topic limitations

AWS Reserved Topic Starting Character: do not attempt to publish or subscribe to any topic beginning with the $ identifier (except for the $aws/ hierarchy). This will result in a terminated connection by the AWS IoT Core broker since this is considered a reserved identifier by AWS IoT Core.

Internal usage special character: the special character ~ is not allowed in topic names.

Multiple subscribers

The current implementation has some limitations when multiple subscribers on the same topic but with different QoS are used. The underlying AWS IPC Java v2 client does not expose the QoS of the received message in its callback APIs, and it is not possible to infer the QoS based solely on the topic name given that multiple subscribers can subscribe onto the same topic but with different QoS. To overcome this issue, the Cloud Connection will forward two copies of the same message to the subscribers; one with QoS 0 and one with QoS 1.

Manage Device Shadows

This Cloud Connection allows to create the following Publish/Subscribe components for managing AWS Device Shadows:

  • com.eurotech.framework.aws.ipc.publisher.AwsGreengrassShadowPublisher
  • com.eurotech.framework.aws.ipc.subscriber.AwsGreengrassShadowSubscriber

The AwsGreengrassShadowPublisher allows to publish shadow updates either locally or directly on AWS IoT Core using the option Shadow Publish Target option. Shadow updates published locally are not mirrored to IoT Core unless a MQTT Bridge is configured to do so. Depending on whether classic or named shadows are specified in the component's configuration, one between the following topics is used:

# classic shadow
$aws/things/{thing_name}/shadow/update
# named shadow
$aws/things/{thing_name}/shadow/name/{shadow_name}/update

where {thing_name} is configurable in the AwsGreengrassIPCCloudEndpoint Configuration and {shadow_name} is settable in the AwsGreengrassShadowPublisher configuration.

The AwsGreengrassShadowSubscriber allows to subscribe to shadow update topics either locally or directly from AWS IoT Core using the option Shadow Subscribe Target option. Which topic to subscribe to is defined by the Topic ID configuration. The {iot:thingName} part of is replaced at runtime with the Thing Name option of the Cloud Endpoint layer.

Depending on wheter the Shadow Name is specified, classic or named shadows are used and the topic will change accordingly at runtime. For example:

# classic shadow
$aws/things/{thing_name}/shadow/update/accepted
# named shadow
$aws/things/{thing_name}/shadow/name/{shadow_name}/update/accepted

Tip

If none of the options available as Topic ID suits the application, please use the more generic IoT Core Subscriber where the topic can be defined entirely.