image-package
Important
This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.
Manages Azure Sphere images on disk.
| Operation | Description |
|---|---|
| pack-application | Creates an image package. |
| pack-board-config | Creates a board configuration image package. |
| show | Displays details about an image package. |
pack-application
Creates an executable application from a compiled and linked image and an app_manifest.json file.
Real-time capable applications (RTApps) are built as ELF or AXF files and not as raw binaries. Before packaging an RTApp, edit the application manifest file so that ApplicationType is set to "RealTimeCapable", and EntryPoint is set to the name of the ELF or AXF file, which must be in the root of the application directory.
Tip
This command is run when you build a high-level application or a real-time capable application using Visual Studio Code or Visual Studio.
- The build process creates an approot<app-name> directory, which is the input directory specified in the
--package-directoryparameter. - The application manifest file is provided in the
--application-manifestparameter. - For high-level applications, an application runtime version is provided in the
--target-api-setparameter.
Required parameters
| Parameter | Type | Description |
|---|---|---|
| --destination | Path to image package | Specifies a path and filename for the output image package. |
| --package-directory | Path to approot_folder | Identifies the input directory, which is used as the system root for the Azure Sphere image file. The app_manifest.json file for the application must be in this directory. |
Optional parameters
| Parameter | Type | Description |
|---|---|---|
| -a, --application-manifest | String | Specifies the path to the application manifest file. This can be a JSON file or a directory which contains app_manifest.json. You may provide a relative or absolute path. |
| --hardware-definitions | String | Specifies an optional space-separated list of paths to the directories containing hardware definition (JSON) files. The values from the files are used to map peripheral names in app_manifest.json to underlying values. You can provide a relative or absolute path. See hardware definition for more information. |
| --target-api-set | String | Specifies the name of the target API set used during compilation. Required for high-level apps if not specified in the app manifest. Not required for RTApps. |
| --target-definition-filename | String | Specifies name of the hardware target definition file used to map peripheral names in app_manifest.json. It must be provided if the application uses hardware definitions. |
| -x, --executables | executable1,executable2 … | Specifies the paths to one or more files to mark as executable in the image package. The EntryPoint listed in the app_manifest files is always marked as executable, so the -x flag is required only if other executables are present. By default, files are not executable when packaged into an image. The sub-paths are relative to the path of the executables. The paths can use either Windows filename syntax (backslashes) or Linux filename syntax (forward slashes); spaces, commas, and semicolons are not allowed. You can either specify -x for each executable file, or use it only once and supply multiple paths separated by commas without intervening spaces. |
Global parameters
The following global parameters are available for the Azure Sphere CLI:
| Parameter | Description |
|---|---|
| --debug | Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report. |
| -h, --help | Prints CLI reference information about commands and their arguments and lists available subgroups and commands. |
| --only-show-errors | Shows only errors, suppressing warnings. |
| -o, --output | Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands. |
| --query | Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples. |
| --verbose | Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs. |
Note
If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.
Example
azsphere image-package pack-application --package-directory C:\AppSamples\LocalSamples\HelloWorld\HelloWorld_HighLevelApp\out\ARM-Debug\approotHelloWorld_HighLevelApp --destination myimage.imagepackage
pack-board-config
Creates a board configuration image package. You can either use a preset board configuration image or provide a custom configuration image.
Required parameters
| Parameter | Type | Description |
|---|---|---|
| --destination | String | Specifies a path to the output filename for the resulting image package. |
Optional parameters
| Parameter | Type | Description |
|---|---|---|
| --board-config-file | Path | Identifies the path to the board configuration image. If this is included, --preset must not be used; the two parameters are mutually exclusive. |
| -n, --name | String | Sets the image package name in the created file's metadata. If not provided, a new name will be generated based on the provided board configuration, incorporating part of the component ID for uniqueness. |
| -p, --preset | String | Provides the ID of the preset board configuration image to apply. Enter either the ID of a preset package, or provide a path for the board config file using the --board-config-file parameter for a custom board configuration image. The ID is an enumeration value and is currently fixed to the single value lan-enc28j60-isu0-int5. |
Global parameters
The following global parameters are available for the Azure Sphere CLI:
| Parameter | Description |
|---|---|
| --debug | Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report. |
| -h, --help | Prints CLI reference information about commands and their arguments and lists available subgroups and commands. |
| --only-show-errors | Shows only errors, suppressing warnings. |
| -o, --output | Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands. |
| --query | Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples. |
| --verbose | Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs. |
Note
If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.
Example
azsphere image-package pack-board-config --preset lan-enc28j60-isu0-int5 --destination board2.imagepackage
show
Displays information about an image package.
Required parameters
| Parameter | Type | Description |
|---|---|---|
| -f, --image-package | String | Specifies the path to the image package. You can provide a relative or absolute path. |
Global parameters
The following global parameters are available for the Azure Sphere CLI:
| Parameter | Description |
|---|---|
| --debug | Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report. |
| -h, --help | Prints CLI reference information about commands and their arguments and lists available subgroups and commands. |
| --only-show-errors | Shows only errors, suppressing warnings. |
| -o, --output | Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands. |
| --query | Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples. |
| --verbose | Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs. |
Note
If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.
Example
azsphere image-package show --image-package C:\sample\quickstart_steps\QuickStart-AzureSphereBlink1\QuickStart-AzureSphereBlink1\out\ARM-Debug\QuickStart-AzureSphereBlink1.imagepackage
Image package metadata:
Section: Identity
Image Type: Application
Component ID: 99d419ef-296d-43b0-ade1-809efe3a7aba
Image ID: d788fdd1-28eb-4477-9818-a4734289f2f1
Section: Signature
Signing Type: ECDsa256
Cert: a8d5cc6958f48710140d7a26160fc1cfc31f5df0
Section: Debug
Image Name: QuickStart-AzureSphereBlink1
Built On (UTC): 09/07/2020 13:18:52
Built On (Local): 09/07/2020 14:18:52
Section: Temporary Image
Remove image at boot: False
Under development: True
Section: ABI Depends
Depends on: ApplicationRuntime, version 5