image-package, pkg

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

Build the required sample using Visual Studio Code or Visual Studio. An approot_<folder> folder is created which has the app_manifest.json file containing the TargetApplicationRuntimeVersion field. Ensure that you provide the location to this folder in the input parameter.

Required parameters

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

Optional parameters

Parameter Type Description Supported version
-x, --executables executable1,executable2 Specifies the sub-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 --input path. 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 v1
-Azure Sphere CLI v2 Beta
-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 CLI v1
-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 CLI v1
-s, --targetapiset String Sets the target API set for the image package. Azure Sphere CLI v1
-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 CLI v1
-a, --application-manifest-path 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 v2 Beta
--hardware-definitions 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 CLI v1
--target-api-set String Sets the target API set for the image package. Azure Sphere CLI v2 Beta
--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 v2 Beta
Global parameters

Parameter Description
-v, --verbose Provides verbose output in Azure Sphere CLI v1
-?, --help Displays help on the command in Azure Sphere CLI v1

Note

If you are using Azure Sphere CLI v2 Beta, see Global Parameters for more information on available options.

Example

azsphere image-package pack-application --input C:\AppSamples\LocalSamples\HelloWorld\HelloWorld_HighLevelApp\out\ARM-Debug\approotHelloWorld_HighLevelApp --output 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
-o, --output filename Specifies a filename for the output image package. Azure Sphere CLI v1
-f, --destination-file filename Specifies a filename for the output image package. Azure Sphere CLI v2 Beta

Optional parameters

Parameter Type Description Supported version
-i, --input Path Identifies the path to the board configuration image. You can add multiple images by adding additional parameters, or multiple paths can be combined in a single parameter in a comma-separated list. If this is included, --preset must not be used; the two parameters are mutually exclusive. - Azure Sphere CLI v1
- Azure Sphere CLI v2 Beta
-n, --name package-name 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 v1
- Azure Sphere CLI v2 Beta
-p, --preset String Provides the ID of the preset board configuration image to apply. Either use this flag with the ID of a preset package, or provide --input 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 v1
- Azure Sphere CLI v2 Beta
Global parameters

Parameter Description
-v, --verbose Provides verbose output in Azure Sphere CLI v1
-?, --help Displays help on the command in Azure Sphere CLI v1

Note

If you are using Azure Sphere CLI v2 Beta, see Global Parameters for more information on available options.

Example

azsphere image-package pack-board-config --preset lan-enc28j60-isu0-int5 --output board2.imagepackage

show

Displays information about an image package.

Required parameters

Parameter Type Description Supported version
-f, --filepath String Specifies the path to the image package. You can provide a relative or absolute path. Azure Sphere CLI v1
-f, --file-path String Specifies the path to the image package. You can provide a relative or absolute path. Azure Sphere CLI v2 Beta
Global parameters

Parameter Description
-v, --verbose Provides verbose output in Azure Sphere CLI v1
-?, --help Displays help on the command in Azure Sphere CLI v1

Note

If you are using Azure Sphere CLI v2 Beta, see Global Parameters for more information on available options.

Example

azsphere image-package show --filepath 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