# Getting started with Software Package Catalog
You can build and maintain the AWS IoT Device Management Software Package Catalog through the AWS Management Console, AWS IoT Core API operations, and AWS Command Line Interface (AWS CLI).
**Note**
Enabling AWS IoT fleet indexing is a requirement to use Software Package Catalog. Basic operations such as creating a software package version in the AWS Management Console and using the `CreatePackage` API command will fail without AWS IoT fleet indexing enabled.
For more information on using AWS IoT fleet indexing with Software Package Catalog, see [Preparing fleet indexing](preparing-fleet-indexing.md).
**Using the console**
To use the AWS Management Console, sign into your AWS account and navigate to [AWS IoT Core](https://console.aws.amazon.com/iot/home). In the navigation pane, choose **Software packages**. You can then create and manage packages and their versions from this section.
**Using API or CLI operations**
You can use the AWS IoT Core API operations to create and manage Software Package Catalog features. For more information, see [AWS IoT API Reference](https://docs.aws.amazon.com/iot/latest/apireference/) and [AWS SDKs and Toolkits](https://aws.amazon.com/developer/tools/). The AWS CLI commands also manage your catalog. For more information, see the [AWS IoT CLI Command Reference](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/index.html).
**Topics**
+ [Creating a software package and package version](creating-package-and-version.md)
+ [Deploying a package version through AWS IoT jobs](deploying-package-version.md)
+ [Associating a package version to an AWS IoT thing](associating-package-version.md)
# Creating a software package and package version
You can use the following steps to create a package and an initial version thing through the AWS Management Console.
**To create a software package**
1. Sign into your AWS account and navigate to the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. On the navigation pane, choose **Software packages**.
1. On the **AWS IoT software package** page, choose **Create package**. The **Enable dependencies for package management** dialog box appears.
1. Under **Fleet indexing**, select **Add device software packages and version**. This is required for Software Package Catalog and provides fleet indexing and metrics about your fleet.
1. [Optional] If you want AWS IoT jobs to update the reserved named shadow when jobs successfully complete, select **Auto update shadows from jobs**. If you do not want AWS IoT jobs to make this update, leave this check-box unselected.
1. [Optional] To grant AWS IoT jobs the rights to update the reserved named shadow, under **Select role**, choose **Create role**. If you don't want AWS IoT jobs to make this update, this role is not required.
1. Create or select a role.
1. If you **don’t have a role** for this purpose: When the **Create role** dialog box appears, enter a **Role name**, and then choose **Create**.
1. If you **do have a role** for this purpose: For **Select role**, choose your role and then make sure the **Attach policy to IAM role** check box is selected.
1. Choose **Confirm**. The **Create new package** page appears.
1. Under **Package detail**, enter a **Package name**.
1. Under **Package description**, enter information to help you identify and manage this package.
1. [Optional] You can use tags to help you categorize and manage this package. To add tags, expand **Tags**, choose **Add tag**, and enter a key-value pair. You can enter up to 50 tags. For more information, see [Tagging your AWS IoT resources](https://docs.aws.amazon.com/iot/latest/developerguide/tagging-iot.html).
**To add a package version while creating a new package**
1. Under **Initial version**, enter a **Version name**.
We recommend using the [SemVer format](https://semver.org/) (for example, `1.0.0.0`) to uniquely identify your package version. You are also able to use a different formatting strategy that better suits your use case. For more information, see [Package version lifecycle](preparing-to-use-software-package-catalog.md#package-version-lifecycle).
1. Under **Version description**, enter information that will help you identify and manage this package version .
**Note**
The **Default version** check box is deactivated because package versions are created in a `draft` state. You can name the default version after you create the package version and when you change the state to `published`. For more information, see [Package version lifecycle](preparing-to-use-software-package-catalog.md#package-version-lifecycle).
1. [Optional] To help you manage this version or to communicate information to your devices, enter one or more name-value pairs for **Version attributes**. Choose **Add attribute** for each name-value pair you enter. For more information, see [Version attributes](preparing-to-use-software-package-catalog.md#version-attributes).
1. [Optional] You can use tags to help you categorize and manage this package. To add tags, expand **Tags**, choose **Add** tag, and enter a key-value pair. You can enter up to 50 tags. For more information, see [Tagging your AWS IoT resources](https://docs.aws.amazon.com/iot/latest/developerguide/tagging-iot.html).
1. Choose **Next**.
**Associate the Software Bill of Materials to a Package Version (Optional)**
1. On **Step 3: Version SBOMs (Optional)** in the **SBOM configurations** window, choose the default SBOM file format and validation mode used to validate your software bill of materials before it is associated to your package version.
1. In the **Add SBOM file** window, enter the Amazon Resource Name (ARN) representing your versioned Amazon S3 bucket and the preferred SBOM file format if the default type doesn't work.
**Note**
You can either add a single SBOM file or a single zip file containing multiple SBOMs if you have more than one software bill of material for your package version.
1. In the **Added SBOM file** window, you can view the SBOM file you added for your package version.
1. Choose **Create package and version**. The package version page appears and you can see the validation status of your SBOM file in the **Added SBOM file** window. The initial status will be `In progress` as the SBOM file undergoes validation.
**Note**
The SBOM file validation statuses are `Invalid file`, `Not started`, `In progress`, `Validated (SPDX)`, `Validated (CycloneDX)`, and the validation failure reasons.
# Deploying a package version through AWS IoT jobs
You can use the following steps to deploy a package version through the AWS Management Console.
**Prerequisites:**
Before you begin, do the following:
+ Register AWS IoT things with AWS IoT Core. For directions to add your devices to AWS IoT Core, see [Create a thing object](https://docs.aws.amazon.com/iot/latest/developerguide/create-iot-resources.html#create-aws-thing).
+ [Optional] Create an AWS IoT thing group or dynamic thing group to target the devices that you will deploy the package version. For directions to create a thing group, see [Create a static thing group](https://docs.aws.amazon.com/iot/latest/developerguide/thing-groups.html#create-thing-group). For directions to create a dynamic thing group, see [Create a dynamic thing group](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html#create-dynamic-thing-group).
+ Create a software package and a package version. For more information, see [Creating a software package and package version](creating-package-and-version.md).
+ Create a job document. For more information, see [Preparing the job document and package version for deployment](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html#preparing-to-deploy).
**To deploy an AWS IoT job**
1. On the [AWS IoT console](https://console.aws.amazon.com/iot/home), choose **Software packages**.
1. Choose the software package that you want to deploy. The **software package details** page appears.
1. Choose the package version that you want to deploy, under **Versions**, and choose **Deploy job version**.
1. If this is your first time deploying a job through this portal, a dialog box describing the requirements appears. Review the information and choose **Acknowledge**.
1. Enter a name for the deployment or leave the autogenerated name in the **Name** field.
1. [Optional] In the **Description** field, enter a description that identifies the purpose or contents of the deployment, or leave the autogenerated information.
**Note:** We recommend that you don't use personally identifiable information in the Job name and description fields.
1. [Optional] Add any tags to associate with this job.
1. Choose **Next**.
1. Under **Job targets**, choose the things or thing groups that should receive the job.
1. In the **Job file** field, specify the job document JSON file.
1. Open **Jobs integration with the Package Catalog service**.
1. Select the packages and versions that are specified within your job document.
**Note**
You are required to choose the same packages and package versions that are specified within the job document. You can include more, but the job will issue instructions only for the packages and versions included in the job document. For more information, see [Naming the packages and versions when deploying](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html#naming-package-versions).
1. Choose **Next**.
1. On the Job configuration page, select one of the following job types in the Job configuration dialog box:
+ **Snapshot job:** A snapshot job is complete when it's finished its run on the target devices and groups.
+ **Continuous job:** A continuous job applies to thing groups and runs on any device that you later add to a specified target group.
1. In the **Additional configurations - optional** dialog box, review the following optional job configurations and make your selections accordingly. For more information, see [Job rollout, scheduling, and abort configurations](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-configurations-details.html#job-rollout-abort-scheduling) and [Job execution timeout and retry configurations](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-configurations-details.html#job-timeout-retry).
+ Rollout configuration
+ Scheduling configuration
+ Job executions timeout configuration
+ Job executions retry configuration
+ Abort configuration
1. Review the job selections and then choose **Submit**.
After you create the job, the console generates a JSON signature and places it in your job document. You can use the AWS IoT console to view the status of a job, or cancel or delete a job. To manage jobs, go to the [Job hub of the console](https://console.aws.amazon.com/iot/home#/jobhub).
# Associating a package version to an AWS IoT thing
After you install software on your device, you can associate a package version to an AWS IoT thing’s reserved named shadow. If AWS IoT jobs has been configured to update the thing’s reserved named shadow after the job deploys and successfully completes, you don’t need to complete this procedure. For more information, see [Reserved named shadow](preparing-to-use-software-package-catalog.md#reserved-named-shadow).
**Prerequisites:**
Before you begin, do the following:
+ Create an AWS IoT thing, or things, and establish telemetry through AWS IoT Core. For more information, see [Getting started with AWS IoT Core](https://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html).
+ Create a software package and package version. For more information, see [Creating a software package and package version](creating-package-and-version.md).
+ Install the package version software on the device.
**Note**
Associating a package version to an AWS IoT thing doesn’t update or install software on the physical device. The package version must be deployed to the device.
**To associate a package version to an AWS IoT thing**
1. On the [AWS IoT console](https://console.aws.amazon.com/iot/home) navigation pane, expand the **All devices** menu and choose **Things**.
1. Identify the AWS IoT thing that you want to update from the list and choose the thing name to display its details page.
1. In the **Details** section, choose **Packages and versions**.
1. Choose **Add to package and version**.
1. For **Choose a device package**, choose the software package you want.
1. For **Choose a version**, choose the software version you want.
1. Choose **Add device package**.
The package and version appear on the **Selected packages and versions** list.
1. Repeat these steps for each package and version that you want to associate to this thing.
1. When you’re finished, choose **Add package and version details**. The **Thing details** page opens and you can see the new package and version in the list.