Skip to main content
Documentation Update

Garnet Framework has evolved with architectural improvements for better cost efficiency and scalability. This documentation is current and reflects these changes, though we continue to expand certain sections with additional examples and detailed guidance.

Thank you for your patience as we complete this update.

Integrating with AWS IoT

Garnet Framework provides a seamless integration with AWS IoT Core, enabling you to synchronize AWS IoT Things and their organizational structures with your knowledge graph. This integration automatically tracks the lifecycle of Things and Thing Groups, monitors group membership changes, and reports connectivity status in real-time.

Understanding the Integration​

By synchronizing AWS IoT Core with your knowledge graph, you can create effective device management capabilities and maintain a single source of truth for all your assets - whether they're AWS IoT Things or devices from other sources. This unified view facilitates cross-domain queries, analytics, and automation.

The integration works by listening to AWS IoT Core event messages published on reserved MQTT topics:

AWS IoT Sync Architecture

When events occur in AWS IoT Core, Garnet Framework automatically creates, updates, or deletes the corresponding entities in your knowledge graph, maintaining synchronization between the two systems.

Entity Types and Relationships​

Garnet Framework uses two primary entity types to model AWS IoT resources:

  • AwsIotThing: Represents an individual AWS IoT Thing registered in AWS IoT Core
  • AwsIotThingGroup: Represents a group of AWS IoT Things in AWS IoT Core

The relationship between Things and Thing Groups is modeled using the thingGroups attribute, which contains an array of relationships to the groups a Thing belongs to.

Here's an example of an AwsIotThing entity with its connectivity status:

{
    "id": "urn:ngsi-ld:AwsIotThing:ExampleThing",
    "type": "AwsIotThing",
    "connectivityStatus": {
        "type": "Property",
        "ipAddress": {
            "type": "Property",
            "value": "54.239.28.85"  
        },
        "principalIdentifier": {
            "type": "Property",
            "value": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
        },
        "sessionIdentifier": {
            "type": "Property",
            "value": "12345678-abcd-1234-efgh-123456789012"
        },
        "versionNumber": {
            "type": "Property",
            "value": 0
        },
        "value": "CONNECTED",
        "observedAt": "2025-05-20T09:43:45.512Z"
    },
    "thingGroups": {
        "type": "Relationship",
        "object": [
            "urn:ngsi-ld:AwsIotThingGroup:GarnetGroup-001",
            "urn:ngsi-ld:AwsIotThingGroup:SuperGarnetGroup"
        ],
        "objectType": "AwsIotThingGroup"
    }
}

And here's an example of an AwsIotThingGroup entity showing the group hierarchy:

{
    "id": "urn:ngsi-ld:AwsIotThingGroup:GarnetGroup-003",
    "type": "AwsIotThingGroup",
    "thingGroupName": {
        "type": "Property",
        "value": "GarnetGroup-003"
    },
    "thingGroupId": {
        "type": "Property",
        "value": "7de4a8fd-b9b5-4caf-ae2a-10d7d67b5565"
    },
    "eventType": {
        "type": "Property",
        "value": "CREATED",
        "observedAt": "2025-05-11T09:04:04.711Z"
    },
    "customAttribute": {
        "type": "Property",
        "value": "ExampleValue"
    },
    "inGroupHierarchy": {
        "type": "ListRelationship",
        "objectList": [
            {
                "object": "urn:ngsi-ld:AwsIotThingGroup:GarnetGroup-001"
            },
            {
                "object": "urn:ngsi-ld:AwsIotThingGroup:GarnetGroup-002"
            }
        ],
        "objectType": "AwsIotThingGroup"
    },
    "inParentGroup": {
        "type": "Relationship",
        "object": "urn:ngsi-ld:AwsIotThingGroup:GarnetGroup-001",
        "objectType": "AwsIotThingGroup"
    }
}

The inGroupHierarchy attribute uses a ListRelationship to maintain the ordered list of groups in the hierarchy, while the inParentGroup attribute indicates the direct parent group. This structure enables efficient navigation of the Thing Group hierarchy in your knowledge graph.

Event Synchronization​

Garnet Framework maintains synchronization with AWS IoT Core through an event-driven architecture that captures changes as they occur. The system listens to reserved MQTT topics where AWS IoT Core publishes various event types:

  • When a Thing is created, updated, or deleted in the AWS IoT registry, Garnet Framework automatically reflects these changes in your knowledge graph, ensuring your digital representation stays current with the physical device inventory.

  • Similarly, Thing Group operations, such as creating new groups or modifying existing ones, are captured and represented as AwsIotThingGroup entities with appropriate attributes and relationships.

  • As Things are assigned to or removed from Thing Groups, Garnet Framework updates the membership relationships, maintaining an accurate representation of your organizational structure.

  • Perhaps most valuably, connectivity events are tracked in real-time. When a Thing connects to or disconnects from AWS IoT Core via MQTT, its status is immediately updated in the knowledge graph, along with contextual information like IP addresses and session identifiers.

This event-driven approach ensures that your knowledge graph remains synchronized with AWS IoT Core without requiring periodic polling or manual updates. For detailed information about the specific events and their formats, you can refer to the AWS IoT Core documentation.

Extending the Integration​

While Garnet Framework provides built-in integration with AWS IoT Core, you can extend this approach to other AWS IoT services and protocols. For example, you could build similar integrations for:

  • AWS IoT Core for LoRaWAN events, which are also published to MQTT topics when gateways connect or disconnect, or when devices join the network
  • AWS IoT FleetWise for vehicle data
  • AWS IoT SiteWise for industrial equipment
  • Custom event sources that publish to MQTT topics in AWS IoT Core

By following the same event-driven pattern and creating appropriate entity types and relationships, you can create a unified view of your entire IoT ecosystem within AWS. This extensibility allows you to adapt the framework to your specific requirements while maintaining a consistent approach to context information management.

Monitoring Connectivity Status​

A key capability of the AWS IoT integration is real-time connectivity tracking. When a Thing connects to or disconnects from AWS IoT Core via MQTT, Garnet Framework automatically updates its connectivity status in the knowledge graph, enabling you to maintain an accurate view of your device fleet's operational state.

This feature is only available for Things that connect to AWS IoT Core using MQTT.

Connectivity Status Updates​

When a Thing connects to AWS IoT Core, its entity in the knowledge graph is updated with a connectivityStatus property set to CONNECTED, along with additional information such as IP address and session identifier, as shown in the example entity above.

Similarly, when a Thing disconnects, its connectivityStatus property is updated to DISCONNECTED, with additional information about the reason for disconnection.

Querying Connectivity Status​

You can use the NGSI-LD API to query AWS IoT Things based on their connectivity status. For example, to find all disconnected Things:

GET Disconnected Things
GET /ngsi-ld/v1/entities?type=AwsIotThing&q=connectivityStatus=="DISCONNECTED"
Headers:
    'Authorization': ${GARNET_TOKEN}
    'Content-Type': 'application/json'

You can also filter by specific disconnection reasons, such as CONNECTION_LOST:

GET Things with Connection Lost
GET /ngsi-ld/v1/entities?type=AwsIotThing&q=connectivityStatus=="DISCONNECTED";connectivityStatus.disconnectReason=="CONNECTION_LOST"
Headers:
    'Authorization': ${GARNET_TOKEN}
    'Content-Type': 'application/json'

Filtering by IP Address​

When a Thing is connected, its connectivityStatus property includes the IP address. You can use regular expressions to filter connected Things by IP address range:

GET Things by IP Address
GET /ngsi-ld/v1/entities?type=AwsIotThing&q=connectivityStatus.ipAddress~=".*54.239.*"&options=concise
Headers:
    'Authorization': ${GARNET_TOKEN}
    'Content-Type': 'application/json'

In this example, the query uses a regular expression to match IP addresses with specific patterns. The pattern .*54.239.* matches IP addresses that contain "54.239", such as the "54.239.28.85" address shown in our example entity.

Note that when a Thing is disconnected, the connectivityStatus property doesn't include the IP address, as shown in this example:

{
  "id": "urn:ngsi-ld:AwsIotThing:IotDeviceAws",
  "type": "AwsIotThing",
  "connectivityStatus": {
    "type": "Property",
    "disconnectReason": {
      "type": "Property",
      "value": "CONNECTION_LOST"
    },
    "clientInitiatedDisconnect": {
      "type": "Property",
      "value": "false"
    },
    "value": "DISCONNECTED",
    "observedAt": "2025-05-27T10:22:41.760Z"
  }
}

Extended Use Cases​

By combining AWS IoT integration with other Garnet Framework capabilities, you can implement various IoT management scenarios:

  • Real-time Monitoring: Create subscriptions to be notified when AWS IoT Things connect or disconnect, enabling immediate response to connectivity issues.

  • Geospatial Analysis: If your AWS IoT Things include location data, you can perform geospatial queries to find Things in specific areas or analyze spatial patterns.

  • Historical Analysis: Use the data lake capabilities described in the previous section to analyze historical connectivity patterns, identify problematic Things, or optimize your IoT infrastructure.

  • Cross-Domain Integration: Relate your AWS IoT Things to other entities in your knowledge graph, such as assets, locations, or business processes, creating a comprehensive digital twin of your operations.

The AWS IoT integration enhances Garnet Framework with comprehensive device management capabilities, extending beyond basic device tracking to enable context-aware IoT applications that adapt intelligently to your operational needs.