# Managing devices with AWS IoT
AWS IoT provides a registry that helps you manage *things*. A thing is a representation of a specific device or logical entity. It can be a physical device or sensor (for example, a light bulb or a switch on a wall). It can also be a logical entity like an instance of an application or physical entity that does not connect to AWS IoT but is related to other devices that do (for example, a car that has engine sensors or a control panel).
Information about a thing is stored in the registry as JSON data. Here is an example thing:
```
{
"version": 3,
"thingName": "MyLightBulb",
"defaultClientId": "MyLightBulb",
"thingTypeName": "LightBulb",
"attributes": {
"model": "123",
"wattage": "75"
}
}
```
Things are identified by a name. Things can also have attributes, which are name-value pairs you can use to store information about the thing, such as its serial number or manufacturer.
A typical device use case involves the use of the thing name as the default MQTT client ID. Although we don't enforce a mapping between a thing's registry name and its use of MQTT client IDs, certificates, or shadow state, we recommend you choose a thing name and use it as the MQTT client ID for both the registry and the Device Shadow service. This provides organization and convenience to your IoT fleet without removing the flexibility of the underlying device certificate model or shadows.
You don't need to create a thing in the registry to connect a device to AWS IoT. Adding things to the registry allows you to manage and search for devices more easily.
Thing registry data (including attributes, thing types, and group memberships) can also be dynamically retrieved in the rules engine to use in message processing and routing. For more information, see [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data).
# Managing things with the registry
You use the AWS IoT console, AWS IoT API, or the AWS CLI to interact with the registry. The following sections show how to use the CLI to work with the registry.
**When naming your thing objects:**
+ Don't use personally identifiable information in your thing name. The thing name can appear in unencrypted communications and reports.
**Topics**
+ [
# Create a thing
](create-thing.md)
+ [
# List things
](list-things.md)
+ [
# Describe things
](search-things.md)
+ [
# Update a thing
](update-thing.md)
+ [
# Delete a thing
](delete-thing.md)
+ [
# Attach a principal to a thing
](attach-thing-principal.md)
+ [
# List things associated with a principal
](list-principal-things.md)
+ [
# List principals associated with a thing
](list-thing-principals.md)
+ [
# List things associated with a principal V2
](list-principal-things-v2.md)
+ [
# List principals associated with a thing V2
](list-thing-principals-v2.md)
+ [
# Detach a principal from a thing
](detach-thing-principal.md)
# Create a thing
The following command shows how to use the AWS IoT **CreateThing** command from the CLI to create a thing. You can't change a thing's name after you create it. To change a thing's name, create a new thing, give it the new name, and then delete the old thing.
```
$ aws iot create-thing \
--thing-type-name "MyLightBulb" \
--attribute-payload "{\"attributes\": {\"wattage\":\"75\", \"model\":\"123\"}}"
```
The **CreateThing** command displays the name and Amazon Resource Name (ARN) of your new thing:
```
{
"thingArn": "arn:aws:iot:us-east-1:123456789012:thing/MyLightBulb",
"thingName": "MyLightBulb",
"thingId": "12345678abcdefgh12345678ijklmnop12345678"
}
```
**Note**
We don't recommend using personally identifiable information in your thing names.
For more information, see [create-thing](https://docs.aws.amazon.com//cli/latest/reference/iot/create-thing.html) from the AWS CLI Command Reference.
# List things
You can use the **ListThings** command to list all things in your account:
```
$ aws iot list-things
```
```
{
"things": [
{
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 1,
"thingName": "MyLightBulb"
},
{
"attributes": {
"numOfStates":"3"
},
"version": 11,
"thingName": "MyWallSwitch"
}
]
}
```
You can use the **ListThings** command to search for all things of a specific thing type:
```
$ aws iot list-things --thing-type-name "LightBulb"
```
```
{
"things": [
{
"thingTypeName": "LightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 1,
"thingName": "MyRGBLight"
},
{
"thingTypeName": "LightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 1,
"thingName": "MySecondLightBulb"
}
]
}
```
You can use the **ListThings** command to search for all things that have an attribute with a specific value. This command searches up to three attributes.
```
$ aws iot list-things --attribute-name "wattage" --attribute-value "75"
```
```
{
"things": [
{
"thingTypeName": "StopLight",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 3,
"thingName": "MyLightBulb"
},
{
"thingTypeName": "LightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 1,
"thingName": "MyRGBLight"
},
{
"thingTypeName": "LightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 1,
"thingName": "MySecondLightBulb"
}
]
}
```
For more information, see [list-things](https://docs.aws.amazon.com//cli/latest/reference/iot/list-things.html) from the AWS CLI Command Reference.
# Describe things
You can use the **DescribeThing** command to display more detailed information about a thing:
```
$ aws iot describe-thing --thing-name "MyLightBulb"
{
"version": 3,
"thingName": "MyLightBulb",
"thingArn": "arn:aws:iot:us-east-1:123456789012:thing/MyLightBulb",
"thingId": "12345678abcdefgh12345678ijklmnop12345678",
"defaultClientId": "MyLightBulb",
"thingTypeName": "StopLight",
"attributes": {
"model": "123",
"wattage": "75"
}
}
```
You can also access this API within the rules engine using the inline function `get_registry_data()`. You can use this function to dynamically access and utilize thing registry information (including attributes, thing types, and group memberships) by calling `DescribeThing` and `ListThingGroupsForThing` APIs directly within AWS IoT rules, enabling real-time message processing and routing based on your device registry data. For more information, see [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data).
For more information, see [describe-thing](https://docs.aws.amazon.com//cli/latest/reference/iot/describe-thing.html) from the AWS CLI Command Reference.
# Update a thing
You can use the **UpdateThing** command to update a thing. This command updates only the thing's attributes. You can't change a thing's name. To change a thing's name, create a new thing, give it the new name, and then delete the old thing.
```
$ aws iot update-thing --thing-name "MyLightBulb" --attribute-payload "{\"attributes\": {\"wattage\":\"150\", \"model\":\"456\"}}"
```
The **UpdateThing** command does not produce output. You can use the **DescribeThing** command to see the result:
```
$ aws iot describe-thing --thing-name "MyLightBulb"
{
"attributes": {
"model": "456",
"wattage": "150"
},
"version": 2,
"thingName": "MyLightBulb"
}
```
For more information, see [update-thing](https://docs.aws.amazon.com//cli/latest/reference/iot/update-thing.html) from the AWS CLI Command Reference.
# Delete a thing
You can use the **DeleteThing** command to delete a thing:
```
$ aws iot delete-thing --thing-name "MyThing"
```
This command returns successfully with no error if the deletion is successful or you specify a thing that doesn't exist.
For more information, see [delete-thing](https://docs.aws.amazon.com//cli/latest/reference/iot/delete-thing.html) from the AWS CLI Command Reference.
# Attach a principal to a thing
A physical device can use a principal to communicate with AWS IoT. A principal can be an X.509 certificate or an Amazon Cognito ID. You can associate a certificate or an Amazon Cognito ID with the thing in the registry that represents your device, by running the [attach-thing-principal](https://docs.aws.amazon.com//cli/latest/reference/iot/attach-thing-principal.html) command.
To attach a certificate or an Amazon Cognito ID to your thing, use the [attach-thing-principal](https://docs.aws.amazon.com//cli/latest/reference/iot/attach-thing-principal.html) command:
```
$ aws iot attach-thing-principal \
--thing-name "MyLightBulb1" \
--principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847"
```
To attach a certificate to your thing with an attachment type (exclusive attachment or non-exclusive attachment), use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/attach-thing-principal.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/attach-thing-principal.html) command and specify a type in the `--thing-principal-type` field. An exclusive attachment means your IoT thing is the only thing attached to the certificate, and this certificate cannot be associated with any other things. An non-exclusive attachment means your IoT thing is attached to the certificate, and this certificate can be associated with other things. For more information, see [Associating an AWS IoT thing to an MQTT client connection](exclusive-thing.md).
**Note**
For the [Associating an AWS IoT thing to an MQTT client connection](exclusive-thing.md) feature, you can only use X.509 certificate as a principal.
```
$ aws iot attach-thing-principal \
--thing-name "MyLightBulb2" \
--principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847" \
--thing-principal-type "EXCLUSIVE_THING"
```
If the attachment is successful, the **AttachThingPrincipal** command does not produce any output. To describe the attachment, use list-thing-principals-v2 CLI command.
For more information, see [AttachThingPrincipal](https://docs.aws.amazon.com//iot/latest/apireference/API_AttachThingPrincipal.html) from the *AWS IoT Core API Reference*.
# List things associated with a principal
To list the things associated with the specified principal, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-things.htmls](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-things.htmls) command. Note that this command doesn't list the attachment type between the thing and the certificate. To list the attachment type, use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-thingsv2.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-thingsv2.html) command. For more information, see [List things associated with a principal V2](list-principal-things-v2.md).
```
$ aws iot list-principal-things \
--principal "arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8"
```
The output can look like the following.
```
{
"things": [
"MyLightBulb1",
"MyLightBulb2"
]
}
```
For more information, see [ListPrincipalThings](https://docs.aws.amazon.com//iot/latest/apireference/API_ListPrincipalThings.html) from the *AWS IoT Core API Reference*.
# List principals associated with a thing
To list the principals associated with the specified thing, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-thing-principals.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-thing-principals.html) command. Note that this command doesn't list the attachment type between the thing and the certificate. To list the attachment type, use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-thing-principalsv2.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-thing-principalsv2.html) command. For more information, see [List principals associated with a thing V2](list-thing-principals-v2.md).
```
$ aws iot list-thing-principals \
--thing-name "MyLightBulb1"
```
The output can look like the following.
```
{
"principals": [
"arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8",
"arn:aws:iot:us-east-1:123456789012:cert/1a234b39b4b68278f2e9d84bf97eac2cbf4a1c28b23ea29a44559b9bcf8d395b"
]
}
```
For more information, see [ListThingPrincipals](https://docs.aws.amazon.com//iot/latest/apireference/API_ListThingPrincipals.html) from the *AWS IoT Core API Reference*.
# List things associated with a principal V2
To list the things associated with the specified certificate, along with the attachment type, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-thingsv2.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-thingsv2.html) command. The attachment type refers to how the certificate is attached to the thing.
```
$ aws iot list-principal-things-v2 \
--principal "arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8"
```
The output can look like the following.
```
{
"PrincipalThingObjects": [
{
"thingPrincipalType": "NON_EXCLUSIVE_THING",
"thing": "arn:aws:iot:us-east-1:123456789012:thing/thing_1"
},
{
"thingPrincipalType": "NON_EXCLUSIVE_THING",
"thing": "arn:aws:iot:us-east-1:123456789012:thing/thing_2"
}
]
}
```
For more information, see [ListPrincipalThingsV2](https://docs.aws.amazon.com//iot/latest/apireference/API_ListPrincipalThingsV2.html) from the *AWS IoT Core API Reference*.
# List principals associated with a thing V2
To list the certificates associated with the specified thing, along with the attachment type, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-thing-principalsv2.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-thing-principalsv2.html) command. The attachment type refers to how the certificate is attached to the thing.
```
$ aws iot list-thing-principals-v2 \
--thing-name "thing_1"
```
The output can look like the following.
```
{
"ThingPrincipalObjects": [
{
"thingPrincipalType": "NON_EXCLUSIVE_THING",
"principal": "arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8"
},
{
"thingPrincipalType": "NON_EXCLUSIVE_THING",
"principal": "arn:aws:iot:us-east-1:123456789012:cert/1a234b39b4b68278f2e9d84bf97eac2cbf4a1c28b23ea29a44559b9bcf8d395b"
}
]
}
```
For more information, see [ListThingsPrincipalV2](https://docs.aws.amazon.com//iot/latest/apireference/API_ListThingPrincipalsV2.html) from the *AWS IoT Core API Reference*.
# Detach a principal from a thing
You can use the `DetachThingPrincipal` command to detach a certificate from a thing:
```
$ aws iot detach-thing-principal \
--thing-name "MyLightBulb" \
--principal "arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8"
```
The **DetachThingPrincipal** command doesn't produce any output.
For more information, see [detach-thing-principal](https://docs.aws.amazon.com//iot/latest/apireference/API_DetachThingPrincipal.html) from the *AWS IoT Core API Reference*.
# Thing types
Thing types allow you to store description and configuration information that is common to all things associated with the same thing type. This simplifies the management of things in the registry. For example, you can define a LightBulb thing type. All things associated with the LightBulb thing type share a set of attributes: serial number, manufacturer, and wattage. When you create a thing of type LightBulb (or change the type of an existing thing to LightBulb) you can specify values for each of the attributes defined in the LightBulb thing type.
Although thing types are optional, their use makes it easier to discover things.
+ Things with a thing type can have up to 50 attributes.
+ Things without a thing type can have up to three attributes.
+ A thing can be associated with only one thing type.
+ There is no limit on the number of thing types you can create in your account.
You can't change a thing type name after it has been created. You can deprecate a thing type at any time to prevent new things from being associated with it. You can also delete thing types that have no things associated with them.
**Topics**
+ [
# Create a thing type
](create-thing-type.md)
+ [
# List thing types
](list-thing-types.md)
+ [
# Describe a thing type
](describe-thing-type.md)
+ [
# Associate a thing type with a thing
](associate-thing-type.md)
+ [
# Update a thing type
](update-thing-type.md)
+ [
# Deprecate a thing type
](deprecate-thing-type.md)
+ [
# Delete a thing type
](delete-thing-types.md)
# Create a thing type
You can use the **CreateThingType** command to create a thing type:
```
$ aws iot create-thing-type
--thing-type-name "LightBulb" --thing-type-properties "thingTypeDescription=light bulb type, searchableAttributes=wattage,model"
```
The **CreateThingType** command returns a response that contains the thing type and its ARN:
```
{
"thingTypeName": "LightBulb",
"thingTypeId": "df9c2d8c-894d-46a9-8192-9068d01b2886",
"thingTypeArn": "arn:aws:iot:us-west-2:123456789012:thingtype/LightBulb"
}
```
# List thing types
You can use the **ListThingTypes** command to list thing types:
```
$ aws iot list-thing-types
```
The **ListThingTypes** command returns a list of the thing types defined in your AWS account:
```
{
"thingTypes": [
{
"thingTypeName": "LightBulb",
"thingTypeProperties": {
"searchableAttributes": [
"wattage",
"model"
],
"thingTypeDescription": "light bulb type"
},
"thingTypeMetadata": {
"deprecated": false,
"creationDate": 1468423800950
}
}
]
}
```
# Describe a thing type
You can use the **DescribeThingType** command to get information about a thing type:
```
$ aws iot describe-thing-type --thing-type-name "LightBulb"
```
The **DescribeThingType** command returns information about the specified type:
```
{
"thingTypeProperties": {
"searchableAttributes": [
"model",
"wattage"
],
"thingTypeDescription": "light bulb type"
},
"thingTypeId": "df9c2d8c-894d-46a9-8192-9068d01b2886",
"thingTypeArn": "arn:aws:iot:us-west-2:123456789012:thingtype/LightBulb",
"thingTypeName": "LightBulb",
"thingTypeMetadata": {
"deprecated": false,
"creationDate": 1544466338.399
}
}
```
# Associate a thing type with a thing
You can use the **CreateThing** command to specify a thing type when you create a thing:
```
$ aws iot create-thing --thing-name "MyLightBulb" --thing-type-name "LightBulb" --attribute-payload "{\"attributes\": {\"wattage\":\"75\", \"model\":\"123\"}}"
```
You can use the **UpdateThing** command at any time to change the thing type associated with a thing:
```
$ aws iot update-thing --thing-name "MyLightBulb"
--thing-type-name "LightBulb" --attribute-payload "{\"attributes\": {\"wattage\":\"75\", \"model\":\"123\"}}"
```
You can also use the **UpdateThing** command to disassociate a thing from a thing type.
# Update a thing type
You can use the **UpdateThingType** command to update a thing type when you create a thing:
```
$ aws iot create-thing --thing-name "MyLightBulb" --thing-type-name "LightBulb" --attribute-payload "{\"attributes\": {\"wattage\":\"75\", \"model\":\"123\"}}"
```
You can use the **UpdateThing** command at any time to change the thing type associated with a thing:
```
$ aws iot update-thing --thing-name "MyLightBulb"
--thing-type-name "LightBulb" --attribute-payload "{\"attributes\": {\"wattage\":\"75\", \"model\":\"123\"}}"
```
You can also use the **UpdateThing** command to disassociate a thing from a thing type.
# Deprecate a thing type
Thing types are immutable. They can't be changed after they are defined. You can, however, deprecate a thing type to prevent users from associating any new things with it. All existing things associated with the thing type are unchanged.
To deprecate a thing type, use the **DeprecateThingType** command:
```
$ aws iot deprecate-thing-type --thing-type-name "myThingType"
```
You can use the **DescribeThingType** command to see the result:
```
$ aws iot describe-thing-type --thing-type-name "StopLight":
```
```
{
"thingTypeName": "StopLight",
"thingTypeProperties": {
"searchableAttributes": [
"wattage",
"numOfLights",
"model"
],
"thingTypeDescription": "traffic light type",
},
"thingTypeMetadata": {
"deprecated": true,
"creationDate": 1468425854308,
"deprecationDate": 1468446026349
}
}
```
Deprecating a thing type is a reversible operation. You can undo a deprecation by using the `--undo-deprecate` flag with the **DeprecateThingType** CLI command:
```
$ aws iot deprecate-thing-type --thing-type-name "myThingType" --undo-deprecate
```
You can use the **DescribeThingType** CLI command to see the result:
```
$ aws iot describe-thing-type --thing-type-name "StopLight":
```
```
{
"thingTypeName": "StopLight",
"thingTypeArn": "arn:aws:iot:us-east-1:123456789012:thingtype/StopLight",
"thingTypeId": "12345678abcdefgh12345678ijklmnop12345678"
"thingTypeProperties": {
"searchableAttributes": [
"wattage",
"numOfLights",
"model"
],
"thingTypeDescription": "traffic light type"
},
"thingTypeMetadata": {
"deprecated": false,
"creationDate": 1468425854308,
}
}
```
# Delete a thing type
You can delete thing types only after they have been deprecated. To delete a thing type, use the **DeleteThingType** command:
```
$ aws iot delete-thing-type --thing-type-name "StopLight"
```
**Note**
Before you can delete a thing type, wait for five minutes after you deprecate it.
# Static thing groups
Static thing groups allow you to manage several things at once by categorizing them into groups. Static thing groups contain a group of things that are managed by using the console, CLI, or the API. [Dynamic thing groups](dynamic-thing-groups.md), on the other hand, contain things that match a specified query. Static thing groups can also contain other static thing groups — you can build a hierarchy of groups. You can attach a policy to a parent group and it is inherited by its child groups, and by all of the things in the group and in its child groups. This makes control of permissions easy for large numbers of things.
**Note**
Thing group policies don't allow access to AWS IoT Greengrass data plane operations. To allow a thing access to an AWS IoT Greengrass data plane operation, add the permission to an AWS IoT policy that you attach to the thing's certificate. For more information, see [Device authentication and authorization](https://docs.aws.amazon.com/greengrass/v2/developerguide/device-auth#iot-policies.html) in the *AWS IoT Greengrass developer guide*.
Here are the things you can do with static thing groups:
+ Create, describe or delete a group.
+ Add a thing to a group, or to more than one group.
+ Remove a thing from a group.
+ List the groups you have created.
+ List all child groups of a group (its direct and indirect descendants.)
+ List the things in a group, including all the things in its child groups.
+ List all ancestor groups of a group (its direct and indirect parents.)
+ Add, delete or update the attributes of a group. (Attributes are name-value pairs you can use to store information about a group.)
+ Attach or detach a policy to or from a group.
+ List the policies attached to a group.
+ List the policies inherited by a thing (by virtue of the policies attached to its group, or one of its parent groups.)
+ Configure logging options for things in a group. See [Configure AWS IoT logging](configure-logging.md).
+ Create jobs that are sent to and executed on every thing in a group and its child groups. See [AWS IoT Jobs](iot-jobs.md).
**Note**
When a thing is attached to a static thing group to which an AWS IoT Core policy is attached to, the thing name must match the client ID.
Here are some limitations of static thing groups:
+ A group can have at most one direct parent.
+ If a group is a child of another group, specify this at the time it is created.
+ You can't change a group's parent later, so be sure to plan your group hierarchy and create a parent group before you create any child groups it contains.
+
The number of groups to which a thing can belong is [limited](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-limits).
+ You can't add a thing to more than one group in the same hierarchy. (In other words, you can't add a thing to two groups that share a common parent.)
+ You can't rename a group.
+ Thing group names can't contain international characters, such as û, é and ñ.
+ Don't use personally identifiable information in your thing group name. The thing group name can appear in unencrypted communications and reports.
Attaching and detaching policies to groups can enhance the security of your AWS IoT operations in a number of significant ways. The per-device method of attaching a policy to a certificate, which is then attached to a thing, is time consuming and makes it difficult to quickly update or change policies across a fleet of devices. Having a policy attached to the thing's group saves steps when it is time to rotate the certificates on a thing. And policies are dynamically applied to things when they change group membership, so you aren't required to re-create a complex set of permissions each time a device changes membership in a group.
## Create a static thing group
Use the **CreateThingGroup** command to create a static thing group:
```
$ aws iot create-thing-group --thing-group-name LightBulbs
```
The **CreateThingGroup** command returns a response that contains the static thing group's name, ID, and ARN:
```
{
"thingGroupName": "LightBulbs",
"thingGroupId": "abcdefgh12345678ijklmnop12345678qrstuvwx",
"thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs"
}
```
**Note**
We don't recommend using personally identifiable information in your thing group names.
Here is an example that specifies a parent of the static thing group when it is created:
```
$ aws iot create-thing-group --thing-group-name RedLights --parent-group-name LightBulbs
```
As before, the **CreateThingGroup** command returns a response that contains the static thing group's name,, ID, and ARN:
```
{
"thingGroupName": "RedLights",
"thingGroupId": "abcdefgh12345678ijklmnop12345678qrstuvwx",
"thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights",
}
```
**Important**
Keep in mind the following limits when creating thing group hierarchies:
A thing group can have only one direct parent.
The number of direct child groups a thing group can have is [limited](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-group-limits).
The maximum depth of a group hierarchy is [limited](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-group-limits).
The number of attributes a thing group can have is [limited](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-group-limits). (Attributes are name-value pairs you can use to store information about a group.) The lengths of each attribute name and each value are also [limited](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-group-limits).
## Describe a thing group
You can use the **DescribeThingGroup** command to get information about a thing group:
```
$ aws iot describe-thing-group --thing-group-name RedLights
```
The **DescribeThingGroup** command returns information about the specified group:
```
{
"thingGroupName": "RedLights",
"thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights",
"thingGroupId": "12345678abcdefgh12345678ijklmnop12345678",
"version": 1,
"thingGroupMetadata": {
"creationDate": 1478299948.882
"parentGroupName": "Lights",
"rootToParentThingGroups": [
{
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/ShinyObjects",
"groupName": "ShinyObjects"
},
{
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs",
"groupName": "LightBulbs"
}
]
},
"thingGroupProperties": {
"attributePayload": {
"attributes": {
"brightness": "3400_lumens"
},
},
"thingGroupDescription": "string"
},
}
```
## Add a thing to a static thing group
You can use the **AddThingToThingGroup** command to add a thing to a static thing group:
```
$ aws iot add-thing-to-thing-group --thing-name MyLightBulb --thing-group-name RedLights
```
The **AddThingToThingGroup** command does not produce any output.
**Important**
You can add a thing to a maximum of 10 groups. But you can't add a thing to more than one group in the same hierarchy. (In other words, you can't add a thing to two groups which share a common parent.)
If a thing belongs to as many thing groups as possible, and one or more of those groups is a dynamic thing group, you can use the [https://docs.aws.amazon.com/iot/latest/apireference/API_AddThingToThingGroup.html#iot-AddThingToThingGroup-request-overrideDynamicGroups](https://docs.aws.amazon.com/iot/latest/apireference/API_AddThingToThingGroup.html#iot-AddThingToThingGroup-request-overrideDynamicGroups) flag to make static groups take priority over dynamic groups.
## Remove a thing from a static thing group
You can use the **RemoveThingFromThingGroup** command to remove a thing from a group:
```
$ aws iot remove-thing-from-thing-group --thing-name MyLightBulb --thing-group-name RedLights
```
The **RemoveThingFromThingGroup** command does not produce any output.
## List things in a thing group
You can use the **ListThingsInThingGroup** command to list the things that belong to a group:
```
$ aws iot list-things-in-thing-group --thing-group-name LightBulbs
```
The **ListThingsInThingGroup** command returns a list of the things in the given group:
```
{
"things":[
"TestThingA"
]
}
```
With the `--recursive` parameter, you can list things belonging to a group and those in any of its child groups:
```
$ aws iot list-things-in-thing-group --thing-group-name LightBulbs --recursive
```
```
{
"things":[
"TestThingA",
"MyLightBulb"
]
}
```
**Note**
This operation is [eventually consistent](https://web.stanford.edu/class/cs345d-01/rl/eventually-consistent.pdf). In other words, changes to the thing group might not be reflected at once.
## List thing groups
You can use the **ListThingGroups** command to list your account's thing groups:
```
$ aws iot list-thing-groups
```
The **ListThingGroups** command returns a list of the thing groups in your AWS account:
```
{
"thingGroups": [
{
"groupName": "LightBulbs",
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs"
},
{
"groupName": "RedLights",
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights"
},
{
"groupName": "RedLEDLights",
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLEDLights"
},
{
"groupName": "RedIncandescentLights",
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedIncandescentLights"
}
{
"groupName": "ReplaceableObjects",
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/ReplaceableObjects"
}
]
}
```
Use the optional filters to list those groups that have a given group as parent (`--parent-group`) or groups whose name begins with a given prefix (`--name-prefix-filter`.) The `--recursive` parameter allows you to list all children groups, not just direct child groups of a thing group:
```
$ aws iot list-thing-groups --parent-group LightBulbs
```
In this case, the **ListThingGroups** command returns a list of the direct child groups of the thing group defined in your AWS account:
```
{
"childGroups":[
{
"groupName": "RedLights",
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights"
}
]
}
```
Use the `--recursive` parameter with the **ListThingGroups** command to list all child groups of a thing group, not just direct children:
```
$ aws iot list-thing-groups --parent-group LightBulbs --recursive
```
The **ListThingGroups** command returns a list of all child groups of the thing group:
```
{
"childGroups":[
{
"groupName": "RedLights",
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights"
},
{
"groupName": "RedLEDLights",
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLEDLights"
},
{
"groupName": "RedIncandescentLights",
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedIncandescentLights"
}
]
}
```
**Note**
This operation is [eventually consistent](https://web.stanford.edu/class/cs345d-01/rl/eventually-consistent.pdf). In other words, changes to the thing group might not be reflected at once.
## List groups for a thing
You can use the **ListThingGroupsForThing** command to list the direct groups that a thing belongs to:
```
$ aws iot list-thing-groups-for-thing --thing-name MyLightBulb
```
The **ListThingGroupsForThing** command returns a list of the direct thing groups that this thing belongs to:
```
{
"thingGroups":[
{
"groupName": "LightBulbs",
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs"
},
{
"groupName": "RedLights",
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights"
},
{
"groupName": "ReplaceableObjects",
"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/ReplaceableObjects"
}
]
}
```
You can also access this API within the rules engine using the inline function `get_registry_data()`. You can use this function to dynamically access and utilize thing registry information (including attributes, thing types, and group memberships) by calling `DescribeThing` and `ListThingGroupsForThing` APIs directly within AWS IoT rules, enabling real-time message processing and routing based on your device registry data. For more information, see [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data).
## Update a static thing group
You can use the **UpdateThingGroup** command to update the attributes of a static thing group:
```
$ aws iot update-thing-group --thing-group-name "LightBulbs" --thing-group-properties "thingGroupDescription=\"this is a test group\", attributePayload=\"{\"attributes\"={\"Owner\"=\"150\",\"modelNames\"=\"456\"}}"
```
The **UpdateThingGroup** command returns a response that contains the group's version number after the update:
```
{
"version": 4
}
```
**Note**
The number of attributes that a thing can have is [limited](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-limits).
## Delete a thing group
To delete a thing group, use the **DeleteThingGroup** command:
```
$ aws iot delete-thing-group --thing-group-name "RedLights"
```
The **DeleteThingGroup** command does not produce any output.
**Important**
If you try to delete a thing group that has child thing groups, you receive an error:
```
A client error (InvalidRequestException) occurred when calling the DeleteThingGroup
operation: Cannot delete thing group : RedLights when there are still child groups attached to it.
```
Before you delete the group, delete any child groups first.
You can delete a group that has child things, but any permissions granted to the things by membership in the group no longer apply. Before deleting a group that has a policy attached, check carefully that removing those permissions would not stop the things in the group from being able to function properly. Also, commands that show which groups a thing belongs to (for example, **ListGroupsForThing**) might continue to show the group while records in the cloud are being updated.
## Attach a policy to a static thing group
You can use the **AttachPolicy** command to attach a policy to a static thing group and so, by extension, to all things in that group and things in any of its child groups:
```
$ aws iot attach-policy \
--target "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs" \
--policy-name "myLightBulbPolicy"
```
The **AttachPolicy** command does not produce any output
**Important**
You can attach a maximum number of two policies to a group.
**Note**
We don't recommend using personally identifiable information in your policy names.
The `--target` parameter can be a thing group ARN (as above), a certificate ARN, or an Amazon Cognito Identity. For more information about policies, certificates and authentication, see [Authentication](authentication.md).
For more information, see [AWS IoT Core policies](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html).
## Detach a policy from a static thing group
You can use the **DetachPolicy** command to detach a policy from a group and so, by extension, to all things in that group and things in any of its child groups:
```
$ aws iot detach-policy --target "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs" --policy-name "myLightBulbPolicy"
```
The **DetachPolicy** command does not produce any output.
## List the policies attached to a static thing group
You can use the **ListAttachedPolicies** command to list the policies attached to a static thing group:
```
$ aws iot list-attached-policies --target "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights"
```
The `--target` parameter can be a thing group ARN (as above), a certificate ARN, or an Amazon Cognito identity.
Add the optional `--recursive` parameter to include all policies attached to the group's parent groups.
The **ListAttachedPolicies** command returns a list of policies:
```
{
"policies": [
"MyLightBulbPolicy"
...
]
}
```
## List the groups for a policy
You can use the **ListTargetsForPolicy** command to list the targets, including any groups, that a policy is attached to:
```
$ aws iot list-targets-for-policy --policy-name "MyLightBulbPolicy"
```
Add the optional `--page-size number` parameter to specify the maximum number of results to be returned for each query, and the `--marker string` parameter on subsequent calls to retrieve the next set of results, if any.
The **ListTargetsForPolicy** command returns a list of targets and the token to use to retrieve more results:
```
{
"nextMarker": "string",
"targets": [ "string" ... ]
}
```
## Get effective policies for a thing
You can use the **GetEffectivePolicies** command to list the policies in effect for a thing, including the policies attached to any groups the thing belongs to (whether the group is a direct parent or indirect ancestor):
```
$ aws iot get-effective-policies \
--thing-name "MyLightBulb" \
--principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847"
```
Use the `--principal` parameter to specify the ARN of the certificate attached to the thing. If you are using Amazon Cognito identity authentication, use the `--cognito-identity-pool-id` parameter and, optionally, add the `--principal` parameter to specify an Amazon Cognito identity. If you specify only the `--cognito-identity-pool-id`, the policies associated with that identity pool's role for unauthenticated users are returned. If you use both, the policies associated with that identity pool's role for authenticated users are returned.
The `--thing-name` parameter is optional and can be used instead of the `--principal` parameter. When used, the policies attached to any group the thing belongs to, and the policies attached to any parent groups of these groups (up to the root group in the hierarchy) are returned.
The **GetEffectivePolicies** command returns a list of policies:
```
{
"effectivePolicies": [
{
"policyArn": "string",
"policyDocument": "string",
"policyName": "string"
}
...
]
}
```
## Test authorization for MQTT actions
You can use the **TestAuthorization** command to test whether an [MQTT](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html) action (`Publish`, `Subscribe`) is allowed for a thing:
```
aws iot test-authorization \
--principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847" \
--auth-infos "{\"actionType\": \"PUBLISH\", \"resources\": [ \"arn:aws:iot:us-east-1:123456789012:topic/my/topic\"]}"
```
Use the `--principal` parameter to specify the ARN of the certificate attached to the thing. If using Amazon Cognito Identity authentication, specify a Cognito Identity as the `--principal` or use the `--cognito-identity-pool-id` parameter, or both. (If you specify only the `--cognito-identity-pool-id` then the policies associated with that identity pool's role for unauthenticated users are considered. If you use both, the policies associated with that identity pool's role for authenticated users are considered.
Specify one or more MQTT actions you want to test by listing sets of resources and action types following the `--auth-infos` parameter. The `actionType` field should contain "PUBLISH", "SUBSCRIBE", "RECEIVE", or "CONNECT". The `resources` field should contain a list of resource ARNs. See [AWS IoT Core policies](iot-policies.md) for more information.
You can test the effects of adding policies by specifying them with the `--policy-names-to-add` parameter. Or you can test the effects of removing policies by them with the `--policy-names-to-skip` parameter.
You can use the optional `--client-id` parameter to further refine your results.
The **TestAuthorization** command returns details on actions that were allowed or denied for each set of `--auth-infos` queries you specified:
```
{
"authResults": [
{
"allowed": {
"policies": [
{
"policyArn": "string",
"policyName": "string"
}
]
},
"authDecision": "string",
"authInfo": {
"actionType": "string",
"resources": [ "string" ]
},
"denied": {
"explicitDeny": {
"policies": [
{
"policyArn": "string",
"policyName": "string"
}
]
},
"implicitDeny": {
"policies": [
{
"policyArn": "string",
"policyName": "string"
}
]
}
},
"missingContextValues": [ "string" ]
}
]
}
```
# Dynamic thing groups
Dynamic thing groups are created from specific search queries in the registry. Search query parameters such as device connectivity, device shadow creation, and AWS IoT Device Defender violations data support this. Dynamic thing groups require fleet indexing enabled to index, search, and aggregate your devices' data. You can preview the things in a dynamic thing group using a fleet indexing search query before creating it. For more information, see [Fleet indexing](iot-indexing.md) and [Query syntax](query-syntax.md).
**Note**
Dynamic thing group operations are metered under registry operations. For more information, see [AWS IoT Core additional metering details](https://aws.amazon.com/iot-core/pricing/additional-details/).
Dynamic thing groups differ from static thing groups in the following ways:
+ Thing membership is not explicitly defined. To create a dynamic thing group, define [a search query string](example-queries.md) to determine group membership.
+ Dynamic thing groups can't be part of a hierarchy.
+ Dynamic thing groups can't have policies applied to them.
+ You use a different set of commands to create, update, and delete dynamic thing groups. For all other operations, you use the same commands for both types of thing groups.
+ The number of dynamic groups per AWS account is [limited](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-group-limits).
+ Don't use personally identifiable information in your thing group name. The thing group name can appear in unencrypted communications and reports.
For more information about static thing groups, see [Static thing groups](thing-groups.md).
## Use cases of dynamic thing groups
You can use dynamic thing groups for the following use cases:
### Specify a dynamic thing group as a target for a job
Creating a continuous job with a dynamic thing group as target allows you to automatically target devices when they meet the desired criteria. The criteria can be the connectivity state or any criteria stored in registry or shadow such as software version or model. If a thing doesn’t appear in the dynamic thing group, it won’t receive the job document from the job.
For example, if your device fleet requires a firmware update to minimize the risk of interruption during the update process, and you only want to update the firmware on devices with a battery life greater than 80%. You can create a dynamic thing group called 80PercentBatteryLife that only includes devices with a battery life above 80% and use it as the target for your job. Only devices that meet your battery life criteria will receive the firmware update. As devices reach the 80% battery life criteria, they are automatically added to the dynamic thing group and will receive the firmware update.
You may also have multiple device models with different firmware or operating system, necessitating different versions of new software updates. This is the most common use case for dynamic groups with continuous jobs, where you can create a dynamic group for each device model, firmware and OS combination. You can then set up continuous jobs to each of these dynamic groups to push software updates as devices automatically become members of these groups based on the defined criteria.
For more information about specifying thing groups as job targets, see [CreateJob](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateJob.html).
### Use dynamic group membership changes to perform desired actions
Each time a device is added to or removed from a dynamic thing group, a notification is sent to an MQTT topic as part of [registry event](https://docs.aws.amazon.com//iot/latest/developerguide/registry-events.html) updates. You can configure [AWS IoT Core rules](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rules.html) to interact with AWS services based on the dynamic group membership updates and take desired actions. Example actions include writing to Amazon DynamoDB, invoking a Lambda function, or sending a notification to Amazon SNS.
### Add devices to a dynamic thing group for automatic violation detection
AWS IoT Device Defender Detect customers can define a [security profile](https://docs.aws.amazon.com//iot/latest/developerguide/device-defender-detect.html) on a dynamic thing group. Devices of the dynamic thing group are automatically detected for violations by the security profile defined on the group.
### Set log levels on dynamic thing groups to observe devices with fine-grained logging
You can specify a log level on a dynamic thing group. This is useful if you only want to customize logging level and detail for devices that meet certain criteria. For example, if you suspect devices with certain firmware version are causing errors on a specific rule's published topic, you might want to set detailed logging to debug these issues. In this case, you can create a dynamic group for all devices that have this firmware version, which we assume is stored as a registry attribute or in a device shadow. You can then set a debug level, with logging target defined as this dynamic thing group. For more information about fine-grained logging, see [Monitor AWS IoT using CloudWatch Logs](https://docs.aws.amazon.com//iot/latest/developerguide/cloud-watch-logs.html#fine-grained-logging). For more information about how to specify a logging level for a specific thing group, see [Configure resource-specific logging in AWS IoT](https://docs.aws.amazon.com//iot/latest/developerguide/configure-logging.html#fine-logging-cli).
## Create a dynamic thing group
Use the **CreateDynamicThingGroup** command to create a dynamic thing group. To create a dynamic thing group for the 80PercentBatteryLife scenario, use the **create-dynamic-thing-group** CLI command:
```
$ aws iot create-dynamic-thing-group --thing-group-name "80PercentBatteryLife" --query-string "attributes.batterylife80"
```
**Note**
Don't use personally identifiable information in your dynamic thing group names.
The **CreateDynamicThingGroup** command returns a response. The response contains the index name, query string, query version, thing group name, thing group ID, and the Amazon Resource Name (ARN) of your thing group:
```
{
"indexName": "AWS_Things",
"queryVersion": "2017-09-30",
"thingGroupName": "80PercentBatteryLife",
"thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/80PercentBatteryLife",
"queryString": "attributes.batterylife80\n",
"thingGroupId": "abcdefgh12345678ijklmnop12345678qrstuvwx"
}
```
The creation of dynamic thing groups doesn't happen at once. The dynamic thing group backfill takes time to complete. When you create a dynamic thing group, the status of the group is set to `BUILDING`. When the backfill is complete, the status changes to `ACTIVE`. To check the status of your dynamic thing group, use the [DescribeThingGroup](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThingGroup.html) command.
## Describe a dynamic thing group
Use the **DescribeThingGroup** command to get information about a dynamic thing group:
```
$ aws iot describe-thing-group --thing-group-name "80PercentBatteryLife"
```
The **DescribeThingGroup** command returns information about the specified group:
```
{
"status": "ACTIVE",
"indexName": "AWS_Things",
"thingGroupName": "80PercentBatteryLife",
"thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/80PercentBatteryLife",
"queryString": "attributes.batterylife80\n",
"version": 1,
"thingGroupMetadata": {
"creationDate": 1548716921.289
},
"thingGroupProperties": {},
"queryVersion": "2017-09-30",
"thingGroupId": "84dd9b5b-2b98-4c65-84e4-be0e1ecf4fd8"
}
```
Running **DescribeThingGroup** on a dynamic thing group returns attributes that are specific to the dynamic thing groups. Example return attributes are the queryString and the status.
The status of a dynamic thing group can take the following values:
`ACTIVE`
The dynamic thing group is ready for use.
`BUILDING`
The dynamic thing group is being created, and thing membership is being processed.
`REBUILDING`
The dynamic thing group's membership is being updated, following the adjustment of the group's search query.
**Note**
After you create a dynamic thing group, use it regardless of its status. Only dynamic thing groups with an `ACTIVE` status include all of the things that match the search query for that dynamic thing group. Dynamic thing groups with `BUILDING` and `REBUILDING` statuses might not include all of the things that match the search query.
## Update a dynamic thing group
Use the **UpdateDynamicThingGroup** command to update the attributes of a dynamic thing group, including the group's search query. The following command updates two attributes. One is the thing group description, and the other is the query string that changes the membership criteria to battery life > 85:
```
$ aws iot update-dynamic-thing-group --thing-group-name "80PercentBatteryLife" --thing-group-properties "thingGroupDescription=\"This thing group contains devices with a battery life greater than 85 percent.\"" --query-string "attributes.batterylife85"
```
The **UpdateDynamicThingGroup** command returns a response that contains the group's version number after the update:
```
{
"version": 2
}
```
The update of a dynamic thing group doesn't happen at once. The dynamic thing group backfill takes time to complete. When you update a dynamic thing group, the status of the group changes to `REBUILDING` while the group updates its membership. When the backfill is complete, the status changes to `ACTIVE`. To check the status of your dynamic thing group, use the [DescribeThingGroup](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThingGroup.html) command.
## Delete a dynamic thing group
Use the **DeleteDynamicThingGroup** command to delete a dynamic thing group:
```
$ aws iot delete-dynamic-thing-group --thing-group-name "80PercentBatteryLife"
```
The **DeleteDynamicThingGroup** command doesn't produce any output.
Commands that show which groups a thing belongs to (for example, **ListGroupsForThing**) might continue to show the group while records in the cloud are being updated.
## Dynamic and Static Thing Group Limitations
Dynamic thing groups and static thing groups share the following limitations:
+ The number of attributes that a thing group can have is [limited](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-group-limits).
+ The number of groups to which a thing can belong is [limited](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-group-limits).
+ You can't rename thing groups.
+ Thing group names can't contain international characters, such as û, é, and ñ.
## Dynamic Thing Group Limitations
Dynamic thing groups have the following limitations:
### Fleet indexing
With the fleet indexing service enabled, you can perform search queries on your fleet of devices. You can create and manage dynamic thing groups after the fleet indexing backfill is completed. The completion time for the backfill process is directly affeted by the size of your device fleet registered with the AWS Cloud. After you enable the fleet indexing service for dynamic thing groups, you cannot disable it until you delete all of your dynamic thing groups.
**Note**
If you have permissions to query the fleet index, you can access the data of things across the entire fleet.
### The number of dynamic thing groups is limited
The number of dynamic thing groups is [limited](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-group-limits).
### Successful commands can log errors
When you create or update a dynamic thing group, it's possible that some things are eligible for inclusion in a dynamic thing group, but they are not added to it. That scenario will cause a succeessful create or update command while logging an error and generating an [`AddThingToDynamicThingGroupsFailed` metric](metrics_dimensions.md#iot-metrics). A single metric can represent multiple log entries.
An [error log entry](https://docs.aws.amazon.com/iot/latest/apireference/cwl-format.html#dynamic-group-logs) in the CloudWatch log is created when the following occurs:
+ An eligible thing can't be added to a dynamic thing group.
+ A thing is removed from a dynamic thing group to add it to another group.
When a thing becomes eligible to be added to a dynamic thing group, consider the following:
+ Is the thing already in as many groups as it can be? (See [limits](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-limits))
+ **NO: **The thing is added to the dynamic thing group.
+ **YES:** Is the thing a member of any dynamic thing groups?
+ **NO:** The thing can't be added to the dynamic thing group, an error is logged, and an [`AddThingToDynamicThingGroupsFailed` metric](metrics_dimensions.md#iot-metrics) is generated.
+ **YES:** Is the dynamic thing group to join older than any dynamic thing group that the thing is already a member of?
+ **NO:** The thing can't be added to the dynamic thing group, an error is logged, and an [`AddThingToDynamicThingGroupsFailed` metric](metrics_dimensions.md#iot-metrics) is generated.
+ **YES:** Remove the thing from the most recent dynamic thing group, log an error, and add the thing to the dynamic thing group. This generates an error and an [`AddThingToDynamicThingGroupsFailed` metric](metrics_dimensions.md#iot-metrics) for the dynamic thing group from which the thing was removed.
When a thing in a dynamic thing group no longer meets the search query, the thing is removed from the dynamic thing group. Likewise, when a thing is updated to meet a dynamic thing group's search query, the thing is then added to the group as previously described. These additions and removals are normal and don't produce error log entries.
### With `overrideDynamicGroups` enabled, static groups take priority over dynamic groups
The number of groups to which a thing can belong is [limited](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-limits). When you use the [AddThingToThingGroup](https://docs.aws.amazon.com/iot/latest/apireference/API_AddThingToThingGroup.html) or [UpdateThingGroupsForThing](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateThingGroupsForThing.html) commands to update thing membership, adding the `--overrideDynamicGroups` parameter gives static thing groups priority over dynamic thing groups.
When you add a thing to a static thing group, consider the following:
+ Does the thing already belong to the maximum number of groups?
+ **NO:** The thing is added to the static thing group.
+ **YES:** Is the thing in any dynamic groups?
+ **NO:** The thing can't be added to the thing group. The command raises an exception.
+ **YES:** Was **--overrideDynamicGroups** enabled?
+ **NO:** The thing can't be added to the thing group. The command raises an exception.
+ **YES:** The thing is removed from the most recently created dynamic thing group, an error is logged, and an [`AddThingToDynamicThingGroupsFailed` metric](metrics_dimensions.md#iot-metrics) is generated for the dynamic thing group from which the thing was removed. Then, the thing is added to the static thing group.
### Older dynamic thing groups take priority over newer ones
The number of groups to which a thing can belong is [limited](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-limits). When a create or update operation creates additional group eligibility for a thing and the thing has reached its group limit, removal from another dynamic thing group can occur to enable this addition. For more information about how this occurs, see [Successful commands can log errors](#log-errors) and [With `overrideDynamicGroups` enabled, static groups take priority over dynamic groups](#membership-limit) for examples.
When a thing is removed from a dynamic thing group, an error is logged and an event is raised.
### You can't apply policies to dynamic thing groups
Attempting to apply a policy to a dynamic thing group generates an exception.
### Dynamic thing group membership is eventually consistent
Only the final state of a thing is evaluated for the registry. Intermediary states can be skipped if states are updated rapidly. Avoid associating a rule or job with a dynamic thing group whose membership depends on an intermediary state.
# Associating an AWS IoT thing to an MQTT client connection
An exclusive thing association is when you attach an X.509 certificate to a single AWS IoT thing. In this case, the certificate cannot be used with other things. By ensuring that a certificate is used only by a single IoT thing, it helps prevent security vulnerabilities.
In AWS IoT, the client ID is a unique identifier for a thing or a device when it connects to the AWS IoT Core MQTT broker. If you use a non-exclusive association, multiple things can be attached to the same certificate. When non-exclusive thing association is in place, to maintain a clear association and to avoid potential conflicts, you must match your client ID with the thing name.
**Topics**
+ [
## Use cases
](#exclusive-thing-benefits)
+ [
## How to associate a thing to a connection
](#exclusive-thing-how-to)
## Use cases
Associating a thing to a connection provides the following capabilities.
**Note**
Note that if your IoT thing and client connection has a non-exclusive association, you can use all the following capabilities except the lifecycle events capability. To include your thing name in the lifecycle event messages, you IoT thing and client connection must have an exclusive association.
**Thing policy variables** - You can use thing policy variables to authorize device access to AWS IoT API operations. These variables allow you to write AWS IoT Core policies that grant or deny permissions based on thing properties like names, types, and attribute values. By using thing policy variables, you can apply the same policy to control multiple AWS IoT Core devices. This allows you to simplify policy management and reduce resource duplication. For more information, see [Thing policy variables](https://docs.aws.amazon.com//iot/latest/developerguide/thing-policy-variables.html).
**Lifecycle events** - You can receive the thing name in lifecycle events (for example, connect, disconnect and subscribe, and unsubscribe). This allows processing of the thing name included in the messages, such as in rules. For more information, see [Lifecycle events](https://docs.aws.amazon.com//iot/latest/developerguide/life-cycle-events.html).
**Resource-specific logging** - You can configure resource-specific logging for thing groups, and easily apply the desired logging configuration for all things within the thing group defined. For more information, see [Configure Resource-specific overrides in AWS IoT (CLI)](configure-logging.md#fine-logging-cli).
**Cost allocation** - You can create billing groups with custom tags for cost allocation and add the things to these groups. For more information, see [Billing groups](https://docs.aws.amazon.com//iot/latest/developerguide/tagging-iot-billing-groups.html).
## How to associate a thing to a connection
If your client ID matches your thing's name in the registry, after you attach an X.509 certificate to that IoT thing, AWS IoT Core will associate the client connection with the thing. If your client ID doesn't match the thing's name in the registry, you can exclusively attach an X.509 certificate to the thing to establish this association. The thing that has this exclusive attachment is called an exclusive thing. Otherwise, it's called a non-exclusive thing. When a certificate is associated with an exclusive thing, this certificate can only be associated with other things if you detach it from the exclusive thing. In this section, choose either AWS Management Console or AWS CLI to associate a thing to a connection.
### AWS Management Console
**To attach a certificate to a thing exclusively using the AWS Management Console.**
1. Open the [AWS IoT home page](https://console.aws.amazon.com//iot/home#/home) in the AWS IoT console. On the left navigation, from **Security**, choose **Certificates**.
1. On the **Certificates** page, choose a certificate you want to attach a thing to. Then choose **Attach to things** from **Actions** on the upper right corner of the page.
Alternatively, choose a certificate and navigate to the certificate details page. Choose the **Things** tab, then choose **Attach to things**.
1. On the **Attach certificate to thing(s)** page, check the **Associate thing to connection** check box. Then choose a thing to attach this certificate to from the **Things** dropdown list.
1. Choose **Attach thing(s)**. If the action succeeds, you will see a banner that says "Successfully attached a thing to your certificate", and the thing will be added to the **Things** tab.
**To detach a certificate from an exclusive thing using the AWS Management Console**
1. Open the [AWS IoT home page](https://console.aws.amazon.com//iot/home#/home) in the AWS IoT console. On the left navigation, from **Security**, choose **Certificates**.
1. On the **Certificates** page, choose a certificate and navigate to the certificate details page.
1. On the certificate details page, choose the **Things** tab. Then choose a thing that you want to detach the certificate to. Choose **Detach things**.
1. On the **Detach things** window, confirm your action. Choose **Detach**. If the action succeeds, you will see a banner that says "Successfully detached a thing from your certificate", and the thing will no longer appear in the **Things** tab.
### AWS CLI
1. To attach a certificate to an thing using AWS CLI, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/attach-thing-principal.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/attach-thing-principal.html) command. To specify the exclusive certificate-to-thing attachment, you must specify `EXCLUSIVE_THING` in the `--thing-principal-type` field. An example command can be the following.
```
aws iot attach-thing-principal \
--thing-name "thing_1" \
--principal "arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8" \
--thing-principal-type "EXCLUSIVE_THING"
```
This command doesn't produce any output. For more information, see [Attach a principal to a thing](attach-thing-principal.md).
1. To list the things associated with the specified certificate along with the attachment type, run the `list-principal-things-v2` command. The attachment type refers to how the certificate is attached to the thing. An example command can be the following.
```
$ aws iot list-principal-things-v2 \
--principal "arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8"
```
The output can look like the following.
```
{
"PrincipalThingObjects": [
{
"thingPrincipalType": "EXCLUSIVE_THING",
"thing": "arn:aws:iot:us-east-1:123456789012:thing/thing_1"
}
]
}
```
For more information, see [List things associated with a principal V2](list-principal-things-v2.md).
1. To list the principals associated with the specified thing along with the attachment type, run the `list-thing-principals-v2` command . The attachment type refers to how the certificate is attached to the thing. An example command can be the following.
```
$ aws iot list-thing-principals-v2 \
--thing-name "thing_1"
```
The output can look like the following.
```
{
"ThingPrincipalObjects": [
{
"thingPrincipalType": "EXCLUSIVE_THING",
"principal": "arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8"
}
]
}
```
For more information, see [List principals associated with a thing V2](list-thing-principals-v2.md).
1. To detach a certificate from a thing, run the [detach-thing-principal](https://docs.aws.amazon.com/cli/latest/reference/iot/detach-thing-principal.html) command.
```
aws iot detach-thing-principal \
--principal "arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8" \
--thing-name "thing_1"
```
This command doesn't produce any output. For more information, see [Detach a principal from a thing](detach-thing-principal.md).
# Adding propagating attributes for message enrichment
In AWS IoT Core, you can enrich MQTT messages from devices by adding propagating attributes, which are contextual metadata from thing attributes or connection details. This process, known as message enrichment, can be helpful in various scenarios. For example, you can enrich messages for every inbound publish operation without making any device side changes or needing to use rules. By leveraging propagating attributes, you can benefit from a more efficient and cost-effective way to enrich your IoT data without the complexities of configuring rules or managing republishing configurations.
The message enrichment feature is available to AWS IoT Core customers who use [basic ingest](https://docs.aws.amazon.com//iot/latest/developerguide/iot-basic-ingest.html) and [message broker](https://docs.aws.amazon.com//iot/latest/developerguide/mqtt.html). It's important to note while publishing devices can use any MQTT version, subscribers (applications or services consuming messages) must support [MQTT 5](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html) to receive the enriched messages with propagating attributes. The enriched messages will be added as MQTT 5 user properties to every message published from devices. If you use[ rules](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rules.html), you can leverage the [get\$1user\$1properties](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-user-properties) function to retrieve the enriched data for message routing or processing based on the data.
In AWS IoT Core, you can add propagating attributes when you create or update a thing type, by using the AWS Management Console or the AWS CLI.
**Important**
When adding propagating attributes, you must make sure that the client publishing the message has been authenticated with a certificate. For more information, see [Client authentication](client-authentication.md).
**Note**
If you attempt to test this feature using the MQTT test client within console, it may not work since this feature requires MQTT clients authenticated with an associated certificate.
## AWS Management Console
**To add propagating attributes for message enrichment using the AWS Management Console**
1. Open the [AWS IoT home page](https://console.aws.amazon.com//iot/home#/home) in the AWS IoT console. On the left navigation, from **Manage**, choose **All devices**. Then choose **Thing types**.
1. On the **Thing types** page, choose **Create thing type**.
To configure message enrichment by updating a thing type, choose a thing type. Then on the thing type details page, choose **Update**.
1. On the **Create thing type** page, choose or enter the thing type information in **Thing type properties**.
If you choose to update a thing type, you will see **Thing type properties** after you choose **Update** in the previous step.
1. In **Additional configuration**, expand **Propagating attributes**. Then choose **Thing attribute** and enter the thing attribute you want to populate to the published MQTT5 messages. Using the console, you can add up to three thing attributes.
On the **Propagating attributes** section, choose **Connection attribute** and enter the attribute type and optionally the attribute name.
1. Optionally, add tags. Then choose **Create thing type**.
If you choose to update a thing type, choose **Update thing type**.
## AWS CLI
1. To add propagating attributes for message enrichment by creating a new thing type using the AWS CLI, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/create-thing-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/create-thing-type.html) command. An example command can be the following.
```
aws iot create-thing-type \
--thing-type-name "LightBulb" \
--thing-type-properties "{\"mqtt5Configuration\":{\"propagatingAttributes\":[{\"userPropertyKey\":\"iot:ClientId\", \"connectionAttribute\":\"iot:ClientId\"}, {\"userPropertyKey\":\"test\", \"thingAttribute\":\"A\"}]}}" \
```
The output of the command can look like the following.
```
{
"thingTypeName": "LightBulb",
"thingTypeArn": "arn:aws:iot:us-west-2:123456789012:thingtype/LightBulb",
"thingTypeId": "ce3573b0-0a3c-45a7-ac93-4e0ce14cd190"
}
```
1. To configure message enrichment by updating a thing type using AWS CLI, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-thing-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-thing-type.html) command. Note that you can only update `mqtt5Configuration` when you run this command. An example command can be the following.
```
aws iot update-thing-type \
--thing-type-name "MyThingType" \
--thing-type-properties "{\"mqtt5Configuration\":{\"propagatingAttributes\":[{\"userPropertyKey\":\"iot:ClientId\", \"connectionAttribute\":\"iot:ClientId\"}, {\"userPropertyKey\":\"test\", \"thingAttribute\":\"A\"}]}}" \
```
This command doesn't produce any output.
1. To describe a thing type, run the `describe-thing-type` command. This command will produce an output with message enrichment configuration information in the `thing-type-properties` field. An example command can be the following.
```
aws iot describe-thing-type \
--thing-type-name "LightBulb"
```
The output can look like the following.
```
{
"thingTypeName": "LightBulb",
"thingTypeId": "bdf72512-0116-4392-8d79-bf39b17ef73d",
"thingTypeArn": "arn:aws:iot:us-east-1:123456789012:thingtype/LightBulb",
"thingTypeProperties": {
"mqtt5Configuration": {
"propagatingAttributes": [
{
"userPropertyKey": "iot:ClientId",
"connectionAttribute": "iot:ClientId"
},
{
"userPropertyKey": "test",
"thingAttribute": "attribute"
}
]
}
},
"thingTypeMetadata": {
"deprecated": false,
"creationDate": "2024-10-18T17:37:46.656000+00:00"
}
}
```
For more information, see [Thing types](thing-types.md).