Overview of Azure Sphere applications

Azure Sphere devices can run two types of applications:

• High-level applications run containerized on the Azure Sphere OS
• Real-time capable applications (RTApps) run on bare metal or with a real-time operating system (RTOS) on the real-time cores

A high-level application is required for every Azure Sphere device; RTApps are optional.

High-level applications

Every Azure Sphere device has a high-level application, which runs on the Azure Sphere OS and may use the application libraries. A high-level application can:

• Configure and interact with Azure Sphere peripherals, such as the general-purpose input/output (GPIO) pins, universal asynchronous receiver/transmitters (UARTs), and other interfaces

• Communicate with RTApps

• Communicate with the internet and cloud-based services

• Broker trust relationships with other devices and services via certificate-based authentication

A high-level application runs in a container in Normal World user mode, as described in What is Azure Sphere?. The application container supports a subset of the POSIX environment and a set of application libraries (Applibs) that are specific to the Azure Sphere OS. The libraries and functions that are available to high-level applications are restricted to ensure that the platform remains secure and can be easily updated. Applications can access only the libraries and run-time services that Microsoft provides; neither direct file I/O nor shell access are available, among other constraints. Development environment describes the base API set and introduces the Azure Sphere application libraries that support device-specific features.

High-level applications are expected to run continuously and are automatically restarted if they stop or fail.

Create a high-level application provides more information about features.

Real-time capable applications

An Azure Sphere device may also have one or more real-time capable applications in addition to its high-level application. An RTApp can:

• Configure and interact with peripherals integrated into the Azure Sphere MCU, such as the GPIO pins and UARTs
• Communicate with high-level applications

RTApps can run either on bare metal or with a real-time operating system (RTOS). The Azure Sphere samples repo on GitHub includes a bare-metal HelloWorld sample as well as a sample that demonstrates inter-core communication between high-level and RTApps. The Azure Samples repo on GitHub contains a sample that shows how to use Azure Sphere with Azure RTOS.

Additional drivers and samples for RTApps that target the M4 real-time cores on the MT3620 chip are available on GitHub from Azure Sphere partners MediaTek and Codethink.

Each RTApp runs isolated on a particular I/O core and can communicate only with a high-level application; it cannot use the internet, the Azure Sphere applibs, or other features of the Azure Sphere OS.

Create a real-time capable application provides more information about the features and development process for RTApps.

Features common to all applications

Despite the significant differences between high-level apps and RTApps, all Azure Sphere applications have some things in common. You can develop, build, and debug both types of applications using Visual Studio or Visual Studio Code, or by invoking CMake and Ninja using the CLI.

In addition, the following security features apply to both high-level and RTApps:

• Application capabilities
• Device capabilities
• Signing and deployment requirements

Application capabilities

Regardless of where it runs, every Azure Sphere application must specify the external services and interfaces that it requires—for example, its I/O and network requirements—to prevent any unauthorized or unexpected use.

Application capabilities are the resources that an application requires. Application capabilities include the peripherals that the application uses, the internet hosts to which a high-level application connects, and permission to change the network configuration, among others. Every application must have an application manifest that identifies these resources.

Device capabilities

A device capability enables a device-specific activity. Device capabilities are granted by the Azure Sphere Security Service. By default, Azure Sphere chips have no device capabilities. There are two main types of device capabilities: the appDevelopment device capability and the fieldServicing device capability.

The appDevelopment device capability changes the type of signing that the device trusts. By default, Azure Sphere devices trust production-signed image packages but do not trust SDK-signed image packages. As a result, you cannot sideload an SDK-signed image package to an Azure Sphere device that does not have this capability. When the appDevelopment capability is present, however, the device trusts SDK-signed image packages. In addition, it enables you to start, stop, debug, or remove an application from the device. In summary, the application development capability must be present on the device before you can:

• Sideload an image package that was built by Visual Studio or the azsphere image-package command.
• Start, stop, debug, or remove an image package from the Azure Sphere device, regardless of how the image package is signed.

The azsphere device enable-development command creates and applies the appDevelopment capability and prevents the device from receiving cloud application updates.

The fieldServicing capability permits device-to-computer communications on devices that are in the DeviceComplete manufacturing state. With this capability, you can sideload production-signed images, but not delete them. You can start and stop applications, but not debug them. You can also perform routine maintenance tasks such as configuring Wi-Fi. It is intended for short-term use during a servicing session, a limited period during which access to the device is granted on a per-operation basis.

Signing and deployment requirements

All image packages deployed to an Azure Sphere device must be signed. The Azure Sphere SDK and the azsphere image-package command sign image packages for testing by using an SDK signing key. Azure Sphere devices trust this key only if the appDevelopment device capability is also present.

The Azure Sphere Security Service production-signs image packages when you upload them to the cloud. Production-signed image packages can be sideloaded or loaded from the cloud.

To prevent the installation of rogue software, applications can be loaded on an Azure Sphere device in only two ways:

• Sideloading, which can be used both for software development and testing and for field servicing of devices. Sideloading for software development and testing requires the appDevelopment device capability. Sideloading for field servicing requires the fieldServicing device capability and production-signed image packages. Both Visual Studio and Visual Studio Code sideload applications during development and debugging; you can also sideload manually by using the Azure Sphere CLI.

• Cloud update, which can be performed only by the Azure Sphere Security Service. Use the Azure Sphere CLI to create and manage cloud deployments.

Partner applications

Applications that work together can be considered partner applications and then can be sideloaded separately. When you sideload an application that has a partner, the partner application remains on the Azure Sphere device if it has already been deployed. Each application declares a list of its partners in its project configuration.

To add partners to the CMake project configuration, specify the component ID of the partner app in the partnerComponents field of the configurations section of the launch.vs.json or the .vscode/launch.json file:

"partnerComponents": [ "25025d2c-66da-4448-bae1-ac26fcdd3627" ]

High-level apps and RTApps that communicate with each other must be identified as partners. Azure Sphere does not support communication between pairs of high-level apps or pairs of RTApps.