device, dev

Manages Azure Sphere devices.

Operation Description
app Changes the status of applications on a device.
capability, cap Manages device capabilities
claim Claims a previously unclaimed device to the Azure Sphere tenant
enable-cloud-test, ect Sets up a device to disable debugging and receive updates
enable-development, edv Sets up a device for local debugging
image, img Manages images for a device
list Displays all devices in the tenant
list-attached Lists the attached devices
manufacturing-state, mfg Manages the manufacturing state of the attached device
recover Uses special recovery mode to load new firmware onto the device
restart Restarts the attached device
show Displays details about the update configuration of the device
show-attached Displays details about the attached device from the device itself
show-count Shows the total number of devices in a tenant
show-deployment-status Displays the status of the most recent deployment update
show-os-version Displays the local device operating system version
sideload, sl Loads an image onto the attached device
update Updates a single device by placing it in a specific device group.
wifi Manages the Wi-Fi configuration for the device

app

Manages applications on the device

Many of the app options require the appDevelopment capability, which can be acquired by using azsphere enable-development. To start, stop, or debug an SDK-signed application or a production-signed application, the device must have the appDevelopment capability.

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

Operation Description
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.

app 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 ID of the component for which to return storage information. If omitted, displays information for all applications.
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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 app 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 app 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.

app show-status

Displays the current status of the applications on the device.

Optional parameters

Parameter Description
-i, --componentid GUID ID of the component for which to display status. If omitted, shows status of all components.
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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 app show-status
54acba7c-7719-461a-89db-49c807e0fa4d: App state: running

Command completed successfully in 00:00:01.1103343.

app start

Starts applications on the device.

Optional parameters

Parameter Description
-d, --debug Command starts the application for debugging. Requires --componentid.
-i, --componentid GUID ID of the component to start. If omitted, starts all applications.
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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 app start
54acba7c-7719-461a-89db-49c807e0fa4d: App state: running

Command completed successfully in 00:00:01.1183407.

app stop

Stops the applications on the device.

Optional parameters

Parameter Description
-i, --componentid GUID ID of the component to stop. If omitted, stops all applications.
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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 app stop
54acba7c-7719-461a-89db-49c807e0fa4d: App state: stopped

Command completed successfully in 00:00:01.1210256.

capability, cap

Manages device capabilities.

Device capabilities determine the operations that can be performed on an individual Azure Sphere device. The device capabilities are downloaded as a file from the Azure Sphere Security Service using the azsphere device capability download command and can be applied to the attached Azure Sphere device using the --apply parameter, or in a separate command using azsphere device capability update.

Operation Description
download Downloads a device capability configuration from the Azure Sphere Security Service
select Selects a downloaded capability file to use for a servicing session
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.

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 cloud-loaded applications can be loaded and start, stop, debug, and delete are prohibited. The appDevelopment capability is applied as part of the azsphere device enable-development command.

Downloading the fieldServicing capability results in a file containing the capability for a single Azure Sphere device. The fieldServicing capability file is downloaded to your local computer and can be used in conjunction with the azsphere device capability select command.

Required parameters

Parameter Description
-t, --type capability-type Type of capability. Values are appDevelopment, fieldServicing, or none. Use none to remove the appDevelopment capability or the fieldServicing capability.

Optional parameters

Parameter Description
-i, --deviceid id 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 string [Multi-Device] 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 string [Multi-Device] 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 Path and filename at which to save the capability configuration. Include an absolute or relative path. Required with the --deviceid parameter.
-p, --apply Command 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 select

Selects a capability file to use with the attached Azure Sphere device.

The azsphere device capability select command can be used with any capability, but is most often used with the fieldServicing capability to enable a servicing session. Any user role has access to the azsphere device capability select command.

When you use the fieldServicing capability, communication is enabled between the Azure Sphere device and the local computer containing the capability file. The fieldServicing capability file is used for a session between the local computer and the Azure Sphere device, and each command in the session is prepended with a message indicating the capability file in use.

To end a servicing session, use azsphere device capability select --none.

Each fieldServicing capability file is unique to a specific Azure Sphere device. If you try to use a capability file meant for another device, you will receive the following message:

error: selected capability is not compatible with device <device ID>

Optional parameters

Parameter Description
-f, --filepath string Path to the downloaded fieldServicing capability file. If you do not provide a path, the command will store a temporary file in the local directory using the naming convention: fieldServicing-.cap.
-i, --deviceid id ID of the device for which to assign the capability configuration.
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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 select --filepath <file path>

capability show-attached

Displays the capability configuration stored on the attached device.

Optional parameters

Parameter Description
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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 Path and name of the device capability file to apply.

Optional parameters

Parameter Description
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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 ID of the device to claim. If omitted, azsphere claims the attached device.
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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.

enable-cloud-test, ect

Readies the attached device for testing cloud loading by disabling application development, deleting any existing applications, and enabling cloud-loaded application updates.

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

Specifically, enable-cloud-test:

  • Removes the appDevelopment capability for the attached device
  • Assigns the device to a device group that enables cloud-loaded application updates
  • Reboots the device

The specific tasks that enable-cloud-test performs depend on whether a product and device group have already been assigned for this device.

If azsphere device enable-cloud-test is issued without parameters, the device will be placed in the “Field Test” device group of the device’s current product. This is one of the default device groups created automatically for each product, which enables application updates. An error will be given if the device doesn’t have a product, or a “Field Test” device group doesn’t exist within it.

If a product is specified, the device will be placed in the “Field Test” device group of that product. An error will be given if this device group doesn’t exist.

If a device group is specified, the device will be placed in it. An error will be given if the target device group doesn’t enable application updates.

Optional parameters

Parameter Description
-dgi, --devicegroupid GUID 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.
-dgn, --devicegroupname string Name of the device group. Use with --productname to apply command to a device group, or use --devicegroupid.
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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.
-pi, --productid GUID ID of an existing product to apply to the device. If specified, the device will be moved to the default "Field Test" device group of this product, unless --devicegroupname is also specified.
-pn, --productname string Name of an existing product. Use with --devicegroupname to specify a device group within the product, or use --devicegroupid.
Global parameters

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

Examples

Example 1. Assign device to existing device group by its ID

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

azsphere device enable-cloud-test --devicegroupid ba23a5ed-f1a8-4d54-9513-5cad5d53598e

Getting device group by ID 'ba23a5ed-f1a8-4d54-9513-5cad5d53598e'.
Removing applications from device.
Removing debugging server from device.
Component '8548b129-b16f-4f84-8dbe-d2c847862e78' deleted or was not present beforehand.
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 'ba23a5ed-f1a8-4d54-9513-5cad5d53598e' for the device.
(Device ID: <device ID>)
Successfully updated device's device group.
Successfully set up device for application updates.
(Device ID: <device ID>)

Example 2. Assign device to different device group

This example is similar to the preceding example, but retains the existing product for the device. Here the enable-cloud-test 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 application updates to a production environment that does.

azsphere device enable-cloud-test --devicegroupname "Field Test"

Getting device group 'Field Test' for product 'MyToasterWithDgs'.
Removing applications from device.
Removing debugging server from device.
Component '8548b129-b16f-4f84-8dbe-d2c847862e78' deleted or was not present beforehand.
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 '5ac17dc0-85ce-4e5e-9d8b-8708355da252' for the device.
(Device ID: <device ID>)
Successfully updated device's device group.
Successfully set up device for application updates.
(Device ID: <device ID>)
Command completed in 00:00:17.8082885.

Example 3. Assign device by product name

This example enables cloud loading and assigns the device to a product by name.

azsphere device enable-cloud-test --productname NewToaster
Getting device group 'Field Test' for product 'NewToaster'.
Removing applications from device.
Removing debugging server from device.
Component '8548b129-b16f-4f84-8dbe-d2c847862e78' deleted or was not present beforehand.
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 '78674bd6-02a8-4a1c-9480-80fff039203f' for the device.
(Device ID: <device ID>)
Successfully updated device's device group.
Successfully set up device for application updates.
(Device ID: <device ID>)

enable-development, edv

Sets up the attached device for local debugging and disables cloud-loaded application updates.

Specifically, enable-development:

  • Downloads and applies the appDevelopment capability for the attached device
  • Assigns the device to a device group that does not enable cloud-loaded application updates
  • Reboots the device

If you issue the azsphere device enable-development command with no parameters:

  • If the device doesn’t already have a product or device group, the command downloads and applies the appDevelopment capability for the attached device, and reboots the device. Any existing apps remain on the device, and the OS is updated. Therefore, the install process to claim your device and the Quickstart to build a high-level application will be unaffected.
  • If the device already has a product, the command moves the device to the product's Development device group. By default, application updates are disabled for this group, thus ensuring that sideloaded apps are not overwritten.

If you issue the azsphere device enable-development command with the --productname parameter:

  • Places the device in the "Development" device group for the product. An error occurs if this device group doesn’t exist.

If you issue the azsphere device enable-development command with the --devicegroupid parameter:

  • Places the device in the specified device group is specified. The target device group must not enable application updates; if the device group enables application updates, an error occurs.

In some cases, azsphere device enable-development reports an error and suggests that you claim the device. If you have already claimed the device, use azsphere tenant show-selected to ensure that you are logged in to the tenant in which you claimed the device. If not, use azsphere login to log into the correct tenant. When you're sure you're logged into the appropriate tenant, use azsphere device claim to claim the device.

Optional parameters

Parameter Description
-dgi, --devicegroupid GUID 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 string [Multi-Device] 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 string [Multi-Device] 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.
-dgn, --devicegroupname string Name of the device group. Use with --productname to apply command to a device group, or use --devicegroupid.
-r, --enablertcoredebugging Command installs drivers required to debug applications running on a real-time core. This option requires administrator permissions.
-pi, --productid GUID ID of an existing product to apply to the device. If specified, the device will be moved to the default "Development" device group of this product, unless --devicegroupname is also specified.
-pn, --productname string Product name. Use with --devicegroupname to apply command to a device group, or use --devicegroupid.
Global parameters

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

Example

azsphere device enable-development --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.

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.

Note

Long image names will be truncated at 15 characters.

Optional parameters

Parameter Description
-f, --full All software images that are installed on the device are included in the list. By default, lists only application images, debuggers, and board configuration images.
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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 All software images that will be installed on the device are included in the list. By default, lists only 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 string [Multi-Device] 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 string [Multi-Device] 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.

list

Lists all devices in a tenant. Lists truncates after first 500 devices.

Global parameters

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

Example

azsphere device list

list-attached

Lists the devices attached to the local PC.

Global parameters

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

Example

azsphere device list-attached

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 string [Multi-Device] 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 string [Multi-Device] 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: AllComplete
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.

Required parameters

Parameter Description
-s, --state SettableManufacturingStates Manufacturing state to set for the device. Currently the only settable state is AllComplete.

Optional parameters

Parameter Description
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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 update --state AllComplete
Manufacturing State: AllComplete
Command completed successfully in 00:00:00.9005143.

recover

Replaces the system software on the device.

Optional parameters

Parameter Description
-i, --images folder 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 string [Multi-Device] 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 string [Multi-Device] 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

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 ID of the device. By default, shows information about the attached device.
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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
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-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 string [Multi-Device] 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 string [Multi-Device] 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-deployment-status

Displays the deployment status of application and operating system updates for the device.

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

Optional parameters

Parameter Description
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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-deployment-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.

show-count

Displays the number of devices in the current tenant.

Global parameters

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

Example

azsphere device show-count

show-os-version

Displays the current operating system version on the attached device.

Optional parameters

Parameter Description
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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-os-version

sideload, sl

Manages the application on the device.

Some sideload options require the appDevelopment capability, which can be acquired by using enable-development. 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.

Operation Description
delete Deletes the current application from the device.
deploy Loads an application onto the device.

Note that the parameters to start, stop, show-status, and show-quota have been moved to the azsphere device app command.

sideload delete

Deletes applications from the device.

Optional parameters

Parameter Description
-i, --componentid GUID ID of the application to delete from the device. If omitted, deletes all applications.
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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 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 Command forces the deployment of an image that uses a Beta API that may no longer be supported.
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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 Command 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.

update

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

In addition to device groups you create in a product, five default device groups are added when a product is created:

  • Development device group disables cloud application updates and delivers the Retail Evaluation OS.
  • Field Test device group enables cloud application updates, and delivers the Retail OS.
  • Production device group enables cloud application updates, and delivers the Retail OS.
  • Production OS Evaluation device group enables cloud application updates and delivers the Retail Evaluation OS.
  • Field Test OS Evaluation device group enables cloud application updates and delivers the Retail Evaluation OS.

Optional parameters

Parameter Description
-dgi, --devicegroupid GUID ID of the device group. Use either device group ID or a device group name and product name pair.
-dgn, --devicegroupname string Name of the device group. Use either device group ID or a device group name and product name pair.
-i, --deviceid GUID ID of the device to move. By default, moves the attached device.
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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.
-pn, --productname string Name of the product. Use either device group ID or a device group name and product name pair.
Global parameters

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

Example

azsphere device update --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.

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.
disable Disables a wireless network on the device.
enable Enables a wireless network on the device.
forget Removes the details of a wireless network from 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 SSID of the network. Network SSIDs are case-sensitive.

Optional parameters

Parameter Description
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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, --psk string WPA/WPA2 key for the new network. Omit to add the SSID as an open network. If your key contains an ampersand (&), enclose the key in quotation marks.
-t, --targeted-scan Command attempts to connect to a network even when it is not broadcasting or is hidden by network congestion.
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 disable

Disables a wireless network on the attached device.

Required parameters

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

Optional parameters

Parameter Description
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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.

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 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 forget

Deletes information about a wireless network from the device.

Required parameters

Parameter Description
-i, --id integer 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 forget --id 1
Successfully removed network.
Command completed successfully in 00:00:01.0055424.

wifi list

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

Optional parameters

Parameter Description
-ip, --deviceip string [Multi-Device] 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 string [Multi-Device] 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 string [Multi-Device] 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 string [Multi-Device] 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 string [Multi-Device] 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 string [Multi-Device] 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.