Interact with component configuration - Amazon IoT Greengrass
Minimum SDK versionsGetConfigurationUpdateConfigurationSubscribeToConfigurationUpdateSubscribeToValidateConfigurationUpdatesSendConfigurationValidityReport
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Interact with component configuration

The component configuration IPC service lets you do the following:

  • Get and set component configuration parameters.

  • Subscribe to component configuration updates.

  • Validate component configuration updates before the nucleus applies them.

Minimum SDK versions

The following table lists the minimum versions of the Amazon IoT Device SDK that you must use to interact with component configuration.

SDK Minimum version

Amazon IoT Device SDK for Java v2

v1.2.10

Amazon IoT Device SDK for Python v2

v1.5.3

Amazon IoT Device SDK for C++ v2

v1.17.0

Amazon IoT Device SDK for JavaScript v2

v1.12.0

GetConfiguration

Gets a configuration value for a component on the core device. You specify the key path for which to get a configuration value.

Request

This operation's request has the following parameters:

componentName (Python: component_name)

(Optional) The name of the component.

Defaults to the name of the component that makes the request.

keyPath (Python: key_path)

The key path to the configuration value. Specify a list where each entry is the key for a single level in the configuration object. For example, specify ["mqtt", "port"] to get the value of port in the following configuration.

{
  "mqtt": {
    "port": 443
  }
}

To get the component's complete configuration, specify an empty list.

Response

This operation's response has the following information:

componentName (Python: component_name)

The name of the component.

value

The requested configuration as an object.

UpdateConfiguration

Updates a configuration value for this component on the core device.

Request

This operation's request has the following parameters:

keyPath (Python: key_path)

(Optional) The key path to the container node (the object) to update. Specify a list where each entry is the key for a single level in the configuration object. For example, specify the key path ["mqtt"] and the merge value { "port": 443 } to set the value of port in the following configuration.

{
  "mqtt": {
    "port": 443
  }
}

The key path must specify a container node (an object) in the configuration. If the node doesn't exist in the component's configuration, this operation creates it and sets its value to the object in valueToMerge.

Defaults to the root of the configuration object.

timestamp

The current Unix epoch time in milliseconds. This operation uses this timestamp to resolve concurrent updates to the key. If the key in the component configuration has a greater timestamp than the timestamp in the request, then the request fails.

valueToMerge (Python: value_to_merge)

The configuration object to merge at the location that you specify in keyPath. For more information, see Update component configurations.

Response

This operation doesn't provide any information in its response.

SubscribeToConfigurationUpdate

Subscribe to receive notifications when a component's configuration updates. When you subscribe to a key, you receive a notification when any child of that key updates.

This operation is a subscription operation where you subscribe to a stream of event messages. To use this operation, define a stream response handler with functions that handle event messages, errors, and stream closure. For more information, see Subscribe to IPC event streams.

Event message type: ConfigurationUpdateEvents

Request

This operation's request has the following parameters:

componentName (Python: component_name)

(Optional) The name of the component.

Defaults to the name of the component that makes the request.

keyPath (Python: key_path)

The key path to the configuration value for which to subscribe. Specify a list where each entry is the key for a single level in the configuration object. For example, specify ["mqtt", "port"] to get the value of port in the following configuration.

{
  "mqtt": {
    "port": 443
  }
}

To subscribe to updates for all values in the component's configuration, specify an empty list.

Response

This operation's response has the following information:

messages

The stream of notification messages. This object, ConfigurationUpdateEvents, contains the following information:

configurationUpdateEvent (Python: configuration_update_event)

The configuration update event. This object, ConfigurationUpdateEvent, contains the following information:

componentName (Python: component_name)

The name of the component.

keyPath (Python: key_path)

The key path to the configuration value that updated.

SubscribeToValidateConfigurationUpdates

Subscribe to receive notifications before this component's configuration updates. This lets components validate updates to their own configuration. Use the SendConfigurationValidityReport operation to tell the nucleus whether or not the configuration is valid.

Important

Local deployments don't notify components of updates.

This operation is a subscription operation where you subscribe to a stream of event messages. To use this operation, define a stream response handler with functions that handle event messages, errors, and stream closure. For more information, see Subscribe to IPC event streams.

Event message type: ValidateConfigurationUpdateEvents

Request

This operation's request doesn't have any parameters.

Response

This operation's response has the following information:

messages

The stream of notification messages. This object, ValidateConfigurationUpdateEvents, contains the following information:

validateConfigurationUpdateEvent (Python: validate_configuration_update_event)

The configuration update event. This object, ValidateConfigurationUpdateEvent, contains the following information:

deploymentId (Python: deployment_id)

The ID of the Amazon IoT Greengrass deployment that updates the component.

configuration

The object that contains the new configuration.

SendConfigurationValidityReport

Tell the nucleus whether or not a configuration update to this component is valid. The deployment fails if you tell the nucleus that the new configuration isn't valid. Use the SubscribeToValidateConfigurationUpdates operation to subscribe to validate configuration updates.

If a component doesn't respond to a validate configuration update notification, the nucleus waits the amount of time that you specify in the deployment's configuration validation policy. After that timeout, the nucleus proceeds with the deployment. The default component validation timeout is 20 seconds. For more information, see Create deployments and the DeploymentConfigurationValidationPolicy object that you can provide when you call the CreateDeployment operation.

Request

This operation's request has the following parameters:

configurationValidityReport (Python: configuration_validity_report)

The report that tells the nucleus whether or not the configuration update is valid. This object, ConfigurationValidityReport, contains the following information:

status

The validity status. This enum, ConfigurationValidityStatus, has the following values:

  • ACCEPTED – The configuration is valid and the nucleus can apply it to this component.

  • REJECTED – The configuration isn't valid and the deployment fails.

deploymentId (Python: deployment_id)

The ID of the Amazon IoT Greengrass deployment that requested the configuration update.

message

(Optional) A message that reports why the configuration isn't valid.

Response

This operation doesn't provide any information in its response.