# Getting started with AWS IoT TwinMaker
The topics in this section describe how to do the following.
+ Create and set up a new workspace.
+ Create an entity and add a component to it.
Prerequisites:
To create your first workspace and scene, you need the following AWS resources.
+ An [AWS account](http://aws.amazon.com).
+ An IAM service role for AWS IoT TwinMaker. This role is automatically generated by default, when you create a new AWS IoT TwinMaker workspace in the [AWS IoT TwinMaker console](https://console.aws.amazon.com/iottwinmaker/).
If you don't choose to let AWS IoT TwinMaker automatically create a new IAM service role, you must specify one that you have already created.
For instructions on creating and managing this service role, see [Create and manage a service role for AWS IoT TwinMaker](twinmaker-gs-service-role.md).
For more information about IAM service roles, see [Creating a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html).
**Important**
This service role must have an attached policy that grants permission for the service to read and write to an Amazon S3 bucket. AWS IoT TwinMaker uses this role to access other services on your behalf. You will also need to assign a trust relationship between this role and AWS IoT TwinMaker so that the service can assume the role. If your twin interacts with other AWS services, add the necessary permissions for those services as well.
**Topics**
+ [
# Create and manage a service role for AWS IoT TwinMaker
](twinmaker-gs-service-role.md)
+ [
# Create a workspace
](twinmaker-gs-workspace.md)
+ [
# Create your first entity
](twinmaker-gs-entity.md)
+ [
# Setting up an AWS account
](set-up-aws-account.md)
# Create and manage a service role for AWS IoT TwinMaker
AWS IoT TwinMaker requires that you use a service role to allow it to access resources in other services on your behalf. This role must have a trust relationship with AWS IoT TwinMaker. When you create a workspace, you must assign this role to the workspace. This topic contains example policies that show you how to configure permissions for common scenarios.
## Assign trust
The following policy establishes a trust relationship between your role and AWS IoT TwinMaker. Assign this trust relationship to the role that you use for your workspace.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "iottwinmaker.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
## Amazon S3 permissions
The following policy allows your role to read and delete from and write to an Amazon S3 bucket. Workspaces store resources in Amazon S3, so the Amazon S3 permissions are required for all workspaces.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetBucket*",
"s3:GetObject",
"s3:ListBucket",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::*"
]
},
{
"Effect": "Allow",
"Action": [
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::*/DO_NOT_DELETE_WORKSPACE_*"
]
}
]
}
```
------
**Note**
When you create a workspace, AWS IoT TwinMaker creates a file in your Amazon S3 bucket that indicates it's being used by a workspace. This policy gives AWS IoT TwinMaker permission to delete that file when you delete the workspace.
AWS IoT TwinMaker places other objects related to your workspace. It's your responsibility to delete these objects when you delete a workspace.
## Assign permissions to a specific Amazon S3 bucket
When you create a workspace in the AWS IoT TwinMaker console, you can choose to have AWS IoT TwinMaker create an Amazon S3 bucket for you. You can find information about this bucket by using the following AWS CLI command.
```
aws iottwinmaker get-workspace --workspace-id workspace name
```
The following example shows the format of the output of this command.
```
{
"arn": "arn:aws:iottwinmaker:region:account Id:workspace/workspace name",
"creationDateTime": "2021-11-30T11:30:00.000000-08:00",
"description": "",
"role": "arn:aws:iam::account Id:role/service role name",
"s3Location": "arn:aws:s3:::bucket name",
"updateDateTime": "2021-11-30T11:30:00.000000-08:00",
"workspaceId": "workspace name"
}
```
To update your policy so that it assigns permissions for a specific Amazon S3 bucket, use the value of *bucket name*.
The following policy allows your role to read and delete from and write to a specific Amazon S3 bucket.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetBucket*",
"s3:GetObject",
"s3:ListBucket",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::bucket name",
"arn:aws:s3:::bucket name/*"
]
},
{
"Effect": "Allow",
"Action": [
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::iottwinmakerbucket/DO_NOT_DELETE_WORKSPACE_*"
]
}
]
}
```
------
## Permissions for built-in connectors
If your workspace interacts with other AWS services by using built-in connectors, you must include permissions for those services in this policy. If you use the **com.amazon.iotsitewise.connector** component type, you must include permissions for AWS IoT SiteWise. For more information about component types, see [Using and creating component types](twinmaker-component-types.md).
**Note**
If you interact with other AWS services by using a custom component type, you must grant the role permission to run the Lambda function that implements the function in your component type. For more information, see [Permissions for a connector to an external data source](#twinmaker-gs-service-role-external).
The following example shows how to include AWS IoT SiteWise in your policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetBucket*",
"s3:GetObject",
"s3:ListBucket",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::bucket name",
"arn:aws:s3:::bucket name/*"
]
},
{
"Effect": "Allow",
"Action": [
"iotsitewise:DescribeAsset"
],
"Resource": "arn:aws:s3:::bucket name"
},
{
"Effect": "Allow",
"Action": [
"iotsitewise:DescribeAssetModel"
],
"Resource": "arn:aws:s3:::bucket name"
},
{
"Effect": "Allow",
"Action": [
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::*/DO_NOT_DELETE_WORKSPACE_*"
]
}
]
}
```
------
If you use the **com.amazon.iotsitewise.connector** component type and need to read property data from AWS IoT SiteWise, you must include the following permission in your policy.
```
...
{
"Action": [
"iotsitewise:GetPropertyValueHistory",
],
"Resource": [
"AWS IoT SiteWise asset resource ARN"
],
"Effect": "Allow"
},
...
```
If you use the **com.amazon.iotsitewise.connector** component type and need to write property data to AWS IoT SiteWise, you must include the following permission in your policy.
```
...
{
"Action": [
"iotsitewise:BatchPutPropertyValues",
],
"Resource": [
"AWS IoT SiteWise asset resource ARN"
],
"Effect": "Allow"
},
...
```
If you use the **com.amazon.iotsitewise.connector.edgevideo** component type, you must include permissions for AWS IoT SiteWise and Kinesis Video Streams. The following example policy shows how to include AWS IoT SiteWise and Kinesis Video Streams permissions in your policy.
```
...
{
"Action": [
"iotsitewise:DescribeAsset",
"iotsitewise:GetAssetPropertyValue"
],
"Resource": [
"AWS IoT SiteWise asset resource ARN for the Edge Connector for Kinesis Video Streams"
],
"Effect": "Allow"
},
{
"Action": [
"iotsitewise:DescribeAssetModel"
],
"Resource": [
"AWS IoT SiteWise model resource ARN for the Edge Connector for Kinesis Video Streams"
],
"Effect": "Allow"
},
{
"Action": [
"kinesisvideo:DescribeStream"
],
"Resource": [
"Kinesis Video Streams stream ARN"
],
"Effect": "Allow"
},
...
```
## Permissions for a connector to an external data source
If you create a component type that uses a function that connects to an external data source, you must give your service role permission to use the Lambda function that implements the function. For more information about creating component types and functions, see [Using and creating component types](twinmaker-component-types.md).
The following example gives permission to your service role to use a Lambda function.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetBucket*",
"s3:GetObject",
"s3:ListBucket",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*"
]
},
{
"Action": [
"lambda:invokeFunction"
],
"Resource": [
"arn:aws:lambda:us-east-1:111122223333:function:example-function"
],
"Effect": "Allow"
},
{
"Effect": "Allow",
"Action": [
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::*/DO_NOT_DELETE_WORKSPACE_*"
]
}
]
}
```
------
For more information about creating roles and assigning policies and trust relationships to them by using the IAM console, the AWS CLI, and the IAM API, see [Creating a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html).
## Modify your workspace IAM role to use the Athena data connector
To use the [AWS IoT TwinMaker Athena tabular data connector](https://docs.aws.amazon.com//iot-twinmaker/latest/guide/athena-tabular-data-connector.html), you must update your AWS IoT TwinMaker workspace IAM role. Add the following permissions to your workspace IAM role:
**Note**
This IAM change only works for Athena tabular data stored with AWS Glue and Amazon S3. To use Athena with other data sources, you must configure an IAM role for Athena, see [Identity and access management in Athena](https://docs.aws.amazon.com/athena/latest/ug/security-iam-athena.html).
```
{
"Effect": "Allow",
"Action": [
"athena:GetQueryExecution",
"athena:GetQueryResults",
"athena:GetTableMetadata",
"athena:GetWorkGroup",
"athena:StartQueryExecution",
"athena:StopQueryExecution"
],
"Resource": [
"athena resouces arn"
]
},// Athena permission
{
"Effect": "Allow",
"Action": [
"glue:GetTable",
"glue:GetTables",
"glue:GetDatabase",
"glue:GetDatabases"
],
"Resource": [
"glue resouces arn"
]
},// This is an example for accessing aws glue
{
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetObject"
],
"Resource": [
"Amazon S3 data source bucket resources arn"
]
}, // S3 bucket for storing the tabular data.
{
"Effect": "Allow",
"Action": [
"s3:GetBucketLocation",
"s3:GetObject",
"s3:ListBucket",
"s3:ListBucketMultipartUploads",
"s3:ListMultipartUploadParts",
"s3:AbortMultipartUpload",
"s3:CreateBucket",
"s3:PutObject",
"s3:PutBucketPublicAccessBlock"
],
"Resource": [
"S3 query result bucket resources arn"
]
} // Storing the query results
```
Read the [Identity and access management in Athena](https://docs.aws.amazon.com/athena/latest/ug/security-iam-athena.html) for more information on Athena IAM configuration.
# Create a workspace
To create and configure your first workspace, use the following steps.
**Note**
This topic shows you how to create a simple workspace with a single resource. For a fully featured workspace with multiple resources, try the sample setup in the [AWS IoT TwinMaker samples](https://github.com/aws-samples/aws-iot-twinmaker-samples) Github repository.
1. On the [AWS IoT TwinMaker console](https://console.aws.amazon.com/iottwinmaker/home) home page, choose **Workspaces** in the left navigation pane.
1. On the **Workspaces** page, choose **Create workspace**.
1. On the **Create a Workspace** page, enter a name for your workspace.
1. (Optional) Add a description for your workspace.
1. Under **S3 resource**, choose **Create an S3 bucket**. This option creates an Amazon S3 bucket where AWS IoT TwinMaker stores information and resources related to the workspace. Each workspace requires its own bucket.
1. Under **Execution role**, choose either **Auto-generate a new role** or the custom IAM role that you created as for this workspace.
If you choose **Auto-generate a new role**, AWS IoT TwinMaker attaches a policy to the role that grants permission to the new service role to access other AWS services, including permission to read and write to the Amazon S3 bucket that you specify in the previous step. For information about assigning permissions to this role, see [Create and manage a service role for AWS IoT TwinMaker](twinmaker-gs-service-role.md).
1. Choose **Create Workspace**. The following banner appears at the top of the **Workspaces** page.
![\[A banner with the recommended IAM policy and role names, and a button that lets you get the required JSON.\]](http://docs.aws.amazon.com/iot-twinmaker/latest/guide/images/DashboardPolicy.png)
1. Choose **Get json**. We recommend you add the IAM policy you see to the IAM role that AWS IoT TwinMaker created for users and accounts that view the Grafana dashboard. The name of this role follows this pattern: *workspace-name*DashboardRole, For instructions on how to create a policy and attach it to a role, see [Modifying a role permissions policy (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.htmlroles-managingrole-editing-console.html#roles-modify_permissions-policy).
The following example contains the policy to add to the dashboard role.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::iottwinmaker-workspace-workspace-name-lower-case-123456789012",
"arn:aws:s3:::iottwinmaker-workspace-workspace-name-lower-case-123456789012/*"
]
},
{
"Effect": "Allow",
"Action": [
"iottwinmaker:Get*",
"iottwinmaker:List*"
],
"Resource": [
"arn:aws:iottwinmaker:us-east-1:111122223333:workspace/workspace-name",
"arn:aws:iottwinmaker:us-east-1:111122223333:workspace/workspace-name/*"
]
},
{
"Effect": "Allow",
"Action": "iottwinmaker:ListWorkspaces",
"Resource": "*"
}
]
}
```
------
You're now ready to start creating a data model for your workspace with your first entity. For instructions on how to do this, see [Create your first entity](twinmaker-gs-entity.md).
# Create your first entity
To create your first entity, use the following steps.
1. On the **Workspaces** page, choose your workspace, and then in the left pane choose **Entities**.
1. On the **Entities** page, choose **Create**, and then choose **Create entity**.
![\[A TwinMaker Entities console page with the Create entity option appearing under Create.\]](http://docs.aws.amazon.com/iot-twinmaker/latest/guide/images/CreateEntity.png)
1. In the **Create an entity** window, enter a name for your entity. This example uses a **CookieMixer** entity.
1. (Optional) Enter a description for your entity.
1. Choose **Create entity**,
Entities contain data about each item in your workspace. You put data into entities by adding components. AWS IoT TwinMaker provides the following built-in component types.
+ **Parameters**: Adds a set of key-value properties.
+ **Document**: Adds a name and a URL for a document that contains information about the entity.
+ **Alarms**: Connects to an alarm time-series data source.
+ **SiteWise connector**: Pulls time-series properties that are defined in an AWS IoT SiteWise asset.
+ **Edge Connector for Kinesis Video Streams AWS IoT Greengrass**: Pulls video data from the Edge Connector for KVS AWS IoT Greengrass. For more information, see [AWS IoT TwinMaker video integration](video-integration.md).
You can see these component types and their definitions by choosing **Component types** in the left pane. You can also create a new component type on the **Component types** page. For more information about creating component types, see [Using and creating component types](twinmaker-component-types.md).
In this example, we create a simple document component that adds descriptive information about your entity.
1. On the **Entities** page, choose the entity, and then choose add component.
![\[A TwinMaker Entities console page showing the Add component button.\]](http://docs.aws.amazon.com/iot-twinmaker/latest/guide/images/AddComponent.png)
1. In the **Add component** window, enter a name for your component. Since this example uses a cookie mixer entity, we enter **MixerDescription** in the **Name** field.
![\[A TwinMaker Add Component console page showing the Name field and "Add a doc" button.\]](http://docs.aws.amazon.com/iot-twinmaker/latest/guide/images/DocumentComponent.png)
1. Choose **Add a doc**, then enter values for the doc **Name** and **External Url**. With the documents component, you can store a list of external URLs that contain important information about the entity.
1. Choose **Add component**.
You're now ready to create your first scene. For instructions on how to do this, see [Creating and editing AWS IoT TwinMaker scenes](scenes.md).
# Setting up an AWS account
If you do not have an AWS account, complete the following steps to create one.
**To sign up for an AWS account**
1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup).
1. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad.
When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks).
## Sign up for an AWS account
If you do not have an AWS account, complete the following steps to create one.
**To sign up for an AWS account**
1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup).
1. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad.
When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks).
AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**.
## Create a user with administrative access
After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks.
**Secure your AWS account root user**
1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password.
For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*.
1. Turn on multi-factor authentication (MFA) for your root user.
For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*.
**Create a user with administrative access**
1. Enable IAM Identity Center.
For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*.
1. In IAM Identity Center, grant administrative access to a user.
For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*.
**Sign in as the user with administrative access**
+ To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user.
For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*.
**Assign access to additional users**
1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions.
For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*.
1. Assign users to a group, and then assign single sign-on access to the group.
For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*.