device, dev

Manages Azure Sphere devices.

Operation Description
capability, cap Manages device capabilities
claim Claims a previously unclaimed device to the Azure Sphere tenant
image, img Manages images for a device
link-feed Links a device to a feed
manufacturing-state, mfg Manages the manufacturing state of the attached device
prep-debug Sets up a device for local debugging
prep-field Sets up a device to disable debugging and receive over-the-air (OTA) updates
recover Uses special recovery mode to load new firmware onto the device
restart Restarts the attached device
show-attached Displays details about the attached device from the device itself
show-ota-config Displays details about the OTA update configuration of the device
show-ota-status Displays the status of the most recent OTA update
sideload, sl Loads an application onto the attached device or changes the status of the application
update-device-group Moves a device into a device group
update-sku Sets the product SKU for a device
wifi Manages the Wi-Fi configuration for the device

capability, cap

Manages device capabilities.

Currently, the only capability is appdevelopment, which enables you to sideload SDK-signed image packages to the device and to start, stop, debug, or delete any image package from the device.

Operation Description
download Downloads a device capability configuration from the Azure Sphere Security Service
show-attached Displays the capability configuration for the attached device
update Applies a device capability configuration to the attached device

capability download

Downloads a device capability from the Azure Sphere Security Service and applies it to a device.

The appdevelopment capability lets you sideload SDK-signed applications and start, stop, debug, or delete any application on the device. Without the appdevelopment capability, only OTA-deployed applications can be loaded and start, stop, debug, and delete are prohibited.

Required parameters

Parameter Description
-t, --type capability-type Specifies the type of capability, either appdevelopment or none. Use none to remove the appdevelopment capability.

Optional parameters

Parameter Description
-i, --deviceid id Specifies the ID of the device for which to get the capability configuration. If you specify a device ID, you must also use --output. If omitted, gets a capability for the attached device.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-o, --output path Specifies the path and filename at which to save the capability configuration. Include a path, even for the current directory. Required with the --deviceid parameter.
-p, --apply Applies the device capability configuration to the attached device. Do not use with --deviceid or --output.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device capability download --type appdevelopment --output ./appdevcap

Downloading device capability configuration for device ID <device ID>.
Successfully downloaded device capability configuration.
Successfully wrote device capability configuration file './appdevcap'.
Command completed successfully in 00:00:07.7393213.

capability show-attached

Displays the capability configuration for the attached device.

Optional parameters

Parameter Description
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device capability show-attached
Device Capabilities:
        Enable App development
Command completed successfully in 00:00:00.8746160.

capability update

Applies a device capability configuration to the attached device.

Required parameters

Parameter Description
-f, --filepath path Specifies the path and name of the device capability file to apply.

Optional parameters

Parameter Description
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device capability update --filepath appdevcap

Applying device capability configuration to device.
Successfully applied device capability configuration to device.
The device is rebooting.
Command completed successfully in 00:00:07.7393213.

claim

Claims a previously unclaimed device for the current Azure Sphere tenant.

Important

Before you claim the device, ensure that you are signed in to the correct Azure Sphere tenant. A device can be claimed only once. Once claimed, a device cannot be moved to a different tenant.

Optional parameters

Parameter Description
-i, --deviceid GUID Specifies the ID of the device to claim. If omitted, azsphere claims the attached device.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device claim

Claiming device.
Claiming attached device ID <device ID> into tenant ID 'd343c263-4aa3-4558-adbb-d3fc34631800'.
Successfully claimed device ID <device ID> into tenant 'Microsoft' with ID 'd343c263-4aa3-4558-adbb-d3fc34631800'.
Command completed successfully in 00:00:05.5459143.

image, img

Returns information about the images that are installed on or targeted to the attached device.

Operation Description
list-installed Provides details about the images that are currently installed on the attached device
list-targeted Provides details about the images that are targeted to the attached device.

image list-installed

Lists the images that are installed on the attached device. The list of information includes the component and image IDs.

Optional parameters

Parameter Description
-f, --full Lists both customer and system software images that are installed on the device. By default, lists only customer application images, debuggers, and board configuration images.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device image list-installed
Installed images:
 --> gdbserver
   --> Image type:   Application
   --> Component ID: 8548b129-b16f-4f84-8dbe-d2c847862e78
   --> Image ID:     43d2707f-0bc7-4956-92c1-4a3d0ad91a74
 --> Mt3620Blink4
   --> Image type:   Application
   --> Component ID: 970d2ff1-86b4-4e50-9e80-e5af2845f465
   --> Image ID:     e53ce989-0ecf-493d-8056-fc0683a566d3
Command completed successfully in 00:00:01.6189314.

image list-targeted

Lists the images that have been uploaded to the Azure Sphere Security Service and will be installed the next time the device is updated.

Optional parameters

Parameter Description
-f, --full Lists both customer and system software images that will be installed on the device. By default, lists only customer application images.
-i, --deviceid GUID Specifies the ID of the device for which to list targeted images. By default, lists images for the attached device.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device image list-targeted

Successfully retrieved the current image set for device with ID <device ID> from your Azure Sphere tenant:
 --> ID:   [6e9cdc9d-c9ca-4080-9f95-b77599b4095a]
 --> Name: 'ImageSet-Mt3620Blink1-2018.07.19-18.15.42'
Images to be installed:
 --> [ID: 116c0bc5-be17-47f9-88af-8f3410fe7efa]
Command completed successfully in 00:00:04.2733444.

Links a device to a feed and optionally adds a new image to the feed.

Optional parameters

Parameter Description
-c, --componentid GUID Specifies the ID of an existing component that the feed will deliver. Either --componentid or --imagepath is required with --newfeedname. You may add multiple components to the feed by either using this flag multiple times to specify multiple components, or once and separate the component IDs with commas and no intervening spaces.
-d, --dependentfeedid GUID Specifies the ID of the system software feed that the new feed depends on. Required with --newfeedname.
-f --feedid GUID Specifies the ID of an existing feed to link to the device group for the specified device. If omitted, creates a new feed and assigns it the name in the optional --newfeedname parameter. If you already have a feed for this component, use it to avoid cluttering your tenant with redundant feeds. Either --feedid or --newfeedname is required.
--force Forces the deployment of an image that uses a Beta API that may no longer be supported.
-i, --deviceid GUID Specifies the ID of the device to which to link the feed. If omitted, links the feed to the attached device.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-p, --imagepath path Specifies the path to an image package to upload to the feed and validates the component ID of the image package against the component ID for the feed. If omitted, creates a new feed but does not assign an initial image set. Either --imagepath or --componentid is required with --newfeedname. You may add multiple image paths to the feed by either using this flag multiple times to specify multiple image paths or using it once and separating the image paths with commas and no intervening spaces.
-n, --newfeedname string Specifies a name for the feed. Requires --dependentfeedid. Feed names must be unique within an Azure Sphere tenant. Either --newfeedname or --feedid is required.
-s, --newimagesetname string Specifies the name for the new image set to create. If omitted, generates an image set name based on the component name and a time stamp. Requires --imagepath.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Examples

This example creates a new feed and supplies an image package for the feed to deliver.

azsphere device link-feed --dependentfeedid 3369f0e1-dedf-49ec-a602-2aa98669fd61 --imagepath "C:\Users\User\Documents\Visual Studio 2017\Projects\Mt3620Blink5\Mt3620Blink5\bin\ARM\Debug\Mt3620Blink5.imagepackage" --newfeedname Model100AppFeedOTA --newimagesetname Model100Appv1.0

Getting the details for device with ID <device ID>.
Uploading image from file 'C:\Users\User\Documents\Visual Studio 2017\Projects\Mt3620Blink5\Mt3620Blink5\bin\ARM\Debug\Mt3620Blink5.imagepackage':
 --> Image ID:       'b66f1398-4ad6-4f12-be84-8ad607676ec3'
 --> Component ID:   '8fb105a3-35d0-423a-9427-a21852623965'
 --> Component name: 'Mt3620Blink5'
Create a new feed with name 'Model100AppFeedOTA'.
Adding feed with ID '8e2d3b19-bb01-4e36-b974-5b2f8df502e9' to device group with ID 'c0346077-eb9e-4dbc-85ad-03313867be69'.
Creating new image set with name 'Model100Appv1.0' for image with ID 'b66f1398-4ad6-4f12-be84-8ad607676ec3'.
Adding image set with ID '70207e9a-d080-42d7-899e-fb02822fbc32' to feed with ID '8e2d3b19-bb01-4e36-b974-5b2f8df502e9'.
Successfully linked device <device ID> to feed with ID '8e2d3b19-bb01-4e36-b974-5b2f8df502e9'.
Command completed successfully in 00:00:25.5193828.

The next example creates a new feed for an existing component. The feed depends on the Retail Azure Sphere OS feed and is named BlinkLink. The feed services the devices in the same device group as the attached device.

azsphere device link-feed --componentid 16995a70-377f-4bd2-b29d-1b0fffcbe287 --newfeedname BlinkLink --dependentfeedid 3369f0e1-dedf-49ec-a602-2aa98669fd61

Getting the details for device with ID <device ID>.
Create a new feed with name 'BlinkLink'.
Adding feed with ID '6daf66aa-5a3e-41f9-9659-6c30a2f7673f' to device group with ID 'd80bf785-acae-497c-a62c-21a6ce65b81f'.
Successfully linked device <device ID> to feed with ID '6daf66aa-5a3e-41f9-9659-6c30a2f7673f'.
Command completed successfully in 00:00:07.1315217.

manufacturing-state, mfg

Manages the manufacturing state of the attached device.

Operation Description
show Displays the manufacturing state of the attached device
update Updates the manufacturing state of the attached device if it is not already AllComplete.

Caution

Manufacturing state changes are permanent and irreversible.

manufacturing-state show

Displays the manufacturing state of the attached device.

Optional parameters

Parameter Description
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device manufacturing-state show
Manufacturing State: Blank
Command completed successfully in 00:00:00.9005143.

manufacturing-state update

Updates the manufacturing state of the attached device if the state is not already AllComplete.

This command is intended for use during the manufacturing process.

Caution

Manufacturing state changes are permanent and irreversible.

Optional parameters

Parameter Description
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-s, --state SettableManufacturingStates Specifies the manufacturing state to set for the device. Currently the only settable state is AllComplete.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device manufacturing-state update --state AllComplete
Manufacturing State: AllComplete
Command completed successfully in 00:00:00.9005143.

prep-debug

Sets up the attached device for local debugging and disables over-the-air application updates.

Specifically, prep-debug:

  • Downloads and applies the appdevelopment capability for the attached device
  • Assigns the device to a device group that does not enable over-the-air application updates
  • Reboots the device

If the command reports an error, it may suggest that you claim the device. First, use azsphere tenant show-selected to ensure that you are logged in to the intended Azure Sphere tenant, and then azsphere login to log into a different tenant if necessary. To claim the device, use azsphere device claim. If you see the error but have already claimed the device, make sure that you are logged in to the tenant in which you claimed the device.

Optional parameters

Parameter Description
-d, --devicegroupid GUID Specifies the ID of a device group that does not apply over-the-air application updates. If omitted, assigns the device to a default group.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-r, --enablertcoredebugging Installs drivers required to debug applications running on a real-time core. This option requires administrator permissions.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device prep-debug --enablertcoredebugging

Installing USB drivers to enable real-time core debugging.
Drivers installed for all attached devices
Getting device capability configuration for application development.
Downloading device capability configuration for device ID <device ID>.
Successfully downloaded device capability configuration.
Successfully wrote device capability configuration file 'C:\Users\Administrator\AppData\Local\Temp\tmpD15E.tmp'.
Setting device group ID '63bbe6ea-14be-4d1a-a6e7-03591d882b42' for device with ID <device ID>.
Successfully disabled over-the-air updates.
Enabling application development capability on attached device.
Applying device capability configuration to device.
Successfully applied device capability configuration to device.
The device is rebooting.
Application development capability enabled.
Successfully set up device <device ID> for application development, and disabled over-the-air updates.
Command completed successfully in 00:00:07.7393213.

prep-field

Readies the attached device for field use by disabling application development, deleting any existing applications, and enabling over-the-air application updates.

It requires a device to be attached to the PC and operates only on the attached device.

The specific tasks that prep-field performs depend on the whether a product SKU and device group have already been assigned for this device. If the product SKU or the device group does not already exist, the command creates it and assigns it to the device, provided that a SKU name or a device group name is supplied with the appropriate parameter.

Optional parameters

Parameter Description
-r, --devicegroupid GUID Specifies the ID of the device group to which to assign the device. If omitted, assigns the device to a default group that enables application updates. Cannot be used with --newdevicegroupname.
-g, --newdevicegroupname string Creates a new device group that allows over-the-air application updates. Device group names must be unique within an Azure Sphere tenant. Cannot be used with --devicegroupid.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-n, --newskuname string Creates a new product SKU and assigns it to the device. SKU names must be unique within an Azure Sphere tenant. Cannot be used with --skuid.
-d, --skudescription string Provides a friendly description of the new SKU. Requires --newskuname.
-s, --skuid GUID Specifies the ID of an existing product SKU to apply to the device. Cannot be used with --newskuname.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Examples

Example 1. Create a product SKU and device group for device

This example creates a new product SKU and a new device group, and assigns both to the attached device.

azsphere device prep-field --newdevicegroupname AppUpdateGroup --newskuname TestSKU

As the output shows, the command deletes the existing application from the device, removes the appdevelopment capability, creates a device group named AppUpdateGroup, creates a product SKU named TestSKU, and assigns both the device group and the product SKU to the attached device. The new device group is enabled for OTA loading of application updates.

Removing applications from device.
Component '54acba7c-7719-461a-89db-49c807e0fa4d' deleted.
Locking device.
Downloading device capability configuration for device ID <device ID>.
Successfully downloaded device capability configuration.
Applying device capability configuration to device.
Successfully applied device capability configuration to device.
The device is rebooting.
Successfully locked device.
Creating a new device group with name 'AppUpdateGroup'.
Setting device group ID 'bbc91f02-1de4-43a3-bcf2-f6f0994ac723' for device with ID <device ID>.
Creating a new SKU with name 'TestSKU'.
Setting product SKU to '5d88f658-be0c-4814-8319-473f21f4f88f' for device with ID <device ID>.
Successfully set up device <device ID> for OTA loading.
Command completed successfully in 00:00:18.0072081.

Example 2. Assign existing product SKU and device group to device

This example assigns an existing product SKU and device group to the attached device.

azsphere device prep-field --skuid 2bc8c605-6f8f-4802-ba69-c57d63e9c6dd --devicegroupid d80bf785-acae-497c-a62c-21a6ce65b81f

Getting the details of device group with ID ''.
Removing applications from device.
No app present.
Successfully removed applications from device.
Locking device.
Downloading device capability configuration for device ID <device ID>.
Successfully downloaded device capability configuration.
Applying device capability configuration to device.
Successfully applied device capability configuration to device.
The device is rebooting.
Successfully locked device.
Setting device group ID 'd80bf785-acae-497c-a62c-21a6ce65b81f' for device with ID <device ID>.
Setting product SKU to '2bc8c605-6f8f-4802-ba69-c57d63e9c6dd' for device with ID <device ID>.
Successfully set up device <device ID> for OTA loading.
Command completed successfully in 00:00:12.0638169.

Example 3. Assign device to different device group

This example is similar to the preceding example, but retains the existing product SKU for the device. Here the prep-field operation changes the device group to which the device belongs and removes the appDevelopment capability. This command is useful for moving a device from a development environment that does not enable OTA application updates to a production environment that does.

azsphere device prep-field --devicegroupid 655d7b12-07ad-4e8a-b104-c0ec494b8489

Getting the product SKU for device with ID <device ID>.
Getting the details of device group with ID ''.
Removing applications from device.
Component '54acba7c-7719-461a-89db-49c807e0fa4d' deleted.
Successfully removed applications from device.
Locking device.
Downloading device capability configuration for device ID <device ID>.
Successfully downloaded device capability configuration.
Applying device capability configuration to device.
Successfully applied device capability configuration to device.
The device is rebooting.
Successfully locked device.
Setting device group ID '655d7b12-07ad-4e8a-b104-c0ec494b8489' for device with ID <device ID>.
Successfully set up device <device ID> for OTA loading.
Command completed successfully in 00:00:11.1988981.

recover

Replaces the system software on the device.

Optional parameters

Parameter Description
-c, --capability filename Specifies the filename of the device capability image to apply to the device. For Microsoft use only.
-i, --images folder Specifies the path to a folder that contains the image packages to write to the device. By default, recovery uses the images in the SDK unless an alternate path is provided with this flag.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device recover --images .\recovery`

restart

Restarts the attached device.

Optional parameters

Parameter Description
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device restart
Restarting device.
Device restarted successfully.
Command completed successfully in 00:00:10.2668755.

show-attached

Displays information about the attached device from the device itself. These details differ from those that the Azure Sphere Security Service stores for the device.

Optional parameters

Parameter Description
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

Device ID: <device ID>
IP address: 192.168.35.2
Connection path: 1423
Command completed successfully in 00:00:03.3654153.

show-ota-config

Displays information that the Azure Sphere Security Service stores for a device. These details differ from those that the device itself stores.

Optional parameters

Parameter Description
-i, --deviceid GUID Specifies the ID of the device. By default, shows information about the attached device.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device show-ota-config
Retrieved the over-the-air update configuration for device with ID <device ID>:
 --> Device group: 'System Software' with ID '63bbe6ea-14be-4d1a-a6e7-03591d882b42'
 --> SKU: '9d606c43-1fad-4990-b207-554a025e0869' of type 'Chip'
 --> SKU: '946410a0-0057-4b11-af68-d56a684f6681' of type 'Product'
Command completed successfully in 00:00:03.0219123.

show-ota-status

Displays the status of the most recent OTA update for the device.

Use this command to find out which version of the Azure Sphere OS your device is running or whether the current OTA update has completed.

Optional parameters

Parameter Description
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device show-ota-status
The Azure Sphere Security Service is targeting this device with OS version <versionNumber>
Your device has the expected version of the Azure Sphere OS: <versionNumber>.
Command completed successfully in 00:00:03.8184016.

In this example, <versionNumber> represents the current operating system version and is a changeable value.

sideload, sl

Manages the application on the device.

Many of the sideload options require the appdevelopment capability, which can be acquired by using prep-debug. To sideload an SDK-signed application, or to start, stop, debug, or delete an SDK-signed application or a production-signed application, the device must have the appdevelopment capability.

You can use sideload stop and sideload start to restart a running real-time capable application to determine which real-time core it is running on.

Operation Description
delete Deletes the current application from the device.
deploy Loads an application onto the device.
show-quota Displays the amount of storage used by the current application on the device.
show-status Returns the status of the current application on the device.
start Starts the application that is loaded on the device.
stop Stops the application that is running on the device.

sideload delete

Deletes applications from the device.

Optional parameters

Parameter Description
-i, --componentid GUID Specifies the ID of the component to delete. If omitted, deletes all applications.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device sideload delete
Component '54acba7c-7719-461a-89db-49c807e0fa4d' deleted.

sideload deploy

Loads an application onto the attached device and starts the application.

This command fails if the application manifest requests a resource that is being used by an application that is already on the device. In this case, use azsphere device sideload delete to delete the existing application and then try sideloading again. The azsphere device sideload delete command will delete both high level applications and real time applications; to delete one application and leave the other specify the component ID of the application to delete.

The same command is used to deploy both high-level applications and real-time capable applications.

Required parameters

Parameter Description
-p, --imagepackage path Specifies the path and filename of the image package to load on the device. Sideload deployment will fail if the device does not have the appdevelopment capability.

Optional parameters

Parameter Description
--force Forces the deployment of an image that uses a Beta API that may no longer be supported.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-m, --manualstart Does not start the application after loading it.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device sideload deploy --imagepackage "C:\Users\Test\Documents\Visual Studio 2017\Projects\Mt3620Blink6\Mt3620Blink6\bin\ARM\Debug\Mt3620Blink6.imagepackage"
Deploying 'C:\Users\Test\Documents\Visual Studio 2017\Projects\Mt3620Blink6\Mt3620Blink6\bin\ARM\Debug\Mt3620Blink6.imagepackage' to the attached device.
Image package 'C:\Users\Test\Documents\Visual Studio 2017\Projects\Mt3620Blink6\Mt3620Blink6\bin\ARM\Debug\Mt3620Blink6.imagepackage' has been deployed to the attached device.
Command completed successfully in 00:00:03.0567304.

sideload show-quota

Displays the amount of mutable storage allocated and in use on the attached device.

You set the mutable storage quota in the application manifest, and the Azure Sphere OS enforces quotas when it allocates sectors for the file. As a result, if you decrease the MutableStorage value, the amount of storage in use will not change, but the allocated value reported will be different. For example, if the application has already used 16 KB and you change the MutableStorage value to 8, the command reports that the application uses 16 KB of 8 KB allocated. The data remains on the device.

Optional parameters

Parameter Description
-i, --componentid GUID Specifies the ID of the component for which to return storage information. If omitted, displays information for all applications.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

C:\>azsphere device sideload show-quota

8548b129-b16f-4f84-8dbe-d2c847862e78: No mutable storage allocated.
Command completed successfully in 00:00:02.3003524.

C:\> azsphere.exe device sideload deploy -p Mt3620Blink1_Mutable.imagepackage
Deploying 'Mt3620Blink1_Mutable.imagepackage' to the attached device.
Image package 'Mt3620Blink1_Mutable.imagepackage' has been deployed to the attached device.
Command completed successfully in 00:00:04.8939438.

C:\>azsphere device sideload show-quota
8548b129-b16f-4f84-8dbe-d2c847862e78: No mutable storage allocated.
ee8abc15-41f3-491d-a4c7-4af49948e159: 0KB out of 16KB of mutable storage used.
Command completed successfully in 00:00:02.0410841.

sideload show-status

Displays the current status of the applications on the device.

Optional parameters

Parameter Description
-i, --componentid GUID Specifies the ID of the component for which to display status. If omitted, shows status of all components.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device sideload show-status
54acba7c-7719-461a-89db-49c807e0fa4d: App state: running

Command completed successfully in 00:00:01.1103343.

sideload start

Starts applications on the device.

Optional parameters

Parameter Description
-i, --componentid GUID Specifies the ID of the component to start. If omitted, starts all applications.
-d, --debug Starts the application for debugging. Requires --componentid.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device sideload start
54acba7c-7719-461a-89db-49c807e0fa4d: App state: running

Command completed successfully in 00:00:01.1183407.

sideload stop

Stops the applications on the device.

Optional parameters

Parameter Description
-i, --componentid GUID Specifies the ID of the component to stop. If omitted, stops all applications.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device sideload stop
54acba7c-7719-461a-89db-49c807e0fa4d: App state: stopped

Command completed successfully in 00:00:01.1210256.

update-device-group

Moves the device into a different device group in your Azure Sphere tenant.

Required parameters

Parameter Description
-d, --devicegroupid GUID Specifies the ID of the device group to which to move the device.

Optional parameters

Parameter Description
-i, --deviceid GUID Specifies the ID of the device to move. By default, moves the attached device.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device update-device-group --devicegroupid 63bbe6ea-14be-4d1a-a6e7-03591d882b42
Successfully moved device <device ID> to device group '63bbe6ea-14be-4d1a-a6e7-03591d882b42' in your Azure Sphere tenant.

Command completed successfully in 00:00:02.7316538.

update-sku

Sets the product SKU for a device.

Required parameters

Parameter Description
-s, --skuid GUID Specifies the ID of the SKU to assign to the device.

Optional parameters

Parameter Description
-i, --deviceid GUID Specifies the ID of the device. By default, assigns the SKU to the attached device.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device update-sku --skuid 319725fd-1591-4a92-be9a-2f8cf90707f1
Successfully set SKU '319725fd-1591-4a92-be9a-2f8cf90707f1' for device ID <device ID> in your Azure Sphere tenant.
Command completed successfully in 00:00:02.5983519.

wifi

Changes the wireless configuration for the attached device.

To use the device on a wireless network, you must add information about the network and enable the network on the device. Although you can input non-ASCII characters in SSIDs, azsphere does not display them properly.

If your application uses the WifiConfig API, you must also include the WifiConfig capability in the application's app_manifest.json file.

Operation Description
add Adds the details of a wireless network to the device.
delete Removes the details of a wireless network from the device.
disable Disables a wireless network on the device.
enable Enables a wireless network on the device.
list Lists the current Wi-Fi configuration for the device.
scan Scans for available networks.
show-status Displays the status of the wireless interface.

wifi add

Adds information about a Wi-Fi connection to the device.

A device can have multiple Wi-Fi connections.

Although you can input non-ASCII characters in SSIDs, azsphere does not display them properly.

The azsphere command can connect to hidden SSIDs if you include the --targeted-scan parameter.

Required parameters

Parameter Description
-s, --ssid string Specifies the SSID of the network. Network SSIDs are case-sensitive.

Optional parameters

Parameter Description
-p, --psk string Specifies the WPA/WPA2 key for the new network. Omit to add this SSID as an open network. If your key contains an ampersand (&), enclose the key in quotation marks.
-t, --targeted-scan Attempts to connect to a network even when it is not broadcasting or is hidden by network congestion.
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device wifi add --ssid MyNetwork --psk myKey123

Add network succeeded:
ID : 2
SSID : MyNetwork
Configuration state : enabled
Connection state : unknown
Security state : psk

Command completed successfully in 00:00:01.7039497.

If the network SSID or key has embedded spaces or an ampersand, enclose the SSID or key in quotation marks. If the SSID or key includes a quotation mark, use a backslash to escape the quotation mark. Backslashes do not require escape if they are part of a value. For example:

azsphere device wifi add --ssid "New SSID" --psk "key \"value\" with quotes"

wifi delete

Deletes information about a wireless network from the device.

Required parameters

Parameter Description
-i, --id integer Specifies the ID of the network to delete.

Optional parameters

Parameter Description
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device wifi delete --id 1
Successfully removed network.
Command completed successfully in 00:00:01.0055424.

wifi disable

Disables a wireless network on the attached device.

Required parameters

Parameter Description
-i, --id integer Specifies the ID of the network to disable.

Optional parameters

Parameter Description
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device wifi disable --id 2
Successfully disabled network:
ID                  : 2
SSID                : NETGEAR21-5G
Configuration state : disabled
Connection state    : disconnected
Security state      : psk
Command completed successfully in 00:00:01.4166658.

wifi enable

Enables a wireless network on the attached device.

To change from one network to another if both are within range, disable the currently connected network before you enable the new network.

Required parameters

Parameter Description
-i, --id integer Specifies the ID of the network to enable.

Optional parameters

Parameter Description
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device wifi enable --id 2
Successfully enabled network:
ID                  : 2
SSID                : NETGEAR21-5G
Configuration state : enabled
Connection state    : connected
Security state      : psk
Command completed successfully in 00:00:01.4063645.

wifi list

Displays information about all the Wi-Fi connections on the device.

Optional parameters

Parameter Description
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
Global parameters

Parameter Description
-v, --verbose Provides verbose output
-?, --help Displays help on the command

Example

azsphere device wifi list
Network list:

ID                  : 0
SSID                : NETGEAR21
Configuration state : enabled
Connection state    : connected
Security state      : psk
ID                  : 1

SSID                : A_WiFi_SSID
Configuration state : enabled
Connection state    : disconnected
Security state      : open
ID                  : 2

SSID                : NETGEAR21-5G
Configuration state : enabled
Connection state    : disconnected
Security state      : psk
Command completed successfully in 00:00:00.7698180.

wifi scan

Scans for wireless networks within range of the device. The command will return up to 64 wireless network, but the number of wireless networks displayed may be limited by environmental factors such as the density of access points in range.

Optional parameters

Parameter Description
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.

Example

azsphere device wifi scan

Scan results:
SSID : NETGEAR21
Security state : psk
BSSID : 44:94:fc:36:c8:65
Signal level : -66
Frequency : 2442

SSID : CenturyLink9303
Security state : psk
BSSID : 58:8b:f3:09:ae:d2
Signal level : -75
Frequency : 2412

SSID : NETGEAR21-5G
Security state : psk
BSSID : 44:94:fc:36:c8:64
Signal level : -86
Frequency : 5765

SSID : belkin.c32
Security state : psk
BSSID : 08:86:3b:0b:cc:32
Signal level : -86
Frequency : 2462
Command completed successfully in 00:00:07.4163320.

wifi show-status

Displays information about the current Wi-Fi connection on the device.

Optional parameters

Parameter Description
-ip, --deviceip [Multi-Device] Specifies the IP address of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.
-l, --devicelocation [Multi-Device] Specifies the FTDI location ID of the device to use for this operation. This is only required when multiple devices are attached. You may specify either a device IP or device location.

Example

azsphere dev wifi show-status
SSID                : NETGEAR23
Configuration state : enabled
Connection state    : connected
Security state      : psk
Frequency           : 2417
Mode                : station
Key management      : WPA2-PSK
WPA State           : COMPLETED
IP Address          : 192.168.1.9
MAC Address         : be:98:26:be:0d:e0

Command completed successfully in 00:00:01.7341825.