image-package

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 --input parameter.
  • The application manifest file is provided in the --applicationmanifestpath parameter.
  • For high-level applications, an application runtime version is provided in the --targetapiset parameter.

Required parameters

Parameter Type Description Supported version
--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. Azure Sphere CLI
--destination Path to image package Specifies a path and filename for the output image package. Azure Sphere CLI
-i, --input 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. Azure Sphere classic CLI
-o, --output Path to image package Specifies a path and filename for the output image package. Azure Sphere classic CLI

Optional parameters

Parameter Type Description Supported version
-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. Azure Sphere CLI
--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. Azure Sphere CLI
--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. Azure Sphere CLI
--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. Azure Sphere CLI
-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.
- Azure Sphere CLI
- Azure Sphere classic CLI
-a, --applicationmanifestpath 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. Azure Sphere classic CLI
-p, --hardwaredefinitions String Specifies the optional path to a hardware definition JSON file that is used to map peripheral names in app_manifest.json to underlying values. You may provide a relative or absolute path. See hardware definition for more information. Azure Sphere classic CLI
-s, --targetapiset 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. Azure Sphere classic CLI
-f, --targetdefinitionfilename 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. Azure Sphere classic CLI
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 Supported version
--destination String Specifies a path to the output filename for the resulting image package. Azure Sphere CLI
-o, --output String Specifies a path to the output filename for the resulting image package. Azure Sphere classic CLI

Optional parameters

Parameter Type Description Supported version
--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. Azure Sphere CLI
-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. - Azure Sphere CLI
- Azure Sphere classic CLI
-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. - Azure Sphere CLI
-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 --input 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. Azure Sphere classic CLI
-i, --input Path Identifies the path to the board configuration image. If this is included, --preset must not be used; the two parameters are mutually exclusive. Azure Sphere classic CLI
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 Supported version
-f, --image-package String Specifies the path to the image package. You can provide a relative or absolute path. Azure Sphere CLI
-f, --filepath String Specifies the path to the image package. You can provide a relative or absolute path. Azure Sphere classic CLI
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