Release Notes 19.02, 19.03, and 19.04

Article
08/08/2023

The Azure Sphere 19.02 preview feature release and 19.03 and 19.04 quality releases include the changes, new features, and known issues described in this article.

Note

Starting with the 19.02 feature release, we plan one major feature release and two minor quality releases per quarter. A feature release contains new functionality, whereas a quality release contains bug fixes. The Azure Sphere 19.03 release is the first quality release.

About the 19.04 quality release

The 19.04 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.02 release. It does not contain any user-visible changes.

As noted in OS feeds, we now support both a Retail Evaluation feed and a Retail feed for the Azure Sphere OS. The 19.04 update was released on the Retail Evaluation feed on April 10. Starting April 24, it is available on the Retail feed. During the evaluation period, you can verify that your OTA-deployed software continues to work as you expect.

If your devices are connected to the internet, they will be updated OTA within 24 hours after the 19.04 version is released to the feed that their device groups depend on.

About the 19.03 quality release

The 19.03 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.02 release.

As noted in OS feeds, we now support both a Retail Evaluation feed and a Retail feed for the Azure Sphere OS. The 19.03 release was initially available only through the Retail Evaluation feed. Effective March 28, it is available on the Retail feed. During the evaluation period, you can verify that your OTA-deployed software continues to work as you expect.

Changes in the 19.03 release

The 19.03 release resolves a problem in which Azure Sphere did not accept a DHCP offer if the packet sent by the DHCP server had a zero UDP checksum.

How to update to the 19.03 release

You can update to the 19.03 release immediately from the Retail Evaluation feed, or you can update from the Retail feed after the evaluation period ends.

To update during the evaluation period

To obtain the release during the evaluation period, you will need to set up a new device group and feed that depend on the Retail Evaluation feed. Set up a device group for OS evaluation explains how. Currently, update to the Retail Evaluation feed is supported for device groups that enable over-the-air application updates.

The procedure assumes that your device is running the 18.11 release or later. If your device is running an earlier release or has never been used, first follow the instructions in the next section to update to the version on the Retail feed and then set up a device group that depends on the Retail Evaluation feed and assign your device to it. Currently, the Retail Evaluation feed downloads the OS only to devices that are configured for over-the-air (OTA) application deployment.

The azsphere device recover command always recovers to the Retail OS version. If you update to the 19.03 release during the evaluation period and then recover your device, the device will receive the 19.02 release.

To update after the evaluation period

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 19.03 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.
If your Azure Sphere device has been claimed but is running TP 4.2.1, follow the instructions in the 18.11 Release Notes to update the Azure Sphere OS on a claimed device and move the device into a device group that does not deliver OTA application updates. This procedure will update the device to the current release on the Retail feed.

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

Retirement of TP 4.2.1

We no longer support the TP 4.2.1 release. Devices that are running TP 4.2.1 will no longer be issued certificates by the Azure Sphere Security Service, and consequently cannot authenticate to the Device Provisioning Service (DPS). Attempts to authenticate will return the error AZURE_SPHERE_PROV_RESULT_DEVICEAUTH_NOT_READY. You must update these devices to the current release.

New features and changes in the 19.02 release

This release includes substantial investments in the Azure Sphere OS support for the MT3620 hardware. The following sections describe new and changed features.

SPI

This release adds support for use of the Serial Peripheral Interface (SPI) on the MT3620. A Beta API for SPI is available for use in application development. The LSM6DS3_SPI sample shows how you can develop applications that use SPI.

I2C

This release adds support for the Inter-Integrated Circuit (I2C) interface on the MT3620. A Beta API for I2C is available for use in application development. The LSM6DS3_I2C sample shows how you can develop applications that use I2C.

DHCP and SNTP servers

In this release, the Azure Sphere OS includes DHCP and SNTP server support for private LAN configurations. The Private Ethernet sample shows how to use them.

Application size and storage

One MiB of read-only flash memory is now dedicated for customer-deployed image packages at runtime. During development, the 1 MiB limit includes the gdbserver debugger, which requires approximately 280KiB in the current release. Keep in mind, however, that the debugger size may change in future releases. For additional details, see:

The azsphere device sideload show-quota command has been added to display the amount of mutable storage allocated and used by an application.

Azure IoT support

The Azure Sphere OS has updated its Azure IoT SDK to the LTS Oct 2018 version. In addition, a new Azure IoT reference solution shows how to use Azure Sphere with either Azure IoT Central or an Azure IoT Hub.

OS update protection

The Azure Sphere OS now detects additional update scenarios that might cause the device to fail to boot. When one of these problems occurs, the OS automatically rolls back the device to its last known good configuration. Rollback may take longer than successful update because the device reboots but is otherwise not visible to customers.

CMake preview

A CMake Sample provides an early preview of CMake as an alternative for building Azure Sphere applications. This limited preview lets customers begin testing the use of existing assets in Azure Sphere development.

Wi-Fi setup and device control via BLE

The Wi-Fi Setup and Device Control Via BLE reference solution extends the Bluetooth Wi-Fi pairing solution that was released in 18.11 to demonstrate how to control a device locally via BLE when, for example, internet access is not available. The updated reference solution also uses a passkey to protect the BLE bonding process. Only bonded devices may provide Wi-Fi credentials or perform local control via encrypted BLE connection.

OS feeds

The 'Preview MT3620' feed has been renamed to 'Retail Azure Sphere OS.' It retains the same feed ID (3369f0e1-dedf-49ec-a602-2aa98669fd61) as in the 18.11 release. Because the feed ID has not changed, you do not need to change your existing application deployments.

The new 'Retail Evaluation Azure Sphere OS' feed (feed ID 82bacf85-990d-4023-91c5-c6694a9fa5b4) delivers an evaluation version of the Azure Sphere OS approximately two weeks before that version is released to the Retail feed.

See Azure Sphere OS feeds for details about the feeds.

Compatibility with the previous release

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

New APIs for SPI and I2C along with additions to the networking API for SNTP and DHCP
Enhancements to production APIs, including additional options for UART and additional error codes for networking

The 19.02 release supports two Target API sets: 1 and 1+Beta1902.

18.11 applications and the 19.02 release

Existing application images that were built with the 18.11 SDK should run successfully on the 19.02 OS. For the 19.02 release, this is true for images that use Beta APIs as well images that use only production APIs. Thus, if you've created an OTA deployment for an 18.11 image package, it should continue to work on 19.02.

If you use the 19.02 SDK to rebuild an 18.11 application that uses Beta APIs, however, you must update the Target API Set property to 1+Beta1902 in the Visual Studio Project > Properties page, as described in Beta API features.

If you do not update the Target API Set property, the build fails with the following message:

Target API Set %s is not supported by this SDK. Please update your SDK at http://aka.ms/AzureSphereSDKDownload, or open the Project Properties and select a 'Target API Set' that this SDK supports. Available targets are: [ ..., ...]. Ensure that the Configuration selected on that page includes the active build configuration (such as Debug, Release, All Configurations).

19.02 applications and the 18.11 release

If you install the 19.02 SDK and try to build an application before your device has received the OTA update to 19.02, you may encounter errors upon sideloading the application onto your device. If in doubt, verify the OS and SDK versions. The sections that follow summarize the expected behavior.

Building 19.02 applications against the 18.11 SDK

If you try to build an application that uses Target API Set 1 against the 18.11 SDK, compilation will fail if the application uses any new symbols that were introduced at 19.02, such as new UART enums or networking errors codes. Otherwise, the build will succeed but sideloading might fail, as described in the following section.

If you try to build an application that uses Target API Set 1+Beta1902 against the 18.11 SDK, the build will fail with one of the following messages:

The specified task executable location "C:\Program Files (x86)\Microsoft Azure Sphere SDK\\SysRoot\tools\gcc\arm-poky-linux-musleabi-gcc.exe" is invalid.

OR:

1>A task was canceled., followed by multiple errors like mt3620_rdb.h:9:10: fatal error: soc/mt3620_i2cs.h: No such file or directory

Sideloading 19.02 applications on the 18.11 OS

Both Visual Studio and the azsphere command sideload applications onto Azure Sphere devices. If you sideload an application that was built against the 19.02 SDK onto a device that is running the 18.11 OS, expect the following results:

If your application was built for Target API Set 1, it fails at run time if it uses new UART options or networking errors.
If your application was built for Target API Set 1+Beta1902, it fails at run time if it uses new Beta APIs, UART options, or networking error codes. For example, if your 19.02 application uses the new I2C API, you might see an error like the following:

Error relocating /mnt/apps/c5b532c2-8379-49b9-8771-7228b03c23f3/bin/app: I2CMaster_Open: symbol not found

OTA deployment of 19.02 applications on the 18.11 OS

OTA deployment of 19.02 applications to the 18.11 OS is not possible because all application feeds depend on the Retail Azure Sphere OS feed, which provides the 19.02 OS.

Sample applications

All Azure Sphere samples in GitHub require the 19.02 SDK. We recommend that you update your local version of the [GitHub samples repo](https://github.com/Azure/azure-sphere-samples upon installation of the 19.02 release.

If you try to build older (18.11) samples against the 19.02 SDK, you may see the following error:

Could not add sysroot details to application manifest from '*filename*'. The specified sysroot '1+Beta1902' contains TargetBetaApis 'Beta1902', but the application manifest only contains the TargetApplicationRuntimeVersion field. Either the TargetApplicationRuntimeVersion field must be removed or the TargetBetaApis field must be added.

To correct this error, remove TargetApplicationRuntimeVersion field from the application manifest or update the samples.

Known issues in 19.02

This section lists known issues in the current release.

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:

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.
Close Visual Studio 2019.
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.