Release Notes 19.05, 19.06, and 19.07

The Azure Sphere 19.05, 19.06, and 19.07 preview releases include the changes, new features, and known issues described in this article.

Important

19.07 is an important update for the development and manufacturing scenarios described below. For these scenarios, you need to update your devices to the 19.07 release by August 5.

If your devices are connected to the internet, they should receive the update over the air (OTA); no action is required on your part. To find out which release a device is running, use the azsphere device show-ota-status command.

If it's not possible to put the device online, you will need to recover the device.

After August 5, attempts to add or remove the AppDevelopment capability (azsphere device prep-debug and azsphere device enable-cloud-test) will fail on development devices that are running an older release of the Azure Sphere OS, with the error below. This is due to the normal yearly update to the production keys that are used to sign capabilities and images.

error: The device did not accept the device capability configuration. Please check the Azure Sphere OS on your device is up to date using 'azsphere device show-ota-status'.

In addition, if you create a new production-signed application image for factory installation after August 5, you must also update your factory process to install the 19.07 OS release. However, you can continue to run your existing factory process with your existing application and OS images, until you need to create a new version of the application.

To update to the latest release

  • If your Azure Sphere device is already running the 18.11 OS release (or later), is connected to the internet, and is a member of a device group that depends on the Retail OS feed, it should be updated OTA within 24 hours after the new release is available on the Retail feed.

  • If you have an Azure Sphere device that has never been used, complete all the procedures in Install Azure Sphere. When you complete these steps, your device will be running the OS that the Retail feed delivers and will be ready for application development.

How to verify installation

You can verify the installed OS version by issuing the following command in an Azure Sphere Developer Command Prompt:

azsphere device show-ota-status

To check which version of the SDK is installed, use the following command:

azsphere show-version

New features and changes in the 19.07 release

The 19.07 quality release includes an updated Azure Sphere OS only; it does not include an updated SDK. Continue to use the Azure Sphere SDK Preview from the Visual Studio Marketplace. This release supports the same APIs as the 19.05 release.

Fixed bugs

This release fixes a bug that prevented the deletion of temporary images. Starting at the 19.05 release, if you sideloaded a production-signed image with the --temporary flag (as in a factory-floor scenario), the image could not be deleted unless the device had the AppDevelopment capability. This bug was a regression from the previous release. It has now been fixed.

Common vulnerabilities

The periodic Azure Sphere quality releases incorporate current patches to the custom Linux-based OS. When potentially significant common vulnerabilities and exposures (CVEs) have been found and fixed, we list those issues in the Release Notes. The 19.07 quality release includes changes to mitigate against CVE-2019-5436.

Although Microsoft does not believe that Azure Sphere is exploitable as a result of these vulnerabilities, we have nevertheless prioritized mitigation.

New features and changes in the 19.06 release

The 19.06 quality release includes an updated Azure Sphere OS only; it does not include an updated SDK. Continue to use the Azure Sphere SDK Preview from the Visual Studio Marketplace. This release supports the same APIs as the 19.05 release. It does not contain any user-visible changes.

The periodic Azure Sphere quality releases incorporate current patches to the custom Linux-based OS. When potentially significant common vulnerabilities and exposures (CVEs) have been found and fixed, we list those issues in the Release Notes.

The 19.06 quality release includes important changes to the Azure Sphere OS to mitigate against the following Linux vulnerabilities:

Although Microsoft does not believe that Azure Sphere is exploitable as a result of these vulnerabilities, we have nevertheless prioritized mitigation.

New features and changes in the 19.05 release

The 19.05 release includes substantial investments in the Azure Sphere OS support for the MT3620 hardware and in tooling support for additional application development scenarios. The following sections describe new and changed features.

Real-time core preview

This release includes Beta support for developing, deploying, and debugging real-time capable applications (RTApps) on the MT3620’s two M4 cores. You can find information about RTApp development in the Develop real-time capable applications topic in the Azure Sphere online documentation.

The Azure Sphere samples repository on GitHub includes samples that show how to use GPIO and UART peripherals from an RTApp and how to communicate between an RTApp and a high-level (A7) application.

Support for additional hardware platforms

Several hardware ecosystem partners have recently announced new Azure Sphere-enabled products:

  • SEEED MT3620 Mini Development Board: Development board with single-band Wi-Fi for size-constrained prototypes. This board uses the AI-Link module for a quick path from prototype to commercialization.
  • AI-Link WF-M620-RSA1 Wi-Fi Module: Single-band Wi-Fi module designed for cost-sensitive applications.
  • USI Azure Sphere Combo Module: Dual-band Wi-Fi and Bluetooth module. The on-board Bluetooth chipset supports BLE and Bluetooth 5 Mesh. The chipset can also work as an NFC tag to support non-contact Bluetooth pairing and device provisioning scenarios.
  • Avnet Guardian module: Module designed for securely connecting existing equipment to the internet. The module attaches to the equipment through Ethernet and connects to the cloud via dual-band Wi-Fi.
  • Avnet MT3620 Starter Kit: Development board with dual-band Wi-Fi connectivity featuring modular connectors that support a range of MikroE Click and Grove modules.
  • Avnet Wi-Fi Module: Dual-band Wi-Fi module. Stamp hole (castellated) pin design allows for easy assembly and simpler quality assurance.

To target a particular hardware product in an application, you set the application's TargetHardwareDefinitionDirectory property. Both Visual Studio and CMake build procedures support this property, and it applies to the sample applications as well as your own custom applications. For more information, see Manage target hardware dependencies in the online documentation and the Hardware/README.md file in the Azure Sphere Samples repository on GitHub.

Application runtime version

The application runtime version (ARV) has been incremented from 1 to 2 at this release. The Azure Sphere SDK now includes three sysroots: 1, 2, and 2+Beta1905. Support in azsphere commands enables detection of conflicting application and OS dependencies. See Target API sets, ARV, and sysroots for details about ARVs.

ADC preview

The MT3620 supports analog-to-digital (ADC) converters. This release provides preview support for using ADC on the real-time capable (M4) cores. The ADC folder in the Azure Sphere samples repository contains the ADC_RTApp_MT3620_BareMetal sample, which shows how to use ADC in a real-time capable application.

API changes

The 19.05 Azure Sphere OS release includes several changes to the API set:

  • New Application API for communication with real-time capable applications.
  • Changes to the Beta API for networking. Several previous Beta features have been replaced by new functionality. See the networking API reference for details.
  • Promotion of the mutable storage API to production from Beta.
  • POSIX API support for random number generation from Pluton's random number generator.

Visual Studio support

This release requires any edition of Visual Studio 2019, version 16.04 or later, or Visual Studio 2017, version 15.9 or later.

Visual Studio now supports F5 deployment and debugging for applications that use CMake.

The UART, GPIO, and Azure IoT templates have been moved to the Azure Sphere samples repository on GitHub. Visual Studio now provides a simple Blink template and a static library template for Azure Sphere.

Ethernet

Ethernet is now supported as an alternative to Wi-Fi for communicating with the Azure Sphere Security Service and your own services. The HTTPS and AzureIoT samples can now be run over Ethernet in addition to Wi-Fi. The Azure Sphere Samples repository on GitHub includes documentation on how to wire the supported MicroChip part, bring up the Ethernet interface, and connect to Azure IoT or your own web services.

Local device discovery

The Azure Sphere OS offers new network firewall and multicast capabilities that enable apps to run mDNS and DNS-SD for device discovery on local networks.

Azure Sphere samples on GitHub

All Azure Sphere samples in GitHub require the 19.05 SDK. We recommend that you update your local version of the GitHub samples repo upon installation of the 19.05 release.

To build the sample applications, you must clone the entire repository.

Hardware-specific information

The Hardware folder in the samples repository contains a folder for each current Azure Sphere hardware platform. Within each folder are hardware-specific JSON and header (.h) files that you can use to target the samples—or your own applications—at any Azure Sphere hardware.

The README.md file describes how to change the hardware target for the samples.

Network requirements for samples

All Azure Sphere samples now support the use of either Wi-Fi or Ethernet for networking.

Security changes

Strong stack protection and address space layout randomization (ASLR) are now enabled by default when building high-level applications. To take advantage of these features in an existing application, you need to rebuild the application.

Compatibility with the previous release

The 19.05 and 19.06 releases support three Target API sets: 2, 2+Beta1905, 1

For details about compatibility with the previous release, see Beta APIs and OS compatibility.

Important

The Networking API, which was a Beta feature in the 19.02 release, remains a Beta feature in the 19.05 release. However, the API has changed in ways that might break existing code at future releases. See the networking API reference for details.

Known issues in 19.05

This section lists known issues in the current release.

Inaccurate clock on real-time cores

The GPT0 and GPT1 timers that are built into the real-time cores should use a 32 KHz clock source, but currently they do not run at the correct frequency. Consequently, applications that use these timers will get inaccurate timeouts. For example, a request for a 1-second delay could actually delay for 1.5 seconds. GPT3 has higher resolution, but if your scenario requires more than one timer, you may need to use GPT0 or GPT1. You can work around this issue by implementing a timer queue and running all the timers from GPT3.

Determine where an RTApp runs

By default, the RTApp is deployed to the first available real-time core on the device. To find out which core the application is running on, use the azsphere device app start command to start the application. The azsphere device sideload show-status command does not currently display this information.

You cannot choose which of the two real-time cores an RTApp runs on.

CMake startup item

When you're developing RTApps using CMake, the Select Startup Item menu may reset, resulting in an error when you try to start the application. This tends to occur when you regenerate the CMake cache. Before starting the application, ensure that the menu specifies GDB Debugger (RTCore):

startup item menu

Installation of both Visual Studio 2017 and Visual Studio 2019 Preview

If you have installed the 18.11 Azure Sphere SDK Preview for Visual Studio with both Visual Studio 2017 and Visual Studio 2019 Preview, the Azure Sphere SDK Preview for Visual Studio installer may fail to install or uninstall on either or both versions with the message "unexpected error". To recover from this problem:

  1. Start Visual Studio 2019 Preview and go to Extensions > Extensions and Updates. Search for "azure Sphere" and uninstall the Visual Studio Extension for Azure Sphere Preview.
  2. Close Visual Studio 2019.
  3. Run the Azure Sphere SDK Preview for Visual Studio installer again.

Wi-Fi commands return device error 13.1

The azsphere device wifi show-status command may return error: device error 13.1 if the most recent azsphere device wifi add command supplied an incorrect --key value. If this occurs, use the azsphere device wifi delete command to delete the incorrect Wi-Fi network configuration and then add the network again with the correct key.

Non-ASCII characters in paths

The Azure Sphere tools do not support non-ASCII characters in paths.

Build errors with C++

The Visual Studio Integrated Development Environment (IDE) does not generate an error if you add a C++ source file to an Azure Sphere project. However, C++ development is not supported with Azure Sphere, and the resulting project will not build correctly.