Sideload an application image package for testing
Important
This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.
During development, you might need to sideload an image package onto the Azure Sphere device for testing. When you build an application with the Visual Studio or Visual Studio Code integrated development environment (IDE), the SDK packages the application image for you. If you have direct access to an Azure Sphere device, the SDK can also delete existing applications that aren't marked as partners, load the new image package onto the device, start it, and enable debugging. You can also sideload an image package directly from the command line.
You must first enable the appDevelopment capability for the device and add the device to a device group that does not support cloud application updates. Assigning devices to such a group ensures that your sideloaded applications will not be overwritten by cloud deployments. To prepare your device, use the azsphere device enable-development command. You can then sideload the image.
Sideload and debug an image package from the command line
To sideload the image package from the command line, you delete any existing applications on the device and then load the new one.
To stop and delete all applications on the device:
azsphere device sideload delete
To delete a single application, add the --component-id option, as follows:
azsphere device sideload delete --component-id <ComponentID>
Next, sideload the new image package:
azsphere device sideload deploy --image-package <imagepackagepath>
Replace imagepackagepath with the path to the image package. If you're using Visual Studio or Visual Studio Code, you can find the image package in the bin\ARM\Debug or bin\ARM\Release subfolder of the application's project folder. By default, the command starts the application after deploying it.
To debug the application, add the --manual-start flag to the azsphere device sideload deploy command to suppress automatic start, and then start the application for debugging:
azsphere device sideload deploy --manual-start --image-package <imagepackagepath>
azsphere device app start --debug --component-id <ComponentID>
The command displays the output and debug ports for high-level applications:
Output Port: 2342
GDB Port: 2345
Mark applications as partners
Applications that are related should be marked as partner applications. There are many situations where you would load multiple applications, such as a pair of high-level and real-time applications that communicate with each other. Marking the applications as partners will prevent one from being deleted when the second is loaded. When the Visual Studio and Visual Studio Code IDEs sideload a new image package, they delete any existing applications that aren't marked as partner applications.
To mark an application as a partner using CMake in Visual Studio:
Edit the launch.vs.json file for the application.
Add the following line:
"partnerComponents": [ "<Component ID>" ]Substitute the component ID of the partner application for
<Component ID>and save the file. You can find the component ID of each application in its app_manifest.json file or by using azsphere device image list-installed or azsphere device app show-status.
To mark an application as a partner using CMake in Visual Studio Code:
Edit the .vscode\launch.json file for the application.
Add the following line:
"partnerComponents": [ "<Component ID>" ]Substitute the component ID of the partner application for
<Component ID>and save the file. You can find the component ID of each application in its app_manifest.json file or by using azsphere device image list-installed or azsphere device app show-status.