Sideload an application image package for testing
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 az sphere 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:
az sphere device sideload delete
To delete a single application, add the --component-id option, as follows:
az sphere device sideload delete --component-id <ComponentID>
Next, sideload the new image package:
az sphere 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 az sphere device sideload deploy command to suppress automatic start, and then start the application for debugging:
az sphere device sideload deploy --manual-start --image-package <imagepackagepath>
az sphere 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 az sphere device image list-installed or az sphere 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 az sphere device image list-installed or az sphere device app show-status.