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).
MQTT bridge
The MQTT bridge component (aws.greengrass.clientdevices.mqtt.Bridge
) relays MQTT messages between client
devices, local Greengrass publish/subscribe, and Amazon IoT Core. You can use this component to act on MQTT
messages from client devices in custom components and sync client devices with the
Amazon Web Services Cloud.
Client devices are local IoT devices that connect to a Greengrass core device to send MQTT
messages and data to process. For more information, see Interact with local IoT devices.
You can use this component to relay messages between the following message brokers:
-
Local MQTT – The local MQTT broker handles messages between client devices and a
core device.
-
Local publish/subscribe – The local Greengrass message broker handles messages between
components on a core device. For more information about how to interact with these messages
in Greengrass components, see Publish/subscribe local messages.
-
Amazon IoT Core – The Amazon IoT Core MQTT broker handles messages between IoT devices and
Amazon Web Services Cloud destinations. For more information about how to interact with these messages in
Greengrass components, see Publish/subscribe Amazon IoT Core MQTT messages.
The MQTT bridge uses QoS 1 to publish and subscribe to Amazon IoT Core, even when a client
device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you
might observe additional latency when you relay MQTT messages from client devices on the
local MQTT broker to Amazon IoT Core. For more information about MQTT configuration on core
devices, see Configure MQTT timeouts and cache settings.
Versions
This component has the following versions:
Type
This component is a plugin component
(aws.greengrass.plugin
). The Greengrass
nucleus runs this component in the same Java Virtual Machine (JVM) as the nucleus. The
nucleus restarts when you change this component's version on the core device.
This component uses the same log file as the Greengrass
nucleus. For more information, see Monitor Amazon IoT Greengrass logs.
For more information, see Component types.
Operating system
This component can be installed on core devices that run the following operating systems:
Requirements
This component has the following requirements:
Dependencies
When you deploy a component, Amazon IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the released versions of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the Amazon IoT Greengrass console. On the component details page, look for the Dependencies list.
- 2.2.3
-
The following table lists the dependencies for version 2.2.2 of this
component.
- 2.2.0 – 2.2.2
-
The following table lists the dependencies for versions 2.2.0 to 2.2.2 of this
component.
- 2.1.1
-
The following table lists the dependencies for version 2.1.1 of this
component.
- 2.0.0 to 2.1.0
-
The following table lists the dependencies for versions 2.0.0 through 2.1.0 of this
component.
For more information about component dependencies, see the component recipe reference.
Configuration
This component provides the following configuration parameters that you can
customize when you deploy the component.
- 2.2.x
-
mqttTopicMapping
-
The topic
mappings that you want to bridge. This component subscribes to messages on the source
topic and publishes the messages that it receives to the destination topic. Each topic
mapping defines the topic, source type, and destination type.
This object contains the following information:
topicMappingNameKey
-
The name of this topic mapping. Replace
topicMappingNameKey
with a name that helps you identify
this topic mapping.
This object contains the following information:
topic
-
The topic or topic filter to bridge between the source and target
brokers.
You can use the +
and #
MQTT topic
wildcards to relay messages on all topics that match a topic filter.
For more information, see MQTT topics in
the Amazon IoT Core Developer Guide.
targetTopicPrefix
-
The prefix to add to the target topic when this component relays
the message.
source
-
The source message broker. Choose from the following options:
-
LocalMqtt
– The local MQTT broker where client devices
communicate.
-
Pubsub
– The local Greengrass publish/subscribe message broker.
-
IotCore
– The Amazon IoT Core MQTT message broker.
The MQTT bridge uses QoS 1 to publish and subscribe to Amazon IoT Core, even when a client
device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you
might observe additional latency when you relay MQTT messages from client devices on the
local MQTT broker to Amazon IoT Core. For more information about MQTT configuration on core
devices, see Configure MQTT timeouts and cache settings.
source
and target
must be different.
target
-
The target message broker. Choose from the following options:
-
LocalMqtt
– The local MQTT broker where client devices
communicate.
-
Pubsub
– The local Greengrass publish/subscribe message broker.
-
IotCore
– The Amazon IoT Core MQTT message broker.
The MQTT bridge uses QoS 1 to publish and subscribe to Amazon IoT Core, even when a client
device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you
might observe additional latency when you relay MQTT messages from client devices on the
local MQTT broker to Amazon IoT Core. For more information about MQTT configuration on core
devices, see Configure MQTT timeouts and cache settings.
source
and target
must be different.
brokerUri
-
(Optional) The URI of the local MQTT broker. You must specify this parameter if you
configure the MQTT broker to use a different port than the default port 8883. Use the
following format, and replace port
with the port where the MQTT
broker operates: ssl://localhost:port
.
Default: ssl://localhost:8883
Example: Configuration merge update
The following example configuration update specifies the following:
-
Relay messages from client devices to Amazon IoT Core on topics that match the
clients/+/hello/world
topic filter.
-
Relay messages from client devices to local publish/subscribe on topics that match the
clients/+/detections
topic filter, and add the events/input/
prefix to the target topic. The resulting target topic matches the
events/input/clients/+/detections
topic filter.
-
Relay messages from client devices to Amazon IoT Core on topics that match the
clients/+/status
topic filter, and add the
$aws/rules/StatusUpdateRule/
prefix to the target topic. This example
relays these messages directly to an Amazon IoT rule named
StatusUpdateRule
to reduce costs using Basic Ingest.
{
"mqttTopicMapping": {
"ClientDeviceHelloWorld": {
"topic": "clients/+/hello/world",
"source": "LocalMqtt",
"target": "IotCore"
},
"ClientDeviceEvents": {
"topic": "clients/+/detections",
"targetTopicPrefix": "events/input/",
"source": "LocalMqtt",
"target": "Pubsub"
},
"ClientDeviceCloudStatusUpdate": {
"topic": "clients/+/status",
"targetTopicPrefix": "$aws/rules/StatusUpdateRule/",
"source": "LocalMqtt",
"target": "IotCore"
}
}
}
- 2.1.x
-
mqttTopicMapping
-
The topic
mappings that you want to bridge. This component subscribes to messages on the source
topic and publishes the messages that it receives to the destination topic. Each topic
mapping defines the topic, source type, and destination type.
This object contains the following information:
topicMappingNameKey
-
The name of this topic mapping. Replace
topicMappingNameKey
with a name that helps you identify
this topic mapping.
This object contains the following information:
topic
-
The topic or topic filter to bridge between the source and target
brokers.
If you specify the LocalMqtt
or IotCore
source
broker, you can use the +
and #
MQTT topic wildcards
to relay messages on all topics that match a topic filter. For more
information, see MQTT topics in the
Amazon IoT Core Developer Guide.
source
-
The source message broker. Choose from the following options:
-
LocalMqtt
– The local MQTT broker where client devices
communicate.
-
Pubsub
– The local Greengrass publish/subscribe message broker.
-
IotCore
– The Amazon IoT Core MQTT message broker.
The MQTT bridge uses QoS 1 to publish and subscribe to Amazon IoT Core, even when a client
device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you
might observe additional latency when you relay MQTT messages from client devices on the
local MQTT broker to Amazon IoT Core. For more information about MQTT configuration on core
devices, see Configure MQTT timeouts and cache settings.
source
and target
must be different.
target
-
The target message broker. Choose from the following options:
-
LocalMqtt
– The local MQTT broker where client devices
communicate.
-
Pubsub
– The local Greengrass publish/subscribe message broker.
-
IotCore
– The Amazon IoT Core MQTT message broker.
The MQTT bridge uses QoS 1 to publish and subscribe to Amazon IoT Core, even when a client
device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you
might observe additional latency when you relay MQTT messages from client devices on the
local MQTT broker to Amazon IoT Core. For more information about MQTT configuration on core
devices, see Configure MQTT timeouts and cache settings.
source
and target
must be different.
brokerUri
-
(Optional) The URI of the local MQTT broker. You must specify this parameter if you
configure the MQTT broker to use a different port than the default port 8883. Use the
following format, and replace port
with the port where the MQTT
broker operates: ssl://localhost:port
.
Default: ssl://localhost:8883
Example: Configuration merge update
The following example configuration update specifies to relay messages from client devices
to Amazon IoT Core on the clients/MyClientDevice1/hello/world
and
clients/MyClientDevice2/hello/world
topics.
{
"mqttTopicMapping": {
"ClientDevice1HelloWorld": {
"topic": "clients/MyClientDevice1/hello/world",
"source": "LocalMqtt",
"target": "IotCore"
},
"ClientDevice2HelloWorld": {
"topic": "clients/MyClientDevice2/hello/world",
"source": "LocalMqtt",
"target": "IotCore"
}
}
}
- 2.0.x
-
mqttTopicMapping
-
The topic
mappings that you want to bridge. This component subscribes to messages on the source
topic and publishes the messages that it receives to the destination topic. Each topic
mapping defines the topic, source type, and destination type.
This object contains the following information:
topicMappingNameKey
-
The name of this topic mapping. Replace
topicMappingNameKey
with a name that helps you identify
this topic mapping.
This object contains the following information:
topic
-
The topic or topic filter to bridge between the source and target
brokers.
If you specify the LocalMqtt
or IotCore
source
broker, you can use the +
and #
MQTT topic wildcards
to relay messages on all topics that match a topic filter. For more
information, see MQTT topics in the
Amazon IoT Core Developer Guide.
source
-
The source message broker. Choose from the following options:
-
LocalMqtt
– The local MQTT broker where client devices
communicate.
-
Pubsub
– The local Greengrass publish/subscribe message broker.
-
IotCore
– The Amazon IoT Core MQTT message broker.
The MQTT bridge uses QoS 1 to publish and subscribe to Amazon IoT Core, even when a client
device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you
might observe additional latency when you relay MQTT messages from client devices on the
local MQTT broker to Amazon IoT Core. For more information about MQTT configuration on core
devices, see Configure MQTT timeouts and cache settings.
source
and target
must be different.
target
-
The target message broker. Choose from the following options:
-
LocalMqtt
– The local MQTT broker where client devices
communicate.
-
Pubsub
– The local Greengrass publish/subscribe message broker.
-
IotCore
– The Amazon IoT Core MQTT message broker.
The MQTT bridge uses QoS 1 to publish and subscribe to Amazon IoT Core, even when a client
device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you
might observe additional latency when you relay MQTT messages from client devices on the
local MQTT broker to Amazon IoT Core. For more information about MQTT configuration on core
devices, see Configure MQTT timeouts and cache settings.
source
and target
must be different.
Example: Configuration merge update
The following example configuration update specifies to relay messages from client devices
to Amazon IoT Core on the clients/MyClientDevice1/hello/world
and
clients/MyClientDevice2/hello/world
topics.
{
"mqttTopicMapping": {
"ClientDevice1HelloWorld": {
"topic": "clients/MyClientDevice1/hello/world",
"source": "LocalMqtt",
"target": "IotCore"
},
"ClientDevice2HelloWorld": {
"topic": "clients/MyClientDevice2/hello/world",
"source": "LocalMqtt",
"target": "IotCore"
}
}
}
Local log file
This component uses the same log file as the
Greengrass nucleus component.
- Linux
-
/greengrass/v2
/logs/greengrass.log
- Windows
-
C:\greengrass\v2
\logs\greengrass.log
To view this component's logs
Changelog
The following table describes the changes in each version of the component.
Version
|
Changes
|
2.2.4
|
Version updated for Greengrass client devices auth component version 2.3.0
release.
|
2.2.3
|
This version contains bug fixes and improvements.
|
2.2.2
|
- Bug fixes and improvements
-
|
2.2.1
|
- Bug fixes and improvements
-
Fixes issues that can result in the MQTT bridge failing to subscribe to
MQTT topics.
|
2.2.0
|
- New features
-
-
Adds support for MQTT topic wildcards (# and
+ ) when you specify local publish/subscribe as the source
message broker.
This feature requires v2.6.0 or later of the Greengrass nucleus
component.
-
Adds the targetTopicPrefix option, which you can specify
to configure the MQTT bridge to add a prefix to the target topic when it
relays a message.
|
2.1.1
|
- Bug fixes and improvements
-
|
2.1.0
|
|
2.0.1
|
This version includes bug fixes and improvements.
|
2.0.0
|
Initial version.
|