IoT Data Destinations

The IoT Data service adapter enables UDP Gateway to publish messages to AWS IoT Core's data plane, allowing integration with IoT device ecosystems, IoT Core Rules, and Thing Shadows. This integration is ideal for bridging UDP-based device protocols into AWS IoT Core's MQTT infrastructure, where powerful Rules Engine capabilities can route, transform, and process device data.

Operating Modes

The IoT Data adapter supports two distinct operating modes that determine how UDP packets are published to MQTT topics:

Static Mode (Default)

In static mode, all UDP packets are published to a single MQTT topic with metadata wrapped in a JSON packet envelope. The envelope includes source IP/port, timestamp, batch tag, and the payload encoded according to the destination's Formatter setting.

Configuration: No special configuration required. Static mode is the default when DynamicTopicSuffix is not set or is false.

Dynamic Topic Suffix Mode

In dynamic topic suffix mode, each UDP packet is published to a unique MQTT topic based on extracted payload data or source network information. The raw binary payload is sent without JSON wrapping, preserving the original device protocol format.

Configuration options:

• DynamicTopicSuffix (boolean, default: false) - Set to true to enable dynamic topic suffix mode
• TopicSuffixExpression (string, optional) - A binary range expression that extracts bytes from the UDP payload (e.g., "[0:4]" extracts the first 4 bytes). If not specified, the topic suffix defaults to {source_ip}/{source_port}
• TopicSuffixFormatter (string, default: "hex") - Controls how extracted bytes are converted to a string for the topic. Options: "hex", "ascii", "utf8", "base64"

Topic construction:

{base_topic_from_arn}/{dynamic_suffix}

Where the suffix is either:

• The formatted result of TopicSuffixExpression evaluated against the payload, or
• {source_ip}/{source_port} if no expression is provided

Example configuration (JSON):

{
  "DestinationArn": "arn:aws:iot:us-east-1:123456789012:topic/devices",
  "DynamicTopicSuffix": true,
  "TopicSuffixExpression": "[0:4]",
  "TopicSuffixFormatter": "hex"
}

This configuration would publish packets to topics like devices/A1B2C3D4, where A1B2C3D4 is the hex representation of the first 4 bytes of each UDP payload.

Things to Know About IoT Data Destinations

• The ARN must use the iot service identifier and specify a topic path
• Dynamic mode preserves raw binary payloads, while static mode wraps them in JSON
• Topic suffixes are automatically sanitized to comply with MQTT restrictions
• Complex topic patterns (multiple dynamic segments, literal suffixes) require IoT Core Rules
• All messages are published with QoS 0 (at most once)
• Batching controls how many messages are published concurrently, not combined into single messages
• The service adapter uses the region from the ARN, ensure IAM permissions match
• Consider using composite destinations to publish to both IoT Data and other services simultaneously